1LWP::Protocol(3)      User Contributed Perl Documentation     LWP::Protocol(3)
2
3
4

NAME

6       LWP::Protocol - Base class for LWP protocols
7

SYNOPSIS

9        package LWP::Protocol::foo;
10        require LWP::Protocol;
11        @ISA=qw(LWP::Protocol);
12

DESCRIPTION

14       This class is used a the base class for all protocol implementations
15       supported by the LWP library.
16
17       When creating an instance of this class using "LWP::Protocol::cre‐
18       ate($url)", and you get an initialised subclass appropriate for that
19       access method. In other words, the LWP::Protocol::create() function
20       calls the constructor for one of its subclasses.
21
22       All derived LWP::Protocol classes need to override the request() method
23       which is used to service a request. The overridden method can make use
24       of the collect() function to collect together chunks of data as it is
25       received.
26
27       The following methods and functions are provided:
28
29       $prot = LWP::Protocol->new()
30           The LWP::Protocol constructor is inherited by subclasses. As this
31           is a virtual base class this method should not be called directly.
32
33       $prot = LWP::Protocol::create($scheme)
34           Create an object of the class implementing the protocol to handle
35           the given scheme. This is a function, not a method. It is more an
36           object factory than a constructor. This is the function user agents
37           should use to access protocols.
38
39       $class = LWP::Protocol::implementor($scheme, [$class])
40           Get and/or set implementor class for a scheme.  Returns '' if the
41           specified scheme is not supported.
42
43       $prot->request(...)
44            $response = $protocol->request($request, $proxy, undef);
45            $response = $protocol->request($request, $proxy, '/tmp/sss');
46            $response = $protocol->request($request, $proxy, \&callback, 1024);
47
48           Dispatches a request over the protocol, and returns a response
49           object. This method needs to be overridden in subclasses.  Refer to
50           LWP::UserAgent for description of the arguments.
51
52       $prot->collect($arg, $response, $collector)
53           Called to collect the content of a request, and process it appro‐
54           priately into a scalar, file, or by calling a callback.  If $arg is
55           undefined, then the content is stored within the $response.  If
56           $arg is a simple scalar, then $arg is interpreted as a file name
57           and the content is written to this file.  If $arg is a reference to
58           a routine, then content is passed to this routine.
59
60           The $collector is a routine that will be called and which is
61           responsible for returning pieces (as ref to scalar) of the content
62           to process.  The $collector signals EOF by returning a reference to
63           an empty sting.
64
65           The return value from collect() is the $response object reference.
66
67           Note: We will only use the callback or file argument if
68           $response->is_success().  This avoids sending content data for
69           redirects and authentication responses to the callback which would
70           be confusing.
71
72       $prot->collect_once($arg, $response, $content)
73           Can be called when the whole response content is available as $con‐
74           tent.  This will invoke collect() with a collector callback that
75           returns a reference to $content the first time and an empty string
76           the next.
77

SEE ALSO

79       Inspect the LWP/Protocol/file.pm and LWP/Protocol/http.pm files for
80       examples of usage.
81

83       Copyright 1995-2001 Gisle Aas.
84
85       This library is free software; you can redistribute it and/or modify it
86       under the same terms as Perl itself.
87
88
89
90perl v5.8.8                       2004-04-06                  LWP::Protocol(3)
Impressum