ICB Protocol v2

This is an overview of the v2 XML icb protocol. It's a quick hack to make icbd compatable with a flash-based icb client used for other applications than icb historically has been used. It's also a proof of concept for using the icb system with an XML protocol.

Future real development will re-address the idea of the actual XML structure and DTD.

Basic Packet Layout:

The basic unit ICB clients and server communicate with is a packet with the following layout:

<PACKET PROTO="2" TYPE="type">
<DATA TYPE="DTYPE">VALUE</DATA>
<DATA TYPE="DTYPE">VALUE 2</DATA>
...
<DATA TYPE="DTYPE">VALUE N</DATA>
</PACKET>

where:

PROTO="2" defines the packet as part of this protocol

`type' is the type of packet this is (see below for valid packet types)

`sender-id' is a unique id of the sender of this packet

`dest-id' is a unique id of the recipient

DTYPE's can be one of the following:

`id' is optional unique id tag to be returned in all response packets (not yet supported)
`param' is optional parameters of data
`data' is the data of the packet
`sender' is the sender of the packet (perhaps not to be used)
`recipient' is the desired recipient of the packet

VALUE's are typically just simple text but may also be XML sub nodes (such as in the WHO packet)

ICB Packet Types

LOGIN : Login packet

Client to Server

Packet Type: LOGIN

Sender: No, Recipient: Yes, Param: 4 - 6, Data: 0

Param 0: Login id of user. Required.
Param 1: Nickname to use upon login into ICB. Required.
Param 2: Default group to log into in ICB, or do group who of. A null string for who listing will show all groups. Required.
Param 3: Login command. Required. Currently one of the following:
- "login" log into ICB
- "w" just show who is currently logged into ICB
Param 4: Password to authenticate the user to ICB.
Param 5: If when logging in, default group (Param 2) does not exist, create it with this status. Optional.

Thus the ICB Login Packet has the following layout:

<PACKET PROTO="2" TYPE="LOGIN">
<DATA TYPE="recipient">server</DATA>
<DATA TYPE="param">Loginid</DATA>
<DATA TYPE="param">Nickname</DATA>
<DATA TYPE="param">DefaultGroup</DATA>
<DATA TYPE="param">Command</DATA>
<DATA TYPE="param">Password</DATA>
<DATA TYPE="param">GroupStatus</DATA>
</PACKET>

Server to Client

None, the server response is sent as a LOGINOK packet.

LOGINOK : Login OK packet

Client to Server

None, the client request is sent using a LOGIN packet.

Server to Client

Packet Type: LOGINOK
Sender: Yes, Recipient: No, Param: 0, Data: 1

Data 0: Result code

Thus the ICB Login OK Packet has the following layout:

<PACKET PROTO="2" TYPE="LOGINOK">
<DATA TYPE="SENDER">Server</DATA>
<DATA TYPE="data">result-code</DATA>
</PACKET>

OPEN : Open Message packet

Client to Server

Packet Type: OPEN
Sender: No, Recipient: No, Param: 0, Data: 1
- Data 0: Content of message

Thus the ICB Open Packet has the following layout:

<PACKET PROTO="2" TYPE="OPEN">
<DATA TYPE="DATA">MessageText</DATA>
</PACKET>

Server to Client

Packet Type: OPEN
Sender: Yes, Recipient: No, Param: 0, Data: 1
- Sender: Nickname of person who sent the message
- Data 0: Content of message

Thus the ICB Open Packet has the following layout:

<PACKET PROTO="2" TYPE="OPEN">
<DATA TYPE="SENDER">Nickname</DATA>
<DATA TYPE="DATA">MessageText</DATA>
</PACKET>

PERSONAL : Personal Message Packet

Client to Server

Not valid. Clients cannot send servers Personal Message packets.

Server to Client

Packet Type: PERSONAL
Sender: Yes, Recipient: No, Param: 0 Data: 1
- Sender: Nickname of person who sent the message
- Data 0: Content of Message

Thus the ICB Personal Message Packet has the following layout:

<PACKET PROTO="2" TYPE="PERSONAL">
<DATA TYPE="SENDER">Nickname</DATA>
<DATA TYPE="DATA">MessageText</DATA>
</PACKET>

STATUS: Status Message Packet

Client to Server

Not valid. Clients cannot send servers Status Message packets.

Server to Client

Packet Type: STATUS
Sender: No, Recipient: No, Params: 1, Data: 1
- Param 0: Status Message Category
- Data 0: Content of Message

Thus the ICB Status Message Packet has the following layout:

<PACKET PROTO="2" TYPE="STATUS">
<DATA TYPE="PARAM">Category</DATA>
<DATA TYPE="DATA">MessageText</DATA>
</PACKET>

ERROR: Error Message Packet

Client to Server

Not valid. Clients cannot send servers Error Message packets.

