[ViewVC] Diff of: cvs/AnyEvent-HTTP/README

Comparing AnyEvent-HTTP/README (file contents):
Revision 1.8 by root, Tue Jul 7 00:15:32 2009 UTC vs.
Revision 1.13 by root, Wed Jun 16 19:17:30 2010 UTC

         The callback will be called with the response body data as first
         argument (or "undef" if an error occured), and a hash-ref with
         response headers as second argument.
         All the headers in that hash are lowercased. In addition to the
-        response headers, the "pseudo-headers" "HTTPVersion", "Status" and
+        response headers, the "pseudo-headers" (uppercase to avoid clashing
+        with possible response headers) "HTTPVersion", "Status" and "Reason"
-        "Reason" contain the three parts of the HTTP Status-Line of the same
+        contain the three parts of the HTTP Status-Line of the same name.
-        name. The pseudo-header "URL" contains the original URL (which can
+        The pseudo-header "URL" contains the actual URL (which can differ
-        differ from the requested URL when following redirects).
+        from the requested URL when following redirects - for example, you
+        might get an error that your URL scheme is not supported even though
+        your URL is a valid http URL because it redirected to an ftp URL, in
+        which case you can look at the URL pseudo header).
+        The pseudo-header "Redirect" only exists when the request was a
+        result of an internal redirect. In that case it is an array
+        reference with the "($data, $headers)" from the redirect response.
+        Note that this response could in turn be the result of a redirect
+        itself, and "$headers->{Redirect}[1]{Redirect}" will then contain
+        the original response, and so on.
         If the server sends a header multiple times, then their contents
         will be joined together with a comma (","), as per the HTTP spec.
         If an internal error occurs, such as not being able to resolve a
         headers => hashref
             The request headers to use. Currently, "http_request" may
             provide its own "Host:", "Content-Length:", "Connection:" and
             "Cookie:" headers and will provide defaults for "User-Agent:"
-            and "Referer:".
+            and "Referer:" (this can be suppressed by using "undef" for
+            these headers in which case they won't be sent at all).
         timeout => $seconds
             The time-out to use for various stages - each connect attempt
-            will reset the timeout, as will read or write activity. Default
+            will reset the timeout, as will read or write activity, i.e.
+            this is not an overall timeout.
-            timeout is 5 minutes.
+            Default timeout is 5 minutes.
         proxy => [$host, $port[, $scheme]] or undef
             Use the given http proxy for all requests. If not specified,
             then the default proxy (as specified by $ENV{http_proxy}) is
             used.
-            $scheme must be either missing or "http" for HTTP, or "https"
+            $scheme must be either missing, "http" for HTTP or "https" for
-            for HTTPS.
+            HTTPS.
         body => $string
             The request body, usually empty. Will be-sent as-is (future
             versions of this module might offer more options).
             and high-security (CA and common-name verification) TLS context.
             The default for this option is "low", which could be interpreted
             as "give me the page, no matter what".
+        on_prepare => $callback->($fh)
+            In rare cases you need to "tune" the socket before it is used to
+            connect (for exmaple, to bind it on a given IP address). This
+            parameter overrides the prepare callback passed to
+            "AnyEvent::Socket::tcp_connect" and behaves exactly the same way
+            (e.g. it has to provide a timeout). See the description for the
+            $prepare_cb argument of "AnyEvent::Socket::tcp_connect" for
+            details.
         on_header => $callback->($headers)
             When specified, this callback will be called with the header
             hash as soon as headers have been successfully received from the
             remote server (not on locally-generated errors).
             memory (so the callback writes it to a file) or when only some
             information should be extracted, or when the body should be
             processed incrementally.
             It is usually preferred over doing your own body handling via
-            "want_body_handle".
+            "want_body_handle", but in case of streaming APIs, where HTTP is
+            only used to create a connection, "want_body_handle" is the
+            better alternative, as it allows you to install your own event
+            handler, reducing resource usage.
         want_body_handle => $enable
             When enabled (default is disabled), the behaviour of
             AnyEvent::HTTP changes considerably: after parsing the headers,
             and instead of downloading the body (if any), the completion
             initial headers, an interactive protocol is used (typical
             example would be the push-style twitter API which starts a
             JSON/XML stream).
             If you think you need this, first have a look at "on_body", to
-            see if that doesn'T solve your problem in a better way.
+            see if that doesn't solve your problem in a better way.
         Example: make a simple HTTP GET request for http://www.nethype.de/
            http_request GET => "http://www.nethype.de/", sub {
               my ($body, $hdr) = @_;
               print "$body\n";
            };
            undef $request;
+  DNS CACHING
+    AnyEvent::HTTP uses the AnyEvent::Socket::tcp_connect function for the
+    actual connection, which in turn uses AnyEvent::DNS to resolve
+    hostnames. The latter is a simple stub resolver and does no caching on
+    its own. If you want DNS caching, you currently have to provide your own
+    default resolver (by storing a suitable resolver object in
+    $AnyEvent::DNS::RESOLVER).
   GLOBAL FUNCTIONS AND VARIABLES
     AnyEvent::HTTP::set_proxy "proxy-url"
         Sets the default proxy server to use. The proxy-url must begin with
-        a string of the form "http://host:port" (optionally "https:...").
+        a string of the form "http://host:port" (optionally "https:..."),
+        croaks otherwise.
+        To clear an already-set proxy, use "undef".
     $AnyEvent::HTTP::MAX_RECURSE
         The default value for the "recurse" request parameter (default: 10).
     $AnyEvent::HTTP::USERAGENT
         The default value for the "User-Agent" header (the default is
         "Mozilla/5.0 (compatible; U; AnyEvent-HTTP/$VERSION;
         +http://software.schmorp.de/pkg/AnyEvent)").
     $AnyEvent::HTTP::MAX_PER_HOST
-        The maximum number of concurrent conenctions to the same host
+        The maximum number of concurrent connections to the same host
         (identified by the hostname). If the limit is exceeded, then the
         additional requests are queued until previous connections are
         closed.
         The default value for this is 4, and it is highly advisable to not

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing AnyEvent-HTTP/README (file contents): Revision 1.8 by root, Tue Jul 7 00:15:32 2009 UTC vs. Revision 1.13 by root, Wed Jun 16 19:17:30 2010 UTC

Diff Legend

Comparing AnyEvent-HTTP/README (file contents):
Revision 1.8 by root, Tue Jul 7 00:15:32 2009 UTC vs.
Revision 1.13 by root, Wed Jun 16 19:17:30 2010 UTC