NAME

Net::SMS::HTTP - Lightweight HTTP implementation

SYNOPSIS

    use Net::SMS::HTTP;
    $http = new Net::SMS::HTTP;
    $req = $http->request("http://www.cpan.org/") 
        or die "Unable to get document: $!";
    print $http->body();

DESCRIPTION

    Net::SMS::HTTP is a stand-alone lightweight HTTP/1.1
    implementation for perl.  It is not intended to replace LWP,
    but rather is intended for use in situations where it is
    desirable to install the minimal number of modules to
    achieve HTTP support, or where LWP is not a good candidate
    due to CPU overhead, such as slower processors.

    Net::SMS::HTTP is ideal for CGI (or mod_perl) programs or for
    bundling for redistribution with larger packages where only
    HTTP GET and POST functionality are necessary.

    Net::SMS::HTTP supports basic POST and GET operations only.  As
    of 0.2.1, Net::SMS::HTTP supports HTTP/1.1 and is compliant with
    the Host header, necessary for name based virtual hosting. 
    Additionally, HTTP::Live now supports Proxies.

    If you require more functionality, such as FTP or HTTPS,
    please see libwwwperl (LWP).  LWP is a significantly better
    and more comprehensive package than Net::SMS::HTTP, and should
    be used instead of Net::SMS::HTTP whenever possible.

CONSTRUCTOR

new

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

METHODS

request ( URL )

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 http://www.w3.org/Protocols/HTTP/HTRESP.html for detailled information about HTTP status codes.

prepare_post

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 Net::SMS::HTTP module. You may not override Host, Connection, or Accept.

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

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

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

body

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

headers_array

Returns an array of the HTTP headers returned by the remote server.

headers_string

Returns a string representation of the HTTP headers returned by the remote server.

get_header ( $header )

Returns an array of values for the requested header.

NOTE: HTTP requests are not limited to a single instance of each header. As a result, there may be more than one entry for every header.

protocol

Returns the HTTP protocol identifier, as reported by the remote server. This will generally be either HTTP/1.0 or HTTP/1.1.

proxy ( $proxy_server )

The URL or hostname of the proxy to use for the next request.

status

Returns the HTTP status code returned by the server. This is also reported as the return value of request().

status_message

Returns the textual description of the status code as returned by the server. The status string is not required to adhere to any particular format, although most HTTP servers use a standard set of descriptions.

response

Returns the entire unparsed HTTP response as returned by the server.

reset

You must call this prior to re-using an Net::SMS::HTTP handle, otherwise the results are undefined.

EXAMPLES

    # Get and print out the headers and body of the CPAN homepage
    use Net::SMS::HTTP;
    $http = new Net::SMS::HTTP;
    $req = $http->request("http://www.cpan.org/")
        or die "Unable to get document: $!";
    die "Request failed ($req): ".$http->status_message()
      if $req ne "200";
    @headers = $http->headers_array();
    $body = $http->body();
    foreach $header (@headers)
    {
      print "$header$CRLF";
    }
    print "$CRLF";
    print "$body$CRLF";

    # POST a query to the dejanews USENET search engine
    use Net::SMS::HTTP;
    $http = new Net::SMS::HTTP;
    %vars = (
             "QRY" => "perl",
             "ST" => "MS",
             "svcclass" => "dncurrent",
             "DBS" => "2"
            );
    $http->prepare_post(\%vars);
    $req = $http->request("http://www.deja.com/dnquery.xp")
      or die "Unable to get document: $!";
    print "req: $req\n";
    print $http->body();

UNIMPLEMENTED

    - FTP 
    - HTTPS (SSL)
    - Authenitcation/Authorizaton/Proxy-Authorization
      are not directly supported, and require MIME::Base64.
    - Redirects (Location) are not automatically followed
    - multipart/form-data POSTs are not supported (necessary for
      File uploads).
    

BUGS

    Some bugs likely still exist.  This is a beta version.
    
    Large requests are stored in ram, potentially more than once
    due to HTTP/1.1 chunked transfer mode support.  A future
    version of this module may support writing requests to a
    filehandle to avoid excessive disk use.

COPYRIGHT

Copyright (c) 2001 Simplwire. All rights reserved.

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