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