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 to change 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 network calls and implements a small amount
       of glue to assist in implementing interfaces 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.  The return 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 a reference to the
       object.

       The $host parameter is the name of the host to contact.  If $host starts with a "/"
       character, the parameter is assumed to contain the name of a program and the given program
       is spawned as a child process.  This is useful for driving programs that can be operated
       interactively from the command-line, such as UW-imapd.

       The $peerport parameter specifies the TCP port used for the network connection. The
       parameter should be in the syntax understood by "IO::Socket::INET->new".  This parameter
       is ignored if a child process is spawned.

       The %options parameter specifies any options to use.  The following list enumerates the
       options, and their default values, currently understood by "Net::xAP":

       "Synchronous => 1"
           Setting this option causes "Net::xAP" to issue a "response" method immediately after
           sending the command to the server.  Currently, this option should always be left on.
           Non-synchronous command/response processing has not been tested.

           One down-side to Synchronous mode is that commands cannot be sent to the server from
           within a callback.  Instead, the results should be saved, and the commands should be
           sent after the current command has completed.

       "NonSyncLits => 0"
           Setting this option causes "Net::xAP" to use non-synchronizing literals.  This should
           only be enabled if the protocol and server this feature.

       "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 still in Internet
           Draft.  This option is only intended to be used by protocol developers.  Most bug
           reports related to this feature will be ignored.

       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. It will be called when a
       response is received from the server.

       @args is a list of $type-$value pairs.  The $type indicates what type of data type to use
       for $value.  This is used to control the encoding necessary to pass the command arguments
       to the server.

       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 a literal
           depending on the content of $value.

       "PARENS"
           The data in $value will be interpreted as an array reference and be sent inside a pair
           of parentheses.

       "STRING"
           The data will be sent to the server as either a quoted string or literal 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 response object, otherwise it
       will return the sequence number associated with the command just sent to the server.

   parse_fields $str
       Splits the specified $str into fields.  A list reference is returned contain the
       individual fields.  Parenthetical clauses are represented as nested list references of
       arbitrary depth.  Quoted strings 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 a completion response.  For
       each response, the appropriate callbacks are triggered.  This is automatically called if
       the "Synchronous" option is 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 the operation.

   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.

       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 traffic direction, the object
       reference, and a timestamp. The parameter $direction is used to indicate the direction of
       the traffic related to 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 provides subclasses with the
       ability to make alterations to $text before being output by "debug_print" method.  The
       base class version does no alteration 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 are likely 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.  This will be "OK", "NO",
       or "BAD".

   text
       Returns the human readable text associated 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
       Returns a list reference containing the response code portion of the server response.

CAVEATS

       With only a few exceptions, the methods provided in this class are intended for use by
       developers adding support for additional protocols.  Don't muck with this level, unless
       you know what you're doing.

AUTHOR

       Kevin Johnson <kjj@pobox.com>

COPYRIGHT

       Copyright (c) 1997-1999 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.