TWiki/TWikiNetDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::Net="></a> Package =TWiki::Net
   2
   3 Object that brokers access to network resources.
   4
   5 <div>
   6   <ul>
   7     <li><a href="#Package =TWiki::Net="> Package TWiki::Net</a><ul>
   8         <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a><ul>
   9             <li><a href="#get_ExternalResource( $url ) ->"> getExternalResource( $url ) -&gt; $response</a></li>
  10           </ul>
  11         </li>
  12         <li><a href="#set_MailHandler( \fn )"> setMailHandler( \&amp;fn )</a></li>
  13         <li><a href="#ObjectMethod <strong>sendEmail</strong> ($text,"> ObjectMethod sendEmail <tt>($text,$retries) -&gt; $error</tt></a></li>
  14       </ul>
  15     </li>
  16   </ul>
  17 </div>
  18
  19 ## <a name="ObjectMethod &lt;strong&gt;finish&lt;/strong&gt; ()"></a> [[ObjectMethod]] **finish** `()`
  20
  21 Break circular references.
  22
  23 ### <a name="get_ExternalResource( $url ) - $"></a> getExternalResource( $url ) -&gt; $response
  24
  25 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.
  26
  27 Note that the `$url` may have an optional user and password, as specified by the relevant RFC. Any proxy set in `configure` is honoured.
  28
  29 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:
  30
  31 <table border="1" cellpadding="0" cellspacing="0">
  32   <tr>
  33     <td><code>code()</code></td>
  34   </tr>
  35   <tr>
  36     <td><code>message()</code></td>
  37   </tr>
  38   <tr>
  39     <td><code>header($field)</code></td>
  40   </tr>
  41   <tr>
  42     <td><code>content()</code></td>
  43   </tr>
  44   <tr>
  45     <td><code>is_error()</code></td>
  46   </tr>
  47   <tr>
  48     <td><code>is_redirect()</code></td>
  49   </tr>
  50 </table>
  51
  52 Note that if LWP is **not** available, this function:
  53
  54 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`.
  55 2. Will not parse multipart content
  56
  57 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).
  58
  59 Note: Callers can easily check the availability of other HTTP::Response methods as follows:
  60
  61     my $response = TWiki::Func::getExternalResource($url);
  62     if (!$response->is_error() && $response->isa('HTTP::Response')) {
  63         ... other methods of HTTP::Response may be called
  64     } else {
  65         ... only the methods listed above may be called
  66     }
  67
  68 ## <a name="set_MailHandler( \fn )"></a> setMailHandler( \\&amp;fn )
  69
  70 - `\&fn` - reference to a function($) (see \_sendEmailBySendmail for proto)
  71
  72 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.
  73
  74 ## <a name="ObjectMethod &lt;strong&gt;sendEmail&lt;/strong&gt; ($text,"></a> [[ObjectMethod]] **sendEmail** `($text,$retries) -> $error`
  75
  76 - `$text` - text of the mail, including MIME headers
  77 - `$retries` - number of times to retry the send (default 1)
  78
  79 Send an email specified as MIME format content. Date: ...\\nFrom: ...\\nTo: ...\\nCC: ...\\nSubject: ...\\n\\nMailBody...