buildrelease

[openafs-wiki.git] / TWiki / TWikiNetDotPm.mdwn

diff --git a/TWiki/TWikiNetDotPm.mdwn b/TWiki/TWikiNetDotPm.mdwn
index bac816a..2da93d3 100644 (file)
--- a/TWiki/TWikiNetDotPm.mdwn
+++ b/TWiki/TWikiNetDotPm.mdwn
@@ -5,7 +5,10 @@ Object that brokers access to network resources.
 <div>
   <ul>
     <li><a href="#Package =TWiki::Net="> Package TWiki::Net</a><ul>
-        <li><a href="#ObjectMethod <strong>getUrl</strong> ($protocol"> ObjectMethod getUrl <tt>($protocol,$host,$port,$url,$user,$pass) -&gt; $text</tt></a></li>
+        <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a><ul>
+            <li><a href="#get_ExternalResource( $url ) ->"> getExternalResource( $url ) -&gt; $response</a></li>
+          </ul>
+        </li>
         <li><a href="#set_MailHandler( \fn )"> setMailHandler( \&amp;fn )</a></li>
         <li><a href="#ObjectMethod <strong>sendEmail</strong> ($text,"> ObjectMethod sendEmail <tt>($text,$retries) -&gt; $error</tt></a></li>
       </ul>
@@ -13,9 +16,54 @@ Object that brokers access to network resources.
   </ul>
 </div>
 
-## <a name="ObjectMethod &lt;strong&gt;getUrl&lt;/strong&gt; ($protocol"></a> [[ObjectMethod]] **getUrl** `($protocol,$host,$port,$url,$user,$pass) -> $text`
+## <a name="ObjectMethod &lt;strong&gt;finish&lt;/strong&gt; ()"></a> [[ObjectMethod]] **finish** `()`
 
-Get the text at the other end of a URL
+Break circular references.
+
+### <a name="get_ExternalResource( $url ) - $"></a> getExternalResource( $url ) -&gt; $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:
+
+<table border="1" cellpadding="0" cellspacing="0">
+  <tr>
+    <td><code>code()</code></td>
+  </tr>
+  <tr>
+    <td><code>message()</code></td>
+  </tr>
+  <tr>
+    <td><code>header($field)</code></td>
+  </tr>
+  <tr>
+    <td><code>content()</code></td>
+  </tr>
+  <tr>
+    <td><code>is_error()</code></td>
+  </tr>
+  <tr>
+    <td><code>is_redirect()</code></td>
+  </tr>
+</table>
+
+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
+
+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 = 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
+    }
 
 ## <a name="set_MailHandler( \fn )"></a> setMailHandler( \\&amp;fn )