1 | package Net::HTTP;
|
---|
2 |
|
---|
3 | use strict;
|
---|
4 | use vars qw($VERSION @ISA $SOCKET_CLASS);
|
---|
5 |
|
---|
6 | $VERSION = "5.834";
|
---|
7 | unless ($SOCKET_CLASS) {
|
---|
8 | eval { require IO::Socket::INET } || require IO::Socket;
|
---|
9 | $SOCKET_CLASS = "IO::Socket::INET";
|
---|
10 | }
|
---|
11 | require Net::HTTP::Methods;
|
---|
12 | require Carp;
|
---|
13 |
|
---|
14 | @ISA = ($SOCKET_CLASS, 'Net::HTTP::Methods');
|
---|
15 |
|
---|
16 | sub new {
|
---|
17 | my $class = shift;
|
---|
18 | Carp::croak("No Host option provided") unless @_;
|
---|
19 | $class->SUPER::new(@_);
|
---|
20 | }
|
---|
21 |
|
---|
22 | sub configure {
|
---|
23 | my($self, $cnf) = @_;
|
---|
24 | $self->http_configure($cnf);
|
---|
25 | }
|
---|
26 |
|
---|
27 | sub http_connect {
|
---|
28 | my($self, $cnf) = @_;
|
---|
29 | $self->SUPER::configure($cnf);
|
---|
30 | }
|
---|
31 |
|
---|
32 | 1;
|
---|
33 |
|
---|
34 | __END__
|
---|
35 |
|
---|
36 | =head1 NAME
|
---|
37 |
|
---|
38 | Net::HTTP - Low-level HTTP connection (client)
|
---|
39 |
|
---|
40 | =head1 SYNOPSIS
|
---|
41 |
|
---|
42 | use Net::HTTP;
|
---|
43 | my $s = Net::HTTP->new(Host => "www.perl.com") || die $@;
|
---|
44 | $s->write_request(GET => "/", 'User-Agent' => "Mozilla/5.0");
|
---|
45 | my($code, $mess, %h) = $s->read_response_headers;
|
---|
46 |
|
---|
47 | while (1) {
|
---|
48 | my $buf;
|
---|
49 | my $n = $s->read_entity_body($buf, 1024);
|
---|
50 | die "read failed: $!" unless defined $n;
|
---|
51 | last unless $n;
|
---|
52 | print $buf;
|
---|
53 | }
|
---|
54 |
|
---|
55 | =head1 DESCRIPTION
|
---|
56 |
|
---|
57 | The C<Net::HTTP> class is a low-level HTTP client. An instance of the
|
---|
58 | C<Net::HTTP> class represents a connection to an HTTP server. The
|
---|
59 | HTTP protocol is described in RFC 2616. The C<Net::HTTP> class
|
---|
60 | supports C<HTTP/1.0> and C<HTTP/1.1>.
|
---|
61 |
|
---|
62 | C<Net::HTTP> is a sub-class of C<IO::Socket::INET>. You can mix the
|
---|
63 | methods described below with reading and writing from the socket
|
---|
64 | directly. This is not necessary a good idea, unless you know what you
|
---|
65 | are doing.
|
---|
66 |
|
---|
67 | The following methods are provided (in addition to those of
|
---|
68 | C<IO::Socket::INET>):
|
---|
69 |
|
---|
70 | =over
|
---|
71 |
|
---|
72 | =item $s = Net::HTTP->new( %options )
|
---|
73 |
|
---|
74 | The C<Net::HTTP> constructor method takes the same options as
|
---|
75 | C<IO::Socket::INET>'s as well as these:
|
---|
76 |
|
---|
77 | Host: Initial host attribute value
|
---|
78 | KeepAlive: Initial keep_alive attribute value
|
---|
79 | SendTE: Initial send_te attribute_value
|
---|
80 | HTTPVersion: Initial http_version attribute value
|
---|
81 | PeerHTTPVersion: Initial peer_http_version attribute value
|
---|
82 | MaxLineLength: Initial max_line_length attribute value
|
---|
83 | MaxHeaderLines: Initial max_header_lines attribute value
|
---|
84 |
|
---|
85 | The C<Host> option is also the default for C<IO::Socket::INET>'s
|
---|
86 | C<PeerAddr>. The C<PeerPort> defaults to 80 if not provided.
|
---|
87 |
|
---|
88 | The C<Listen> option provided by C<IO::Socket::INET>'s constructor
|
---|
89 | method is not allowed.
|
---|
90 |
|
---|
91 | If unable to connect to the given HTTP server then the constructor
|
---|
92 | returns C<undef> and $@ contains the reason. After a successful
|
---|
93 | connect, a C<Net:HTTP> object is returned.
|
---|
94 |
|
---|
95 | =item $s->host
|
---|
96 |
|
---|
97 | Get/set the default value of the C<Host> header to send. The $host
|
---|
98 | must not be set to an empty string (or C<undef>) for HTTP/1.1.
|
---|
99 |
|
---|
100 | =item $s->keep_alive
|
---|
101 |
|
---|
102 | Get/set the I<keep-alive> value. If this value is TRUE then the
|
---|
103 | request will be sent with headers indicating that the server should try
|
---|
104 | to keep the connection open so that multiple requests can be sent.
|
---|
105 |
|
---|
106 | The actual headers set will depend on the value of the C<http_version>
|
---|
107 | and C<peer_http_version> attributes.
|
---|
108 |
|
---|
109 | =item $s->send_te
|
---|
110 |
|
---|
111 | Get/set the a value indicating if the request will be sent with a "TE"
|
---|
112 | header to indicate the transfer encodings that the server can choose to
|
---|
113 | use. The list of encodings announced as accepted by this client depends
|
---|
114 | on availability of the following modules: C<Compress::Raw::Zlib> for
|
---|
115 | I<deflate>, and C<IO::Compress::Gunzip> for I<gzip>.
|
---|
116 |
|
---|
117 | =item $s->http_version
|
---|
118 |
|
---|
119 | Get/set the HTTP version number that this client should announce.
|
---|
120 | This value can only be set to "1.0" or "1.1". The default is "1.1".
|
---|
121 |
|
---|
122 | =item $s->peer_http_version
|
---|
123 |
|
---|
124 | Get/set the protocol version number of our peer. This value will
|
---|
125 | initially be "1.0", but will be updated by a successful
|
---|
126 | read_response_headers() method call.
|
---|
127 |
|
---|
128 | =item $s->max_line_length
|
---|
129 |
|
---|
130 | Get/set a limit on the length of response line and response header
|
---|
131 | lines. The default is 8192. A value of 0 means no limit.
|
---|
132 |
|
---|
133 | =item $s->max_header_length
|
---|
134 |
|
---|
135 | Get/set a limit on the number of header lines that a response can
|
---|
136 | have. The default is 128. A value of 0 means no limit.
|
---|
137 |
|
---|
138 | =item $s->format_request($method, $uri, %headers, [$content])
|
---|
139 |
|
---|
140 | Format a request message and return it as a string. If the headers do
|
---|
141 | not include a C<Host> header, then a header is inserted with the value
|
---|
142 | of the C<host> attribute. Headers like C<Connection> and
|
---|
143 | C<Keep-Alive> might also be added depending on the status of the
|
---|
144 | C<keep_alive> attribute.
|
---|
145 |
|
---|
146 | If $content is given (and it is non-empty), then a C<Content-Length>
|
---|
147 | header is automatically added unless it was already present.
|
---|
148 |
|
---|
149 | =item $s->write_request($method, $uri, %headers, [$content])
|
---|
150 |
|
---|
151 | Format and send a request message. Arguments are the same as for
|
---|
152 | format_request(). Returns true if successful.
|
---|
153 |
|
---|
154 | =item $s->format_chunk( $data )
|
---|
155 |
|
---|
156 | Returns the string to be written for the given chunk of data.
|
---|
157 |
|
---|
158 | =item $s->write_chunk($data)
|
---|
159 |
|
---|
160 | Will write a new chunk of request entity body data. This method
|
---|
161 | should only be used if the C<Transfer-Encoding> header with a value of
|
---|
162 | C<chunked> was sent in the request. Note, writing zero-length data is
|
---|
163 | a no-op. Use the write_chunk_eof() method to signal end of entity
|
---|
164 | body data.
|
---|
165 |
|
---|
166 | Returns true if successful.
|
---|
167 |
|
---|
168 | =item $s->format_chunk_eof( %trailers )
|
---|
169 |
|
---|
170 | Returns the string to be written for signaling EOF when a
|
---|
171 | C<Transfer-Encoding> of C<chunked> is used.
|
---|
172 |
|
---|
173 | =item $s->write_chunk_eof( %trailers )
|
---|
174 |
|
---|
175 | Will write eof marker for chunked data and optional trailers. Note
|
---|
176 | that trailers should not really be used unless is was signaled
|
---|
177 | with a C<Trailer> header.
|
---|
178 |
|
---|
179 | Returns true if successful.
|
---|
180 |
|
---|
181 | =item ($code, $mess, %headers) = $s->read_response_headers( %opts )
|
---|
182 |
|
---|
183 | Read response headers from server and return it. The $code is the 3
|
---|
184 | digit HTTP status code (see L<HTTP::Status>) and $mess is the textual
|
---|
185 | message that came with it. Headers are then returned as key/value
|
---|
186 | pairs. Since key letter casing is not normalized and the same key can
|
---|
187 | even occur multiple times, assigning these values directly to a hash
|
---|
188 | is not wise. Only the $code is returned if this method is called in
|
---|
189 | scalar context.
|
---|
190 |
|
---|
191 | As a side effect this method updates the 'peer_http_version'
|
---|
192 | attribute.
|
---|
193 |
|
---|
194 | Options might be passed in as key/value pairs. There are currently
|
---|
195 | only two options supported; C<laxed> and C<junk_out>.
|
---|
196 |
|
---|
197 | The C<laxed> option will make read_response_headers() more forgiving
|
---|
198 | towards servers that have not learned how to speak HTTP properly. The
|
---|
199 | C<laxed> option is a boolean flag, and is enabled by passing in a TRUE
|
---|
200 | value. The C<junk_out> option can be used to capture bad header lines
|
---|
201 | when C<laxed> is enabled. The value should be an array reference.
|
---|
202 | Bad header lines will be pushed onto the array.
|
---|
203 |
|
---|
204 | The C<laxed> option must be specified in order to communicate with
|
---|
205 | pre-HTTP/1.0 servers that don't describe the response outcome or the
|
---|
206 | data they send back with a header block. For these servers
|
---|
207 | peer_http_version is set to "0.9" and this method returns (200,
|
---|
208 | "Assumed OK").
|
---|
209 |
|
---|
210 | The method will raise an exception (die) if the server does not speak
|
---|
211 | proper HTTP or if the C<max_line_length> or C<max_header_length>
|
---|
212 | limits are reached. If the C<laxed> option is turned on and
|
---|
213 | C<max_line_length> and C<max_header_length> checks are turned off,
|
---|
214 | then no exception will be raised and this method will always
|
---|
215 | return a response code.
|
---|
216 |
|
---|
217 | =item $n = $s->read_entity_body($buf, $size);
|
---|
218 |
|
---|
219 | Reads chunks of the entity body content. Basically the same interface
|
---|
220 | as for read() and sysread(), but the buffer offset argument is not
|
---|
221 | supported yet. This method should only be called after a successful
|
---|
222 | read_response_headers() call.
|
---|
223 |
|
---|
224 | The return value will be C<undef> on read errors, 0 on EOF, -1 if no data
|
---|
225 | could be returned this time, otherwise the number of bytes assigned
|
---|
226 | to $buf. The $buf is set to "" when the return value is -1.
|
---|
227 |
|
---|
228 | You normally want to retry this call if this function returns either
|
---|
229 | -1 or C<undef> with C<$!> as EINTR or EAGAIN (see L<Errno>). EINTR
|
---|
230 | can happen if the application catches signals and EAGAIN can happen if
|
---|
231 | you made the socket non-blocking.
|
---|
232 |
|
---|
233 | This method will raise exceptions (die) if the server does not speak
|
---|
234 | proper HTTP. This can only happen when reading chunked data.
|
---|
235 |
|
---|
236 | =item %headers = $s->get_trailers
|
---|
237 |
|
---|
238 | After read_entity_body() has returned 0 to indicate end of the entity
|
---|
239 | body, you might call this method to pick up any trailers.
|
---|
240 |
|
---|
241 | =item $s->_rbuf
|
---|
242 |
|
---|
243 | Get/set the read buffer content. The read_response_headers() and
|
---|
244 | read_entity_body() methods use an internal buffer which they will look
|
---|
245 | for data before they actually sysread more from the socket itself. If
|
---|
246 | they read too much, the remaining data will be left in this buffer.
|
---|
247 |
|
---|
248 | =item $s->_rbuf_length
|
---|
249 |
|
---|
250 | Returns the number of bytes in the read buffer. This should always be
|
---|
251 | the same as:
|
---|
252 |
|
---|
253 | length($s->_rbuf)
|
---|
254 |
|
---|
255 | but might be more efficient.
|
---|
256 |
|
---|
257 | =back
|
---|
258 |
|
---|
259 | =head1 SUBCLASSING
|
---|
260 |
|
---|
261 | The read_response_headers() and read_entity_body() will invoke the
|
---|
262 | sysread() method when they need more data. Subclasses might want to
|
---|
263 | override this method to control how reading takes place.
|
---|
264 |
|
---|
265 | The object itself is a glob. Subclasses should avoid using hash key
|
---|
266 | names prefixed with C<http_> and C<io_>.
|
---|
267 |
|
---|
268 | =head1 SEE ALSO
|
---|
269 |
|
---|
270 | L<LWP>, L<IO::Socket::INET>, L<Net::HTTP::NB>
|
---|
271 |
|
---|
272 | =head1 COPYRIGHT
|
---|
273 |
|
---|
274 | Copyright 2001-2003 Gisle Aas.
|
---|
275 |
|
---|
276 | This library is free software; you can redistribute it and/or
|
---|
277 | modify it under the same terms as Perl itself.
|
---|
278 |
|
---|
279 | =cut
|
---|