1HTTP::Lite(3)         User Contributed Perl Documentation        HTTP::Lite(3)
2
3
4

NAME

6       HTTP::Lite - Lightweight HTTP implementation
7

SYNOPSIS

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

DESCRIPTION

16       Note: you should look at HTTP::Tiny or LWP before using this module.
17
18       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
26       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
30       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
35       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
39       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

CONSTRUCTOR

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

METHODS

49       request ( $url, $data_callback, $cbargs )
50           Initiates a request to the specified URL.
51
52           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
57           See http://www.w3.org/Protocols/HTTP/HTRESP.html for detailed
58           information about HTTP status codes.
59
60           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
68           If set_callback is used, $data_callback and $cbargs are not used.
69           $cbargs may be either a scalar or a reference.
70
71           The data_callback is called as:
72             &$data_callback( $self, $dataref, $cbargs )
73
74           An example use to save a document to file is:
75
76             # 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
83             $url = "$testpath/bigbinary.dat";
84             open OUT, '>','bigbinary.dat';
85             $res = $http->request($url, \&savetofile, OUT);
86             close OUT;
87
88       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
94           The callbacks are called as:
95             callback ( $self, $phase, $dataref, $cbargs )
96
97           The current phases are:
98
99             connect - connection has been established and headers are being
100                       transmitted.
101
102             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
106             done-headers - all headers have been sent
107
108             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
111             content-done - content has been successfuly transmitted.
112
113             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
118             done - Request is done.
119
120       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
124       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
128       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
137           If you call add_req_header() with $value set to "undef", then the
138           header won't be added.
139
140           To provide (proxy) authentication or authorization, you would use:
141
142               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
148           NOTE: The present implementation limits you to one instance of each
149           header.
150
151       body
152           Returns the body of the document returned by the remote server.
153
154       headers_array
155           Returns an array of the HTTP headers returned by the remote server.
156
157       headers_string
158           Returns a string representation of the HTTP headers returned by the
159           remote server.
160
161       get_header ( $header )
162           Returns an array of values for the requested header.
163
164           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
168       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
172       proxy ( $proxy_server )
173           The URL or hostname of the proxy to use for the next request.
174
175       status
176           Returns the HTTP status code returned by the server.  This is also
177           reported as the return value of request().
178
179       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
185       reset
186           You must call this prior to re-using an HTTP::Lite handle,
187           otherwise the results are undefined.
188
189       local_addr ( $ip )
190           Explicity select the local IP address.  0.0.0.0 (default) lets the
191           system choose.
192
193       local_port ( $port )
194           Explicity select the local port.  0 (default and recommended) lets
195           the system choose.
196
197       method ( $method )
198           Explicity set the method.  Using prepare_post or reset overrides
199           this setting.  Usual choices are GET, POST, PUT, HEAD
200

EXAMPLES

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
218           # 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

UNIMPLEMENTED

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

BUGS

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

AUTHOR

247       Roy Hooper <rhooper@thetoybox.org>
248
249       Now co-maintained by Neil Bowers <neilb@cpan.org>.
250

SEE ALSO

252       This module (HTTP::Lite) is almost certainly not the best module for
253       your needs.
254
255       For most uses HTTP::Tiny is a good choice.  If you need more features,
256       then look at LWP.
257
258       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
264       Some parts copyright 2009 - 2010 Adam Kennedy.
265
266       This program is free software; you can redistribute it and/or modify it
267       under the same terms as Perl itself.
268
269
270
271perl v5.38.0                      2023-07-20                     HTTP::Lite(3)
Impressum