PerlDoc

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

internal package Foswiki::Net

Object that brokers access to network resources.

ObjectMethod finish()

Break circular references.

getExternalResource( $url [, %options] ) → $response

• $url - url to get
• %options may contain
  • method => method to use e.g. POST (GET is the default)
  • headers > =\%headers - hash of additional headers
  • content > =$content - request content (perl) string (default is an empty request body)

Get whatever is at the other end of a URL (using an HTTP GET request). Will only work for encrypted protocols such as https if the LWP CPAN module is installed.

Note that the $url may have an optional user and password, as specified by the relevant RFC. Any proxy set in configure is honoured.

The $response is an object that is known to implement the following subset of the methods of LWP::Response. It may in fact be an LWP::Response object, but it may also not be if LWP is not available, so callers may only assume the following subset of methods is available:

Note that if LWP is not available, this function:

1. can only really be trusted for HTTP/1.0 urls. If HTTP/1.1 or another protocol is required, you are strongly recommended to require LWP.
2. Will not parse multipart content
3. Will not process redirects (configure relies on this)

In the event of the server returning an error, then is_error() will return true, code() will return a valid HTTP status code as specified in RFC 2616 and RFC 2518, and message() will return the message that was received from the server. In the event of a client-side error (e.g. an unparseable URL) then is_error() will return true and message() will return an explanatory message. code() will return 400 (BAD REQUEST).

Note: Callers can easily check the availability of other HTTP::Response methods as follows:

my $response = Foswiki::Func::getExternalResource($url);
if (!$response->is_error() && $response->isa('HTTP::Response')) {
    ... other methods of HTTP::Response may be called
} else {
    ... only the methods listed above may be called
}

setMailHandler( \&fn )

• \&fn - reference to a function($) (see _sendEmailBySendmail for proto)

Install a handler function to take over mail sending from the default SMTP or sendmail methods. This is provided mainly for tests that need to be told when a mail is sent, without actually sending it. It may also be useful in the event that someone needs to plug in an alternative mail handling method.

ObjectMethod sendEmail ( $text, $retries ) → $error

• $text - text of the mail, including MIME headers
• $retries - number of times to retry the send (default 1)

Send an email specified as MIME format content. Date: ...\nFrom: ...\nTo: ...\nCC: ...\nSubject: ...\n\nMailBody...