NAME

ZipTie::HTTP - Agent/client for performing various HTTP/HTTPS requests.

SYNOPSIS

        use ZipTie::HTTP;

        my $http_agent = ZipTie::HTTP->new();
        $http_agent->connect("HTTP", "10.10.10.10", 80, "someUsername", "somePassword");

        my $index_page_response = $http_agent->get("index.html");

DESCRIPTION

ZipTie::HTTP serves an agent/client for performing various HTTP/HTTPS requests. It utilizes much of the LWP modules (LWP::UserAgent, HTTP::Reponse, HTTP::Request, etc.) to provide an easy interface for performing GET and POST requests. Please refer to the documentation for LWP for more understanding and context around the modules that provide the core functionality to this module.

In order to enable HTTPS support, the Crypt::SSLeay module must be properly installed on your system. This is not a requirement of ZipTie::HTTP explicitly, but is implicit because the underlying functionality provided by the LWP and HTTP modules utilize the Crypt::SSLeay module. Refer to the ``SEE ALSO'' section of this documentation for link to the Crypt::SSLeay module documentation.

METHODS

new()

Creates a new instance of the ZipTie::HTTP module with a default timeout value of 30 seconds. This value can be altered by a call to set_timeout($timeout).

After creating a new instance of the ZipTie::HTTP module, it is assumed that the connect($protocol_name, $ip_address, $port, $username, $password) method will be called in order to establish and verify a connection a the HTTP/HTTPS enabled device.

connect($protocol_name, $ip_address, $port, $username, $password, $relativeUrl)

Connects to a device at a specified IP address and port using the specified protocol and any credentials that may be required. The protocol that is specified must either be ``HTTP'' or ``HTTPS'', with it being case-insensitive. Also, the username and password parameters are optional depending on whether or not the device requires username/password authentication.

In order to use HTTPS to connect to a device, the Crypt::SSLeay module must be properly installed. Refer to the ``SEE ALSO'' section of this documentation for link to the Crypt::SSLeay module documentation.

$protocol_name -	The name of the protocol to use, either HTTP or HTTPS is supported.
$ip_address -	The administrative IP address of a device.
$port -	The port to connect to on the device.
$username -	Optional. The username credential for the device.
$password -	Optional. The password credential for the device.
$relativeUrl -	Optional. The relativeUrl to connect to. This is usually necessary if an HTTPS server requires that you login using some page
	other than the root.

get($relative_url)

Sends a HTTP GET request to a URL that is relative the the hostname/IP address that this ZipTie::HTTP object is currently connected to; the results from the request will be retrieved.

$relative_url -	A URL that is relative to the hostname/IP address that this `ZipTie::HTTP object` is already connected to.
	For example, if connected to ``10.100.10.10'', the relative URL could be something like ``home.htm'' or
	``someone/somedir/righthere/blarg.htm''.

Depending on the context of the call, different values will be returned. If a scalar return context is desired, the raw HTML contents of the GET request response will be returned. If an array/list return context is desired, the raw HTML contents along with a HTTP::Response object that encapsulates the raw response will be returned.

post($relative_url, $form_ref)

Sends a HTTP POST request to a URL that is relative the the hostname/IP address that this ZipTie::HTTP object is currently connected to. This method is essentially an interface to the LWP::UserAgent method, which itself is just a wrapper for the HTTP::Request::Common::POST method fuctionality. Refer to the documentation for either of these modules/methods for more information on the parameters passed in.

$relative_url -	A URL that is relative to the hostname/IP address that this `ZipTie::HTTP` object is already connected to.
	For example, if connected to ``10.100.10.10'', the relative URL could be something like ``home.htm'' or
	``someone/somedir/righthere/blarg.htm''.

$form_ref -	A reference to either a hash or array that stores key-value pairs for any addition parameters and/or headers
	that should be part of this `POST` request. This will eventually be passed to the `HTTP::Request::Common::POST`
	method, so please refer to its documentation if more context is required.

Depending on the context of the call, different values will be returned. If a scalar return context is desired, the raw HTML contents of the POST request response will be returned. If an array/list return context is desired, the raw HTML contents along with a HTTP::Response object that encapsulates the raw response will be returned.

get_ip_address()

Retrieves the IP address that this ZipTie::HTTP object is connected to.

get_port()

Retrieves the port that this ZipTie::HTTP object is connected over.

get_protocol_name()

Retrieves the name of the protocol used by this ZipTie::HTTP object for connecting to a server. This will either be ``HTTP'' or ``HTTPS'' but will be case-insensitive.

get_timeout()

Retrieves the time, in seconds, that this ZipTie::HTTP object will wait before timing out during a connection or specific request.

set_timeout($timeout)

Specifies the time, in seconds, that this ZipTie::HTTP object will wait before timing out during a connection or specific request.

ZipTie::HTTPClient Inner Class

NAME

ZipTie::HTTPClient - Inner-class of the ZipTie::HTTP module to handle username/password credential authentication.

SYNOPSIS

DESCRIPTION

The ZipTie::HTTPClient is an inner-class of the ZipTie::HTTP module that handles username/password credential authentication. This is achieved by extending the LWP::UserAgent module to always return a particular username and password anytime a call is made to get_basic_credentials method. This allows one to control the exact username and password that is should be used without having to parse every single HTTP header after a request to figure out what the realm is for authentication.

METHODS THAT ARE OVERWRITTEN

get_basic_credentials(): Overrides the LWP::UserAgent::get_basic_credentials() module to return the username and password values set by calls to set_username($username) and set_password($password).

METHODS

new(@args): Creates a new instance of the ZipTie::HTTPClient class, which is just an implementation of the LWP::UserAgent class. Any possible arguments that could be passed into the constructor for the LWP::UserAgent module can also be passed into this method.
set_username($username): Sets the username credential that will be used in any authentication is required by any requests.
set_password($password): Sets the password credential that will be used in any authentication is required by any requests.

LICENSE

The contents of this file are subject to the AlterPoint Open Technology License (the ``License''); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://inventory.alterpoint.com/license

Software distributed under the License is distributed on an ``AS IS'' basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.

The Original Code is Ziptie Client Framework.

AUTHOR

Contributor(s): dwhite (dylamite@ziptie.org) Date: Jun 28, 2007