LWP::Protocol

LIB::LWP::PROTOCOL(1) User Contributed Perl DocumentationLIB::LWP::PROTOCOL(1)



NAME
       LWP::Protocol - Base class for LWP protocols

DESCRIPTION
       This class is used a the base class for all protocol implementations
       supported by the LWP library.

       When creating an instance of this class using
       LWP::Protocol::create($url), and you get an initialised subclass
       appropriate for that access method. In other words, the
       LWP::Protocol::create() function calls the constructor for one of its
       subclasses.

       All derived LWP::Protocol classes need to override the request() method
       which is used to service a request. The overridden method can make use
       of the collect() function to collect together chunks of data as it is
       received.

SEE ALSO
       Inspect the LWP/Protocol/file.pm and LWP/Protocol/http.pm files for
       examples of usage.

METHODS AND FUNCTIONS
       $prot = new HTTP::Protocol;

       The LWP::Protocol constructor is inherited by subclasses. As this is a
       virtual base class this method should not be called directly.

       $prot = LWP::Protocol::create($url)

       Create an object of the class implementing the protocol to handle the
       given scheme. This is a function, not a method. It is more an object
       factory than a constructor. This is the function user agents should use
       to access protocols.

       $class = LWP::Protocol::implementor($scheme, [$class])

       Get and/or set implementor class for a scheme.  Returns '' if the
       specified scheme is not supported.

       $prot->request(...)

        $response = $protocol->request($request, $proxy, undef);
        $response = $protocol->request($request, $proxy, '/tmp/sss');
        $response = $protocol->request($request, $proxy, \&callback, 1024);

       Dispactches a request over the protocol, and returns a response object.
       This method needs to be overridden in subclasses.  Referer to the
       LWP::UserAgent manpage for description of the arguments.

       $prot->timeout($seconds)

       Get and set the timeout value in seconds

       $prot->use_alarm($yesno)

       Indicates if the library is allowed to use the core alarm() function to
       implement timeouts.

       $prot->parse_head($yesno)

       Should we initialize response headers from the <head> section of HTML
       documents.

       $prot->collect($arg, $response, $collector)

       Called to collect the content of a request, and process it
       appropriately into a scalar, file, or by calling a callback.  If $arg
       is undefined, then the content is stored within the $response.  If $arg
       is a simple scalar, then $arg is interpreted as a file name and the
       content is written to this file.  If $arg is a reference to a routine,
       then content is passed to this routine.

       The $collector is a routine that will be called and which is reponsible
       for returning pieces (as ref to scalar) of the content to process.  The
       $collector signals EOF by returning a reference to an empty sting.

       The return value from collect() is the $response object reference.

       Note: We will only use the callback or file argument if
       $response->is_success().  This avoids sendig content data for redirects
       and authentization responses to the callback which would be confusing.

       $prot->collect_once($arg, $response, $content)

       Can be called when the whole response content is available as $content.
       This will invoke collect() with a collector callback that returns a
       reference to $content the first time and an empty string the next.




3rd Berkeley Distribution    perl 5.003, patch 07        LIB::LWP::PROTOCOL(1)