MAN page from OpenSuSE perl-NetxAP-0.02-bp157.1.1.x86_64.rpm
Net::xAP
Section: User Contributed Perl Documentation (3)
Updated: 2013-04-15
Index NAME
Net::xAP - A base class for protocols such as IMAP, ACAP, IMSP, and ICAP.
SYNOPSIS
"use Net::xAP;"WARNING: This code is in alpha release. Expect the interface tochange from release to release.
DESCRIPTION
This base class implements the substrate common across the
IMAP, ACAP,IMSP, and
ICAP protocols. It provides the interface to the networkcalls and implements a small amount of glue to assist in implementinginterfaces to this protocol family.
END-PROGRAMMER METHODS
The following methods are potentially useful for end-programmers.
last_command_time
Return what time the most recent command was sent to the server. Thereturn value is a
"time" integer.
connection
Returns the connection object being used by the object.
PROTOCOL-DEVELOPER METHODS
The following methods are probably only useful to protocol developers.
new $host, $peerport [, %options]
Create a new instance of Net::xAP, connects to
$host, and returns areference to the object.
The $host parameter is the name of the host to contact. If$host starts with a "/" character, the parameter is assumed tocontain the name of a program and the given program is spawned as achild process. This is useful for driving programs that can beoperated interactively from the command-line, such as UW-imapd.
The $peerport parameter specifies the TCP port used for the networkconnection. The parameter should be in the syntax understood by"IO::Socket::INET->new". This parameter is ignored if a childprocess is spawned.
The %options parameter specifies any options to use. The followinglist enumerates the options, and their default values, currentlyunderstood by "Net::xAP":
- "Synchronous => 1"
- Setting this option causes "Net::xAP" to issue a "response" methodimmediately after sending the command to the server. Currently, thisoption should always be left on. Non-synchronous command/responseprocessing has not been tested.
One down-side to Synchronous mode is that commands cannot be sent tothe server from within a callback. Instead, the results should besaved, and the commands should be sent after the current command hascompleted.
- "NonSyncLits => 0"
- Setting this option causes "Net::xAP" to use non-synchronizingliterals. This should only be enabled if the protocol and server thisfeature.
- "Debug => 0"
- Setting this option causes debug output to be written to "stderr".See the "debug_print" method for a description of the output format.
- "InternetDraft => 0"
- Setting this option adds support for various extensions that are stillin Internet Draft. This option is only intended to be used byprotocol developers. Most bug reports related to this feature will beignored.
All options are also passed to the internal call to"IO::Socket::INET->new", unless a child IMAP process is spawned.
command $callback, $command [, @args]
The
"command" is used to send commands to the server.
The $callback parameter should be a reference to a subroutine. Itwill be called when a response is received from the server.
@args is a list of $type-$value pairs. The $typeindicates what type of data type to use for $value. This is usedto control the encoding necessary to pass the command arguments to theserver.
The following $types are understood:
- "ATOM"
- The data will sent raw to the server.
- "ASTRING"
- The data will be sent to the server as an atom, a quoted string, or aliteral depending on the content of $value.
- "PARENS"
- The data in $value will be interpreted as an array reference and besent inside a pair of parentheses.
- "STRING"
- The data will be sent to the server as either a quoted string orliteral depending on the content of $value.
- "QSTRING"
- The data will be sent to the server as a quoted string.
If the "Synchronous" option is set this method will return a responseobject, otherwise it will return the sequence number associated withthe command just sent to the server.
parse_fields $str
Splits the specified
$str into fields. A list reference isreturned contain the individual fields. Parenthetical clauses arerepresented as nested list references of arbitrary depth. Quotedstrings are stripped of their surrounding quotes and escaped
"\\" and
"\"" characters are unescaped.
response
Reads response lines from the server until one of the lines is acompletion response. For each response, the appropriate callbacks aretriggered. This is automatically called if the
"Synchronous" optionis on.
getline
Get one 'line' of data from the server, including any literal payloads.
close_connection
Closes the connection to the server, returning the results of theoperation.
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.
The list is sorted numerically.
debug [$boolean]
Returns the value of the debug option for the object.
If $boolean is specified, the debug state is set to the given value.
debug_print $direction, $text
Prints
$text to
"STDERR", preceded by an indication of trafficdirection, the object reference, and a timestamp. The parameter
$direction is used to indicate the direction of the traffic relatedto the debug call. Use
0 for data being sent to the server, or
1 for data coming from the server.
debug_text $text
A stub method intended to be overridden by subclasses. It providessubclasses with the ability to make alterations to
$text beforebeing output by
"debug_print" method. The base class version does noalteration of
$text.
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
Creates a new response object.
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".
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
Returns a list reference containing the response code portion of theserver response.
CAVEATS
With only a few exceptions, the methods provided in this class areintended for use by developers adding support for additionalprotocols. Don't muck with this level, unless you know what you'redoing.
AUTHOR
Kevin Johnson <
kjjAATTpobox.com>
COPYRIGHT
Copyright (c) 1997-1999 Kevin Johnson <kjjAATTpobox.com>.
All rights reserved. This program is free software; you canredistribute it and/or modify it under the same terms as Perl itself.
Index
- NAME
- SYNOPSIS
- DESCRIPTION
- END-PROGRAMMER METHODS
- last_command_time
- connection
- PROTOCOL-DEVELOPER METHODS
- new $host, $peerport [, %options]
- command $callback, $command [, @args]
- parse_fields $str
- response
- getline
- close_connection
- sequence
- next_sequence
- pending
- debug [$boolean]
- debug_print $direction, $text
- debug_text $text
- RESPONSE OBJECTS
- new
- tag
- status
- text
- status_code
- CAVEATS
- AUTHOR
- COPYRIGHT
This document was created byman2html,using the manual pages.
