<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<?asciidoc-toc?>
<?asciidoc-numbered?>

<article lang="en">
<articleinfo>
    <title>ADC Protocol</title>
    <author>
        <firstname>version</firstname>
        <othername>1.0.4,</othername>
        <surname>UNRELEASED</surname>
    </author>
    <authorinitials>V1U</authorinitials>
</articleinfo>
<abstract id="_abstract">
<simpara>ADC is a text protocol for a client-server network similar to Neo-Modus'
Direct Connect (NMDC). The goal is to create a simple protocol that doesn&#8217;t
require much effort neither in hub nor client, and is yet extensible. It
addresses some of the issues in the NMDC protocol, but not all.</simpara>
<simpara>The same protocol structure is used both for client-hub and client-client
communication. This document is split into two parts; the first shows the
structure of the protocol, while the second implements a specific system using
this structure. ADC stands for anything you would like it to stand for;
Advanced Direct Connect is the first neutral thing that springs to mind =).</simpara>
<simpara>Many ideas for the protocol come from Jan Vidar Krey&#8217;s DCTNG draft. Major
contributors include Dustin Brody, Walter Doekes, Timmo Stange, Fredrik
Ullner, Fredrik Stenberg and others. Jon Hess contributed the original Direct
Connect idea through the Neo-Modus Direct Connect client / hub.</simpara>
</abstract>
<section id="_version_history">
<title>Version history</title>
<simpara>The latest draft of the next version of this document as well as intermediate
and older versions can be downloaded from
$URL: <ulink url="https://svn.code.sf.net/p/adc/code/trunk/ADC.txt">https://svn.code.sf.net/p/adc/code/trunk/ADC.txt</ulink> $.
This version corresponds to $Revision: 126 $.</simpara>
<section id="_version_1_0_4_unreleased">
<title>Version 1.0.4, UNRELEASED</title>
<itemizedlist>
<listitem>
<simpara>
Separators in the command description for GET, GFI and SND are now explicit.
</simpara>
</listitem>
<listitem>
<simpara>
Clarified UTF-8 encoding note.
</simpara>
</listitem>
</itemizedlist>
</section>
<section id="_version_1_0_3_2013_06_30">
<title>Version 1.0.3, 2013-06-30</title>
<simpara>Fredrik Ullner &lt;<ulink url="mailto:ullner@gmail.com">ullner@gmail.com</ulink>&gt;</simpara>
<itemizedlist>
<listitem>
<simpara>
Added examples for each command.
</simpara>
</listitem>
<listitem>
<simpara>
Features are now described in its own section.
</simpara>
</listitem>
<listitem>
<simpara>
Specified token use from server party in client-client connections.
</simpara>
</listitem>
<listitem>
<simpara>
Changed size in file list schema to an unsigned long to manage files larger than 2 GiB.
</simpara>
</listitem>
</itemizedlist>
</section>
<section id="_version_1_0_2_2013_01_31">
<title>Version 1.0.2, 2013-01-31</title>
<simpara>Fredrik Ullner &lt;<ulink url="mailto:ullner@gmail.com">ullner@gmail.com</ulink>&gt;</simpara>
<itemizedlist>
<listitem>
<simpara>
Editorial updates
</simpara>
</listitem>
<listitem>
<simpara>
Added a terminology section
</simpara>
</listitem>
<listitem>
<simpara>
Added note in STA, severity 2 (Fatal), on responsibility.
</simpara>
</listitem>
<listitem>
<simpara>
State management is now its own section.
</simpara>
</listitem>
<listitem>
<simpara>
The client in a client-client connection should send its INF first now.
</simpara>
</listitem>
</itemizedlist>
</section>
<section id="_version_1_0_1_2008_05_02">
<title>Version 1.0.1, 2008-05-02</title>
<simpara>Jacek Sieka &lt;<ulink url="mailto:arnetheduck@gmail.com">arnetheduck@gmail.com</ulink>&gt;</simpara>
<itemizedlist>
<listitem>
<simpara>
Moved extensions to a separate document
</simpara>
</listitem>
<listitem>
<simpara>
Moved specification to a separate project on SourceForge
</simpara>
</listitem>
</itemizedlist>
</section>
<section id="_version_1_0_2007_12_01">
<title>Version 1.0, 2007-12-01</title>
<simpara>Jacek Sieka &lt;<ulink url="mailto:arnetheduck@gmail.com">arnetheduck@gmail.com</ulink>&gt;</simpara>
<itemizedlist>
<listitem>
<simpara>
Initial release
</simpara>
</listitem>
</itemizedlist>
</section>
</section>
<section id="_line_protocol">
<title>Line protocol</title>
<section id="_general">
<title>General</title>
<itemizedlist>
<listitem>
<simpara>
All messages begin with a four-letter word (FOURCC). The first letter designates how
  the message should be sent and the other three specify what to do.
</simpara>
</listitem>
<listitem>
<simpara>
Parameters are separated by space and a newline (codepoint 0x0a) ends each
  message. The string "\s" escapes space, "\n" newline and "\\" backslash.
  This version of the protocol reserves all other escapes for future use; any
  message containing unknown escapes must be discarded.
</simpara>
</listitem>
<listitem>
<simpara>
All text must be sent as 1-to-4 byte, RFC 3629-compliant UTF-8 encoded Unicode
  in normalization form C.
</simpara>
</listitem>
<listitem>
<simpara>
Clients must ignore unknown/badly formatted messages. Hubs must ignore
  invalid messages and should dispatch unknown messages according to their
  type.
</simpara>
</listitem>
<listitem>
<simpara>
Client addresses must be specified in dotted-decimal form ("x.x.x.x") for
  IPv4 and RFC 4291 form for IPv6. Hub addresses must be specified in URL
  form, with "adc" as protocol specifier ("adc://server:port/").
</simpara>
</listitem>
<listitem>
<simpara>
Numbers are sent as strings in standard floating point notation, using <emphasis>.</emphasis>
  as the decimal separator and without a thousands separator. Integers are
  numbers with neither a decimal portion nor an exponent. Applications should
  be prepared to handle at least 64-bit signed integers and 64-bit floating
  point numbers. A <emphasis>-</emphasis> prefix negates.
</simpara>
</listitem>
<listitem>
<simpara>
SIDs, PIDs, CIDs, and short binary data are sent as base32-encoded strings.
  Long binary data transfers should use the file transfer mechanism with named
  roots.
</simpara>
</listitem>
<listitem>
<simpara>
Extension names, protocol names, and other text not entered by the user may
  only include viewable characters that can be encoded by one byte in the
  UTF-8 encoding (Unicode codepoints 33-127). ADC is case-sensitive, requiring
  upper case for command names.
</simpara>
</listitem>
<listitem>
<simpara>
Some commands and functionality require the use of a hash function.  The
  hash function is negotiated during session setup and stays the same for the
  duration of the session.
</simpara>
</listitem>
</itemizedlist>
</section>
<section id="_message_syntax">
<title>Message syntax</title>
<literallayout class="monospaced">message               ::= message_body? eol
message_body          ::= (b_message_header | cih_message_header | de_message_header | f_message_header | u_message_header)
                          (separator positional_parameter)* (separator named_parameter)*
