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 the IMAP, ACAP, ICAP protocols. It provides the majority of the interface to the network calls and implements a small amount of glue to assist in implementing interfaces to this protocol family.
METHODS
METHODS
new ($host, $peerport [, %options])
Create a new instance of Net::xAP and returns a reference to the object.
The $host parameter is the name of the host to contact.
The $peerport parameter is the tcp port to connect to. The parameter should be in the syntax understood by IO::Socket::INET->new).
%options specifies any options to use. Currently, the only option that Net::xAP uses is Debug. All of the options are passed to a call to IO::Socket::INET->new.
command ($callback, $command [, @args])
The command is used to send commands to the connected server and to setup callbacks for subsequent use by the response method.
The $callback parameter should be a reference to a subroutine that will be called when input is received. This callback is responsible for processing any of the responses from the server that pertain the given command.
@args is a list of $type-$value pairs. The $type says what type of data type to use for $value. The mechanism is used to control the encoding necessary to pass the command arguments to the server.
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 a literal depending on the content of
$value.$xAP_PARENS
The data in
$valuewill be interpreted as an array reference and be sent inside a pair of parentheses.$xAP_STRING
The data will be sent to the server as either a quoted string or literal 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 fields and returns a reference to the list. getline uses the parse_line method to do the parsing.
last_command_time
Return what time the most recent command was sent to the server. It returns 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 still awaiting a complete response from the server. This will also include any recent commands issued without corresponding response methods called. 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 intended to provide subclasses to make alterations to $text for use by the debug_print method. The base-class version does no alteration of $text.
debug_print($direction, $text)
Prints $text to STDERR. The parameter $direction is used to notate what direction the call is interested in - 0 for data being sent 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 are likely 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. This will be OK, NO, or BAD.
status_text
Returns the human readable text assocated with the status of the response object.
This will typically be overridden by a subclass of the xAP class to handle things like status codes.
status_code
parse_status (@list)
CAVEATS
With only a few exceptions, the methods provided in this class are not intended to be used by end-programmers. They are intended to be used by implementers of protocols that use the class.
AUTHOR
Kevin Johnson <kjj@pobox.com>
COPYRIGHT
Copyright (c) 1997 Kevin Johnson <kjj@pobox.com>.
All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.