MAN page from Mandrake Other perl-NetxAP-0.01-1.i386.rpm

Net::xAP

Section: User Contributed Perl Documentation (3)
Updated: perl 5.004, patch 04
Index

NAME

Net::xAP - An interface to the protocol beneath IMAP, ACAP, and ICAP.

WARNING: This code is in alpha release. Expect the interface to change.

SYNOPSIS

use Net::xAP;

DESCRIPTION

This base class implements the protocol that is common across theIMAP, ACAP, ICAP protocols. It provides the majority of the interfaceto the network calls and implements a small amount of glue to assistin implementing interfaces to this protocol family.

METHODS

new ($host, $peerport [, %options])

Create a new instance of Net::xAP and returns a reference to theobject.

The $host parameter is the name of the host to contact.

The $peerport parameter is the tcp port to connect to. Theparameter should be in the syntax understood byIO::Socket::INET->new).

%options specifies any options to use. Currently, the only optionthat Net::xAP uses is Debug. All of the options are passed to acall to IO::Socket::INET->new.

command ($callback, $command [, @args])

The command is used to send commands to the connected server and tosetup callbacks for subsequent use by the response method.

The $callback parameter should be a reference to a subroutine thatwill be called when input is received. This callback is responsiblefor processing any of the responses from the server that pertain thegiven command.

@args is a list of $type-$value pairs. The $type sayswhat type of data type to use for $value. The mechanism is used tocontrol the encoding necessary to pass the command arguments to theserver.

The following $types are understood:

• $xAP_ATOM: The data will sent raw to the server.
• $xAP_ASTRING: The data will be sent to the server as an atom, a quoted string, or aliteral depending on the content of $value.
• $xAP_PARENS: The data in $value will be interpreted as an array reference and besent inside a pair of parentheses.
• $xAP_STRING: The data will be sent to the server as either a quoted string orliteral depending on the content of $value.

parse_line

as_astring

as_string

send_command

response

getline

Gets one line of data from the server, parses it into a list of fieldsand returns a reference to the list. getline uses theparse_line method to do the parsing.

last_command_time

Return what time the most recent command was sent to the server. Itreturns value as a time integer.

connection

Returns the connection object being used by the object.

sequence

Returns the sequence number of the last command issued to the server.

next_sequence

Returns the sequence number that will be assigned to the next command issued.

pending

Returns a list of sequence numbers for the commands that are stillawaiting a complete response from the server. This will also includeany recent commands issued without corresponding response methodscalled. NEEDS TO BE REWORDED

The list is sorted numerically.

debug ([$boolean])

Returns the value of the debug flag for the object.

If $boolean is specified, set the debug state to the given value.

debug_text ($text)

A stub method intended to be overridden by subclasses. It is intendedto provide subclasses to make alterations to $text for use by thedebug_print method. The base-class version does no alteration of$text.

debug_print($direction, $text)

Prints $text to STDERR. The parameter $direction is used tonotate what direction the call is interested in - 0 for data beingsent to the server, 1 for data coming from the server.

This mechanism might change in the future...

Response Objects

A response object is the data type returned by the response method.A few convenience routines are provided at the Net::xAP level that arelikely to be common across several protocols.

new

tag

Returns the tag associated with the response object.

status

Returns the command status associated with the response object. Thiswill be OK, NO, or BAD.

status_text

Returns the human readable text assocated with the status of theresponse object.

This will typically be overridden by a subclass of the xAP class tohandle things like status codes.

status_code

parse_status (@list)

CAVEATS

With only a few exceptions, the methods provided in this class are notintended to be used by end-programmers. They are intended to be usedby implementers of protocols that use the class.

AUTHOR

Kevin Johnson <kjjAATTpobox.com>

COPYRIGHT

This document was created byman2html,using the manual pages.