Server to Client

Packet Type: ERROR
Sender: No, Recipient: No, Params: 0-1, Data: 1
- Param 0: Category (optional)
- Data 0: Content of Message

Thus the ICB Error Message Packet has the following layout:

<PACKET PROTO="2" TYPE="ERROR">
<DATA TYPE="PARAM">Category</DATA>
<DATA TYPE="DATA">ErrorText</DATA>
</PACKET>

IMPORTANT: Important Message Packet

Client to Server

Not valid. Clients cannot send servers Important Message packets.

Server to Client

Packet Type: IMPORTANT
Sender: No, Recipient: No, Params: 1, Data: 1
- Param 0: Important Message Category
- Data 1: Content of Message

Thus the ICB Important Message Packet has the following layout:

<PACKET PROTO="2" TYPE="IMPORTANT">
<DATA TYPE="PARAM">Category</DATA>
<DATA TYPE="DATA">MessageText</DATA>
</PACKET>

EXIT: Exit Packet

Client to Server

Not valid. Clients cannot send servers Exit Message packets.

Server to Client

Packet Type: EXIT
Sender: No, Recipient: No, Params: 0, Data: 0-1
- Data 0: Reason for exit (optional)

Thus the ICB Exit Message Packet has the following layout:

<PACKET PROTO="2" TYPE="EXIT">
<DATA TYPE="DATA">ReasonText</DATA>
</PACKET>

COMMAND: Command Packet

Client to Server

Packet Type: COMMAND
Sender: No, Recipient: Optional, Params: 1+, Data: 0+
- Recipient: who to perform this command on (optional)
- Param 0: Command. Required.
- Param 1 (and up): Arguments (Optional)
- Data 0 (and up): Data (Optional)

Thus the ICB Command Packet has the following layout:

<PACKET PROTO="2" TYPE="COMMAND">
<DATA TYPE="RECIPIENT">Nickname</DATA>
<DATA TYPE="PARAM">Command</DATA>
<DATA TYPE="PARAM">Optional Command Arg 1</DATA>
...
<DATA TYPE="PARAM">Optional Command Arg N</DATA>
<DATA TYPE="DATA">Optional Data 0</DATA>
...
<DATA TYPE="DATA">Optional Data N</DATA>
</PACKET>

Server to Client

Not valid. Servers cannot send clients Command packets.

CMDOUT: Command Output Packet

Client to Server

Not valid. Clients cannot send servers Command Output packets.

Server to Client

Packet Type: CMDOUT
Sender: Yes, Recipient: No, Params: 1+, Data: 0+
- Sender: Sender of the the command
- Param 0: Output Type. Required.
- Param 1+: Various Other Parameters. Optional.
- Data 0+: Various Output. Optional.

Thus the ICB Command Output Packet has the following layout:

<PACKET PROTO="2" TYPE="CMDOUT">
<DATA TYPE="SENDER">Nickname</DATA>
<DATA TYPE="PARAM">OutputType</DATA>
<DATA TYPE="PARAM">Optional Arg 1</DATA>
...
<DATA TYPE="PARAM">Optional Arg N</DATA>
<DATA TYPE="DATA">Optional Output 0</DATA>
...
<DATA TYPE="DATA">Optional Output N</DATA>
</PACKET>

PROTOCOL: Protocol Packet

Client to Server

Packet Type: PROTOCOL
Sender: No, Recipient: No, Params: 1-3
- Param 0: Protocol Level. Required.
- Param 1: Host ID. Optional.
- Param 2: Client ID. Optional.

Thus the ICB Protocol Packet has the following layout:

<PACKET PROTO="2" TYPE="PROTOCOL">
<DATA TYPE="PARAM">ProtoLevel</DATA>
<DATA TYPE="PARAM">HostID</DATA>
<DATA TYPE="PARAM">ClientVersionID</DATA>
</PACKET>

Server to Client

Packet Type: PROTOCOL
Sender: No, Recipient: No, Params: 1-3
- Param 0: Protocol Level. Required.
- Param 1: Host ID. Optional.
- Param 2: Server ID. Optional.

Thus the ICB Protocol Packet has the following layout:

<PACKET PROTO="2" TYPE="PROTOCOL">
<DATA TYPE="PARAM">ProtoLevel</DATA>
<DATA TYPE="PARAM">HostID</DATA>
<DATA TYPE="PARAM">ServerVersionID</DATA>
</PACKET>

BEEP: Beep Packet

Client to Server

Not valid. Clients cannot send servers Beep packets.

Server to Client

Packet Type: BEEP
Sender: Yes, Recipient: No, Params: 0, Data: 0
- Sender: Nickname of person who sent beep

Thus the ICB Beep Packet has the following layout:

<PACKET PROTO="2" TYPE="BEEP">
<DATA TYPE="SENDER">Nickname</DATA>
</PACKET>

