view release on metacpan or  search on metacpan

lib/CPANPLUS/Internals/Source/CPANMetaDB/HTTP.pm  view on Meta::CPAN

       http_write
       initialize
       upper

=head1 CONSTRUCTOR

=over 4

=item new

This is the constructor for HTTP::Lite.  It presently takes no
arguments.  A future version of HTTP::Lite might accept parameters.

=back

=head1 METHODS

=over 4

=item request ( $url, $data_callback, $cbargs )

Initiates a request to the specified URL.

Returns undef if an I/O error is encountered, otherwise the HTTP
status code will be returned.  200 series status codes represent
success, 300 represent temporary errors, 400 represent permanent
errors, and 500 represent server errors.

See F<http://www.w3.org/Protocols/HTTP/HTRESP.html> for detailled
information about HTTP status codes.

The $data_callback parameter, if used, is a way to filter the data as it is
received or to handle large transfers.  It must be a function reference, and
will be passed: a reference to the instance of the http request making the
callback, a reference to the current block of data about to be added to the
body, and the $cbargs parameter (which may be anything).  It must return
either a reference to the data to add to the body of the document, or undef.

If set_callback is used, $data_callback and $cbargs are not used.  $cbargs
may be either a scalar or a reference.

The data_callback is called as: 
  &$data_callback( $self, $dataref, $cbargs )

An example use to save a document to file is:

  # Write the data to the filehandle $cbargs
  sub savetofile {
    my ($self,$phase,$dataref,$cbargs) = @_;
    print $cbargs $$dataref;
    return undef;
  }

  $url = "$testpath/bigbinary.dat";
  open OUT, ">bigbinary.dat";
  $res = $http->request($url, \&savetofile, OUT);
  close OUT;

=item set_callback ( $functionref, $dataref )

At various stages of the request, callbacks may be used to modify the
behaviour or to monitor the status of the request.  These work like the
$data_callback parameter to request(), but are more verstaile.  Using
set_callback disables $data_callback in request()

The callbacks are called as: 
  callback ( $self, $phase, $dataref, $cbargs )

The current phases are:

  connect - connection has been established and headers are being
            transmitted.
            
  content-length - return value is used as the content-length.  If undef,
            and prepare_post() was used, the content length is
            calculated.
                   
  done-headers - all headers have been sent
  
  content - return value is used as content and is sent to client.  Return
            undef to use the internal content defined by prepare_post().
            
  content-done - content has been successfuly transmitted.
  
  data - A block of data has been received.  The data is referenced by
            $dataref.  The return value is dereferenced and replaces the
            content passed in.  Return undef to avoid using memory for large
            documents.

  done - Request is done.

=item prepare_post ( $hashref )

Takes a reference to a hashed array of post form variables to upload. 
Create the HTTP body and sets the method to POST.

=item http11_mode ( 0 | 1 )

Turns on or off HTTP/1.1 support.  This is off by default due to
broken HTTP/1.1 servers.  Use 1 to enable HTTP/1.1 support.

=item add_req_header ( $header, $value )

=item get_req_header ( $header )

=item delete_req_header ( $header )

Add, Delete, or a HTTP header(s) for the request.  These functions
allow you to override any header.  Presently, Host, User-Agent,
Content-Type, Accept, and Connection are pre-defined by the HTTP::Lite
module.  You may not override Host, Connection, or Accept.

To provide (proxy) authentication or authorization, you would use:

    use HTTP::Lite;
    use MIME::Base64;
    $http = new HTTP::Lite;
    $encoded = encode_base64('username:password');
    $http->add_req_header("Authorization", $encoded);

B<NOTE>: The present implementation limits you to one instance
of each header.

=item body

Returns the body of the document retured by the remote server.