Net::xAP(3pm)

📦
version 0.02 · 3 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Net::xAP — the base class bestie for IMAP, ACAP, IMSP, and ICAP 💖

perl v5.36.0 · User Contributed Perl Documentation · Net::xAP(3pm)

okay so bestie, pull up a chair 🫶 this is Net::xAP, a base class for protocols like IMAP, ACAP, IMSP, and ICAP. it's giving foundation, it's giving substrate, and it is very much in alpha. lowkey important, so listen up.

✨ SYNOPSIS ✨

use Net::xAP;
⚠️ WARNING, and I mean it: This code is in alpha release. Expect the interface to change from release to release. no cap. don't build your whole personality on it 💀

🌸 DESCRIPTION 🌸

This base class implements the substrate common across the IMAP, ACAP, IMSP, and ICAP protocols. It handles the interface to the network calls, and it does a lil bit of glue work to help you implement interfaces to this whole protocol family. it's the friend that introduces everyone at the party 🎀

🫶 END-PROGRAMMER METHODS 🫶

The following methods are potentially useful for end-programmers. (yes, that's you, you're the end-programmer, hi 👋)

last_command_time

Returns 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. that's it. that's the whole vibe 🔥

🧚 PROTOCOL-DEVELOPER METHODS 🧚

The following methods are probably only useful to protocol developers. if that's not you, you can still read it, I'm not gonna gatekeep 💅

new $host, $peerport [, %options]

Creates a new instance of Net::xAP, connects to $host, and returns a reference to the object. iconic behavior.

The $host parameter is the name of the host to contact. BUT — if $host starts with a / character, the parameter is assumed to contain the name of a program, and that program gets spawned as a child process. This is useful for driving programs that can be operated interactively from the command-line, such as UW-imapd. slay, we love a dual-purpose parameter.

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. (save it for later, babe 🍓)
  • 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. (yes, that sentence trails off in the original, I'm not fixing it, that's the lore 🙈)
  • 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. main character energy, fr fr.

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. (again, "will sent" is the original wording, I'm preserving it with love 🫶)
  • 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. (wrapped like a lil gift 🎁)
  • 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. bye bestie 👋

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. leave it alone, it's fine 💜

👑 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. treat them nice 🌸

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. three moods, pick one 💅

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. not me warning you and then you mucking with it anyway 😭

🌟 AUTHOR 🌟

Kevin Johnson <kjj@pobox.com>

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.

that's the whole page, bestie 🫶 — brought to you by perl v5.36.0, dated 2022-11-19, and it's Net::xAP(3pm), no cap 💖✨

📦 where this page comes from