PING: Ping Packet

Client to Server

Note; the user of a client sends ping requests as a sub-command of packet type COMMAND. A client to server PING packet is handled by the client itself in response to a server PING packet.

Packet Type: PING
Sender: No, Recipient: No, Params: 0, Data: 0

Thus the ICB Ping Packet has the following layout:

<PACKET PROTO="2" TYPE="PING"></PACKET>

Server to Client

Packet Type: PING
Sender: No, Recipient: No, Params: 0, Data: 0

Thus the ICB Ping Packet has the following layout:

<PACKET PROTO="2" TYPE="PING"></PACKET>

PONG: Pong Packet

Client to Server

Packet Type: PONG
Sender: No, Recipient: No, Params: 0, Data: 0

Thus the ICB Pong Packet has the following layout:

<PACKET PROTO="2" TYPE="PONG"></PACKET>

Server to Client

None; the server processes the PONG packet from the client as a response to a PING packet.

NOOP: NOOP Packet

Client to Server

Packet Type: NOOP
Sender: No, Recipient: No, Params: 0, Data: 0

Thus the ICB NOOP has the following layout:

<PACKET PROTO="2" TYPE="NOOP"></PACKET>

Server to Client

None.

USERS: Number of Users Packet

Client to Server

Packet Type: USERS
Sender: No, Recipient: No, Params: 0-1, Data: 0
- Param 0: The group name to count users in (optional)

Thus the ICB USERS packet has the following layout:

<PACKET PROTO="2" TYPE="USERS">
<DATA TYPE="PARAM">.</DATA>
</PACKET>

Server to Client

Packet Type: USERS
Sender: No, Recipient: No, Params: 0, Data: 1
- Data 0: The number of users counted

Thus the ICB USERS packet has the following layout:

<PACKET PROTO="2" TYPE="USERS">
<DATA TYPE="DATA">10</DATA>
</PACKET>

WHO: Who Packet

Packet Type: WHO (Proto v2 or later required)

Client to Server

Sender: No, Recipient: No, Params: 1-2, Data: 0
- Param 0: The type: "user" or "group"
- Param 1: The group name to count users in (optional)

Thus the ICB WHO packet has the following layout:

<PACKET PROTO="2" TYPE="WHO">
<DATA TYPE="PARAM">user</DATA>
<DATA TYPE="PARAM">.</DATA>
</PACKET>

Server to Client

Sender: No, Recipient: No, Params: 1, Data: 1+
- Param 0: The type: "user" or "group"
- Data 0: The users found

Thus the ICB WHO has the following layout:

<PACKET PROTO="2" TYPE="WHO">
<DATA TYPE="PARAM">user</DATA>
<DATA TYPE="DATA">
<USER IDLE="sec" LOGIN="time_t" USER="loginID" SITE="siteID" REGISTERED="Yes"
    AWAY="No" GROUP="groupName" ARRIVAL="time_t in this group">Nickname</USER>
</DATA>
...
<DATA TYPE="DATA">
<USER IDLE="sec" LOGIN="time_t" USER="loginID" SITE="siteID" REGISTERED="Yes"
    AWAY="No" GROUP="groupName" ARRIVAL="time_t in this group">Nickname N</USER>
</DATA>
</PACKET>

Sub-Command Packet Types

The following packet types have been migrated from sub-command types to full packet types. The ones listed below haven't been full migrated yet and are included as a listing that I can update as I make my way through. Eventually, this text will disappear. See "COMMAND and CMDOUT Packet Types" below for further information.

These already exist as top-level packet command types, but need to be updated to reflect their client to server communication.

BEEP
STATUS
PING

These need to be migrated entirely.

DROP
SHUTDOWN
WALL
CANCEL
G
INVITE
PASS
BOOT
TOPIC
MOTD
M
ECHOBACK
NAME
V
WHEREIS
RESTART
NEWS
HUSH
SHUSH
S_HELP
EXCLUDE
SHUTTIME
NOTIFY
TALK
NOBEEP
AWAY
NOAWAY

The Life Cycle of an ICB session

The steps a typical ICB session goes thru is as follows:

The client opens a connection to the server.
The server sends the client a Protocol packet.
The client sends the server a Login packet.
If the login packet command is "w", a listing of the current ICB users is sent to the client, and then the server sends the client an Exit packet, and the client closes the connection.
If the login packet command is "login", the server sends a Login OK packet
The client and server send any number of Open, Personal, Status, Error, Important, Command, Command Output, Beep, Ping and Pong packets according to the above rules.
(Optional) The server sends the client an Exit packet.
The client closes the connection.

Further Information on Various Packet Types

Login Packet

The client can send one and only one Login Packet to the server.

Message IDs in Command and Command Output

