head	1.3;
access;
symbols;
locks; strict;
comment	@# @;


1.3
date	2008.01.22.03.21.28;	author TWikiContributor;	state Exp;
branches;
next	1.2;

1.2
date	2007.01.16.04.11.59;	author TWikiContributor;	state Exp;
branches;
next	1.1;

1.1
date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
branches;
next	;


desc
@new-topic
@


1.3
log
@buildrelease
@
text
@---+ Package =TWiki::Net=

Object that brokers access to network resources.


%TOC%

---++ ObjectMethod *finish* <tt>()</tt>
Break circular references.



---+++ getExternalResource( $url ) -> $response

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:
| =code()= |
| =message()= |
| =header($field)= |
| =content()= |
| =is_error()= |
| =is_redirect()= |

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=.
   1 Will not parse multipart content

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:

<verbatim>
my $response = TWiki::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
}
</verbatim>


---++ 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* <tt>($text,$retries) -> $error</tt>

   * =$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...


@


1.2
log
@buildrelease
@
text
@d8 2
a9 1
---++ ObjectMethod *getUrl* <tt>($protocol,$host,$port,$url,$user,$pass) -> $text</tt>
a10 1
Get the text at the other end of a URL
d13 45
@


1.1
log
@buildrelease
@
text
@d8 1
a8 1
---++ ObjectMethod *getUrl* <tt>($host,$port,$url,$user,$pass,$header) -> $text</tt>
d15 1
d25 1
@
