GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  BIO::DAS::HTTP::FETCH (3)

.ds Aq ’

NAME

Bio::Das::HTTP::Fetch - Manage the HTTP protocol for DAS transactions

CONTENTS

SYNOPSIS



 my $fetcher      = Bio::Das::HTTP::Fetch->new(
                                    -request   => $request,
                                    -headers   => {Accept-encoding => gzip},
                                    -proxy     => $proxy,
                                    -norfcwarn => $nowarn,
                  );

 $fetcher->send_request();
 $fetcher->read();

 my $request          = $fetcher->request;
 my $socket           = $fetcher->socket;
 my $error            = $fetcher->error;
 my $url              = $fetcher->url;
 my $path             = $fetcher->path;
 my $outgoing_args    = $fetcher->outgoing_args;
 my $outgoing_headers = $fetcher->outgoing_headers;
 my $auth             = $fetcher->auth;
 my $incoming_header  = $fetcher->incoming_header;
 my $method           = $fetcher->method;

 my $protocol         = $fetcher->mode([$new_protocol]);
 my $status           = $fetcher->status([$new_status]);
 my $debug            = $fetcher->debug([$new_debug]);

 my ($protocol,$host,$port,$path,$user,$pass) = $fetcher->parse_url($url);



DESCRIPTION

This is a low-level class that is used for managing multiplexed connections to DAS HTTP servers. It is used internally by Bio::Das and it is unlikely that application programs will ever interact with it directly. The exception is when writing custom authentication subroutines to fetch username/password information for password-protected servers, in which case an Bio::Das::HTTP::Fetch is passed to the authentication subroutine.

    METHODS

Following is a complete list of methods implemented by Bio::Das::HTTP::Fetch.
$fetcher = Bio::Das::HTTP::Request->new(@args) Create a new fetcher object. At the time the object is created, it will attempt to establish a non-blocking connection with the remote server. This means that the call to new() may be returned before the connection is established.

Arguments are as follows:



  Name         Description
  ----         -----------

  -request     The Bio::Das::Request to run.

  -headers     A hashref containing additional
               headers to attach to the HTTP request.
               Typically used to enable data stream compression.

  -proxy       An HTTP proxy to use.

  -norfcwarn   Disable the warning that appears when the request
               contains username/password information attached to
               the URL.

  -debug       Activate verbose debugging messages



$socket = $fetcher->socket Return the IO::Socket associated with the HTTP request. The socket is marked nonblocking and may not yet be in a connected state.
$path = $fetcher->path Return the path part of the HTTP request.
$request = $fetcher->request Return the Bio::Das::Request object that the fetcher will attempt to satisfy.
$args = $fetcher->args Returns a hashref containing the CGI arguments to be passed to the HTTP server. This is simply delegated to the request’s args() method.
$url = $fetcher->url Returns the URL for the HTTP request. This is simply delegated to the request’s url() method.
$headers = $fetcher->outgoing_headers Returns a hashref containing the HTTP headers that will be sent in the request.
$host = $fetcher->host Returns the host to which the fetcher will connect. Note that this is <B>notB> necessarily the same host as the DAS server, as this method will return the name of the <B>proxyB> if an HTTP proxy has been specified. To get the DAS server hostname, call $fetcher->request->host.
$credentials = $fetcher->auth Return the authentication credentials as a base64-encoded string.
$header = $fetcher->incoming_header Retrieve the incoming HTTP header. Depending on the state of the connection, the header may be empty or incomplete.
$mode = $fetcher->mode([$new_mode]) This misnamed method gets or sets the protocol, which is one of ’http’ for regular cleartext transactions or ’https’ for transactions using the encrypting SSL/TLS protocol. Note that you must have IO::Socket::SSL and its associated libraries in order to use SSL/TLS.
$mode = $fetcher->mode([$new_mode]) This misnamed method gets or sets the protocol, which is one of ’http’ for regular cleartext transactions or ’https’ for transactions using the encrypting SSL/TLS protocol. Note that you must have IO::Socket::SSL and its associated libraries in order to use SSL/TLS.
$status = $fetcher->status([$new_status]) This method is used to interrogate or change the status of the transaction. The status keeps track of what has been done so far, and is one of:



  waiting          # request not yet sent
  reading header   # request sent, waiting for HTTP header
  reading body     # HTTP header received, waiting for HTTP body
  parsing body     # HTTP body partially received, parsing it
  0                # transaction finished normally, EOF.



$debug = $fetcher->debug([$new_debug]) Get or set the debug flag, which enables verbose diagnostic messages.
($protocol,$host,$port,$path,$user,$pass) = Bio::Das::HTTP::Fetch->parse_url($url,$norfcwarn) This method is invoked as a class method (as Bio::Das::HTTP::Fetch->parse_url) to parse a URL into its components. The $norfcwarn flag inhibits a warning about the unsafe nature of embedding username/password information in the URL of unencrypted transactions.
$socket = Bio::Das::HTTP::Fetch->connect($protocol,$host,$port) This method is used to make a nonblocking connection to the indicated host and port. $protocol is one of ’http’ or ’https’. The resulting IO::Socket will be returned in case of success. Undef will be returned in case of other errors.
$status = $fetcher->send_request() This method sends the HTTP request and returns the resulting status. Because of the vagaries of nonblocking IO, the complete request can be sent in one shot, in which case the returned status will be reading header, or only a partial request might have been written, in which case the returned status will be waiting. In the latter case, send_request() should be called again until the complete request has been submitted.

If a communications error occurs, send_request() will return undef, in which case it should not be called again.

$status = $fetcher->read() This method is called when the fetcher is in one of the read states (reading header, reading body or parsing body). If successful, it returns the new status. If unsuccessful, it returns undef.

On the end of the transaction read() will return numeric 0.

$http_request_string = $fetcher->format_request This method generates the appropriate GET or POST HTTP request and the HTTP request headers.
$cgi_query_string = $fetcher->format_args This method generates the CGI query string.
$headers = $fetcher->format_headers This method generates the outgoing HTTP request headers, for use by format_request().
$escaped_string = $fetcher->escape($unescaped_string) This method performs URL escaping on the passed string.
$canonicalized_string = $fetcher->canonicalize($uncanonicalized_string) This method canonicalizes the case of HTTP headers.
$fetcher->do_headers(@header_lines) This method parses the incoming HTTP header and saves the fields internally where they can be accessed using the headers() method.
$result = $fetcher->do_body($body_data) This method handles the parsing of the DAS document data by sending it to the Bio::Das::Request object. It returns a true result if parsing was successful, or false otherwise.
$error = $fetcher->error([$new_error]) When called without arguments, error() returns the last error message generated by the module. When called with arguments, error() sets the error message and returns undef.
$fetcher->load_ssl This method performs initialization needed to use SSL/TLS transactions.
$fetcher->complete_ssl_handshake($sock) This method is called to complete the SSL handshake, which must be performed in blocking mode. After completing the connection, the socket is set back to nonblocking.

AUTHOR

Lincoln Stein <lstein@cshl.org>.

Copyright (c) 2001 Cold Spring Harbor Laboratory

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See DISCLAIMER.txt for disclaimers of warranty.

SEE ALSO

Bio::Das::Request, Bio::Das::HTTP::Fetch, Bio::Das::Segment, Bio::Das::Type, Bio::Das::Stylesheet, Bio::Das::Source, Bio::RangeI

POD ERRORS

Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 768: You forgot a ’=back’ before ’=head1’
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 DAS::HTTP::FETCH (3) 2009-08-26

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.