|
Packit |
03f954 |
# NAME
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Net::HTTP - Low-level HTTP connection (client)
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
# VERSION
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
version 6.17
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
# SYNOPSIS
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
use Net::HTTP;
|
|
Packit |
03f954 |
my $s = Net::HTTP->new(Host => "www.perl.com") || die $@;
|
|
Packit |
03f954 |
$s->write_request(GET => "/", 'User-Agent' => "Mozilla/5.0");
|
|
Packit |
03f954 |
my($code, $mess, %h) = $s->read_response_headers;
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
while (1) {
|
|
Packit |
03f954 |
my $buf;
|
|
Packit |
03f954 |
my $n = $s->read_entity_body($buf, 1024);
|
|
Packit |
03f954 |
die "read failed: $!" unless defined $n;
|
|
Packit |
03f954 |
last unless $n;
|
|
Packit |
03f954 |
print $buf;
|
|
Packit |
03f954 |
}
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
# DESCRIPTION
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
The `Net::HTTP` class is a low-level HTTP client. An instance of the
|
|
Packit |
03f954 |
`Net::HTTP` class represents a connection to an HTTP server. The
|
|
Packit |
03f954 |
HTTP protocol is described in RFC 2616. The `Net::HTTP` class
|
|
Packit |
03f954 |
supports `HTTP/1.0` and `HTTP/1.1`.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
`Net::HTTP` is a sub-class of one of `IO::Socket::IP` (IPv6+IPv4),
|
|
Packit |
03f954 |
`IO::Socket::INET6` (IPv6+IPv4), or `IO::Socket::INET` (IPv4 only).
|
|
Packit |
03f954 |
You can mix the methods described below with reading and writing from the
|
|
Packit |
03f954 |
socket directly. This is not necessary a good idea, unless you know what
|
|
Packit |
03f954 |
you are doing.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
The following methods are provided (in addition to those of
|
|
Packit |
03f954 |
`IO::Socket::INET`):
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s = Net::HTTP->new( %options )
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
The `Net::HTTP` constructor method takes the same options as
|
|
Packit |
03f954 |
`IO::Socket::INET`'s as well as these:
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Host: Initial host attribute value
|
|
Packit |
03f954 |
KeepAlive: Initial keep_alive attribute value
|
|
Packit |
03f954 |
SendTE: Initial send_te attribute_value
|
|
Packit |
03f954 |
HTTPVersion: Initial http_version attribute value
|
|
Packit |
03f954 |
PeerHTTPVersion: Initial peer_http_version attribute value
|
|
Packit |
03f954 |
MaxLineLength: Initial max_line_length attribute value
|
|
Packit |
03f954 |
MaxHeaderLines: Initial max_header_lines attribute value
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
The `Host` option is also the default for `IO::Socket::INET`'s
|
|
Packit |
03f954 |
`PeerAddr`. The `PeerPort` defaults to 80 if not provided.
|
|
Packit |
03f954 |
The `PeerPort` specification can also be embedded in the `PeerAddr`
|
|
Packit |
03f954 |
by preceding it with a ":", and closing the IPv6 address on brackets "\[\]" if
|
|
Packit |
03f954 |
necessary: "192.0.2.1:80","\[2001:db8::1\]:80","any.example.com:80".
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
The `Listen` option provided by `IO::Socket::INET`'s constructor
|
|
Packit |
03f954 |
method is not allowed.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
If unable to connect to the given HTTP server then the constructor
|
|
Packit |
03f954 |
returns `undef` and $@ contains the reason. After a successful
|
|
Packit |
03f954 |
connect, a `Net:HTTP` object is returned.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s->host
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Get/set the default value of the `Host` header to send. The $host
|
|
Packit |
03f954 |
must not be set to an empty string (or `undef`) for HTTP/1.1.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s->keep\_alive
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Get/set the _keep-alive_ value. If this value is TRUE then the
|
|
Packit |
03f954 |
request will be sent with headers indicating that the server should try
|
|
Packit |
03f954 |
to keep the connection open so that multiple requests can be sent.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
The actual headers set will depend on the value of the `http_version`
|
|
Packit |
03f954 |
and `peer_http_version` attributes.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s->send\_te
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Get/set the a value indicating if the request will be sent with a "TE"
|
|
Packit |
03f954 |
header to indicate the transfer encodings that the server can choose to
|
|
Packit |
03f954 |
use. The list of encodings announced as accepted by this client depends
|
|
Packit |
03f954 |
on availability of the following modules: `Compress::Raw::Zlib` for
|
|
Packit |
03f954 |
_deflate_, and `IO::Compress::Gunzip` for _gzip_.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s->http\_version
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Get/set the HTTP version number that this client should announce.
|
|
Packit |
03f954 |
This value can only be set to "1.0" or "1.1". The default is "1.1".
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s->peer\_http\_version
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Get/set the protocol version number of our peer. This value will
|
|
Packit |
03f954 |
initially be "1.0", but will be updated by a successful
|
|
Packit |
03f954 |
read\_response\_headers() method call.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s->max\_line\_length
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Get/set a limit on the length of response line and response header
|
|
Packit |
03f954 |
lines. The default is 8192. A value of 0 means no limit.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s->max\_header\_length
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Get/set a limit on the number of header lines that a response can
|
|
Packit |
03f954 |
have. The default is 128. A value of 0 means no limit.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s->format\_request($method, $uri, %headers, \[$content\])
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Format a request message and return it as a string. If the headers do
|
|
Packit |
03f954 |
not include a `Host` header, then a header is inserted with the value
|
|
Packit |
03f954 |
of the `host` attribute. Headers like `Connection` and
|
|
Packit |
03f954 |
`Keep-Alive` might also be added depending on the status of the
|
|
Packit |
03f954 |
`keep_alive` attribute.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
If $content is given (and it is non-empty), then a `Content-Length`
|
|
Packit |
03f954 |
header is automatically added unless it was already present.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s->write\_request($method, $uri, %headers, \[$content\])
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Format and send a request message. Arguments are the same as for
|
|
Packit |
03f954 |
format\_request(). Returns true if successful.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s->format\_chunk( $data )
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Returns the string to be written for the given chunk of data.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s->write\_chunk($data)
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Will write a new chunk of request entity body data. This method
|
|
Packit |
03f954 |
should only be used if the `Transfer-Encoding` header with a value of
|
|
Packit |
03f954 |
`chunked` was sent in the request. Note, writing zero-length data is
|
|
Packit |
03f954 |
a no-op. Use the write\_chunk\_eof() method to signal end of entity
|
|
Packit |
03f954 |
body data.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Returns true if successful.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s->format\_chunk\_eof( %trailers )
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Returns the string to be written for signaling EOF when a
|
|
Packit |
03f954 |
`Transfer-Encoding` of `chunked` is used.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s->write\_chunk\_eof( %trailers )
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Will write eof marker for chunked data and optional trailers. Note
|
|
Packit |
03f954 |
that trailers should not really be used unless is was signaled
|
|
Packit |
03f954 |
with a `Trailer` header.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Returns true if successful.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- ($code, $mess, %headers) = $s->read\_response\_headers( %opts )
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Read response headers from server and return it. The $code is the 3
|
|
Packit |
03f954 |
digit HTTP status code (see [HTTP::Status](https://metacpan.org/pod/HTTP::Status)) and $mess is the textual
|
|
Packit |
03f954 |
message that came with it. Headers are then returned as key/value
|
|
Packit |
03f954 |
pairs. Since key letter casing is not normalized and the same key can
|
|
Packit |
03f954 |
even occur multiple times, assigning these values directly to a hash
|
|
Packit |
03f954 |
is not wise. Only the $code is returned if this method is called in
|
|
Packit |
03f954 |
scalar context.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
As a side effect this method updates the 'peer\_http\_version'
|
|
Packit |
03f954 |
attribute.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Options might be passed in as key/value pairs. There are currently
|
|
Packit |
03f954 |
only two options supported; `laxed` and `junk_out`.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
The `laxed` option will make read\_response\_headers() more forgiving
|
|
Packit |
03f954 |
towards servers that have not learned how to speak HTTP properly. The
|
|
Packit |
03f954 |
`laxed` option is a boolean flag, and is enabled by passing in a TRUE
|
|
Packit |
03f954 |
value. The `junk_out` option can be used to capture bad header lines
|
|
Packit |
03f954 |
when `laxed` is enabled. The value should be an array reference.
|
|
Packit |
03f954 |
Bad header lines will be pushed onto the array.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
The `laxed` option must be specified in order to communicate with
|
|
Packit |
03f954 |
pre-HTTP/1.0 servers that don't describe the response outcome or the
|
|
Packit |
03f954 |
data they send back with a header block. For these servers
|
|
Packit |
03f954 |
peer\_http\_version is set to "0.9" and this method returns (200,
|
|
Packit |
03f954 |
"Assumed OK").
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
The method will raise an exception (die) if the server does not speak
|
|
Packit |
03f954 |
proper HTTP or if the `max_line_length` or `max_header_length`
|
|
Packit |
03f954 |
limits are reached. If the `laxed` option is turned on and
|
|
Packit |
03f954 |
`max_line_length` and `max_header_length` checks are turned off,
|
|
Packit |
03f954 |
then no exception will be raised and this method will always
|
|
Packit |
03f954 |
return a response code.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $n = $s->read\_entity\_body($buf, $size);
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Reads chunks of the entity body content. Basically the same interface
|
|
Packit |
03f954 |
as for read() and sysread(), but the buffer offset argument is not
|
|
Packit |
03f954 |
supported yet. This method should only be called after a successful
|
|
Packit |
03f954 |
read\_response\_headers() call.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
The return value will be `undef` on read errors, 0 on EOF, -1 if no data
|
|
Packit |
03f954 |
could be returned this time, otherwise the number of bytes assigned
|
|
Packit |
03f954 |
to $buf. The $buf is set to "" when the return value is -1.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
You normally want to retry this call if this function returns either
|
|
Packit |
03f954 |
\-1 or `undef` with `$!` as EINTR or EAGAIN (see [Errno](https://metacpan.org/pod/Errno)). EINTR
|
|
Packit |
03f954 |
can happen if the application catches signals and EAGAIN can happen if
|
|
Packit |
03f954 |
you made the socket non-blocking.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
This method will raise exceptions (die) if the server does not speak
|
|
Packit |
03f954 |
proper HTTP. This can only happen when reading chunked data.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- %headers = $s->get\_trailers
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
After read\_entity\_body() has returned 0 to indicate end of the entity
|
|
Packit |
03f954 |
body, you might call this method to pick up any trailers.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s->\_rbuf
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Get/set the read buffer content. The read\_response\_headers() and
|
|
Packit |
03f954 |
read\_entity\_body() methods use an internal buffer which they will look
|
|
Packit |
03f954 |
for data before they actually sysread more from the socket itself. If
|
|
Packit |
03f954 |
they read too much, the remaining data will be left in this buffer.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
- $s->\_rbuf\_length
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Returns the number of bytes in the read buffer. This should always be
|
|
Packit |
03f954 |
the same as:
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
length($s->_rbuf)
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
but might be more efficient.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
# SUBCLASSING
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
The read\_response\_headers() and read\_entity\_body() will invoke the
|
|
Packit |
03f954 |
sysread() method when they need more data. Subclasses might want to
|
|
Packit |
03f954 |
override this method to control how reading takes place.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
The object itself is a glob. Subclasses should avoid using hash key
|
|
Packit |
03f954 |
names prefixed with `http_` and `io_`.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
# SEE ALSO
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
[LWP](https://metacpan.org/pod/LWP), [IO::Socket::INET](https://metacpan.org/pod/IO::Socket::INET), [Net::HTTP::NB](https://metacpan.org/pod/Net::HTTP::NB)
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
# AUTHOR
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
Gisle Aas <gisle@activestate.com>
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
# COPYRIGHT AND LICENSE
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
This software is copyright (c) 2001-2017 by Gisle Aas.
|
|
Packit |
03f954 |
|
|
Packit |
03f954 |
This is free software; you can redistribute it and/or modify it under
|
|
Packit |
03f954 |
the same terms as the Perl 5 programming language system itself.
|