b_message_header      ::= 'B' command_name separator my_sid
cih_message_header    ::= ('C' | 'I' | 'H') command_name
de_message_header     ::= ('D' | 'E') command_name separator my_sid separator target_sid
f_message_header      ::= 'F' command_name separator my_sid separator (('+'|'-') feature_name)+
u_message_header      ::= 'U' command_name separator my_cid
command_name          ::= simple_alpha simple_alphanum simple_alphanum
positional_parameter  ::= parameter_value
named_parameter       ::= parameter_name parameter_value?
parameter_name        ::= simple_alpha simple_alphanum
parameter_value       ::= escaped_letter+
target_sid            ::= encoded_sid
my_sid                ::= encoded_sid
encoded_sid           ::= base32_character{4}
my_cid                ::= encoded_cid
encoded_cid           ::= base32_character+
base32_character      ::= simple_alpha | [2-7]
feature_name          ::= simple_alpha simple_alphanum{3}
escaped_letter        ::= [^ \#x0a] | escape 's' | escape 'n' | escape escape
escape                ::= '\'
simple_alpha          ::= [A-Z]
simple_alphanum       ::= [A-Z0-9]
eol                   ::= #x0a
separator             ::= ' '</literallayout>
</section>
<section id="_message_types">
<title>Message types</title>
<simpara>Message type specifies how messages should be routed and thus which additional
fields can be found in the message header. Clients should use the most
limiting type, in terms of recipients, that makes sense for a particular
message when sending it to the hub for distribution. Clients should use the
message type only to aid in parsing the message and otherwise ignore it. The
following message types are defined:</simpara>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="3">
<colspec colname="col_1" colwidth="33*"/>
<colspec colname="col_2" colwidth="33*"/>
<colspec colname="col_3" colwidth="33*"/>
<tbody>
<row>
<entry align="left" valign="top"><simpara>B</simpara></entry>
<entry align="left" valign="top"><simpara>Broadcast</simpara></entry>
<entry align="left" valign="top"><simpara>Hub must send message to all connected clients, including the sender of the message.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>C</simpara></entry>
<entry align="left" valign="top"><simpara>Client message</simpara></entry>
<entry align="left" valign="top"><simpara>Clients must use this message type when communicating directly over TCP.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>D</simpara></entry>
<entry align="left" valign="top"><simpara>Direct message</simpara></entry>
<entry align="left" valign="top"><simpara>The hub must send the message to the target_sid user.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>E</simpara></entry>
<entry align="left" valign="top"><simpara>Echo message</simpara></entry>
<entry align="left" valign="top"><simpara>The hub must send the message to the target_sid user and the my_sid user.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>F</simpara></entry>
<entry align="left" valign="top"><simpara>Feature broadcast</simpara></entry>
<entry align="left" valign="top"><simpara>The hub must send message to all clients that support both all required (+) and no excluded (-) features named. The feature name is matched against the corresponding SU field in INF sent by each client.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>H</simpara></entry>
<entry align="left" valign="top"><simpara>Hub message</simpara></entry>
<entry align="left" valign="top"><simpara>Clients must use this message type when a message is intended for the hub only.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>I</simpara></entry>
<entry align="left" valign="top"><simpara>Info message</simpara></entry>
<entry align="left" valign="top"><simpara>Hubs must use this message type when sending a message to a client that didn&#8217;t come from another client.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>U</simpara></entry>
<entry align="left" valign="top"><simpara>UDP message</simpara></entry>
<entry align="left" valign="top"><simpara>Clients must use this message type when communicating directly over UDP.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_session_hash">
<title>Session hash</title>
<simpara>Certain commands require the use of a hash function. The hash function used is
negotiated using the SUP mechanism each time a new connection is established.
When a client first connects, it offers a set of hash functions as SUP
features. The server picks one of the offered functions and communicates its
choice to the client by placing it before any other hash features present in
the first SUP from the server. Clients and hubs are required to support at
least one hash function, used both for protocol purposes and file
identification.</simpara>
</section>
<section id="_client_identification">
<title>Client identification</title>
<simpara>Each client is identified by three different IDs, Session ID (SID), Private ID
(PID), and Client ID (CID).</simpara>
<section id="_session_id">
<title>Session ID</title>
<simpara>Session IDs appear in all communication that interacts with the hub. They
identify a unique user on a single hub and are assigned by the hub during
initial protocol negotiation. SIDs are 20 bits long and encoded using a 4-byte
base32 encoded string.</simpara>
</section>
<section id="_private_id">
<title>Private ID</title>
<simpara>Private IDs globally identify a unique client. They function during initial
protocol negotiation to generate the CID and are invisible to other clients.
PIDs should be generated in a way to avoid collisions, for example using the
hash of the current time and primary network card MAC address if sufficient
randomness cannot be generated. Hubs and clients may not disclose PIDs to
other clients; doing so weakens the security of the ADC network. Clients
should should keep the same PID between sessions and hubs. PID length follows
the length of the hash algorithm used for the session.</simpara>
</section>
<section id="_client_id">
<title>Client ID</title>
<simpara>Client IDs globally and publicly identify a unique client and underlie client
to client communication. They are generated by hashing the (unencoded) PID
with the session hash algorithm. Hubs should register clients by CID.  CID
length follows the length of the hash algorithm used for the session. Clients
must be prepared to handle CIDs of varying lengths.</simpara>
</section>
</section>
</section>
<section id="_files">
<title>Files</title>
<section id="_file_names_and_structure">
<title>File names and structure</title>
<simpara>Filenames are relative to a fictive root in the user&#8217;s share. "/" separates
directories; each file or directory name must be unique in a case-insensitive
context. All printable characters, including whitespace, are valid names for
files, the "/" and "\" being escaped by "\". Clients must then properly filter
the filename for the target file system, as well as request filenames from
other clients according to these rules. The special names "." and ".." may not
occur as a directory or filename; any file list received containing those must
be ignored. All directory names must end with a "/".</simpara>
<simpara>Shared files are identified relative to the unnamed root "/"
("/dir/subdir/filename.ext"), while extensions can add named roots to this
namespace. For example, "TTH/&#8230;" from the TIGR extension uses the named root
"TTH" to identify files by their Tiger tree hash.  It is invalid for names
from the unnamed root to appear in the share without also being identified by
at least one hash value.</simpara>
<simpara>The rootless filename "files.xml" specifies the full file listing,
uncompressed, in XML using the UTF-8 encoding. It is recommended that clients
use an extension to transfer this list in compressed form.</simpara>
<simpara>Extensions may specify additional rootless filenames, but should generally
avoid doing so to avoid name clashes.</simpara>
<simpara>The special type "list" is used to browse partial lists. A partial file list
has the same structure as a normal list, but directories may be tagged with an
attribute <emphasis>Incomplete="1"</emphasis> to specify that they have unexpanded sub-entries.
Only directory names in the unnamed root may be requested, for instance "/"
and "/share/". The content of that directory will then be sent to the
requesting client to a depth chosen by the sending client (it should normally
only send the directory level requested, but may choose to send more if there
are few entries, for example a directory only containing a few files). The
"Base" attribute of "FileListing" specifies which directory a particular file
list represents.</simpara>
</section>
<section id="_file_list">
<title>File list</title>
<simpara>files.xml is the list of files intended for browsing. The file list must
validate against the following XML schema:</simpara>
<screen>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"&gt;
  &lt;xs:simpleType name="base32Binary"&gt;
    &lt;xs:restriction base="xs:string"&gt;
      &lt;xs:pattern value="[A-Za-z2-7]+"&gt;&lt;/xs:pattern&gt;
    &lt;/xs:restriction&gt;
  &lt;/xs:simpleType&gt;

  &lt;xs:simpleType name="zeroOne"&gt;
    &lt;xs:restriction base="xs:int"&gt;
      &lt;xs:enumeration value="0"&gt;&lt;/xs:enumeration&gt;
      &lt;xs:enumeration value="1"&gt;&lt;/xs:enumeration&gt;
    &lt;/xs:restriction&gt;
  &lt;/xs:simpleType&gt;

  &lt;xs:complexType name="ContainerType"&gt;
    &lt;xs:sequence minOccurs="0" maxOccurs="unbounded"&gt;
      &lt;xs:choice&gt;
        &lt;xs:element ref="Directory"&gt;&lt;/xs:element&gt;
        &lt;xs:element ref="File"&gt;&lt;/xs:element&gt;
        &lt;xs:any processContents="lax"&gt;&lt;/xs:any&gt;
      &lt;/xs:choice&gt;
    &lt;/xs:sequence&gt;
  &lt;/xs:complexType&gt;

  &lt;xs:attribute name="Base" type="xs:string"&gt;&lt;/xs:attribute&gt;
  &lt;xs:attribute name="CID" type="base32Binary"&gt;&lt;/xs:attribute&gt;
  &lt;xs:attribute name="Generator" type="xs:string"&gt;&lt;/xs:attribute&gt;
  &lt;xs:attribute name="Incomplete" type="zeroOne" default="0"&gt;&lt;/xs:attribute&gt;
  &lt;xs:attribute name="Name" type="xs:string"&gt;&lt;/xs:attribute&gt;
  &lt;xs:attribute name="Size" type="xs:unsignedLong"&gt;&lt;/xs:attribute&gt;
  &lt;xs:attribute name="Version" type="xs:int"&gt;&lt;/xs:attribute&gt;

  &lt;xs:element name="FileListing"&gt;
    &lt;xs:complexType&gt;
      &lt;xs:complexContent&gt;
        &lt;xs:extension base="ContainerType"&gt;
          &lt;xs:attribute ref="CID" use="required"&gt;&lt;/xs:attribute&gt;
          &lt;xs:attribute ref="Version" use="required"&gt;&lt;/xs:attribute&gt;
          &lt;xs:attribute ref="Generator" use="optional"&gt;&lt;/xs:attribute&gt;
          &lt;xs:attribute ref="Base" use="required"&gt;&lt;/xs:attribute&gt;
          &lt;xs:anyAttribute processContents="lax"&gt;&lt;/xs:anyAttribute&gt;
        &lt;/xs:extension&gt;
      &lt;/xs:complexContent&gt;
    &lt;/xs:complexType&gt;
  &lt;/xs:element&gt;

  &lt;xs:element name="Directory"&gt;
    &lt;xs:complexType&gt;
      &lt;xs:complexContent&gt;
        &lt;xs:extension base="ContainerType"&gt;
          &lt;xs:attribute ref="Name" use="required"&gt;&lt;/xs:attribute&gt;
          &lt;xs:attribute ref="Incomplete" use="optional"&gt;&lt;/xs:attribute&gt;
          &lt;xs:anyAttribute processContents="lax"&gt;&lt;/xs:anyAttribute&gt;
        &lt;/xs:extension&gt;
      &lt;/xs:complexContent&gt;
    &lt;/xs:complexType&gt;
  &lt;/xs:element&gt;

  &lt;xs:element name="File"&gt;
    &lt;xs:complexType&gt;
      &lt;xs:sequence&gt;
        &lt;xs:any minOccurs="0" maxOccurs="unbounded"&gt;&lt;/xs:any&gt;
      &lt;/xs:sequence&gt;
      &lt;xs:attribute ref="Name" use="required"&gt;&lt;/xs:attribute&gt;
      &lt;xs:attribute ref="Size" use="required"&gt;&lt;/xs:attribute&gt;
      &lt;xs:anyAttribute processContents="lax"&gt;&lt;/xs:anyAttribute&gt;
    &lt;/xs:complexType&gt;
  &lt;/xs:element&gt;

&lt;/xs:schema&gt;</screen>
<simpara>An example file list:</simpara>
<screen>&lt;?xml version="1.0" encoding="utf-8" standalone="yes"?&gt;
&lt;FileListing Version="1" CID="mycid" Generator="DC++ 0.701" Base="/"&gt;
  &lt;Directory Name="share"&gt;
    &lt;Directory Name="DC++ Prerelease"&gt;
      &lt;File Name="DCPlusPlus.pdb" Size="17648640" TTH="xxx" /&gt;
      &lt;File Name="DCPlusPlus.exe" Size="946176" TTH="yyy" /&gt;
    &lt;/Directory&gt;
    &lt;File Name="ADC.txt" Size="154112" TTH="zzz" /&gt;
  &lt;/Directory&gt;
  &lt;!-- Only used by partial lists --&gt;
  &lt;Directory Name="share2" Incomplete="1"/&gt;
&lt;/FileListing&gt;</screen>
<simpara>"encoding" must always be set to UTF-8. Clients must be prepared to handle XML
files both with and without a BOM (byte order mark), although should not
output one.</simpara>
<simpara>"Version" will not change unless a breaking change is done to the structure of
the file.</simpara>
<simpara>"CID" is the CID of the client that generated the list.</simpara>
<simpara>"Generator" is optional and for informative purposes only.</simpara>
<simpara>"Base" is used for partial file lists, but must be present even in the
non-partial list.</simpara>
<simpara>"Incomplete" signals whether a directory in a partial file list contains
unlisted items. "1" means the directory contains unlisted items, "0" that it
does not. Incomplete="0" is the default and may thus be omitted.</simpara>
<simpara>"TTH" is used by the TIGR extension.</simpara>
<simpara>More information may be added to the file by extensions, but is not guaranteed
to be interpreted by other clients.</simpara>
</section>
</section>
<section id="_base_messages">
<title>BASE messages</title>
<simpara>ADC clients/hubs that support the following messages must advertise the feature "BASE" .</simpara>
<simpara>The connecting party will be known as client, the other as server. For each message, the action code and the
message contexts under which it is valid are specified.</simpara>
<simpara>The message context specifies how the message may be received / sent. Hubs and
clients may support using the message in additional contexts as well. The
context codes are as follows:</simpara>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<tbody>
<row>
<entry align="left" valign="top"><simpara>F</simpara></entry>
<entry align="left" valign="top"><simpara>From hub (hub-client TCP)</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>T</simpara></entry>
<entry align="left" valign="top"><simpara>To hub (hub-client TCP)</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>C</simpara></entry>
<entry align="left" valign="top"><simpara>Between clients (client-client TCP)</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>U</simpara></entry>
<entry align="left" valign="top"><simpara>Between clients (client-client UDP)</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<simpara>When requesting a new client-client connection, this protocol is identified by
"ADC/1.0".</simpara>
<simpara>In the descriptions of the commands, the message header and trailing named
parameters have been omitted.</simpara>
<section id="_state_management">
<title>State management</title>
<simpara>ADC defines a state machine to control flow and processing of messages. The receiving end must ensure, according to the state machine, that it does not parse or drop messages while it is in the process of another state where the message might be invalid.</simpara>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">State </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>PROTOCOL</simpara></entry>
<entry align="left" valign="top"><simpara>Feature support recovery</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>IDENTIFY</simpara></entry>
<entry align="left" valign="top"><simpara>User identification and static checks</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>VERIFY</simpara></entry>
<entry align="left" valign="top"><simpara>Password check (does not exist in C-C communication unless announced by an extension)</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>NORMAL</simpara></entry>
<entry align="left" valign="top"><simpara>Normal operation (end state)</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>DATA</simpara></entry>
<entry align="left" valign="top"><simpara>Binary transfers. The state changes back to NORMAL once the transfer is complete.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<simpara>The states presented are the login order, from top to bottom.</simpara>
<section id="_states">
<title>States</title>
<section id="_protocol">
<title>PROTOCOL</title>
<simpara>When the hub receives a SUP, it should reply with its own SUP followed by SID assignment. The hub transitions the state then to IDENTIFY.</simpara>
<simpara>When the server party receives a SUP in the client-client connection, it should reply with its own SUP. The server transitions the state then to IDENTIFY.</simpara>
</section>
<section id="_identify">
<title>IDENTIFY</title>
<simpara>The hub may initiate this state by sending its own INF in this state but is not required. The client should send its INF whereupon the hub shall verify the PD and ID fields and other required fields. The hub transitions the state then to VERIFY if the user is registered or NORMAL if not.</simpara>
<simpara>The client party in the client-client connection shall send its INF whereupon the server party shall send its INF. The server transitions the state then to NORMAL (or VERIFY if an extension implements this).</simpara>
</section>
<section id="_verify">
<title>VERIFY</title>
<simpara>The hub shall send a GPA whereupon the client will respond with a PAS. The server transitions the state then to NORMAL.</simpara>
<simpara>Client-client support for VERIFY must be signaled as an extension.</simpara>
</section>
<section id="_normal">
<title>NORMAL</title>
<simpara>The hub should send its INF if not done already. The server shall send the INF of all connected clients whereupon the connecting client&#8217;s INF shall be last. Normal operation may then commence with chatting and file sharing.</simpara>
<simpara>Normal operation may commence immediately in a client-client connection. Typically, the downloading party sends a GET whereupon the other party sends a SND followed by a transition to the DATA state.</simpara>
</section>
<section id="_data">
<title>DATA</title>
<simpara>The DATA state is an actual binary transfer state, it does not have any commands or other content beyond streaming data.</simpara>
<simpara>The DATA state exist only in the client-client communication, an extension can be used to add binary transfers between a client and a hub. The DATA state commence after a SND command.</simpara>
<simpara>The state transitions back to NORMAL once the correct amount of bytes are transferred (specified by a previous command).</simpara>
</section>
</section>
<section id="_notes">
<title>Notes</title>
<simpara>State always transitions from PROTOCOL to IDENTIFY and never from IDENTIFY to PROTOCOL. Likewise apply between IDENTIFY, VERIFY and NORMAL. This does not apply between NORMAL and DATA.</simpara>
<simpara>Successful commands sent after a state transition indicate that the next state has been reached. For example, PROTOCOL begins a connection and state changes to IDENTIFY once the hub sends the SID.</simpara>
<simpara>The state is shared between the client and the server while the server (implicitly) controls state transitions.</simpara>
<simpara>The connecting party is known as the client and the other is known as the server (or hub). The client initiates the connection and state machine by sending its own SUP.</simpara>
<simpara>A STA is valid in all states (except DATA) and may require that messages are resent (i.e. that the state transition does not occur).</simpara>
<simpara>It is always the client party in a client-client connection that sent the connection request (CTM/RCM) command that is given control of the connection once the NORMAL state has been reached.</simpara>
<simpara>Any party may disconnect the connection if they receive invalid data or insufficient data. All implementations must therefore be prepared for a potential disconnection following each command, meaning that the following state is not achieved. A disconnection should be preceded by a STA or a QUI to indicate what was wrong.</simpara>
<simpara>The hub&#8217;s INF is optionally sent in IDENTIFY or in NORMAL.</simpara>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">State </entry>
<entry align="left" valign="top">Commands</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>PROTOCOL</simpara></entry>
<entry align="left" valign="top"><simpara>STA, SUP, SID</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>IDENTIFY</simpara></entry>
<entry align="left" valign="top"><simpara>STA, INF, QUI</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>VERIFY</simpara></entry>
<entry align="left" valign="top"><simpara>STA, GPA, PAS, QUI</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>NORMAL</simpara></entry>
<entry align="left" valign="top"><simpara>STA, SUP, INF, MSG, SCH, RES, CTM, RCM, QUI, GET, GFI, SND</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
</section>
<section id="_features">
<title>Features</title>
<simpara>Features are used to indicate support for protocol commands or functionality.</simpara>
<simpara>The server may use any feature that the client indicates support for regardless of its own SUP and vice versa. A client can announce features in the SUP regardless of the INF&#8217;s SU field and vice versa.</simpara>
<simpara>A feature name consists of four uppercase letters, where the last letter may be changed to a number to indicate a revised version of the feature.</simpara>
<simpara>A central register of known features is kept to avoid clashes, see below features in this protocol and the features in the extension document.</simpara>
<section id="_base">
<title>BASE</title>
<simpara>All clients must support the BASE feature (unless a future revision takes its place), which is this protocol.</simpara>
<simpara>Clients must add the feature to the INF&#8217;s SU field.</simpara>
</section>
<section id="_tcp4_tcp6">
<title>TCP4 / TCP6</title>
<simpara>The features TCP4 and TCP6 are used to indicate support for incoming TCP connections. The 4 and 6 indicate IPv4 and IPv6.</simpara>
<simpara>Clients should add the feature to the INF&#8217;s SU field.</simpara>
<simpara>Clients that support incoming TCP connections is referenced as <emphasis>active</emphasis> where the opposite is <emphasis>passive</emphasis>.</simpara>
</section>
<section id="_udp4_udp6">
<title>UDP4 / UDP6</title>
<simpara>The features UDP4 and UDP6 are used to indicate support for incoming UDP packets. The 4 and 6 indicate UDP with IPv4 and IPv6.</simpara>
<simpara>Clients should add the feature to the INF&#8217;s SU field.</simpara>
<simpara>Clients that support incoming UDP packets is referenced as <emphasis>active</emphasis> where the opposite is <emphasis>passive</emphasis>.</simpara>
</section>
</section>
<section id="_actions">
<title>Actions</title>
<section id="_sta">
<title>STA</title>
<literallayout class="monospaced">STA code description</literallayout>
<simpara>Contexts: F, T, C, U</simpara>
<simpara>States: PROTOCOL, IDENTIFY, VERIFY, NORMAL</simpara>
<simpara>Status code in the form "xyy" where x specifies severity and yy the specific
error code. The severity and error code are treated separately, the same error
could occur at different severity levels.</simpara>
<simpara>Severity values:</simpara>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<tbody>
<row>
<entry align="left" valign="top"><simpara>0</simpara></entry>
<entry align="left" valign="top"><simpara>Success (used for confirming commands), error code must be "00", and an additional flag "FC" contains the FOURCC of the command being confirmed if applicable.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>1</simpara></entry>
<entry align="left" valign="top"><simpara>Recoverable (error but no disconnect)</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>2</simpara></entry>
<entry align="left" valign="top"><simpara>Fatal (disconnect), sending party is responsible for action.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<simpara>Error codes:</simpara>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<tbody>
<row>
<entry align="left" valign="top"><simpara>00</simpara></entry>
<entry align="left" valign="top"><simpara>Generic, show description</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>x0</simpara></entry>
<entry align="left" valign="top"><simpara>Same as 00, but categorized according to the rough structure set below</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>10</simpara></entry>
<entry align="left" valign="top"><simpara>Generic hub error</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>11</simpara></entry>
<entry align="left" valign="top"><simpara>Hub full</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>12</simpara></entry>
<entry align="left" valign="top"><simpara>Hub disabled</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>20</simpara></entry>
<entry align="left" valign="top"><simpara>Generic login/access error</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>21</simpara></entry>
<entry align="left" valign="top"><simpara>Nick invalid</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>22</simpara></entry>
<entry align="left" valign="top"><simpara>Nick taken</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>23</simpara></entry>
<entry align="left" valign="top"><simpara>Invalid password</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>24</simpara></entry>
<entry align="left" valign="top"><simpara>CID taken</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>25</simpara></entry>
<entry align="left" valign="top"><simpara>Access denied, flag "FC" is the FOURCC of the offending command. Sent when a user is not allowed to execute a particular command</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>26</simpara></entry>
<entry align="left" valign="top"><simpara>Registered users only</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>27</simpara></entry>
<entry align="left" valign="top"><simpara>Invalid PID supplied</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>30</simpara></entry>
<entry align="left" valign="top"><simpara>Kicks/bans/disconnects generic</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>31</simpara></entry>
<entry align="left" valign="top"><simpara>Permanently banned</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>32</simpara></entry>
<entry align="left" valign="top"><simpara>Temporarily banned, flag "TL" is an integer specifying the number of seconds left until it expires (This is used for kick as well…).</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>40</simpara></entry>
<entry align="left" valign="top"><simpara>Protocol error</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>41</simpara></entry>
<entry align="left" valign="top"><simpara>Transfer protocol unsupported, flag "TO" the token, flag "PR" the protocol string. The client receiving a CTM or RCM should send this if it doesn&#8217;t support the C-C protocol.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>42</simpara></entry>
<entry align="left" valign="top"><simpara>Direct connection failed, flag "TO" the token, flag "PR" the protocol string. The client receiving a CTM or RCM should send this if it tried but couldn&#8217;t connect.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>43</simpara></entry>
<entry align="left" valign="top"><simpara>Required INF field missing/bad, flag "FM" specifies missing field, "FB" specifies invalid field.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>44</simpara></entry>
<entry align="left" valign="top"><simpara>Invalid state, flag "FC" the FOURCC of the offending command.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>45</simpara></entry>
<entry align="left" valign="top"><simpara>Required feature missing, flag "FC" specifies the FOURCC of the missing feature.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>46</simpara></entry>
<entry align="left" valign="top"><simpara>Invalid IP supplied in INF, flag "I4" or "I6" specifies the correct IP.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>47</simpara></entry>
<entry align="left" valign="top"><simpara>No hash support overlap in SUP between client and hub.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>50</simpara></entry>
<entry align="left" valign="top"><simpara>Client-client / file transfer error</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>51</simpara></entry>
<entry align="left" valign="top"><simpara>File not available</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>52</simpara></entry>
<entry align="left" valign="top"><simpara>File part not available</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>53</simpara></entry>
<entry align="left" valign="top"><simpara>Slots full</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>54</simpara></entry>
<entry align="left" valign="top"><simpara>No hash support overlap in SUP between clients.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<simpara>Description:
Description of the error, suitable for viewing directly by the user</simpara>
<simpara>Even if an error code is unknown by the client, it should display the text
message alone. Error codes are used so that the client can take different
action on different errors. Most error codes don&#8217;t have parameters and only
make sense in C and I types.</simpara>
</section>
<section id="_sup">
<title>SUP</title>
<literallayout class="monospaced">SUP ('AD' | 'RM') feature (separator ('AD' | 'RM') feature)*</literallayout>
<simpara>Contexts: F, T, C</simpara>
<simpara>States: PROTOCOL, NORMAL</simpara>
<simpara>This command identifies which features a specific client / hub supports.</simpara>
<simpara>This command can also be used to dynamically add / remove features, <emphasis>AD</emphasis>
meaning add and <emphasis>RM</emphasis> meaning remove.</simpara>
</section>
<section id="_sid">
<title>SID</title>
<literallayout class="monospaced">SID sid</literallayout>
<simpara>Contexts: F</simpara>
<simpara>States: PROTOCOL</simpara>
<simpara>This command assigns a SID to a user who is currently logging on.</simpara>
</section>
<section id="_inf">
<title>INF</title>
<literallayout class="monospaced">INF</literallayout>
<simpara>Contexts: F, T, C</simpara>
<simpara>States: IDENTIFY, NORMAL</simpara>
<simpara>This command updates the information about a client. Each time this is
received, it means that the fields specified have been added or updated. Each
field is identified by two characters, directly followed by the data
associated with that field. A field, and the effects of its presence, can be
canceled by sending the field name without data. Clients must ignore fields
they don&#8217;t recognize. Most of these fields are only interesting in the
client-hub communication; during client-client this command is mainly used for
identification purposes. Hubs can choose to require or ignore any or all of
these fields; clients must work without any of them. Many of these fields,
such as share size and client version, are purely informative, and should be
taken with a grain of salt, as it is very easy to fake them. However, clients
should strive to provide accurate data for the general health of the system,
as providing invalid information probably will annoy a great deal of people.
Updates are made in an incremental manner, by sending only the fields that
have changed.</simpara>
<simpara>Fields:</simpara>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="3">
<colspec colname="col_1" colwidth="33*"/>
<colspec colname="col_2" colwidth="33*"/>
<colspec colname="col_3" colwidth="33*"/>
<thead>
<row>
<entry align="left" valign="top">Code </entry>
<entry align="left" valign="top">Type    </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>ID</simpara></entry>
<entry align="left" valign="top"><simpara>base32</simpara></entry>
<entry align="left" valign="top"><simpara>The CID of the client. Mandatory for C-C connections.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>PD</simpara></entry>
<entry align="left" valign="top"><simpara>base32</simpara></entry>
<entry align="left" valign="top"><simpara>The PID of the client. Hubs must check that the hash(PID) == CID and then discard the field before broadcasting it to other clients. Must not be sent in C-C connections.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>I4</simpara></entry>
<entry align="left" valign="top"><simpara>IPv4</simpara></entry>
<entry align="left" valign="top"><simpara>IPv4 address without port. A zero address (0.0.0.0) means that the server should replace it with the real IP of the client. Hubs must check that a specified address corresponds to what the client is connecting from to avoid DoS attacks and only allow trusted clients to specify a different address. Clients should use the zero address when connecting, but may opt not to do so at the user&#8217;s discretion.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>I6</simpara></entry>
<entry align="left" valign="top"><simpara>IPv6</simpara></entry>
<entry align="left" valign="top"><simpara>IPv6 address without port. A zero address (::) means that the server should replace it with the IP of the client.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>U4</simpara></entry>
<entry align="left" valign="top"><simpara>integer</simpara></entry>
<entry align="left" valign="top"><simpara>Client UDP port.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>U6</simpara></entry>
<entry align="left" valign="top"><simpara>integer</simpara></entry>
<entry align="left" valign="top"><simpara>Same as U4, but for IPv6.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>SS</simpara></entry>
<entry align="left" valign="top"><simpara>integer</simpara></entry>
<entry align="left" valign="top"><simpara>Share size in bytes</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>SF</simpara></entry>
<entry align="left" valign="top"><simpara>integer</simpara></entry>
<entry align="left" valign="top"><simpara>Number of shared files</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>VE</simpara></entry>
<entry align="left" valign="top"><simpara>string</simpara></entry>
<entry align="left" valign="top"><simpara>Client identification, version (client-specific, a short identifier then a dotted version number is recommended)</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>US</simpara></entry>
<entry align="left" valign="top"><simpara>integer</simpara></entry>
<entry align="left" valign="top"><simpara>Maximum upload speed, bytes/second</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>DS</simpara></entry>
<entry align="left" valign="top"><simpara>integer</simpara></entry>
<entry align="left" valign="top"><simpara>Maximum download speed, bytes/second</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>SL</simpara></entry>
<entry align="left" valign="top"><simpara>integer</simpara></entry>
<entry align="left" valign="top"><simpara>Maximum simultaneous upload connections (slots)</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>AS</simpara></entry>
<entry align="left" valign="top"><simpara>integer</simpara></entry>
<entry align="left" valign="top"><simpara>Automatic slot allocator speed limit, bytes/sec. The client keeps opening slots as long as its total upload speed doesn&#8217;t exceed this value.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>AM</simpara></entry>
<entry align="left" valign="top"><simpara>integer</simpara></entry>
<entry align="left" valign="top"><simpara>Minimum simultaneous upload connections in automatic slot manager mode</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>EM</simpara></entry>
<entry align="left" valign="top"><simpara>string</simpara></entry>
<entry align="left" valign="top"><simpara>E-mail address</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>NI</simpara></entry>
<entry align="left" valign="top"><simpara>string</simpara></entry>
<entry align="left" valign="top"><simpara>Nickname (or hub name). The hub must ensure that this is unique in the hub up to case-sensitivity. Valid are all characters in the Unicode character set with code point above 32, although hubs may limit this further as they like with an appropriate error message.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>DE</simpara></entry>
<entry align="left" valign="top"><simpara>string</simpara></entry>
<entry align="left" valign="top"><simpara>Description. Valid are all characters in the Unicode character set with code point equal to or greater than 32.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>HN</simpara></entry>
<entry align="left" valign="top"><simpara>integer</simpara></entry>
<entry align="left" valign="top"><simpara>Hubs where user is a normal user and in NORMAL state</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>HR</simpara></entry>
<entry align="left" valign="top"><simpara>integer</simpara></entry>
<entry align="left" valign="top"><simpara>Hubs where user is registered (had to supply password) and in NORMAL state</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>HO</simpara></entry>
<entry align="left" valign="top"><simpara>integer</simpara></entry>
<entry align="left" valign="top"><simpara>Hubs where user is op and in NORMAL state</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>TO</simpara></entry>
<entry align="left" valign="top"><simpara>string</simpara></entry>
<entry align="left" valign="top"><simpara>Token, as received in RCM/CTM, when establishing a C-C connection.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>CT</simpara></entry>
<entry align="left" valign="top"><simpara>integer</simpara></entry>
<entry align="left" valign="top"><simpara>Client (user) type, 1=bot, 2=registered user, 4=operator, 8=super user, 16=hub owner, 32=hub (used when the hub sends an INF about itself). Multiple types are specified by adding the numbers together.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>AW</simpara></entry>
<entry align="left" valign="top"><simpara>integer</simpara></entry>
<entry align="left" valign="top"><simpara>1=Away, 2=Extended away, not interested in hub chat (hubs may skip sending broadcast type MSG commands to clients with this flag)</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>SU</simpara></entry>
<entry align="left" valign="top"><simpara>string</simpara></entry>
<entry align="left" valign="top"><simpara>Comma-separated list of feature FOURCC&#8217;s. This notifies other clients of extended capabilities of the connecting client.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>RF</simpara></entry>
<entry align="left" valign="top"><simpara>string</simpara></entry>
<entry align="left" valign="top"><simpara>URL of referrer (hub in case of redirect, web page)</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<note><simpara>Normally one would only accept an IP (I4 or I6) that is the same as the
source IP of the connecting peer. Use caution when accepting unknown IPs. Only
for trusted users one may allow a different IP or an IP from a different
domain (IPv4 or IPv6) to be specified. If you fail to do this, your hub can be
used as a medium for DDoS attacks.</simpara></note>
<simpara>When the hub sends an INF about itself, the NI becomes hub
name, the VE the hub version, and DE the hub description.</simpara>
</section>
<section id="_msg">
<title>MSG</title>
<literallayout class="monospaced">MSG text</literallayout>
<simpara>Contexts: F, T</simpara>
<simpara>States: NORMAL</simpara>
<simpara>A chat message. The receiving clients should precede it with "&lt;" nick "&gt;", to
allow for uniform message displays.</simpara>
<simpara>Flags:</simpara>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<tbody>
<row>
<entry align="left" valign="top"><simpara>PM&lt;group-SID&gt;</simpara></entry>
<entry align="left" valign="top"><simpara>Private message, &lt;group-SID&gt; is the SID clients must send responses to. This field must contain the originating SID if this is a normal private conversation.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>ME</simpara></entry>
<entry align="left" valign="top"><simpara>Speak in third person, 1 = message should be displayed as /me in IRC ("*nick text")</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_sch">
<title>SCH</title>
<literallayout class="monospaced">SCH</literallayout>
<simpara>Contexts: F, T, C, (U)</simpara>
<simpara>States: NORMAL</simpara>
<simpara>Search. Each parameter is an operator followed by a term. Each term is a
two-letter code followed by the data to search for. Clients must ignore any
unknown fields and complete the search request as if they were not present,
unless no known fields are present in which case the client must ignore the
search.</simpara>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<tbody>
<row>
<entry align="left" valign="top"><simpara>AN, NO, EX</simpara></entry>
<entry align="left" valign="top"><simpara>String search term, where AN is include (and), NO is exclude (and not), and EX is extension. Each filename (including the path to it) should be matched using case insensitive substring search as follows: match all AN, remove those that match any NO, and make sure the extension matches at least one of the EX (if it is present). Extensions must be sent without the leading period ('.').</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>LE</simpara></entry>
<entry align="left" valign="top"><simpara>Smaller (less) than or equal size in bytes</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>GE</simpara></entry>
<entry align="left" valign="top"><simpara>Larger (greater) than or equal size in bytes</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>EQ</simpara></entry>
<entry align="left" valign="top"><simpara>Exact size in bytes</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>TO</simpara></entry>
<entry align="left" valign="top"><simpara>Token, string. Used by the client to tell one search from the other. If present, the responding client must copy this field to each search result.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>TY</simpara></entry>
<entry align="left" valign="top"><simpara>File type, to be chosen from the following (none specified = any type): 1 = File, 2 = Directory</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<simpara>Searching by UDP is subject to IP spoofing; can thus be used to initiate a DoS
attack. Clients should only accept incoming UDP searches in a trusted
environment.</simpara>
</section>
<section id="_res">
<title>RES</title>
<literallayout class="monospaced">RES</literallayout>
<simpara>Contexts: F, T, C, U</simpara>
<simpara>States: NORMAL</simpara>
<simpara>Search result, made up of fields syntactically and structurally similar to the
INF ones. Clients must provide filename, session hash, size and token, but are
encouraged to supply additional fields if available. Passive results should be
limited to 5 and active to 10.</simpara>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<tbody>
<row>
<entry align="left" valign="top"><simpara>FN</simpara></entry>
<entry align="left" valign="top"><simpara>Full filename including path in share</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>SI</simpara></entry>
<entry align="left" valign="top"><simpara>Size, in bytes</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>SL</simpara></entry>
<entry align="left" valign="top"><simpara>Slots currently available</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>TO</simpara></entry>
<entry align="left" valign="top"><simpara>Token</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_ctm">
<title>CTM</title>
<literallayout class="monospaced">CTM protocol separator port separator token</literallayout>
<simpara>Contexts: F, T</simpara>
<simpara>States: NORMAL</simpara>
<simpara>Connect to me. Used by active clients that want to connect to someone, or in
response to RCM. Only TCP active clients may send this. &lt;token&gt; is a string
that identifies the incoming connection triggered by this command and must be
present in the INF command of the connecting client. Implementations should not accept
incoming connections with a token that was not sent earlier. The server party may, but should not, provide the token in its INF.
&lt;protocol&gt; is an arbitrary string specifying the protocol to connect with; in the case of an
ADC 1.0 compliant connection attempt, this should be the string "ADC/1.0". If
&lt;protocol&gt; is supported, a response to RCM must copy the &lt;token&gt; and
&lt;protocol&gt; fields directly. If a protocol is not supported, a DSTA must be
sent indicating this.</simpara>
</section>
<section id="_rcm">
<title>RCM</title>
<literallayout class="monospaced">RCM protocol separator token</literallayout>
<simpara>Contexts: F, T</simpara>
<simpara>States: NORMAL</simpara>
<simpara>Reverse CTM. Used by passive clients to request a connection token from an
active client.</simpara>
</section>
<section id="_gpa">
<title>GPA</title>
<literallayout class="monospaced">GPA data</literallayout>
<simpara>Contexts: F</simpara>
<simpara>States: VERIFY</simpara>
<simpara>Get Password. The data parameter is at least 24 random bytes (base32 encoded).</simpara>
</section>
<section id="_pas">
<title>PAS</title>
<literallayout class="monospaced">PAS password</literallayout>
<simpara>Contexts: T</simpara>
<simpara>States: VERIFY</simpara>
<simpara>Password. The password (utf-8 encoded bytes), followed by the random data
(binary), passed through the session hash algorithm then converted to base32.</simpara>
</section>
<section id="_qui">
<title>QUI</title>
<literallayout class="monospaced">QUI sid</literallayout>
<simpara>Contexts: F</simpara>
<simpara>States: IDENTIFY, VERIFY, NORMAL</simpara>
<simpara>The client identified by &lt;sid&gt; disconnected from the hub. If the SID belongs
to the client receiving the QUI, it means that it should take action according
to the reason (i.e. redirect or not reconnect in case of ban). The hub must
not send data after the QUI to the client being disconnected.</simpara>
<simpara>The following flags may be present:</simpara>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<tbody>
<row>
<entry align="left" valign="top"><simpara>ID</simpara></entry>
<entry align="left" valign="top"><simpara>SID of the initiator of the disconnect (for example the one that issued a kick).</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>TL</simpara></entry>
<entry align="left" valign="top"><simpara>Time Left until reconnect is allowed, in seconds. -1 = forever.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>MS</simpara></entry>
<entry align="left" valign="top"><simpara>Message.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>RD</simpara></entry>
<entry align="left" valign="top"><simpara>Redirect server URL.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>DI</simpara></entry>
<entry align="left" valign="top"><simpara>Any client that has this flag in the QUI message should have its transfers terminated by other clients connected to it, as it is unwanted in the system.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_get">
<title>GET</title>
<literallayout class="monospaced">GET type separator identifier separator start_pos separator bytes</literallayout>
<simpara>Contexts: C</simpara>
<simpara>States: NORMAL</simpara>
<simpara>Requests that a certain file or binary data be transmitted. &lt;start_pos&gt; counts
0 as the first byte. &lt;bytes&gt; may be set to -1 to indicate that the sending
client should fill it in with the number of bytes needed to complete the file
from &lt;start_pos&gt;. &lt;type&gt; is a [a-zA-Z0-9]+ string that specifies the namespace
for identifier and BASE requires that clients recognize the types "file" and
"list". Extensions may add to the identifier names as well as add new types.</simpara>
<simpara>"file" transfers transfer the file data in binary, starting at &lt;start_pos&gt; and
sending &lt;bytes&gt; bytes. Identifier must come from the namespace of the current
session hash.</simpara>
<simpara>"list" transfers are used for partial file lists and have a directory as
identifier. &lt;start_pos&gt; is always 0 and &lt;bytes&gt; contains the uncompressed
length of the generated XML text in the corresponding SND. An optional flag
"RE1" means that the client is requesting a recursive list and that the
sending client should send the directory itself and all subdirectories as
well. If this is too much, the sending client may choose to send only parts.
The flag should be taken as a hint that the requesting client will be getting
the subdirectories as well, so they might as well be sent in one go.
Identifier must be a directory in the unnamed root, ending (and beginning)
with "/".</simpara>
<simpara>Note that GET can also be used by extensions for binary transfers between hub
and client.</simpara>
</section>
<section id="_gfi">
<title>GFI</title>
<literallayout class="monospaced">GFI type separator identifier</literallayout>
<simpara>Contexts: C</simpara>
<simpara>States: NORMAL</simpara>
<simpara>Get File Information. Requests that the other client returns a RES about the
file as if it had responded to a SCH command. Type and identifier are the same
as for GET, but the identifier may come from any namespace, including the
unnamed root.</simpara>
</section>
<section id="_snd">
<title>SND</title>
<literallayout class="monospaced">SND type separator identifier separator start_pos separator bytes</literallayout>
<simpara>Contexts: C</simpara>
<simpara>States: NORMAL</simpara>
<simpara>The sender will transmit until &lt;bytes&gt; bytes of binary data have been sent. The
parameters correspond to the GET parameters except that if &lt;bytes&gt; equals -1
it must be replaced by the number of bytes needed to complete the file
starting at &lt;start_pos&gt;.</simpara>
</section>
</section>
</section>
<section id="_examples">
<title>Examples</title>
<simpara>Note that examples listed here omit the trailing newline character that shall always end a message.</simpara>
<section id="_client_hub_connection">
<title>Client – Hub connection</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Client </entry>
<entry align="left" valign="top">Hub</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>HSUP ADBASE ADTIGR</simpara></entry>
<entry align="left" valign="top"><simpara></simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara></simpara></entry>
<entry align="left" valign="top"><simpara>ISUP ADBASE ADTIGR &#8230;</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara></simpara></entry>
<entry align="left" valign="top"><simpara>ISID &lt;client-sid&gt;</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara></simpara></entry>
<entry align="left" valign="top"><simpara>IINF CT32 &#8230;</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>BINF &lt;my-sid&gt; ID&#8230; PD&#8230;</simpara></entry>
<entry align="left" valign="top"><simpara></simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara></simpara></entry>
<entry align="left" valign="top"><simpara>IGPA &#8230;</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>HPAS &#8230;</simpara></entry>
<entry align="left" valign="top"><simpara></simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara></simpara></entry>
<entry align="left" valign="top"><simpara>BINF &lt;all clients&gt;</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara></simpara></entry>
<entry align="left" valign="top"><simpara>BINF &lt;Client-SID&gt;</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>&#8230;</simpara></entry>
<entry align="left" valign="top"><simpara>&#8230;</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_client_client_connection">
<title>Client – Client connection</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Client </entry>
<entry align="left" valign="top">Server</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>CSUP ADBASE ADTIGR &#8230;</simpara></entry>
<entry align="left" valign="top"><simpara></simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara></simpara></entry>
<entry align="left" valign="top"><simpara>CSUP ADBASE ADTIGR &#8230;</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>CINF IDxxx TO&lt;token&gt;</simpara></entry>
<entry align="left" valign="top"><simpara></simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara></simpara></entry>
<entry align="left" valign="top"><simpara>CINF IDxxx</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara></simpara></entry>
<entry align="left" valign="top"><simpara>CGET &#8230;</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>CSND &#8230;</simpara></entry>
<entry align="left" valign="top"><simpara></simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>&lt;data&gt;</simpara></entry>
<entry align="left" valign="top"><simpara></simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_commands">
<title>Commands</title>
<section id="_sta_2">
<title>STA</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Example </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>ISTA 211 Hub\sfull</simpara></entry>
<entry align="left" valign="top"><simpara>A STA sent from a hub with the severity Fatal (2) and the error code Hub full (11). The descriptive text afterward is to preferably be presented to the user.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>CSTA 151 File\snot\savailable</simpara></entry>
<entry align="left" valign="top"><simpara>A STA is sent in a client to client connection, indicating that the request for a file failed (error code 51), as the file was not vailable. The severity (Recoverable, 1) indicates that an error occured but that the connection will remain.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>ESTA BBBB CCCC 142 Transfer\sprotocol\sunsupported TO123456789 PRADC/0.5</simpara></entry>
<entry align="left" valign="top"><simpara>A STA is sent from one client to another client in a hub, routed as a E-type message (meaning that the sender should receive it as well), as a response for not supporting transfers of the <emphasis>protocol</emphasis> kind. The token <emphasis>123456789</emphasis> is used and the protocol is "ADC/0.5" (see the command CTM for the version that shall be used in this protocol version).</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_sup_2">
<title>SUP</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Example </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>ISUP ADBASE ADTIGR ADBLOM</simpara></entry>
<entry align="left" valign="top"><simpara>A SUP sent from a hub indicating that the hub has added the features BASE, TIGR and BLOM.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>HSUP RMBLOM ADZLIF</simpara></entry>
<entry align="left" valign="top"><simpara>A SUP sent from a client to the hub indicating that the client has added the fature ZLIF and removed the feature BLOM.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_sid_2">
<title>SID</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Example </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>ISID BBBB</simpara></entry>
<entry align="left" valign="top"><simpara>An SID is sent from the hub indicating that the client&#8217;s SID from then on shall be BBBB.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_inf_2">
<title>INF</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Example </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>IINF CT32 NIexample_hub DEThe\s\simple\shub</simpara></entry>
<entry align="left" valign="top"><simpara>An INF is sent from the hub containing its own information: the name is "example_hub" and description "The simple hub".</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>BINF BBBB HN0 HR1 HO2 NIsample_user DEsample\scontent SF123456 SS42 I4192.168.0.1 U46666 IDIPJJWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JMW2KC3I PDIJJJWEPPPLCA33F2ZCR7YO4F6ZXWE4NJ3WQ3C3I</simpara></entry>
<entry align="left" valign="top"><simpara>An INF sent from a client (with the SID BBBB) containing the following information: the name is "sample_user", the description is "sample content", in three hubs in total (one as registered and two as operator), with a total share size of 42 bytes (with 123456 files) etc.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>CINF IPJJWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JMW2KC3I TO123456789</simpara></entry>
<entry align="left" valign="top"><simpara>An INF is sent in a client to client connection indicating the CID and token.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_msg_2">
<title>MSG</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Example </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>IMSG There\sare\s42\susers\sonline</simpara></entry>
<entry align="left" valign="top"><simpara>A MSG that is sent from the hub with the message "There are 42 users online".</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>BMSG BBBB likes\scats ME1</simpara></entry>
<entry align="left" valign="top"><simpara>A MSG that is sent from a client (with SID BBBB), spoken in third person with the message "likes cats". This will appear like (or something similar) "john likes cats" (assuming that the user with BBBB has the name john).</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>DMSG CCCC BBBB I\sprefer\sdogs PMCCCC</simpara></entry>
<entry align="left" valign="top"><simpara>A MSG is sent from a client to another client, spoken as a "private message", with the message "I prefer dogs".</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_sch_2">
<title>SCH</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Example </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>BSCH BBBB ANubuntu ANlinux NOgentoo EXISO EXIMG TO123456789 TY1</simpara></entry>
<entry align="left" valign="top"><simpara>A SCH that is sent from a client where the search terms "ubuntu" and "linux" should be in the file (TY1) name, excluding files that have "gentoo" in them. The extension of the file should be ISO or IMG. The token "123456789" is used.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>BSCH BBBB ANubuntu LE4294967296 TO123456789</simpara></entry>
<entry align="left" valign="top"><simpara>A SCH that is sent from a client where the search term "ubuntu" should be in the file (TY1) name. The token "123456789" is used. The file must be less than 4 GiB in size (4294967296 bytes).</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>FSCH BBBB +TCP4 ANubuntu TO123456789</simpara></entry>
<entry align="left" valign="top"><simpara>A SCH that is sent from a client where the search term "ubuntu" should be in the file (TY1) name. The token "123456789" is used. The hub should only route the SCH to clients that support the feature TCP4.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_res_2">
<title>RES</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Example </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>DRES CCCC BBBB FN/share/linux/ubuntu.iso SI42 SL1 TO123456789 TRIPPPWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JMW2KCII</simpara></entry>
<entry align="left" valign="top"><simpara>A RES that is sent from a client (through the hub) indicating a response with the file name "ubuntu.iso" (and its path within the share), where the file sise is 42 bytes. The token "123456789" is used. The TR field indicate the hash of the file (see the TIGR extension).</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>URES IPJJWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JMW2KCII TRIPPPWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JMW2KCII FN/share/linux/ubuntu.iso SI42 TO123456789</simpara></entry>
<entry align="left" valign="top"><simpara>A RES that is sent from a client (via UDP) indicating a response with the file name "ubuntu.iso" (and its path within the share), where the file sise is 42 bytes. The token "123456789" is used. The TR field indicate the hash of the file (see the TIGR extension).</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>CRES FN/share/linux/ubuntu.iso SI42</simpara></entry>
<entry align="left" valign="top"><simpara>A RES that is sent from a client indicating a response with the file name "ubuntu.iso" (and its path within the share), where the file sise is 42 bytes.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_ctm_2">
<title>CTM</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Example </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>DCTM BBBB CCCC ADC/1.0 6666 123456789</simpara></entry>
<entry align="left" valign="top"><simpara>A CTM that is sent from a client to another client indicating that it wants to have a client to client connection. The protocol "ADC/1.0" is used. The port 6666 is used. The token is 123456789. The hub should only send this to the target user (with SID CCCC).</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>ECTM BBBB CCCC ADC/0.5 6666 123456789</simpara></entry>
<entry align="left" valign="top"><simpara>A CTM that is sent from a client to another client indicating that it wants to have a client to client connection. The (fictional) protocol "ADC/1.0" is used. The port 6666 is used. The token is 123456789. The hub should send this to the target user (with SID CCCC) and to the originating party (with SID BBBB).</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_rcm_2">
<title>RCM</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Example </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>DRCM BBBB CCCC ADC/1.0 123456789</simpara></entry>
<entry align="left" valign="top"><simpara>A RCM that is sent from a client to another client indicating that it wants to have a client to client connection. The protocol "ADC/1.0" is used. TThe token is 123456789. The hub should only send this to the target user (with SID CCCC).</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>ERCM BBBB CCCC ADC/0.5 123456789</simpara></entry>
<entry align="left" valign="top"><simpara>A RCM that is sent from a client to another client indicating that it wants to have a client to client connection. The (fictional) protocol "ADC/0.5" is used. TThe token is 123456789. The hub should send this to the target user (with SID CCCC) and to the originating party (with SID BBBB).</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_gpa_2">
<title>GPA</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Example </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>IGPA JJWEPPPLCA3PF2ZCRRYO3333</simpara></entry>
<entry align="left" valign="top"><simpara>A GPA that is sent from the hub indicating the password-response sequence with the random data JJWEPPPLCA3PF2ZCRRYO3333.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_pas_2">
<title>PAS</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Example </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>HPAS YO4F2ZX2EV2JMW2KCIIYYYYY</simpara></entry>
<entry align="left" valign="top"><simpara>A PAS that is sent from the client where the password and random data is hashed.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_qui_2">
<title>QUI</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Example </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>IQUI BBBB</simpara></entry>
<entry align="left" valign="top"><simpara>A QUI that is sent from the hub indicating that the client BBBB has disconnected.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>IQUI BBBB IDCCCC MSCats\sare\shorrible DI1 TL-1</simpara></entry>
<entry align="left" valign="top"><simpara>A QUI that is sent from the hub indicating that the client BBBB has disconnected. The originator of the action is the client with the SID CCCC. The message "Cats are horrible" is included. All clients should terminate their connections with the client BBBB (DI1). The client should never attempt to reconnect (TL-1).</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_get_2">
<title>GET</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Example </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>CGET file TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JMW2KCII 0 -1</simpara></entry>
<entry align="left" valign="top"><simpara>A GET that is sent from a client as a request for a file with the identifier TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JMW2KCII (see TIGR extension). The sending client should send the entire file.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>CGET list /share/ 0 -1 RE1</simpara></entry>
<entry align="left" valign="top"><simpara>A GET that is sent from a client as a request for a directory with the identifier /share/. The sending client should send the directory and its subdirectories.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>CGET file TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JMW2KCII 6666 3333</simpara></entry>
<entry align="left" valign="top"><simpara>A GET that is sent from a client as a request for a file with the identifier TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JMW2KCII (see TIGR extension). The sending client should send the next 3333 bytes, starting at byte position 6666.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_gfi_2">
<title>GFI</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Example </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>CGFI file TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JMW2KCII</simpara></entry>
<entry align="left" valign="top"><simpara>A GFI that is sent from a client as a request for file information for a file with the identifier TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JMW2KCII (see TIGR extension).</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>CGFI list /share/</simpara></entry>
<entry align="left" valign="top"><simpara>A GFI that is sent from a client as a request for directory information with the identifier /share/.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_snd_2">
<title>SND</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Example </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>CSND file TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JMW2KCII 0 9999</simpara></entry>
<entry align="left" valign="top"><simpara>A SND that is sent from a client prior to streaming data for the file with the identifier TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JMW2KCII (see TIGR extension). The sending client indicates that it will send 9999 bytes and start streaming at the byte position 0 (the beginning of the file).</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>CSND list /share/ 0 66</simpara></entry>
<entry align="left" valign="top"><simpara>A SND that is sent from a client prior to streaming data for the directory with the identifier /share/. The sending client indicates that it will send 66 bytes.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>CSND file TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JMW2KCII 6666 3333</simpara></entry>
<entry align="left" valign="top"><simpara>A SND that is sent from a client prior to streaming data for the file with the identifier TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JMW2KCII (see TIGR extension). The sending client indicates that it will send 3333 bytes and start streaming at the byte position 6666.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
</section>
</section>
<section id="_terminology">
<title>Terminology</title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Term </entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>FOURCC</simpara></entry>
<entry align="left" valign="top"><simpara>Four character code. This may be the message type followed by the command, e.g. "ISTA", "BMSG" etc. This may also be the name of a feature (BASE, TIGR etc). Any four character identification.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Server</simpara></entry>
<entry align="left" valign="top"><simpara>The hub is the <emphasis>server</emphasis> in a client - hub context. The client receiving the incoming connection is the <emphasis>server</emphasis> in a client - client context.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Base32</simpara></entry>
<entry align="left" valign="top"><simpara>An encoding used by the protocol, see RFC 4648 for more information about Base32. Note that the Base32 implementation in ADC is never padded.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Context</simpara></entry>
<entry align="left" valign="top"><simpara>When a command states a context, e.g. "T" (To hub), it defines an expectance on the flow of traffic. A context may refer to one or multiple message types. For example, for the context <emphasis>T</emphasis>, the message types "B", "C", "D", "E", "F" and "H" are valid. Note that the context is not a restriction in any way, implementations may further extend a command&#8217;s expected contexts.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="_standard_extensions">
<title>Standard Extensions</title>
<simpara>Apart from supporting BASE, clients may opt to implement one or more of the
following standard extensions. To be considered for addition, an extension must
be well documented and must be implemented and tested in the real world.</simpara>
<simpara>While in development, extensions are tracked here:
<ulink url="http://adc.sourceforge.net/wiki/index.php/Extensions">http://adc.sourceforge.net/wiki/index.php/Extensions</ulink></simpara>
<simpara>Once they have been tried and accepted, they&#8217;re moved to the official extensions
document that accompanies this one.</simpara>
</section>
</article>