If the client sends the server a packet that contains an ID type, all output sent from the server to the client in response to that Command should place the same Message ID in the Command output packet. This is not yet supported.

Ping and Pong

A client can ping another user to see if their client is active. Clients use the Ping sub-command of a COMMAND packet, the server then sends a PING packet to the other user. That user's client processes the PING packet and returns a PONG packet. The server computes the elapsed time and sends a summary back to the original user. Note that some clients can be paused in "page" mode waiting for the user to continue to the next page. In some clients this may cause a PING request to not be processed until the user has caught up on reading their ICB output and the client becomes active again.

COMMAND and CMDOUT Packet Types

Protocol version 1 implemented about 30 sub-commands as part of the COMMAND packet type. This may have been a result of using single-character identifiers for each packet type, but it's hard to know at this point. Regardless, protocol version 2 (and up) takes these sub-command types and moves them up into the main protocol where they can be more clearly defined and used. the COMMAND and CMDOUT packet types remain for now, and likely will be renamed to LOCAL_COMMAND or somesuch to allow for server-specific extensions that don't require a client to be updated and recompiled.

This is how it used to work and is included since in some cases all of the functionality migration hasn't been finished:

There are various Command Output Types. The ones currently defined are:

"co" : Generic command output (found in Data)
"ec" : Indicates end of output data from command
"wl" : In a who listing, a line of output listing a user. Has the following format:
- Data 0: String indicating whether user is moderator or not. Usually "*" for moderator, and " " for not.
- Data 1: Nickname of user.
- Data 2: Number of seconds user has been idle.
- Data 3: Response Time. No longer in use.
- Data 4: Login Time. Unix time_t format. Seconds since Jan. 1, 1970 GMT.
- Data 5: Username of user.
- Data 6: Hostname of user.
- Data 7: Registration status.
Thus the "wl" Command Output packet has the following layout:
```
<PACKET PROTO="2" TYPE="CMDOUT">
<DATA TYPE="PARAM">wl</DATA>
<DATA TYPE="DATA">Mod</DATA>
<DATA TYPE="DATA">Nickname</DATA>
<DATA TYPE="DATA">Nickname</DATA>
<DATA TYPE="DATA">Resp</DATA>
<DATA TYPE="DATA">LoginTime</DATA>
<DATA TYPE="DATA">UserID</DATA>
<DATA TYPE="DATA">HostID</DATA>
<DATA TYPE="DATA">RegisterInfo</DATA>
</PACKET>
```
"wg" : In a who listing, a line of output listing a group. Has the following format:
- Data 1: Group name.
- Data 2: Group topic.
Thus the "wg" Command Output packet has the following layout:
```
<PACKET PROTO="2" TYPE="CMDOUT">
<DATA TYPE="PARAM">wg</DATA>
<DATA TYPE="DATA">GroupName</DATA>
<DATA TYPE="DATA">GroupTopic</DATA>
</PACKET>
```
Note: the server seems to only accept this from the client and returns a standard who listing for the requested group.
"wh" : Tell client to output header for who listing output.
"gh" : Tell client to output a group header for who listing output. Deprecated.
"ch" : Tell client to list all the commands it handles internally. Deprecated.
"c" : Tell client to list a single command. Deprecated.

Protocol Negotiation

There is currently no way for the client and server to negotiate a protocol level. A proposed method for implementing it will be added here at a later date.

ICB Protocol v2

Basic Packet Layout:

ICB Packet Types

LOGIN : Login packet

Client to Server

Server to Client

LOGINOK : Login OK packet

Client to Server

Server to Client

OPEN : Open Message packet

Client to Server

Server to Client

PERSONAL : Personal Message Packet

Client to Server

Server to Client

STATUS: Status Message Packet

Client to Server

Server to Client

ERROR: Error Message Packet

Client to Server

Server to Client

IMPORTANT: Important Message Packet

Client to Server

Server to Client

EXIT: Exit Packet

Client to Server

Server to Client

COMMAND: Command Packet

Client to Server

Server to Client

CMDOUT: Command Output Packet

Client to Server

Server to Client

PROTOCOL: Protocol Packet

Client to Server

Server to Client

BEEP: Beep Packet

Client to Server

Server to Client

PING: Ping Packet

Client to Server

Server to Client

PONG: Pong Packet

Client to Server

Server to Client

NOOP: NOOP Packet

Client to Server

Server to Client

USERS: Number of Users Packet

Client to Server

Server to Client

WHO: Who Packet

Client to Server

Server to Client

Sub-Command Packet Types

The Life Cycle of an ICB session

Further Information on Various Packet Types

Login Packet

Message IDs in Command and Command Output

Ping and Pong

COMMAND and CMDOUT Packet Types

Protocol Negotiation

Last Modified: Mon Apr 19 16:16:18 PDT 2004 by falcon@icb.net