File Coverage

blib/lib/Net/HTTP.pm
Criterion Covered Total %
statement 13 13 100.0
branch 2 2 100.0
condition n/a
subroutine 5 5 100.0
pod 1 3 33.3
total 21 23 91.3


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