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