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.
PROTOCOL-DEVELOPER METHODS
The following methods are probably only useful to protocol developers.new $host, $peerport [, %options]
new $host, $peerport [, %options]
Create a new instance of Net::xAP, connects to $host, and returns a reference to the object.
- "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]
command $callback, $command [, @args]
The "command" is used to send commands 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
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.
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.
Get one 'line' of data from the server, including any literal payloads.
Closes the connection to the server, returning the results of the
operation.
Returns the sequence number of the last command issued to the server.
Returns the sequence number that will be assigned to the next command issued.
Returns a list of sequence numbers for the commands that are still awaiting a complete response from the server.
The list is sorted numerically.
Returns the value of the debug option for the object.
If $boolean is specified, the debug state is set to the given value.
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.
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.
Returns the tag associated with the response object.
Returns the command status associated with the response object. This
will be "OK", "NO", or "BAD".
Returns the human readable text assocated with the status of the response object.
Returns a list reference containing the response code portion of the server response.