<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"/>
<title>SMAP syntax overview</title>
<link rel="stylesheet" href="manpage.css" type="text/css"/>
<link rel="start" href="index.html" title="Cone: COnsole Newsreader And Emailer"/>
<link rel="up" href="smap1.html" title="Appendix A. Simple Mail Access Protocol, Version 1"/>
<link rel="prev" href="smap1.html" title="Appendix A. Simple Mail Access Protocol, Version 1"/>
<link rel="next" href="conn.html" title="SMAP connection negotiation"/>
<link xmlns="" rel="icon" href="icon.gif" type="image/gif"/>
<meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/>
<!--
Copyright 2002 - 2007 Double Precision, Inc. See COPYING for distribution
information.
-->
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center" rowspan="1">SMAP syntax
overview</th>
</tr>
<tr>
<td width="20%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="smap1.html" shape="rect">Prev</a> </td>
<th width="60%" align="center" rowspan="1" colspan="1">
Appendix A. Simple Mail Access Protocol, Version
1</th>
<td width="20%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="conn.html" shape="rect">Next</a></td>
</tr>
</table>
<hr/>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="smapsyntax" shape="rect" name="smapsyntax"> </a>SMAP syntax overview</h3>
</div>
</div>
</div>
<p>The rest of this document defines the actual SMAP commands,
but all commands from the client, and replies from the server,
follow the same basic syntax. All SMAP commands, and replies,
use the UTF-8 character set (no matter what the natural
language is used for error messages, or prompts). An SMAP
command is generally one or more words. The words are separated
by at least one whitespace character (U+0020, U+0009, or
U+000D). An SMAP command is terminated by the newline
character, (U+000A).</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>The server does not translate actual message contents to
UTF-8. The server provides the contents of a message as is,
to the client. The UTF-8 character set is used for:</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>Names of folders</p>
</li>
<li>
<p>Error and status messages</p>
</li>
<li>
<p>Search strings</p>
</li>
</ul>
</div>
<p>Other text-based entities already use an implicit
character set (such as US-ASCII for names of E-mail headers)
or are specified as opaque text strings (such as message
unique identifiers, loginid and password) and have no
explicitly defined character set.</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="smaplimits" shape="rect" name="smaplimits"> </a>Maximum limitations and timeouts</h4>
</div>
</div>
</div>
<p><a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2822.txt" target="_top" shape="rect">RFC 2822</a> sets the maximum length of a line
in an E-mail message as 998 characters. This limitation is
applicable to SMAP, since SMAP deals with E-mail.
Additionally, SMAP commands may not exceed 8000 characters.
SMAP servers should accept commands up to 8000 characters
long. SMAP clients should not send commands that exceed 8000
characters in length.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>This, of course, does not apply to binary-formatted
multiline replies, that transfer binary MIME
attachments.</p>
</div>
<p>SMAP servers should terminate inactive SMAP clients. SMAP
servers must have a timeout of at least 30 minutes. SMAP
clients must not wait more than 29 minutes before sending the
next command to the server. SMAP clients that must remain
idle for a prolonged period of time should periodically send
the <code class="literal">NOOP</code> command to prevent
themselves from being disconnected for inactivity.</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id689957" shape="rect" name="id689957"> </a>Words</h4>
</div>
</div>
</div>
<p>A word can contain any character except for a control
character (U+0000 through U+001F). If a word contains spaces
or quotes (U+0020 or U+0022), a quote must be added before
the first character of the word, and a second quote character
must follow the last character of the word. Quotes that are
part of the word are doubled. For example: <code class="literal">"Learning the ""ABC""'s"</code> is a single SMAP
word. The word contains a single quote character before the
letter "A" and a second quote character after the letter "C".
Everything else is as it appears. A word that contains a
single quote character is represented as <code class="literal">""""</code>. A word that's meant to be completely
empty is represented by two quotes: <code class="literal">""</code>.</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id689990" shape="rect" name="id689990"> </a>SMAP server replies</h4>
</div>
</div>
</div>
<p>SMAP server replies also (except where noted) are lines of
text terminated by U+000A. There are three general classes of
server replies. All three of them generally contain either
whitespace-delimited words (formatted similarly), or they
begin with one or more whitespace-delimited words, with the
rest being an informative, free-form message.</p>
<p>SMAP servers are allowed to reply with lines of text
terminated by the CR+LF sequence, U+000D U+000A. The ASCII CR
character is interpreted by SMAP clients as whitespace
filler, and is generally ignored. SMAP servers must be
prepared to receive client commands that use either the CR+LF
or the bare LF newline sequence. The only exception to this
rule is the initial connection negotiation, which must use
CR+LF in order to remain compatible with IMAP.</p>
<p>An SMAP client receives the server's response by reading
an entire U+000A-terminated line, then parsing the first
word, or character, to determine the reply's format.</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="statusreply" shape="rect" name="statusreply"> </a>Status replies</h4>
</div>
</div>
</div>
<p>A line whose first word is either “<span class="quote">+OK</span>” or “<span class="quote">-ERR</span>” is a “<span class="quote">status reply</span>”. “<span class="quote">+OK</span>” indicates that the client's request
succeeded, “<span class="quote">-ERR</span>”
indicates that it failed. The rest of the line is a free-form
message, suitable to be displayed as the original command's
acknowledgement. The status reply does not include any actual
information requested by the original command (if any). The
status reply indicates whether the command succeeded or
failed. Information requested by the original command will be
sent before the status reply, using either a "single line",
or a "multiple line" format (see below). A command can result
in more than one single or multi-line reply. The client,
after sending an SMAP command, keeps reading single and
multi-line replies, until a final status reply is read. After
receiving the status reply, the client may proceed to send
the next server command.</p>
<p>The SMAP client must wait until the status reply is
received before sending the next command.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>In order to allow interoperability with IMAP, server
replies prior to logging in are an exception to this reply
format. They follow the general IMAP syntax.</p>
</div>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="singleline" shape="rect" name="singleline"> </a>Single line replies</h4>
</div>
</div>
</div>
<p>A server reply where the first whitespace-delimited word
is the “<span class="quote">*</span>” character
is called a “<span class="quote">single line
reply</span>”. Single line replies send information,
requested by the original command, formatted as
whitespace-delimited words. The information carried by the
words depends on the reply. The actual format of a single
line reply depends on the original command, but can usually
be determined by the word that follows “<span class="quote">*</span>”. This single-line reply does not
indicate if the client's command succeeded, the client must
still wait to receive the final status reply. The only
exception to this rule is the initial connection greeting, or
the unexpected connection termination situation, which is
described later.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>The client must be prepared to receive multiple single
line and multiple line replies, followed by an
“<span class="quote"><code class="literal">-ERR</code></span>” status reply. This
happens when the server encounters an error in a middle of
processing the client's request.</p>
</div>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="multiline" shape="rect" name="multiline"> </a>Multiple line replies</h4>
</div>
</div>
</div>
<p>Certain information returned by an SMAP server cannot be
conveniently represented as a single line of text. An example
would be the contents of a message. Obviously, messages
contains many lines of text. A server reply whose first word
starts with the '{' character is called a “<span class="quote">multiple line reply</span>”. This name is
actually slightly misleading; this format may carry binary
data that bears no resemblance to lines of text.</p>
<p>There are two separate multi-line reply formats. The first
format is suitable for line-oriented textual content. It's
called the “<span class="quote">dot-stuffed
format</span>”. The first word of the server reply is
“<span class="quote">{.<em class="replaceable"><code>nnnn</code></em>}</span>”, where
“<span class="quote"><em class="replaceable"><code>nnnn</code></em></span>” is a
decimal number. This number is the server's estimate of the
total size of the multi-line reply, in bytes. It is not an
exact byte count, just a reasonable estimate. The server is
not required to compute the exact byte count before sending
the data, just provide a ballpark estimate.</p>
<p>The remaining words of the server's multi-line reply line
contain other information, depending on the nature of the
data. For example, a single SMAP command can request the
server to return the contents of two or more messages. The
server may process those messages in any order. The remainder
of the server's multi-line reply line indicates which message
this multi-line reply refers to. The actual data follows the
server's multi-line reply line. The data is transmitted as
lines of text, each line terminated by the U+000A character.
Servers are also allowed to use the U+000D/U+000A end-of-line
sequence. The end of the data is marked by a line that
contains only a single period, U+002E, followed by optional
whitespace. Lines of data that begin with U+002E have a
second U+002E character prepended.</p>
<p>An SMAP client, upon receiving a multi-line reply in this
format, begins reading U+000A-terminated lines of text, until
it reads a line containing a single U+002E, and optional
whitespace. Other lines with a leading U+002E character have
it removed, and the rest of the line gets saved as the
returned data.</p>
<p>The second multi-line server reply format carries binary
data. It begins with the word “<span class="quote">{<em class="replaceable"><code>xxxx</code></em>/<em class="replaceable"><code>yyyy</code></em>}</span>”, where
“<span class="quote"><em class="replaceable"><code>xxxx</code></em></span>” and
“<span class="quote"><em class="replaceable"><code>yyyy</code></em></span>” are
decimal numbers. “<span class="quote"><em class="replaceable"><code>yyyy</code></em></span>” gives the
server's estimate of the total size of the binary data, and
“<span class="quote"><em class="replaceable"><code>xxxx</code></em></span>” gives the
byte count of the first part that the server is about to
send. The server does not have to send everything as one
binary goop. The server is allowed to break down the binary
data in smaller, managable, chunks, which are sent one at a
time.</p>
<p>The remaining words of the multi-line reply line format
are the same as as the dot-stuffed format's. Immediately
following the multi-line reply's trailing U+000A, the server
sends exactly the number of bytes given by <em class="replaceable"><code>xxxx</code></em>. This is called a
"binary chunk".</p>
<p>Each binary chunk is followed by another line of text
terminated by the U+000A character. A trailing line that's
empty, or contains only whitespace, indicates the end of the
multi-line binary data. Otherwise the line contains a single
word, <em class="replaceable"><code>xxxx</code></em> (which
can have leading or trailing whitespace filler), that gives
the byte count of the next binary chunk, which immediately
follows the U+000A character.</p>
<p>The SMAP client reads the initial multi-line reply line,
and obtains the first chunk's byte count, and the estimated
total byte count. The SMAP client then reads the exact number
of bytes indicated by the byte count. Afterwords, the SMAP
client enters a loop where it first reads a
newline-terminated line of text. If the line is empty or
contains only whitespace filler, then this is the end of the
binary data, and the client proceeds to read the next server
reply. Otherwise the client extracts the next chunk's byte
count, reads the indicated number of bytes, then repeats the
process.</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id690653" shape="rect" name="id690653"> </a>An empty multi-line reply</h4>
</div>
</div>
</div>
<p>An expected multi-line reply may be empty. An example: the
client requests specific E-mail headers, but the message does
not have them. This is indicated by an empty multi-line
reply. An empty multi-line reply is indicated by the word
"{.0}" (followed by the remaining words that specify the
context of this multi-line reply). The next line sent by the
server contains a single "." character. This sequence is
parsed by an SMAP client as a completely empty multi-line
reply.</p>
</div>
</div>
<div class="navfooter">
<hr/>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="smap1.html" shape="rect">Prev</a> </td>
<td width="20%" align="center" rowspan="1" colspan="1">
<a accesskey="u" href="smap1.html" shape="rect">Up</a></td>
<td width="40%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="conn.html" shape="rect">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top" rowspan="1" colspan="1">Appendix A. Simple Mail Access
Protocol, Version 1 </td>
<td width="20%" align="center" rowspan="1" colspan="1">
<a accesskey="h" href="index.html" shape="rect">Home</a> | <a accesskey="t" href="bk01-toc.html" shape="rect">ToC</a></td>
<td width="40%" align="right" valign="top" rowspan="1" colspan="1"> SMAP connection negotiation</td>
</tr>
</table>
</div>
</body>
</html>
