437 lines
12 KiB
HTML
437 lines
12 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of Net::HTTP</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>Net::HTTP</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2019-07-18<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
Net::HTTP - Low-level HTTP connection (client)
|
|
<A NAME="lbAC"> </A>
|
|
<H2>VERSION</H2>
|
|
|
|
|
|
|
|
version 6.19
|
|
<A NAME="lbAD"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
use Net::HTTP;
|
|
my $s = Net::HTTP->new(Host => "<A HREF="http://www.perl.com">www.perl.com</A>") || die $@;
|
|
$s->write_request(GET => "/", 'User-Agent' => "Mozilla/5.0");
|
|
my($code, $mess, %h) = $s->read_response_headers;
|
|
|
|
while (1) {
|
|
my $buf;
|
|
my $n = $s->read_entity_body($buf, 1024);
|
|
die "read failed: $!" unless defined $n;
|
|
last unless $n;
|
|
print $buf;
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
The <TT>"Net::HTTP"</TT> class is a low-level <FONT SIZE="-1">HTTP</FONT> client. An instance of the
|
|
<TT>"Net::HTTP"</TT> class represents a connection to an <FONT SIZE="-1">HTTP</FONT> server. The
|
|
<FONT SIZE="-1">HTTP</FONT> protocol is described in <FONT SIZE="-1">RFC 2616.</FONT> The <TT>"Net::HTTP"</TT> class
|
|
supports <TT>"HTTP/1.0"</TT> and <TT>"HTTP/1.1"</TT>.
|
|
<P>
|
|
|
|
<TT>"Net::HTTP"</TT> is a sub-class of one of <TT>"IO::Socket::IP"</TT> (IPv6+IPv4),
|
|
<TT>"IO::Socket::INET6"</TT> (IPv6+IPv4), or <TT>"IO::Socket::INET"</TT> (IPv4 only).
|
|
You can mix the methods described below with reading and writing from the
|
|
socket directly. This is not necessary a good idea, unless you know what
|
|
you are doing.
|
|
<P>
|
|
|
|
The following methods are provided (in addition to those of
|
|
<TT>"IO::Socket::INET"</TT>):
|
|
<DL COMPACT>
|
|
<DT id="1">$s = Net::HTTP->new( %options )<DD>
|
|
|
|
|
|
|
|
|
|
The <TT>"Net::HTTP"</TT> constructor method takes the same options as
|
|
<TT>"IO::Socket::INET"</TT>'s as well as these:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
Host: Initial host attribute value
|
|
KeepAlive: Initial keep_alive attribute value
|
|
SendTE: Initial send_te attribute_value
|
|
HTTPVersion: Initial http_version attribute value
|
|
PeerHTTPVersion: Initial peer_http_version attribute value
|
|
MaxLineLength: Initial max_line_length attribute value
|
|
MaxHeaderLines: Initial max_header_lines attribute value
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>"Host"</TT> option is also the default for <TT>"IO::Socket::INET"</TT>'s
|
|
<TT>"PeerAddr"</TT>. The <TT>"PeerPort"</TT> defaults to 80 if not provided.
|
|
The <TT>"PeerPort"</TT> specification can also be embedded in the <TT>"PeerAddr"</TT>
|
|
by preceding it with a ``:'', and closing the IPv6 address on brackets ``[]'' if
|
|
necessary: ``192.0.2.1:80'',``[2001:db8::1]:80'',``any.example.com:80''.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>"Listen"</TT> option provided by <TT>"IO::Socket::INET"</TT>'s constructor
|
|
method is not allowed.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If unable to connect to the given <FONT SIZE="-1">HTTP</FONT> server then the constructor
|
|
returns <TT>"undef"</TT> and $@ contains the reason. After a successful
|
|
connect, a <TT>"Net:HTTP"</TT> object is returned.
|
|
<DT id="2">$s->host<DD>
|
|
|
|
|
|
|
|
|
|
Get/set the default value of the <TT>"Host"</TT> header to send. The <TT>$host</TT>
|
|
must not be set to an empty string (or <TT>"undef"</TT>) for <FONT SIZE="-1">HTTP/1.1.</FONT>
|
|
<DT id="3">$s->keep_alive<DD>
|
|
|
|
|
|
|
|
|
|
Get/set the <I>keep-alive</I> value. If this value is <FONT SIZE="-1">TRUE</FONT> then the
|
|
request will be sent with headers indicating that the server should try
|
|
to keep the connection open so that multiple requests can be sent.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The actual headers set will depend on the value of the <TT>"http_version"</TT>
|
|
and <TT>"peer_http_version"</TT> attributes.
|
|
<DT id="4">$s->send_te<DD>
|
|
|
|
|
|
|
|
|
|
Get/set the a value indicating if the request will be sent with a ``<FONT SIZE="-1">TE''</FONT>
|
|
header to indicate the transfer encodings that the server can choose to
|
|
use. The list of encodings announced as accepted by this client depends
|
|
on availability of the following modules: <TT>"Compress::Raw::Zlib"</TT> for
|
|
<I>deflate</I>, and <TT>"IO::Compress::Gunzip"</TT> for <I>gzip</I>.
|
|
<DT id="5">$s->http_version<DD>
|
|
|
|
|
|
|
|
|
|
Get/set the <FONT SIZE="-1">HTTP</FONT> version number that this client should announce.
|
|
This value can only be set to ``1.0'' or ``1.1''. The default is ``1.1''.
|
|
<DT id="6">$s->peer_http_version<DD>
|
|
|
|
|
|
|
|
|
|
Get/set the protocol version number of our peer. This value will
|
|
initially be ``1.0'', but will be updated by a successful
|
|
<B>read_response_headers()</B> method call.
|
|
<DT id="7">$s->max_line_length<DD>
|
|
|
|
|
|
|
|
|
|
Get/set a limit on the length of response line and response header
|
|
lines. The default is 8192. A value of 0 means no limit.
|
|
<DT id="8">$s->max_header_length<DD>
|
|
|
|
|
|
|
|
|
|
Get/set a limit on the number of header lines that a response can
|
|
have. The default is 128. A value of 0 means no limit.
|
|
<DT id="9">$s->format_request($method, $uri, %headers, [$content])<DD>
|
|
|
|
|
|
|
|
|
|
Format a request message and return it as a string. If the headers do
|
|
not include a <TT>"Host"</TT> header, then a header is inserted with the value
|
|
of the <TT>"host"</TT> attribute. Headers like <TT>"Connection"</TT> and
|
|
<TT>"Keep-Alive"</TT> might also be added depending on the status of the
|
|
<TT>"keep_alive"</TT> attribute.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If <TT>$content</TT> is given (and it is non-empty), then a <TT>"Content-Length"</TT>
|
|
header is automatically added unless it was already present.
|
|
<DT id="10">$s->write_request($method, $uri, %headers, [$content])<DD>
|
|
|
|
|
|
|
|
|
|
Format and send a request message. Arguments are the same as for
|
|
<B>format_request()</B>. Returns true if successful.
|
|
<DT id="11">$s->format_chunk( $data )<DD>
|
|
|
|
|
|
|
|
|
|
Returns the string to be written for the given chunk of data.
|
|
<DT id="12">$s->write_chunk($data)<DD>
|
|
|
|
|
|
|
|
|
|
Will write a new chunk of request entity body data. This method
|
|
should only be used if the <TT>"Transfer-Encoding"</TT> header with a value of
|
|
<TT>"chunked"</TT> was sent in the request. Note, writing zero-length data is
|
|
a no-op. Use the <B>write_chunk_eof()</B> method to signal end of entity
|
|
body data.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Returns true if successful.
|
|
<DT id="13">$s->format_chunk_eof( %trailers )<DD>
|
|
|
|
|
|
|
|
|
|
Returns the string to be written for signaling <FONT SIZE="-1">EOF</FONT> when a
|
|
<TT>"Transfer-Encoding"</TT> of <TT>"chunked"</TT> is used.
|
|
<DT id="14">$s->write_chunk_eof( %trailers )<DD>
|
|
|
|
|
|
|
|
|
|
Will write eof marker for chunked data and optional trailers. Note
|
|
that trailers should not really be used unless is was signaled
|
|
with a <TT>"Trailer"</TT> header.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Returns true if successful.
|
|
<DT id="15">($code, $mess, %headers) = $s->read_response_headers( %opts )<DD>
|
|
|
|
|
|
|
|
|
|
Read response headers from server and return it. The <TT>$code</TT> is the 3
|
|
digit <FONT SIZE="-1">HTTP</FONT> status code (see HTTP::Status) and <TT>$mess</TT> is the textual
|
|
message that came with it. Headers are then returned as key/value
|
|
pairs. Since key letter casing is not normalized and the same key can
|
|
even occur multiple times, assigning these values directly to a hash
|
|
is not wise. Only the <TT>$code</TT> is returned if this method is called in
|
|
scalar context.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
As a side effect this method updates the 'peer_http_version'
|
|
attribute.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Options might be passed in as key/value pairs. There are currently
|
|
only two options supported; <TT>"laxed"</TT> and <TT>"junk_out"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>"laxed"</TT> option will make <B>read_response_headers()</B> more forgiving
|
|
towards servers that have not learned how to speak <FONT SIZE="-1">HTTP</FONT> properly. The
|
|
<TT>"laxed"</TT> option is a boolean flag, and is enabled by passing in a <FONT SIZE="-1">TRUE</FONT>
|
|
value. The <TT>"junk_out"</TT> option can be used to capture bad header lines
|
|
when <TT>"laxed"</TT> is enabled. The value should be an array reference.
|
|
Bad header lines will be pushed onto the array.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>"laxed"</TT> option must be specified in order to communicate with
|
|
pre-HTTP/1.0 servers that don't describe the response outcome or the
|
|
data they send back with a header block. For these servers
|
|
peer_http_version is set to ``0.9'' and this method returns (200,
|
|
``Assumed <FONT SIZE="-1">OK''</FONT>).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The method will raise an exception (die) if the server does not speak
|
|
proper <FONT SIZE="-1">HTTP</FONT> or if the <TT>"max_line_length"</TT> or <TT>"max_header_length"</TT>
|
|
limits are reached. If the <TT>"laxed"</TT> option is turned on and
|
|
<TT>"max_line_length"</TT> and <TT>"max_header_length"</TT> checks are turned off,
|
|
then no exception will be raised and this method will always
|
|
return a response code.
|
|
<DT id="16">$n = $s->read_entity_body($buf, $size);<DD>
|
|
|
|
|
|
|
|
|
|
Reads chunks of the entity body content. Basically the same interface
|
|
as for <B>read()</B> and <B>sysread()</B>, but the buffer offset argument is not
|
|
supported yet. This method should only be called after a successful
|
|
<B>read_response_headers()</B> call.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The return value will be <TT>"undef"</TT> on read errors, 0 on <FONT SIZE="-1">EOF,</FONT> -1 if no data
|
|
could be returned this time, otherwise the number of bytes assigned
|
|
to <TT>$buf</TT>. The <TT>$buf</TT> is set to "" when the return value is -1.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
You normally want to retry this call if this function returns either
|
|
-1 or <TT>"undef"</TT> with <TT>$!</TT> as <FONT SIZE="-1">EINTR</FONT> or <FONT SIZE="-1">EAGAIN</FONT> (see Errno). <FONT SIZE="-1">EINTR</FONT>
|
|
can happen if the application catches signals and <FONT SIZE="-1">EAGAIN</FONT> can happen if
|
|
you made the socket non-blocking.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This method will raise exceptions (die) if the server does not speak
|
|
proper <FONT SIZE="-1">HTTP.</FONT> This can only happen when reading chunked data.
|
|
<DT id="17">%headers = $s->get_trailers<DD>
|
|
|
|
|
|
|
|
|
|
After <B>read_entity_body()</B> has returned 0 to indicate end of the entity
|
|
body, you might call this method to pick up any trailers.
|
|
<DT id="18">$s->_rbuf<DD>
|
|
|
|
|
|
|
|
|
|
Get/set the read buffer content. The <B>read_response_headers()</B> and
|
|
<B>read_entity_body()</B> methods use an internal buffer which they will look
|
|
for data before they actually sysread more from the socket itself. If
|
|
they read too much, the remaining data will be left in this buffer.
|
|
<DT id="19">$s->_rbuf_length<DD>
|
|
|
|
|
|
|
|
|
|
Returns the number of bytes in the read buffer. This should always be
|
|
the same as:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
length($s->_rbuf)
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
but might be more efficient.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>SUBCLASSING</H2>
|
|
|
|
|
|
|
|
The <B>read_response_headers()</B> and <B>read_entity_body()</B> will invoke the
|
|
<B>sysread()</B> method when they need more data. Subclasses might want to
|
|
override this method to control how reading takes place.
|
|
<P>
|
|
|
|
The object itself is a glob. Subclasses should avoid using hash key
|
|
names prefixed with <TT>"http_"</TT> and <TT>"io_"</TT>.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
<FONT SIZE="-1">LWP</FONT>, IO::Socket::INET, Net::HTTP::NB
|
|
<A NAME="lbAH"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
Gisle Aas <<A HREF="mailto:gisle@activestate.com">gisle@activestate.com</A>>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>COPYRIGHT AND LICENSE</H2>
|
|
|
|
|
|
|
|
This software is copyright (c) 2001-2017 by Gisle Aas.
|
|
<P>
|
|
|
|
This is free software; you can redistribute it and/or modify it under
|
|
the same terms as the Perl 5 programming language system itself.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="20"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="21"><A HREF="#lbAC">VERSION</A><DD>
|
|
<DT id="22"><A HREF="#lbAD">SYNOPSIS</A><DD>
|
|
<DT id="23"><A HREF="#lbAE">DESCRIPTION</A><DD>
|
|
<DT id="24"><A HREF="#lbAF">SUBCLASSING</A><DD>
|
|
<DT id="25"><A HREF="#lbAG">SEE ALSO</A><DD>
|
|
<DT id="26"><A HREF="#lbAH">AUTHOR</A><DD>
|
|
<DT id="27"><A HREF="#lbAI">COPYRIGHT AND LICENSE</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:49 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|