http::request(3) [suse man page]

HTTP::Request(3)					User Contributed Perl Documentation					  HTTP::Request(3)

NAME

       HTTP::Request - HTTP style request message

SYNOPSIS

	require HTTP::Request;
	$request = HTTP::Request->new(GET => 'http://www.example.com/');

       and usually used like this:

	$ua = LWP::UserAgent->new;
	$response = $ua->request($request);

DESCRIPTION

       "HTTP::Request" is a class encapsulating HTTP style requests, consisting of a request line, some headers, and a content body. Note that the
       LWP library uses HTTP style requests even for non-HTTP protocols.  Instances of this class are usually passed to the request() method of an
       "LWP::UserAgent" object.

       "HTTP::Request" is a subclass of "HTTP::Message" and therefore inherits its methods.  The following additional methods are available:

       $r = HTTP::Request->new( $method, $uri )
       $r = HTTP::Request->new( $method, $uri, $header )
       $r = HTTP::Request->new( $method, $uri, $header, $content )
	   Constructs a new "HTTP::Request" object describing a request on the object $uri using method $method.  The $method argument must be a
	   string.  The $uri argument can be either a string, or a reference to a "URI" object.  The optional $header argument should be a
	   reference to an "HTTP::Headers" object or a plain array reference of key/value pairs.  The optional $content argument should be a
	   string of bytes.

       $r = HTTP::Request->parse( $str )
	   This constructs a new request object by parsing the given string.

       $r->method
       $r->method( $val )
	   This is used to get/set the method attribute.  The method should be a short string like "GET", "HEAD", "PUT" or "POST".

       $r->uri
       $r->uri( $val )
	   This is used to get/set the uri attribute.  The $val can be a reference to a URI object or a plain string.  If a string is given, then
	   it should be parseable as an absolute URI.

       $r->header( $field )
       $r->header( $field => $value )
	   This is used to get/set header values and it is inherited from "HTTP::Headers" via "HTTP::Message".	See HTTP::Headers for details and
	   other similar methods that can be used to access the headers.

       $r->accept_decodable
	   This will set the "Accept-Encoding" header to the list of encodings that decoded_content() can decode.

       $r->content
       $r->content( $bytes )
	   This is used to get/set the content and it is inherited from the "HTTP::Message" base class.  See HTTP::Message for details and other
	   methods that can be used to access the content.

	   Note that the content should be a string of bytes.  Strings in perl can contain characters outside the range of a byte.  The "Encode"
	   module can be used to turn such strings into a string of bytes.

       $r->as_string
       $r->as_string( $eol )
	   Method returning a textual representation of the request.

SEE ALSO

       HTTP::Headers, HTTP::Message, HTTP::Request::Common, HTTP::Response

COPYRIGHT

       Copyright 1995-2004 Gisle Aas.

       This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

perl v5.12.1							    2009-06-15							  HTTP::Request(3)

Parser(3pm)						User Contributed Perl Documentation					       Parser(3pm)

NAME

       HTTP::Parser - parse HTTP/1.1 request into HTTP::Request/Response object

SYNOPSIS

	my $parser = HTTP::Parser->new();

	...

	my $status = $parser->add($text);

	if(0 == $status) {
	  print "request: ".$parser->request()->as_string();  # HTTP::Request
	} elsif(-3 == $status) {
	  print "no content length header!
";
	} elsif(-2 == $status) {
	  print "need a line of data
";
	} elsif(-1 == $status) {
	  print "need more data
";
	} else {  # $status > 0
	  print "need $status byte(s)
";
	}

DESCRIPTION

       This is an HTTP request parser.	It takes chunks of text as received and returns a 'hint' as to what is required, or returns the
       HTTP::Request when a complete request has been read.  HTTP/1.1 chunking is supported.  It dies if it finds an error.

   new ( named params... )
       Create a new HTTP::Parser object.  Takes named parameters, e.g.:

	my $parser = HTTP::Parser->new(request => 1);

       request
	   Allows or denies parsing an HTTP request and returning an "HTTP::Request" object.

       response
	   Allows or denies parsing an HTTP response and returning an "HTTP::Response" object.

       If you pass neither "request" nor "response", only requests are parsed (for backwards compatibility); if you pass either, the other
       defaults to false (disallowing both requests and responses is a fatal error).

   add ( string )
       Parse request.  Returns:

       0       if finished (call "object" to get an HTTP::Request or Response object)

       -1      if not finished but not sure how many bytes remain

       -2      if waiting for a line (like 0 with a hint)

       -3      if there was no content-length header, so we can't tell whether we are waiting for more data or not.

	       If you are reading from a TCP stream, you can keep adding data until the connection closes gracefully (the HTTP RFC allows this).

	       If you are reading from a file, you should keep adding until you have all the data.

	       Once you have added all data, you may call "object".  if you are not sure whether you have all the data, the HTTP::Response object
	       might be incomplete.

       count   if waiting for that many bytes

       Dies on error.

       This method of parsing makes it easier to parse a request from an event-based system, on the other hand, it's quite alright to pass in the
       whole request.  Ideally, the first chunk passed in is the header (up to the double newline), then whatever byte counts are requested.

       When a request object is returned, the X-HTTP-Version header has the HTTP version, the uri() method will always return a URI object, not a
       string.

       Note that a nonzero return is just a hint, and any amount of data can be passed in to a subsequent add() call.

   data
       Returns current data not parsed.  Mainly useful after a request has been parsed.  The data is not removed from the object's buffer, and
       will be seen before the data next passed to add().

   extra
       Returns the count of extra bytes (length of data()) after a request.

   object
       Returns the object request.  Only useful after the parse has completed.

AUTHOR

       David Robins <dbrobins@davidrobins.net> Fixes for 0.05 by David Cannings <david@edeca.net>

SEE ALSO

       HTTP::Request, HTTP::Response.

perl v5.10.1							    2011-03-06							       Parser(3pm)