/ 
Net-ICAP-0.04
River stage zero No dependents
/ Net::ICAP::Message

NAME

Net::ICAP::Message - Base class for requests & responses

VERSION

$Id: lib/Net/ICAP/Message.pm, 0.04 2017/04/12 15:54:19 acorliss Exp $

SYNOPSIS

use Net::ICAP::Message;

$msg    = new Net::ICAP::Message;
$rv     = $msg->parse($fh);
@errors = $obj->error;

$value      = $obj->header($name);
%headers    = $obj->getHeaders;
$reqheader  = $obj->reqhdr;
$resheader  = $obj->reshdr;
($type, $body) = $obj->body;
$trailer    = $obj->trailer;
$version    = $obj->version;
$ieof       = $obj->ieof;

$msg = Net::ICAP::Message->new(
    headers => {
        Date    => $date,
        Expires => $exp,
        },
    );
$rv = $obj->body($type, $body);
$rv = $obj->header($name, $value);
$rv = $obj->setHeaders(%headers);
$rv = $obj->reqhdr($text);
$rv = $obj->reshdr($text);
$rv = $obj->body($type, $text);
$rv = $obj->trailer($text);
$rv = $obj->version($version);
$rv = $obj->ieof($bool);

$rv     = $msg->generate($fh);
@errors = $obj->error;

DESCRIPTION

This is the base class from which Net::ICAP::Request and Net::ICAP::Response are built on. It provides the parsing engine for extracting the various portions of an ICAP message, namely:

o Start/Status line
o ICAP headers
o HTTP Request/Response headers
o HTTP Body
o HTTP trailer

To that end, this class automatically verifies valid ICAP header names (but not values), as well as extracting and validating the message body as per the Encapsulated header's values. It, obviously, has to know how to perform chunked encoding & decoding as well.

Net::ICAP::Message is also a message generator ahd, as such, can construct encoded messages based on the data handed to it.

As a base class this is not meant to be used directly.

SUBROUTINES/METHODS

PUBLIC METHODS

The following methods are provided as part of a public API to be used by external code.

body

($type, $body) = $obj->body;
$rv            = $obj->body($type, $body);

Sets or gets the body type and content. Type must be a value consisting of either ICAP_REQ_BODY, ICAP_RES_BODY, ICAP_OPT_BODY, or ICAP_NULL_BODY. The body is assumed to be in raw (NOT chunked encoded) format.

error

$obj->error($msg);
@errors = $obj->error;

Adds an error message to the internal array, or retrieves an array of string error messages. This internal array is reset with every call to the parse method.

$value = $obj->header($name);
$rv    = $obj->header($name, $value);

This method gets or sets a named header. The header named must be recognized as a valid ICAP header. Setting any valid header to a either undef or a zero-length string will cause the header to be deleted.

getHeaders

%headers = $obj->getHeaders;

This method retrieves all ICAP headers set to date.

setHeaders

$rv = $obj->setHeaders(%headers);

This method sets the ICAP headers en masse. All previous headers are purged, and invalid headers ignored. This will return false if invalid headers are declared. Passing it an empty hash will effectively be a no-op.

parse

$rv = $obj->parse($ref);

This method reads from the passed reference and attempts to parse the content. The passed reference can be either a scalar reference, a file handle, or an IO::Handle object. In the case of a scalar reference the read is destructive in that every line read (terminated by \\r\\n) is deleted from the strings content.

In the event of a parsing error this method will simply stop reading and return false. This means you may have additional input that needs to be drained before you can effectively issue a response.

generate

$rv = $obj->generate($ref);

This method generates an ICAP message based on the internal state data. It accepts a reference to write to, which can be either a scalar reference, a file handle, or an IO::Handle object. In the case of a scalar reference it does not erase any previous contents, it appends to it.

This method automatically adds the Date header if it isn't already present.

reqhdr

$rv     = $obj->reqhdr($text);
$header = $obj->reqhdr;

This method gets or sets the HTTP request header.

reshdr

$rv     = $obj->reshdr($text);
$header = $obj->reshdr;

This method gets or sets the HTTP response header.

trailer

$rv     = $obj->reshdr($text);
$header = $obj->reshdr;

This method gets or sets the HTTP headers which were passed as part of the HTTP trailer, rather than in the actual header block itself.

version

$rv     = $obj->version($version);
$method = $obj->version;

This method gets or sets the ICAP protocol version string. It does perform validation of the string and will ignore any unknown strings.

ieof

$rv     = $obj->ieof($val);
$ieof   = $obj->ieof;

This sets or detects whether an ieof marker should be (or was) sent during chunked (de|en)coding.

RESTRICTED METHODS

To do.

DEPENDENCIES

Class::EHierarchy
Paranoid

BUGS AND LIMITATIONS

Positively.

AUTHOR

Arthur Corliss (corliss@digitalmages.com)

LICENSE AND COPYRIGHT

This software is licensed under the same terms as Perl, itself. Please see http://dev.perl.org/licenses/ for more information.

(c) 2013, Arthur Corliss (corliss@digitalmages.com)