data/TWiki/TWikiNetDotPm.txt,v
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
head	1.3;
colas@0
     2
access;
colas@0
     3
symbols;
colas@0
     4
locks; strict;
colas@0
     5
comment	@# @;
colas@0
     6
colas@0
     7
colas@0
     8
1.3
colas@0
     9
date	2008.01.22.03.21.28;	author TWikiContributor;	state Exp;
colas@0
    10
branches;
colas@0
    11
next	1.2;
colas@0
    12
colas@0
    13
1.2
colas@0
    14
date	2007.01.16.04.11.59;	author TWikiContributor;	state Exp;
colas@0
    15
branches;
colas@0
    16
next	1.1;
colas@0
    17
colas@0
    18
1.1
colas@0
    19
date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
colas@0
    20
branches;
colas@0
    21
next	;
colas@0
    22
colas@0
    23
colas@0
    24
desc
colas@0
    25
@new-topic
colas@0
    26
@
colas@0
    27
colas@0
    28
colas@0
    29
1.3
colas@0
    30
log
colas@0
    31
@buildrelease
colas@0
    32
@
colas@0
    33
text
colas@0
    34
@---+ Package =TWiki::Net=
colas@0
    35
colas@0
    36
Object that brokers access to network resources.
colas@0
    37
colas@0
    38
colas@0
    39
%TOC%
colas@0
    40
colas@0
    41
---++ ObjectMethod *finish* <tt>()</tt>
colas@0
    42
Break circular references.
colas@0
    43
colas@0
    44
colas@0
    45
colas@0
    46
---+++ getExternalResource( $url ) -> $response
colas@0
    47
colas@0
    48
Get whatever is at the other end of a URL (using an HTTP GET request). Will
colas@0
    49
only work for encrypted protocols such as =https= if the =LWP= CPAN module is
colas@0
    50
installed.
colas@0
    51
colas@0
    52
Note that the =$url= may have an optional user and password, as specified by
colas@0
    53
the relevant RFC. Any proxy set in =configure= is honoured.
colas@0
    54
colas@0
    55
The =$response= is an object that is known to implement the following subset of
colas@0
    56
the methods of =LWP::Response=. It may in fact be an =LWP::Response= object,
colas@0
    57
but it may also not be if =LWP= is not available, so callers may only assume
colas@0
    58
the following subset of methods is available:
colas@0
    59
| =code()= |
colas@0
    60
| =message()= |
colas@0
    61
| =header($field)= |
colas@0
    62
| =content()= |
colas@0
    63
| =is_error()= |
colas@0
    64
| =is_redirect()= |
colas@0
    65
colas@0
    66
Note that if LWP is *not* available, this function:
colas@0
    67
   1 can only really be trusted for HTTP/1.0 urls. If HTTP/1.1 or another
colas@0
    68
     protocol is required, you are *strongly* recommended to =require LWP=.
colas@0
    69
   1 Will not parse multipart content
colas@0
    70
colas@0
    71
In the event of the server returning an error, then =is_error()= will return
colas@0
    72
true, =code()= will return a valid HTTP status code
colas@0
    73
as specified in RFC 2616 and RFC 2518, and =message()= will return the
colas@0
    74
message that was received from
colas@0
    75
the server. In the event of a client-side error (e.g. an unparseable URL)
colas@0
    76
then =is_error()= will return true and =message()= will return an explanatory
colas@0
    77
message. =code()= will return 400 (BAD REQUEST).
colas@0
    78
colas@0
    79
Note: Callers can easily check the availability of other HTTP::Response methods
colas@0
    80
as follows:
colas@0
    81
colas@0
    82
<verbatim>
colas@0
    83
my $response = TWiki::Func::getExternalResource($url);
colas@0
    84
if (!$response->is_error() && $response->isa('HTTP::Response')) {
colas@0
    85
    ... other methods of HTTP::Response may be called
colas@0
    86
} else {
colas@0
    87
    ... only the methods listed above may be called
colas@0
    88
}
colas@0
    89
</verbatim>
colas@0
    90
colas@0
    91
colas@0
    92
---++ setMailHandler( \&fn )
colas@0
    93
colas@0
    94
   * =\&fn= - reference to a function($) (see _sendEmailBySendmail for proto)
colas@0
    95
Install a handler function to take over mail sending from the default
colas@0
    96
SMTP or sendmail methods. This is provided mainly for tests that
colas@0
    97
need to be told when a mail is sent, without actually sending it. It
colas@0
    98
may also be useful in the event that someone needs to plug in an
colas@0
    99
alternative mail handling method.
colas@0
   100
colas@0
   101
colas@0
   102
---++ ObjectMethod *sendEmail* <tt>($text,$retries) -> $error</tt>
colas@0
   103
colas@0
   104
   * =$text= - text of the mail, including MIME headers
colas@0
   105
   * =$retries= - number of times to retry the send (default 1)
colas@0
   106
colas@0
   107
Send an email specified as MIME format content.
colas@0
   108
Date: ...\nFrom: ...\nTo: ...\nCC: ...\nSubject: ...\n\nMailBody...
colas@0
   109
colas@0
   110
colas@0
   111
@
colas@0
   112
colas@0
   113
colas@0
   114
1.2
colas@0
   115
log
colas@0
   116
@buildrelease
colas@0
   117
@
colas@0
   118
text
colas@0
   119
@d8 2
colas@0
   120
a9 1
colas@0
   121
---++ ObjectMethod *getUrl* <tt>($protocol,$host,$port,$url,$user,$pass) -> $text</tt>
colas@0
   122
a10 1
colas@0
   123
Get the text at the other end of a URL
colas@0
   124
d13 45
colas@0
   125
@
colas@0
   126
colas@0
   127
colas@0
   128
1.1
colas@0
   129
log
colas@0
   130
@buildrelease
colas@0
   131
@
colas@0
   132
text
colas@0
   133
@d8 1
colas@0
   134
a8 1
colas@0
   135
---++ ObjectMethod *getUrl* <tt>($host,$port,$url,$user,$pass,$header) -> $text</tt>
colas@0
   136
d15 1
colas@0
   137
d25 1
colas@0
   138
@