1HTTP::Request::Common(3U)ser Contributed Perl DocumentatiHoTnTP::Request::Common(3)
2
6 HTTP::Request::Common - Construct common HTTP::Request objects
7
9 use HTTP::Request::Common;
10 $ua = LWP::UserAgent->new;
11 $ua->request(GET 'http://www.sn.no/');
12 $ua->request(POST 'http://somewhere/foo', [foo => bar, bar => foo]);
13
15 This module provide functions that return newly created "HTTP::Request"
16 objects. These functions are usually more convenient to use than the
17 standard "HTTP::Request" constructor for the most common requests. The
18 following functions are provided:
19 GET $url
21 GET $url, Header => Value,...
22 The GET() function returns an "HTTP::Request" object initialized
23 with the "GET" method and the specified URL. It is roughly equiva‐
24 lent to the following call
25 HTTP::Request->new(
27 GET => $url,
28 HTTP::Headers->new(Header => Value,...),
29 )
30 but is less cluttered. What is different is that a header named
32 "Content" will initialize the content part of the request instead
33 of setting a header field. Note that GET requests should normally
34 not have a content, so this hack makes more sense for the PUT() and
35 POST() functions described below.
36 The get(...) method of "LWP::UserAgent" exists as a shortcut for
38 $ua->request(GET ...).
39 HEAD $url
41 HEAD $url, Header => Value,...
42 Like GET() but the method in the request is "HEAD".
43 The head(...) method of "LWP::UserAgent" exists as a shortcut for
45 $ua->request(HEAD ...).
46 PUT $url
48 PUT $url, Header => Value,...
49 PUT $url, Header => Value,..., Content => $content
50 Like GET() but the method in the request is "PUT".
51 POST $url
53 POST $url, Header => Value,...
54 POST $url, $form_ref, Header => Value,...
55 POST $url, Header => Value,..., Content => $form_ref
56 This works mostly like GET() with "POST" as the method, but this
57 function also takes a second optional array or hash reference
58 parameter ($form_ref). This argument can be used to pass key/value
59 pairs for the form content. By default we will initialize a
60 request using the "application/x-www-form-urlencoded" content type.
61 This means that you can emulate a HTML <form> POSTing like this:
62 POST 'http://www.perl.org/survey.cgi',
64 [ name => 'Gisle Aas',
65 email => 'gisle@aas.no',
66 gender => 'M',
67 born => '1964',
68 perc => '3%',
69 ];
70 This will create a HTTP::Request object that looks like this:
72 POST http://www.perl.org/survey.cgi
74 Content-Length: 66
75 Content-Type: application/x-www-form-urlencoded
76 name=Gisle%20Aas&email=gisle%40aas.no&gender=M&born=1964&perc=3%25
78 Multivalued form fields can be specified by either repeating the
80 field name or by passing the value as an array reference.
81 The POST method also supports the "multipart/form-data" content
83 used for Form-based File Upload as specified in RFC 1867. You
84 trigger this content format by specifying a content type of
85 'form-data' as one of the request headers. If one of the values in
86 the $form_ref is an array reference, then it is treated as a file
87 part specification with the following interpretation:
88 [ $file, $filename, Header => Value... ]
90 [ undef, $filename, Header => Value,..., Content => $content ]
91 The first value in the array ($file) is the name of a file to open.
93 This file will be read and its content placed in the request. The
94 routine will croak if the file can't be opened. Use an "undef" as
95 $file value if you want to specify the content directly with a
96 "Content" header. The $filename is the filename to report in the
97 request. If this value is undefined, then the basename of the
98 $file will be used. You can specify an empty string as $filename
99 if you want to suppress sending the filename when you provide a
100 $file value.
101 If a $file is provided by no "Content-Type" header, then "Con‐
103 tent-Type" and "Content-Encoding" will be filled in automatically
104 with the values returned by LWP::MediaTypes::guess_media_type()
105 Sending my ~/.profile to the survey used as example above can be
107 achieved by this:
108 POST 'http://www.perl.org/survey.cgi',
110 Content_Type => 'form-data',
111 Content => [ name => 'Gisle Aas',
112 email => 'gisle@aas.no',
113 gender => 'M',
114 born => '1964',
115 init => ["$ENV{HOME}/.profile"],
116 ]
117 This will create a HTTP::Request object that almost looks this (the
119 boundary and the content of your ~/.profile is likely to be differ‐
120 ent):
121 POST http://www.perl.org/survey.cgi
123 Content-Length: 388
124 Content-Type: multipart/form-data; boundary="6G+f"
125 --6G+f
127 Content-Disposition: form-data; name="name"
128 Gisle Aas
130 --6G+f
131 Content-Disposition: form-data; name="email"
132 gisle@aas.no
134 --6G+f
135 Content-Disposition: form-data; name="gender"
136 M
138 --6G+f
139 Content-Disposition: form-data; name="born"
140 1964
142 --6G+f
143 Content-Disposition: form-data; name="init"; filename=".profile"
144 Content-Type: text/plain
145 PATH=/local/perl/bin:$PATH
147 export PATH
148 --6G+f--
150 If you set the $DYNAMIC_FILE_UPLOAD variable (exportable) to some
152 TRUE value, then you get back a request object with a subroutine
153 closure as the content attribute. This subroutine will read the
154 content of any files on demand and return it in suitable chunks.
155 This allow you to upload arbitrary big files without using lots of
156 memory. You can even upload infinite files like /dev/audio if you
157 wish; however, if the file is not a plain file, there will be no
158 Content-Length header defined for the request. Not all servers (or
159 server applications) like this. Also, if the file(s) change in
160 size between the time the Content-Length is calculated and the time
161 that the last chunk is delivered, the subroutine will "Croak".
162 The post(...) method of "LWP::UserAgent" exists as a shortcut for
164 $ua->request(POST ...).
165
167 HTTP::Request, LWP::UserAgent
168
170 Copyright 1997-2004, Gisle Aas
171 This library is free software; you can redistribute it and/or modify it
173 under the same terms as Perl itself.
174perl v5.8.8 2004-04-06 HTTP::Request::Common(3)