local-lib5/man/man3/HTTP::Request::Common.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 "HTTP::Request::Common 3"
 132 .TH HTTP::Request::Common 3 "2009-06-15" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 HTTP::Request::Common \- Construct common HTTP::Request objects
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 4
 138 \&  use HTTP::Request::Common;
 139 \&  $ua = LWP::UserAgent\->new;
 140 \&  $ua\->request(GET 'http://www.sn.no/');
 141 \&  $ua\->request(POST 'http://somewhere/foo', [foo => bar, bar => foo]);
 142 .Ve
 143 .SH "DESCRIPTION"
 144 .IX Header "DESCRIPTION"
 145 This module provide functions that return newly created \f(CW\*(C`HTTP::Request\*(C'\fR
 146 objects.  These functions are usually more convenient to use than the
 147 standard \f(CW\*(C`HTTP::Request\*(C'\fR constructor for the most common requests.  The
 148 following functions are provided:
 149 .ie n .IP "\s-1GET\s0 $url" 4
 150 .el .IP "\s-1GET\s0 \f(CW$url\fR" 4
 151 .IX Item "GET $url"
 152 .PD 0
 153 .ie n .IP "\s-1GET\s0 $url, Header => Value,..." 4
 154 .el .IP "\s-1GET\s0 \f(CW$url\fR, Header => Value,..." 4
 155 .IX Item "GET $url, Header => Value,..."
 156 .PD
 157 The \s-1\fIGET\s0()\fR function returns an \f(CW\*(C`HTTP::Request\*(C'\fR object initialized with
 158 the \*(L"\s-1GET\s0\*(R" method and the specified \s-1URL\s0.  It is roughly equivalent to the
 159 following call
 160 .Sp
 161 .Vb 4
 162 \&  HTTP::Request\->new(
 163 \&     GET => $url,
 164 \&     HTTP::Headers\->new(Header => Value,...),
 165 \&  )
 166 .Ve
 167 .Sp
 168 but is less cluttered.  What is different is that a header named
 169 \&\f(CW\*(C`Content\*(C'\fR will initialize the content part of the request instead of
 170 setting a header field.  Note that \s-1GET\s0 requests should normally not
 171 have a content, so this hack makes more sense for the \s-1\fIPUT\s0()\fR and \s-1\fIPOST\s0()\fR
 172 functions described below.
 173 .Sp
 174 The get(...) method of \f(CW\*(C`LWP::UserAgent\*(C'\fR exists as a shortcut for
 175 \&\f(CW$ua\fR\->request(\s-1GET\s0 ...).
 176 .ie n .IP "\s-1HEAD\s0 $url" 4
 177 .el .IP "\s-1HEAD\s0 \f(CW$url\fR" 4
 178 .IX Item "HEAD $url"
 179 .PD 0
 180 .ie n .IP "\s-1HEAD\s0 $url, Header => Value,..." 4
 181 .el .IP "\s-1HEAD\s0 \f(CW$url\fR, Header => Value,..." 4
 182 .IX Item "HEAD $url, Header => Value,..."
 183 .PD
 184 Like \s-1\fIGET\s0()\fR but the method in the request is \*(L"\s-1HEAD\s0\*(R".
 185 .Sp
 186 The head(...)  method of \*(L"LWP::UserAgent\*(R" exists as a shortcut for
 187 \&\f(CW$ua\fR\->request(\s-1HEAD\s0 ...).
 188 .ie n .IP "\s-1PUT\s0 $url" 4
 189 .el .IP "\s-1PUT\s0 \f(CW$url\fR" 4
 190 .IX Item "PUT $url"
 191 .PD 0
 192 .ie n .IP "\s-1PUT\s0 $url, Header => Value,..." 4
 193 .el .IP "\s-1PUT\s0 \f(CW$url\fR, Header => Value,..." 4
 194 .IX Item "PUT $url, Header => Value,..."
 195 .ie n .IP "\s-1PUT\s0 $url\fR, Header => Value,..., Content => \f(CW$content" 4
 196 .el .IP "\s-1PUT\s0 \f(CW$url\fR, Header => Value,..., Content => \f(CW$content\fR" 4
 197 .IX Item "PUT $url, Header => Value,..., Content => $content"
 198 .PD
 199 Like \s-1\fIGET\s0()\fR but the method in the request is \*(L"\s-1PUT\s0\*(R".
 200 .Sp
 201 The content of the request can be specified using the \*(L"Content\*(R"
 202 pseudo\-header.  This steals a bit of the header field namespace as
 203 there is no way to directly specify a header that is actually called
 204 \&\*(L"Content\*(R".  If you really need this you must update the request
 205 returned in a separate statement.
 206 .ie n .IP "\s-1DELETE\s0 $url" 4
 207 .el .IP "\s-1DELETE\s0 \f(CW$url\fR" 4
 208 .IX Item "DELETE $url"
 209 .PD 0
 210 .ie n .IP "\s-1DELETE\s0 $url, Header => Value,..." 4
 211 .el .IP "\s-1DELETE\s0 \f(CW$url\fR, Header => Value,..." 4
 212 .IX Item "DELETE $url, Header => Value,..."
 213 .PD
 214 Like \s-1\fIGET\s0()\fR but the method in the request is \*(L"\s-1DELETE\s0\*(R".  This function
 215 is not exported by default.
 216 .ie n .IP "\s-1POST\s0 $url" 4
 217 .el .IP "\s-1POST\s0 \f(CW$url\fR" 4
 218 .IX Item "POST $url"
 219 .PD 0
 220 .ie n .IP "\s-1POST\s0 $url, Header => Value,..." 4
 221 .el .IP "\s-1POST\s0 \f(CW$url\fR, Header => Value,..." 4
 222 .IX Item "POST $url, Header => Value,..."
 223 .ie n .IP "\s-1POST\s0 $url\fR, \f(CW$form_ref, Header => Value,..." 4
 224 .el .IP "\s-1POST\s0 \f(CW$url\fR, \f(CW$form_ref\fR, Header => Value,..." 4
 225 .IX Item "POST $url, $form_ref, Header => Value,..."
 226 .ie n .IP "\s-1POST\s0 $url\fR, Header => Value,..., Content => \f(CW$form_ref" 4
 227 .el .IP "\s-1POST\s0 \f(CW$url\fR, Header => Value,..., Content => \f(CW$form_ref\fR" 4
 228 .IX Item "POST $url, Header => Value,..., Content => $form_ref"
 229 .ie n .IP "\s-1POST\s0 $url\fR, Header => Value,..., Content => \f(CW$content" 4
 230 .el .IP "\s-1POST\s0 \f(CW$url\fR, Header => Value,..., Content => \f(CW$content\fR" 4
 231 .IX Item "POST $url, Header => Value,..., Content => $content"
 232 .PD
 233 This works mostly like \s-1\fIPUT\s0()\fR with \*(L"\s-1POST\s0\*(R" as the method, but this
 234 function also takes a second optional array or hash reference
 235 parameter \f(CW$form_ref\fR.  As for \s-1\fIPUT\s0()\fR the content can also be specified
 236 directly using the \*(L"Content\*(R" pseudo\-header, and you may also provide
 237 the \f(CW$form_ref\fR this way.
 238 .Sp
 239 The \f(CW$form_ref\fR argument can be used to pass key/value pairs for the
 240 form content.  By default we will initialize a request using the
 241 \&\f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR content type.  This means that
 242 you can emulate a \s-1HTML\s0 <form> POSTing like this:
 243 .Sp
 244 .Vb 7
 245 \&  POST 'http://www.perl.org/survey.cgi',
 246 \&       [ name   => 'Gisle Aas',
 247 \&         email  => 'gisle@aas.no',
 248 \&         gender => 'M',
 249 \&         born   => '1964',
 250 \&         perc   => '3%',
 251 \&       ];
 252 .Ve
 253 .Sp
 254 This will create a HTTP::Request object that looks like this:
 255 .Sp
 256 .Vb 3
 257 \&  POST http://www.perl.org/survey.cgi
 258 \&  Content\-Length: 66
 259 \&  Content\-Type: application/x\-www\-form\-urlencoded
 260 .Ve
 261 .Sp
 262 .Vb 1
 263 \&  name=Gisle%20Aas&email=gisle%40aas.no&gender=M&born=1964&perc=3%25
 264 .Ve
 265 .Sp
 266 Multivalued form fields can be specified by either repeating the field
 267 name or by passing the value as an array reference.
 268 .Sp
 269 The \s-1POST\s0 method also supports the \f(CW\*(C`multipart/form\-data\*(C'\fR content used
 270 for \fIForm-based File Upload\fR as specified in \s-1RFC\s0 1867.  You trigger
 271 this content format by specifying a content type of \f(CW'form\-data'\fR as
 272 one of the request headers.  If one of the values in the \f(CW$form_ref\fR is
 273 an array reference, then it is treated as a file part specification
 274 with the following interpretation:
 275 .Sp
 276 .Vb 2
 277 \&  [ $file, $filename, Header => Value... ]
 278 \&  [ undef, $filename, Header => Value,..., Content => $content ]
 279 .Ve
 280 .Sp
 281 The first value in the array ($file) is the name of a file to open.
 282 This file will be read and its content placed in the request.  The
 283 routine will croak if the file can't be opened.  Use an \f(CW\*(C`undef\*(C'\fR as
 284 \&\f(CW$file\fR value if you want to specify the content directly with a
 285 \&\f(CW\*(C`Content\*(C'\fR header.  The \f(CW$filename\fR is the filename to report in the
 286 request.  If this value is undefined, then the basename of the \f(CW$file\fR
 287 will be used.  You can specify an empty string as \f(CW$filename\fR if you
 288 want to suppress sending the filename when you provide a \f(CW$file\fR value.
 289 .Sp
 290 If a \f(CW$file\fR is provided by no \f(CW\*(C`Content\-Type\*(C'\fR header, then \f(CW\*(C`Content\-Type\*(C'\fR
 291 and \f(CW\*(C`Content\-Encoding\*(C'\fR will be filled in automatically with the values
 292 returned by \fILWP::MediaTypes::guess_media_type()\fR
 293 .Sp
 294 Sending my \fI~/.profile\fR to the survey used as example above can be
 295 achieved by this:
 296 .Sp
 297 .Vb 8
 298 \&  POST 'http://www.perl.org/survey.cgi',
 299 \&       Content_Type => 'form\-data',
 300 \&       Content      => [ name  => 'Gisle Aas',
 301 \&                         email => 'gisle@aas.no',
 302 \&                         gender => 'M',
 303 \&                         born   => '1964',
 304 \&                         init   => ["$ENV{HOME}/.profile"],
 305 \&                       ]
 306 .Ve
 307 .Sp
 308 This will create a HTTP::Request object that almost looks this (the
 309 boundary and the content of your \fI~/.profile\fR is likely to be
 310 different):
 311 .Sp
 312 .Vb 3
 313 \&  POST http://www.perl.org/survey.cgi
 314 \&  Content\-Length: 388
 315 \&  Content\-Type: multipart/form\-data; boundary="6G+f"
 316 .Ve
 317 .Sp
 318 .Vb 2
 319 \&  \-\-6G+f
 320 \&  Content\-Disposition: form\-data; name="name"
 321 .Ve
 322 .Sp
 323 .Vb 3
 324 \&  Gisle Aas
 325 \&  \-\-6G+f
 326 \&  Content\-Disposition: form\-data; name="email"
 327 .Ve
 328 .Sp
 329 .Vb 3
 330 \&  gisle@aas.no
 331 \&  \-\-6G+f
 332 \&  Content\-Disposition: form\-data; name="gender"
 333 .Ve
 334 .Sp
 335 .Vb 3
 336 \&  M
 337 \&  \-\-6G+f
 338 \&  Content\-Disposition: form\-data; name="born"
 339 .Ve
 340 .Sp
 341 .Vb 4
 342 \&  1964
 343 \&  \-\-6G+f
 344 \&  Content\-Disposition: form\-data; name="init"; filename=".profile"
 345 \&  Content\-Type: text/plain
 346 .Ve
 347 .Sp
 348 .Vb 2
 349 \&  PATH=/local/perl/bin:$PATH
 350 \&  export PATH
 351 .Ve
 352 .Sp
 353 .Vb 1
 354 \&  \-\-6G+f\-\-
 355 .Ve
 356 .Sp
 357 If you set the \f(CW$DYNAMIC_FILE_UPLOAD\fR variable (exportable) to some \s-1TRUE\s0
 358 value, then you get back a request object with a subroutine closure as
 359 the content attribute.  This subroutine will read the content of any
 360 files on demand and return it in suitable chunks.  This allow you to
 361 upload arbitrary big files without using lots of memory.  You can even
 362 upload infinite files like \fI/dev/audio\fR if you wish; however, if
 363 the file is not a plain file, there will be no Content-Length header
 364 defined for the request.  Not all servers (or server
 365 applications) like this.  Also, if the file(s) change in size between
 366 the time the Content-Length is calculated and the time that the last
 367 chunk is delivered, the subroutine will \f(CW\*(C`Croak\*(C'\fR.
 368 .Sp
 369 The post(...)  method of \*(L"LWP::UserAgent\*(R" exists as a shortcut for
 370 \&\f(CW$ua\fR\->request(\s-1POST\s0 ...).
 371 .SH "SEE ALSO"
 372 .IX Header "SEE ALSO"
 373 HTTP::Request, LWP::UserAgent
 374 .SH "COPYRIGHT"
 375 .IX Header "COPYRIGHT"
 376 Copyright 1997\-2004, Gisle Aas
 377 .PP
 378 This library is free software; you can redistribute it and/or
 379 modify it under the same terms as Perl itself.