.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "HTTP::Lite 3pm" .TH HTTP::Lite 3pm "2022-10-13" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" HTTP::Lite \- Lightweight HTTP implementation .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 5 \& use HTTP::Lite; \& $http = HTTP::Lite\->new; \& $req = $http\->request("http://www.cpan.org/") \& or die "Unable to get document: $!"; \& print $http\->body(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBNote:\fR you should look at HTTP::Tiny or \s-1LWP\s0 before using this module. .PP HTTP::Lite is a stand-alone lightweight \s-1HTTP/1.1\s0 implementation for perl. It is not intended as a replacement for the fully-featured \s-1LWP\s0 module. Instead, it is intended for use in situations where it is desirable to install the minimal number of modules to achieve \s-1HTTP\s0 support, or where \s-1LWP\s0 is not a good candidate due to \s-1CPU\s0 overhead, such as slower processors. HTTP::Lite is also significantly faster than \s-1LWP.\s0 .PP HTTP::Lite is ideal for \s-1CGI\s0 (or mod_perl) programs or for bundling for redistribution with larger packages where only \s-1HTTP GET\s0 and \&\s-1POST\s0 functionality are necessary. .PP HTTP::Lite supports basic \s-1POST\s0 and \s-1GET\s0 operations only. As of 0.2.1, HTTP::Lite supports \s-1HTTP/1.1\s0 and is compliant with the Host header, necessary for name based virtual hosting. Additionally, HTTP::Lite now supports Proxies. .PP As of 2.0.0 HTTP::Lite now supports a callback to allow processing of request data as it arrives. This is useful for handling very large files without consuming memory. .PP If you require more functionality, such as \s-1FTP\s0 or \s-1HTTPS,\s0 please see libwwwperl (\s-1LWP\s0). \s-1LWP\s0 is a significantly better and more comprehensive package than HTTP::Lite, and should be used instead of HTTP::Lite whenever possible. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .IP "new" 4 .IX Item "new" This is the constructor for HTTP::Lite. It presently takes no arguments. A future version of HTTP::Lite might accept parameters. .SH "METHODS" .IX Header "METHODS" .ie n .IP "request ( $url, $data_callback, $cbargs )" 4 .el .IP "request ( \f(CW$url\fR, \f(CW$data_callback\fR, \f(CW$cbargs\fR )" 4 .IX Item "request ( $url, $data_callback, $cbargs )" Initiates a request to the specified \s-1URL.\s0 .Sp Returns undef if an I/O error is encountered, otherwise the \s-1HTTP\s0 status code will be returned. 200 series status codes represent success, 300 represent temporary errors, 400 represent permanent errors, and 500 represent server errors. .Sp See \fIhttp://www.w3.org/Protocols/HTTP/HTRESP.html\fR for detailed information about \s-1HTTP\s0 status codes. .Sp The \f(CW$data_callback\fR parameter, if used, is a way to filter the data as it is received or to handle large transfers. It must be a function reference, and will be passed: a reference to the instance of the http request making the callback, a reference to the current block of data about to be added to the body, and the \f(CW$cbargs\fR parameter (which may be anything). It must return either a reference to the data to add to the body of the document, or undef. .Sp If set_callback is used, \f(CW$data_callback\fR and \f(CW$cbargs\fR are not used. \f(CW$cbargs\fR may be either a scalar or a reference. .Sp The data_callback is called as: &$data_callback( \f(CW$self\fR, \f(CW$dataref\fR, \f(CW$cbargs\fR ) .Sp An example use to save a document to file is: .Sp .Vb 6 \& # Write the data to the filehandle $cbargs \& sub savetofile { \& my ($self,$phase,$dataref,$cbargs) = @_; \& print $cbargs $$dataref; \& return undef; \& } \& \& $url = "$testpath/bigbinary.dat"; \& open OUT, \*(Aq>\*(Aq,\*(Aqbigbinary.dat\*(Aq; \& $res = $http\->request($url, \e&savetofile, OUT); \& close OUT; .Ve .ie n .IP "set_callback ( $functionref, $dataref )" 4 .el .IP "set_callback ( \f(CW$functionref\fR, \f(CW$dataref\fR )" 4 .IX Item "set_callback ( $functionref, $dataref )" At various stages of the request, callbacks may be used to modify the behaviour or to monitor the status of the request. These work like the \&\f(CW$data_callback\fR parameter to \fBrequest()\fR, but are more versatile. Using set_callback disables \f(CW$data_callback\fR in \fBrequest()\fR .Sp The callbacks are called as: callback ( \f(CW$self\fR, \f(CW$phase\fR, \f(CW$dataref\fR, \f(CW$cbargs\fR ) .Sp The current phases are: .Sp .Vb 2 \& connect \- connection has been established and headers are being \& transmitted. \& \& content\-length \- return value is used as the content\-length. If undef, \& and prepare_post() was used, the content length is \& calculated. \& \& done\-headers \- all headers have been sent \& \& content \- return value is used as content and is sent to client. Return \& undef to use the internal content defined by prepare_post(). \& \& content\-done \- content has been successfuly transmitted. \& \& data \- A block of data has been received. The data is referenced by \& $dataref. The return value is dereferenced and replaces the \& content passed in. Return undef to avoid using memory for large \& documents. \& \& done \- Request is done. .Ve .ie n .IP "prepare_post ( $hashref )" 4 .el .IP "prepare_post ( \f(CW$hashref\fR )" 4 .IX Item "prepare_post ( $hashref )" Takes a reference to a hashed array of post form variables to upload. Create the \s-1HTTP\s0 body and sets the method to \s-1POST.\s0 .IP "http11_mode ( 0 | 1 )" 4 .IX Item "http11_mode ( 0 | 1 )" Turns on or off \s-1HTTP/1.1\s0 support. This is off by default due to broken \s-1HTTP/1.1\s0 servers. Use 1 to enable \s-1HTTP/1.1\s0 support. .ie n .IP "add_req_header ( $header, $value )" 4 .el .IP "add_req_header ( \f(CW$header\fR, \f(CW$value\fR )" 4 .IX Item "add_req_header ( $header, $value )" .PD 0 .ie n .IP "get_req_header ( $header )" 4 .el .IP "get_req_header ( \f(CW$header\fR )" 4 .IX Item "get_req_header ( $header )" .ie n .IP "delete_req_header ( $header )" 4 .el .IP "delete_req_header ( \f(CW$header\fR )" 4 .IX Item "delete_req_header ( $header )" .PD Add, Delete, or get a \s-1HTTP\s0 header(s) for the request. These functions allow you to override any header. Presently, Host, User-Agent, Content-Type, Accept, and Connection are pre-defined by the HTTP::Lite module. You may not override Host, Connection, or Accept. .Sp If you call \f(CW\*(C`add_req_header()\*(C'\fR with \f(CW$value\fR set to \f(CW\*(C`undef\*(C'\fR, then the header won't be added. .Sp To provide (proxy) authentication or authorization, you would use: .Sp .Vb 5 \& use HTTP::Lite; \& use MIME::Base64; \& $http = HTTP::Lite\->new; \& $encoded = encode_base64(\*(Aqusername:password\*(Aq); \& $http\->add_req_header("Authorization", $encoded); .Ve .Sp \&\fB\s-1NOTE\s0\fR: The present implementation limits you to one instance of each header. .IP "body" 4 .IX Item "body" Returns the body of the document returned by the remote server. .IP "headers_array" 4 .IX Item "headers_array" Returns an array of the \s-1HTTP\s0 headers returned by the remote server. .IP "headers_string" 4 .IX Item "headers_string" Returns a string representation of the \s-1HTTP\s0 headers returned by the remote server. .ie n .IP "get_header ( $header )" 4 .el .IP "get_header ( \f(CW$header\fR )" 4 .IX Item "get_header ( $header )" Returns an array of values for the requested header. .Sp \&\fB\s-1NOTE\s0\fR: \s-1HTTP\s0 requests are not limited to a single instance of each header. As a result, there may be more than one entry for every header. .IP "protocol" 4 .IX Item "protocol" Returns the \s-1HTTP\s0 protocol identifier, as reported by the remote server. This will generally be either \s-1HTTP/1.0\s0 or \s-1HTTP/1.1.\s0 .ie n .IP "proxy ( $proxy_server )" 4 .el .IP "proxy ( \f(CW$proxy_server\fR )" 4 .IX Item "proxy ( $proxy_server )" The \s-1URL\s0 or hostname of the proxy to use for the next request. .IP "status" 4 .IX Item "status" Returns the \s-1HTTP\s0 status code returned by the server. This is also reported as the return value of \fI\f(BIrequest()\fI\fR. .IP "status_message" 4 .IX Item "status_message" Returns the textual description of the status code as returned by the server. The status string is not required to adhere to any particular format, although most \s-1HTTP\s0 servers use a standard set of descriptions. .IP "reset" 4 .IX Item "reset" You must call this prior to re-using an HTTP::Lite handle, otherwise the results are undefined. .ie n .IP "local_addr ( $ip )" 4 .el .IP "local_addr ( \f(CW$ip\fR )" 4 .IX Item "local_addr ( $ip )" Explicity select the local \s-1IP\s0 address. 0.0.0.0 (default) lets the system choose. .ie n .IP "local_port ( $port )" 4 .el .IP "local_port ( \f(CW$port\fR )" 4 .IX Item "local_port ( $port )" Explicity select the local port. 0 (default and recommended) lets the system choose. .ie n .IP "method ( $method )" 4 .el .IP "method ( \f(CW$method\fR )" 4 .IX Item "method ( $method )" Explicity set the method. Using prepare_post or reset overrides this setting. Usual choices are \s-1GET, POST, PUT, HEAD\s0 .SH "EXAMPLES" .IX Header "EXAMPLES" .Vb 10 \& # Get and print out the headers and body of the CPAN homepage \& use HTTP::Lite; \& $http = HTTP::Lite\->new; \& $req = $http\->request("http://www.cpan.org/") \& or die "Unable to get document: $!"; \& die "Request failed ($req): ".$http\->status_message() \& if $req ne "200"; \& @headers = $http\->headers_array(); \& $body = $http\->body(); \& foreach $header (@headers) \& { \& print "$header$CRLF"; \& } \& print "$CRLF"; \& print "$body$CRLF"; \& \& # POST a query to the dejanews USENET search engine \& use HTTP::Lite; \& $http = HTTP::Lite\->new; \& %vars = ( \& "QRY" => "perl", \& "ST" => "MS", \& "svcclass" => "dncurrent", \& "DBS" => "2" \& ); \& $http\->prepare_post(\e%vars); \& $req = $http\->request("http://www.deja.com/dnquery.xp") \& or die "Unable to get document: $!"; \& print "req: $req\en"; \& print $http\->body(); .Ve .SH "UNIMPLEMENTED" .IX Header "UNIMPLEMENTED" .Vb 7 \& \- FTP \& \- HTTPS (SSL) \& \- Authenitcation/Authorizaton/Proxy\-Authorization \& are not directly supported, and require MIME::Base64. \& \- Redirects (Location) are not automatically followed \& \- multipart/form\-data POSTs are not directly supported (necessary \& for File uploads). .Ve .SH "BUGS" .IX Header "BUGS" Some broken \s-1HTTP/1.1\s0 servers send incorrect chunk sizes when transferring files. \&\s-1HTTP/1.1\s0 mode is now disabled by default. .SH "AUTHOR" .IX Header "AUTHOR" Roy Hooper .PP Now co-maintained by Neil Bowers . .SH "SEE ALSO" .IX Header "SEE ALSO" This module (HTTP::Lite) is almost certainly not the best module for your needs. .PP For most uses HTTP::Tiny is a good choice. If you need more features, then look at \s-1LWP\s0. .PP You could also read this review of \s-1CPAN\s0 modules for making \s-1HTTP\s0 requests . .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2000\-2002 Roy Hooper. All rights reserved. .PP Some parts copyright 2009 \- 2010 Adam Kennedy. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.