← Back to branch summary

~ubuntu-branches/ubuntu/warty/libwww-perl/warty

« back to all changes in this revision

Viewing changes to lib/Net/HTTP.pm

  • Committer: Bazaar Package Importer
  • Author(s): Michael Alan Dorman
  • Date: 2004-06-18 16:11:57 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20040618161157-6t4bfw7luro4fi9v
Tags: 5.800-1
http://bugs.debian.org/254742
http://bugs.debian.org/252638
* New upstream version. (closes: bug#254742)
* Fix problem of dangling symlinks---was really a result of the
  Makefile.PL changing up on us (closes: bug#252638)

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/Net/HTTP.pm
1
1
package Net::HTTP;
2
2
 
3
 
# $Id: HTTP.pm,v 1.39 2001/12/03 22:04:54 gisle Exp $
 
3
# $Id: HTTP.pm,v 1.45 2004/05/21 08:56:16 gisle Exp $
4
4
 
5
5
use strict;
6
6
use vars qw($VERSION @ISA);
7
7
 
8
 
$VERSION = "0.04";
 
8
$VERSION = "1.00";
9
9
eval { require IO::Socket::INET } || require IO::Socket;
10
10
require Net::HTTP::Methods;
11
11
 
27
27
 
28
28
=head1 NAME
29
29
 
30
 
Net::HTTP - Low-level HTTP client connection
31
 
 
32
 
=head1 NOTE
33
 
 
34
 
This module is experimental.  Details of its interface is likely to
35
 
change in the future.
 
30
Net::HTTP - Low-level HTTP connection (client)
36
31
 
37
32
=head1 SYNOPSIS
38
33
 
44
39
 while (1) {
45
40
    my $buf;
46
41
    my $n = $s->read_entity_body($buf, 1024);
 
42
    die "read failed: $!" unless defined $n;
47
43
    last unless $n;
48
44
    print $buf;
49
45
 }
52
48
 
53
49
The C<Net::HTTP> class is a low-level HTTP client.  An instance of the
54
50
C<Net::HTTP> class represents a connection to an HTTP server.  The
55
 
HTTP protocol is described in RFC 2616.
 
51
HTTP protocol is described in RFC 2616.  The C<Net::HTTP> class
 
52
support C<HTTP/1.0> and C<HTTP/1.1>.
56
53
 
57
54
C<Net::HTTP> is a sub-class of C<IO::Socket::INET>.  You can mix the
58
55
methods described below with reading and writing from the socket
66
63
 
67
64
=item $s = Net::HTTP->new( %options )
68
65
 
69
 
The C<Net::HTTP> constructor takes the same options as
70
 
C<IO::Socket::INET> as well as these:
 
66
The C<Net::HTTP> constructor method takes the same options as
 
67
C<IO::Socket::INET>'s as well as these:
71
68
 
72
69
  Host:            Initial host attribute value
73
70
  KeepAlive:       Initial keep_alive attribute value
77
74
  MaxLineLength:   Initial max_line_length attribute value
78
75
  MaxHeaderLines:  Initial max_header_lines attribute value
79
76
 
 
77
The C<Host> option is also the default for C<IO::Socket::INET>'s
 
78
C<PeerAddr>.  The C<PeerPort> defaults to 80 if not provided.
 
79
 
 
80
The C<Listen> option provided by C<IO::Socket::INET>'s constructor
 
81
method is not allowed.
 
82
 
 
83
If unable to connect to the given HTTP server then the constructor
 
84
returns C<undef> and $@ contains the reason.  After a successful
 
85
connect, a C<Net:HTTP> object is returned.
 
86
 
80
87
=item $s->host
81
88
 
82
89
Get/set the default value of the C<Host> header to send.  The $host
94
101
=item $s->send_te
95
102
 
96
103
Get/set the a value indicating if the request will be sent with a "TE"
97
 
header to indicate the transfer encodings that the server can chose to
 
104
header to indicate the transfer encodings that the server can choose to
98
105
use.  If the C<Compress::Zlib> module is installed then this will
99
 
annouce that this client accept both the I<deflate> and I<gzip>
 
106
announce that this client accept both the I<deflate> and I<gzip>
100
107
encodings.
101
108
 
102
109
=item $s->http_version
136
143
Format and send a request message.  Arguments are the same as for
137
144
format_request().  Returns true if successful.
138
145
 
 
146
=item $s->format_chunk( $data )
 
147
 
 
148
Returns the string to be written for the given chunk of data.  
 
149
 
139
150
=item $s->write_chunk($data)
140
151
 
141
152
Will write a new chunk of request entity body data.  This method
146
157
 
147
158
Returns true if successful.
148
159
 
149
 
=item $s->format_chunk($data)
150
 
 
151
 
Returns the string to be written for the given chunk of data.
152
 
 
153
 
=item $s->write_chunk_eof(%trailers)
 
160
=item $s->format_chunk_eof( %trailers )
 
161
 
 
162
Returns the string to be written for signaling EOF when a
 
163
C<Transfer-Encoding> of C<chunked> is used.
 
164
 
 
165
=item $s->write_chunk_eof( %trailers )
154
166
 
155
167
Will write eof marker for chunked data and optional trailers.  Note
156
168
that trailers should not really be used unless is was signaled
158
170
 
159
171
Returns true if successful.
160
172
 
161
 
=item $s->format_chunk_eof(%trailers)
162
 
 
163
 
Returns the string to be written for signaling EOF.
164
 
 
165
173
=item ($code, $mess, %headers) = $s->read_response_headers( %opts )
166
174
 
167
 
Read response headers from server.  The $code is the 3 digit HTTP
168
 
status code (see L<HTTP::Status>) and $mess is the textual message
169
 
that came with it.  Headers are then returned as key/value pairs.
170
 
Since key letter casing is not normalized and the same key can occur
171
 
multiple times, assigning these values directly to a hash might be
172
 
risky.
 
175
Read response headers from server and return it.  The $code is the 3
 
176
digit HTTP status code (see L<HTTP::Status>) and $mess is the textual
 
177
message that came with it.  Headers are then returned as key/value
 
178
pairs.  Since key letter casing is not normalized and the same key can
 
179
even occur multiple times, assigning these values directly to a hash
 
180
is not wise.  Only the $code is returned if this method is called in
 
181
scalar context.
173
182
 
174
183
As a side effect this method updates the 'peer_http_version'
175
184
attribute.
176
185
 
177
 
The method will raise exceptions (die) if the server does not speak
178
 
proper HTTP.
179
 
 
180
186
Options might be passed in as key/value pairs.  There are currently
181
187
only two options supported; C<laxed> and C<junk_out>.
182
188
 
183
 
The C<laxed> option will make C<read_response_headers> more forgiving
 
189
The C<laxed> option will make read_response_headers() more forgiving
184
190
towards servers that have not learned how to speak HTTP properly.  The
185
 
<laxed> option is a boolean flag, and is enabled by passing in a TRUE
 
191
C<laxed> option is a boolean flag, and is enabled by passing in a TRUE
186
192
value.  The C<junk_out> option can be used to capture bad header lines
187
193
when C<laxed> is enabled.  The value should be an array reference.
188
194
Bad header lines will be pushed onto the array.
189
195
 
 
196
The C<laxed> option must be specified in order to communicate with
 
197
pre-HTTP/1.0 servers that don't describe the response outcome or the
 
198
data they send back with a header block.  For these servers
 
199
peer_http_version is set to "0.9" and this method returns (200,
 
200
"Assumed OK").
 
201
 
 
202
The method will raise an exception (die) if the server does not speak
 
203
proper HTTP or if the C<max_line_length> or C<max_header_length>
 
204
limits are reached.  If the C<laxed> option is turned on and
 
205
C<max_line_length> and C<max_header_length> checks are turned off,
 
206
then no exception will be raised and this method will always
 
207
return a response code.
 
208
 
190
209
=item $n = $s->read_entity_body($buf, $size);
191
210
 
192
211
Reads chunks of the entity body content.  Basically the same interface
193
 
as for read() and sysread(), but buffer offset is not supported yet.
194
 
This method should only be called after a successful
 
212
as for read() and sysread(), but the buffer offset argument is not
 
213
supported yet.  This method should only be called after a successful
195
214
read_response_headers() call.
196
215
 
197
 
The return value will be C<undef> on errors, 0 on EOF, -1 if no data
198
 
could be returned this time, and otherwise the number of bytes added
199
 
to $buf.
 
216
The return value will be C<undef> on read errors, 0 on EOF, -1 if no data
 
217
could be returned this time, otherwise the number of bytes assigned
 
218
to $buf.  The $buf set to "" when the return value is -1.
200
219
 
201
 
This method might raise exceptions (die) if the server does not speak
202
 
proper HTTP.
 
220
This method will raise exceptions (die) if the server does not speak
 
221
proper HTTP.  This can only happen when reading chunked data.
203
222
 
204
223
=item %headers = $s->get_trailers
205
224
 
215
234
 
216
235
=item $s->_rbuf_length
217
236
 
218
 
Returns the number of bytes in the read buffer.
 
237
Returns the number of bytes in the read buffer.  This should always be
 
238
the same as:
 
239
 
 
240
    length($s->_rbuf)
 
241
 
 
242
but might be more efficient.
219
243
 
220
244
=back
221
245
 
223
247
 
224
248
The read_response_headers() and read_entity_body() will invoke the
225
249
sysread() method when they need more data.  Subclasses might want to
226
 
override this method to contol how reading takes place.
 
250
override this method to control how reading takes place.
227
251
 
228
252
The object itself is a glob.  Subclasses should avoid using hash key
229
253
names prefixed with C<http_> and C<io_>.
234
258
 
235
259
=head1 COPYRIGHT
236
260
 
237
 
Copyright 2001 Gisle Aas.
 
261
Copyright 2001-2003 Gisle Aas.
238
262
 
239
263
This library is free software; you can redistribute it and/or
240
264
modify it under the same terms as Perl itself.