1HTTP::Lite(3) User Contributed Perl Documentation HTTP::Lite(3)
2
6 HTTP::Lite - Lightweight HTTP implementation
7
9 use HTTP::Lite;
10 $http = new HTTP::Lite;
11 $req = $http->request("http://www.cpan.org/")
12 or die "Unable to get document: $!";
13 print $http->body();
14
16 HTTP::Lite is a stand-alone lightweight HTTP/1.1 implementation
17 for perl. It is not intended as a replacement for the
18 fully-features LWP module. Instead, it is intended for use in
19 situations where it is desirable to install the minimal number of
20 modules to achieve HTTP support, or where LWP is not a good
21 candidate due to CPU overhead, such as slower processors.
22 HTTP::Lite is also significantly faster than LWP.
23 HTTP::Lite is ideal for CGI (or mod_perl) programs or for bundling
25 for redistribution with larger packages where only HTTP GET and
26 POST functionality are necessary.
27 HTTP::Lite supports basic POST and GET operations only. As of
29 0.2.1, HTTP::Lite supports HTTP/1.1 and is compliant with the Host
30 header, necessary for name based virtual hosting. Additionally,
31 HTTP::Lite now supports Proxies.
32 As of 2.0.0 HTTP::Lite now supports a callback to allow processing
34 of request data as it arrives. This is useful for handling very
35 large files without consuming memory.
36 If you require more functionality, such as FTP or HTTPS, please
38 see libwwwperl (LWP). LWP is a significantly better and more
39 comprehensive package than HTTP::Lite, and should be used instead
40 of HTTP::Lite whenever possible.
41
43 new This is the constructor for HTTP::Lite. It presently takes no
44 arguments. A future version of HTTP::Lite might accept parameters.
45
47 request ( $url, $data_callback, $cbargs )
48 Initiates a request to the specified URL.
49 Returns undef if an I/O error is encountered, otherwise the HTTP
51 status code will be returned. 200 series status codes represent
52 success, 300 represent temporary errors, 400 represent permanent
53 errors, and 500 represent server errors.
54 See http://www.w3.org/Protocols/HTTP/HTRESP.html for detailled
56 information about HTTP status codes.
57 The $data_callback parameter, if used, is a way to filter the data
59 as it is received or to handle large transfers. It must be a
60 function reference, and will be passed: a reference to the instance
61 of the http request making the callback, a reference to the current
62 block of data about to be added to the body, and the $cbargs
63 parameter (which may be anything). It must return either a
64 reference to the data to add to the body of the document, or undef.
65 If set_callback is used, $data_callback and $cbargs are not used.
67 $cbargs may be either a scalar or a reference.
68 The data_callback is called as:
70 &$data_callback( $self, $dataref, $cbargs )
71 An example use to save a document to file is:
73 # Write the data to the filehandle $cbargs
75 sub savetofile {
76 my ($self,$phase,$dataref,$cbargs) = @_;
77 print $cbargs $$dataref;
78 return undef;
79 }
80 $url = "$testpath/bigbinary.dat";
82 open OUT, ">bigbinary.dat";
83 $res = $http->request($url, \&savetofile, OUT);
84 close OUT;
85 set_callback ( $functionref, $dataref )
87 At various stages of the request, callbacks may be used to modify
88 the behaviour or to monitor the status of the request. These work
89 like the $data_callback parameter to request(), but are more
90 verstaile. Using set_callback disables $data_callback in request()
91 The callbacks are called as:
93 callback ( $self, $phase, $dataref, $cbargs )
94 The current phases are:
96 connect - connection has been established and headers are being
98 transmitted.
99 content-length - return value is used as the content-length. If undef,
101 and prepare_post() was used, the content length is
102 calculated.
103 done-headers - all headers have been sent
105 content - return value is used as content and is sent to client. Return
107 undef to use the internal content defined by prepare_post().
108 content-done - content has been successfuly transmitted.
110 data - A block of data has been received. The data is referenced by
112 $dataref. The return value is dereferenced and replaces the
113 content passed in. Return undef to avoid using memory for large
114 documents.
115 done - Request is done.
117 prepare_post ( $hashref )
119 Takes a reference to a hashed array of post form variables to
120 upload. Create the HTTP body and sets the method to POST.
121 http11_mode ( 0 | 1 )
123 Turns on or off HTTP/1.1 support. This is off by default due to
124 broken HTTP/1.1 servers. Use 1 to enable HTTP/1.1 support.
125 add_req_header ( $header, $value )
127 get_req_header ( $header )
128 delete_req_header ( $header )
129 Add, Delete, or a HTTP header(s) for the request. These functions
130 allow you to override any header. Presently, Host, User-Agent,
131 Content-Type, Accept, and Connection are pre-defined by the
132 HTTP::Lite module. You may not override Host, Connection, or
133 Accept.
134 To provide (proxy) authentication or authorization, you would use:
136 use HTTP::Lite;
138 use MIME::Base64;
139 $http = new HTTP::Lite;
140 $encoded = encode_base64('username:password');
141 $http->add_req_header("Authorization", $encoded);
142 NOTE: The present implementation limits you to one instance of each
144 header.
145 body
147 Returns the body of the document retured by the remote server.
148 headers_array
150 Returns an array of the HTTP headers returned by the remote server.
151 headers_string
153 Returns a string representation of the HTTP headers returned by the
154 remote server.
155 get_header ( $header )
157 Returns an array of values for the requested header.
158 NOTE: HTTP requests are not limited to a single instance of each
160 header. As a result, there may be more than one entry for every
161 header.
162 protocol
164 Returns the HTTP protocol identifier, as reported by the remote
165 server. This will generally be either HTTP/1.0 or HTTP/1.1.
166 proxy ( $proxy_server )
168 The URL or hostname of the proxy to use for the next request.
169 status
171 Returns the HTTP status code returned by the server. This is also
172 reported as the return value of request().
173 status_message
175 Returns the textual description of the status code as returned by
176 the server. The status string is not required to adhere to any
177 particular format, although most HTTP servers use a standard set of
178 descriptions.
179 reset
181 You must call this prior to re-using an HTTP::Lite handle,
182 otherwise the results are undefined.
183 local_addr ( $ip )
185 Explicity select the local IP address. 0.0.0.0 (default) lets the
186 system choose.
187 local_port ( $port )
189 Explicity select the local port. 0 (default and reccomended) lets
190 the system choose.
191 method ( $method )
193 Explicity set the method. Using prepare_post or reset overrides
194 this setting. Usual choices are GET, POST, PUT, HEAD
195
197 # Get and print out the headers and body of the CPAN homepage
198 use HTTP::Lite;
199 $http = new HTTP::Lite;
200 $req = $http->request("http://www.cpan.org/")
201 or die "Unable to get document: $!";
202 die "Request failed ($req): ".$http->status_message()
203 if $req ne "200";
204 @headers = $http->headers_array();
205 $body = $http->body();
206 foreach $header (@headers)
207 {
208 print "$header$CRLF";
209 }
210 print "$CRLF";
211 print "$body$CRLF";
212 # POST a query to the dejanews USENET search engine
214 use HTTP::Lite;
215 $http = new HTTP::Lite;
216 %vars = (
217 "QRY" => "perl",
218 "ST" => "MS",
219 "svcclass" => "dncurrent",
220 "DBS" => "2"
221 );
222 $http->prepare_post(\%vars);
223 $req = $http->request("http://www.deja.com/dnquery.xp")
224 or die "Unable to get document: $!";
225 print "req: $req\n";
226 print $http->body();
227
229 - FTP
230 - HTTPS (SSL)
231 - Authenitcation/Authorizaton/Proxy-Authorization
232 are not directly supported, and require MIME::Base64.
233 - Redirects (Location) are not automatically followed
234 - multipart/form-data POSTs are not directly supported (necessary
235 for File uploads).
236
238 Some broken HTTP/1.1 servers send incorrect chunk sizes
239 when transferring files. HTTP/1.1 mode is now disabled by
240 default.
241
243 Roy Hooper <rhooper@thetoybox.org>
244
246 LWP RFC 2068 - HTTP/1.1 -http://www.w3.org/
247
249 Copyright (c) 2000-2002 Roy Hooper. All rights reserved.
250 Some parts copyright 2009 Adam Kennedy.
252 This program is free software; you can redistribute it and/or modify it
254 under the same terms as Perl itself.
255perl v5.12.0 2009-10-01 HTTP::Lite(3)