ACAP sessions, states, and commands are very similar to IMAP4revl. This is intentional, since the protocol structure defined in IMAP is very flexible. ACAP, like IMAP and many other Internet protocols, is line oriented with lines ending in CRLF sequences.

ACAP sessions may be in one of three states at anyone time. These states are:

Upon initial connection to an ACAP server, a client is in the Nonauthenticated State. A client enters the Authenticated State when a user logs into the server, providing the appropriate type of authentication credentials.

Once logged in, a client may search, add, or remove information in any dataset for which the authenticated user has been allowed access.

The Logout State is entered when a client logs out, a server refuses service, or a connection is otherwise interrupted. This state lasts just long enough for the client and server to close a connection.

Within each state, the client may issue the commands appropriate to that state.

Like IMAP, an ACAP client is required to be able to accept any server response at any time. This recognizes the multithreaded nature of modern MUAs, since they may very well issue multiple commands to a server simultaneously from different threads.

An ACAP client precedes each command with a pseudo-random alphanumeric string, or tag. This is done exactly as in IMAP commands. Server responses include a copy of the tag so that the client may determine to which command the server is responding. Clients should use a different tag for each command that they issue.

ACAP server responses are very similar to IMAP server responses. You may recall that an IMAP server response may contain either tagged or untagged lines. The tagged lines contain an explicit response to the client’s request, and untagged lines may provide additional explanatory information. ACAP server’s work the same way.

An ACAP server responds to requests with one of several status responses. The status responses for an IMAP server are OK, NO, BAD, PREAUTH, and BYE. The ACAP status responses are OK, NO, BAD, ALERT, and BYE. The only difference is ALERT, that informs the client of a condition that the client must display to the user. Each status response can contain an additional response code, which provides detailed information about a problem. Server response codes are described in Table 12-2.

The table contains references to ACAP commands. Although these commands have not yet been introduced, they are included here for later reference. ACAP commands have reasonably straightforward names, so reading them with prior knowledge of lMAP command names should not be difficult.

When a client initiates an ACAP session, the server responds with a banner greeting consisting of an untagged ACAP response. Unlike other protocols, an ACAP server includes its capabilities in this banner greeting, which are provided as a list of parenthesized named values. The capabilities may include any of the following:

A banner greeting for an ACAP server might look like this:

Client:  <establishes connection>
Server:  * ACAP (IMPLEMENTATION "Plugged In ACAP Server v1. 03" )
         (CONTEXTLIMIT "150") (SASL "CRAM-MD5" "KERBEROS_V4")

From the banner, we can see that this ACAP server was created by Plugged In and has a version number of 1. 03. It can support up to 150 contexts per connection, and it supports both CRAM-MD5 and KERBEROS Version 4 authentication. The CRAM-MD5 authentication mechanism is the default and is discussed in more detail in this section.

Three ACAP commands are valid in any state. They are: NOOP, LANG, and LOGOUT. We know about NOOP (no operation) from other protocols.

LANG allows a client to indicate its language preferences. LOGOUT, naturally, is used to end a session.

The LANG command is used by a client that wishes the server to switch languages. The client provides a list of languages that it prefers, and the server switches to the first language in the client’s list that it supports. The server also returns the language that it is now using and a list of comparison operators that may be used for searches in that language. Comparison operators are described in the section “The Authenticated State,” under the SEARCH command. For example:

Client: AC23 LANG "en-au" "en-ca" "en-uk" "en-us"
Server: AC23 LANG "en-au" "i;octet" "i;ascii-numeric" "en;primary"
Server: AC23 OK "G'day, Mate"

The example shows a client asking a server to switch to one of several English variants. In this case, Australian English is requested, and the server switches to it. This can be seen from the greeting given in the response line. Comparison operators may be used with the SEARCH command and will be explained later.

The LOGOUT command simply informs the server that the client will not be issuing further commands. It looks like this:

Client: AC24 LOGOUT
Server: * BYE "See ya later"
Server: AC24 OK "LOGOUT completed"
(connection is closed by both parties)

Table 12-3 lists the ACAP commands that are valid in any state.