local-lib5/man/man3/LWP::Protocol.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "LWP::Protocol 3"
 132 .TH LWP::Protocol 3 "2009-07-07" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 LWP::Protocol \- Base class for LWP protocols
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 3
 138 \& package LWP::Protocol::foo;
 139 \& require LWP::Protocol;
 140 \& @ISA=qw(LWP::Protocol);
 141 .Ve
 142 .SH "DESCRIPTION"
 143 .IX Header "DESCRIPTION"
 144 This class is used a the base class for all protocol implementations
 145 supported by the \s-1LWP\s0 library.
 146 .PP
 147 When creating an instance of this class using
 148 \&\f(CW\*(C`LWP::Protocol::create($url)\*(C'\fR, and you get an initialised subclass
 149 appropriate for that access method. In other words, the
 150 \&\fILWP::Protocol::create()\fR function calls the constructor for one of its
 151 subclasses.
 152 .PP
 153 All derived LWP::Protocol classes need to override the \fIrequest()\fR
 154 method which is used to service a request. The overridden method can
 155 make use of the \fIcollect()\fR function to collect together chunks of data
 156 as it is received.
 157 .PP
 158 The following methods and functions are provided:
 159 .IP "$prot = LWP::Protocol\->\fInew()\fR" 4
 160 .IX Item "$prot = LWP::Protocol->new()"
 161 The LWP::Protocol constructor is inherited by subclasses. As this is a
 162 virtual base class this method should \fBnot\fR be called directly.
 163 .IP "$prot = LWP::Protocol::create($scheme)" 4
 164 .IX Item "$prot = LWP::Protocol::create($scheme)"
 165 Create an object of the class implementing the protocol to handle the
 166 given scheme. This is a function, not a method. It is more an object
 167 factory than a constructor. This is the function user agents should
 168 use to access protocols.
 169 .IP "$class = LWP::Protocol::implementor($scheme, [$class])" 4
 170 .IX Item "$class = LWP::Protocol::implementor($scheme, [$class])"
 171 Get and/or set implementor class for a scheme.  Returns '' if the
 172 specified scheme is not supported.
 173 .IP "$prot\->request(...)" 4
 174 .IX Item "$prot->request(...)"
 175 .Vb 3
 176 \& $response = $protocol\->request($request, $proxy, undef);
 177 \& $response = $protocol\->request($request, $proxy, '/tmp/sss');
 178 \& $response = $protocol\->request($request, $proxy, \e&callback, 1024);
 179 .Ve
 180 .Sp
 181 Dispatches a request over the protocol, and returns a response
 182 object. This method needs to be overridden in subclasses.  Refer to
 183 LWP::UserAgent for description of the arguments.
 184 .ie n .IP "$prot\->collect($arg, $response\fR, \f(CW$collector)" 4
 185 .el .IP "$prot\->collect($arg, \f(CW$response\fR, \f(CW$collector\fR)" 4
 186 .IX Item "$prot->collect($arg, $response, $collector)"
 187 Called to collect the content of a request, and process it
 188 appropriately into a scalar, file, or by calling a callback.  If \f(CW$arg\fR
 189 is undefined, then the content is stored within the \f(CW$response\fR.  If
 190 \&\f(CW$arg\fR is a simple scalar, then \f(CW$arg\fR is interpreted as a file name and
 191 the content is written to this file.  If \f(CW$arg\fR is a reference to a
 192 routine, then content is passed to this routine.
 193 .Sp
 194 The \f(CW$collector\fR is a routine that will be called and which is
 195 responsible for returning pieces (as ref to scalar) of the content to
 196 process.  The \f(CW$collector\fR signals \s-1EOF\s0 by returning a reference to an
 197 empty sting.
 198 .Sp
 199 The return value from \fIcollect()\fR is the \f(CW$response\fR object reference.
 200 .Sp
 201 \&\fBNote:\fR We will only use the callback or file argument if
 202 \&\f(CW$response\fR\->\fIis_success()\fR.  This avoids sending content data for
 203 redirects and authentication responses to the callback which would be
 204 confusing.
 205 .ie n .IP "$prot\->collect_once($arg, $response\fR, \f(CW$content)" 4
 206 .el .IP "$prot\->collect_once($arg, \f(CW$response\fR, \f(CW$content\fR)" 4
 207 .IX Item "$prot->collect_once($arg, $response, $content)"
 208 Can be called when the whole response content is available as
 209 \&\f(CW$content\fR.  This will invoke \fIcollect()\fR with a collector callback that
 210 returns a reference to \f(CW$content\fR the first time and an empty string the
 211 next.
 212 .SH "SEE ALSO"
 213 .IX Header "SEE ALSO"
 214 Inspect the \fILWP/Protocol/file.pm\fR and \fILWP/Protocol/http.pm\fR files
 215 for examples of usage.
 216 .SH "COPYRIGHT"
 217 .IX Header "COPYRIGHT"
 218 Copyright 1995\-2001 Gisle Aas.
 219 .PP
 220 This library is free software; you can redistribute it and/or
 221 modify it under the same terms as Perl itself.