Protocols/OSCAR/Foodgroups/ICBM: Difference between revisions

From NINA Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(8 intermediate revisions by the same user not shown)
Line 8: Line 8:


{{Protocols/OSCAR/Foodgroups/ICBM/Description}}
{{Protocols/OSCAR/Foodgroups/ICBM/Description}}
So now we get to the purpose of this whole thing: messaging. Instant messages are strings of ASCII codes that get sent in very-near-real-time between users of the Basic OSCAR Service (BOS). At no time does one client directly locate another client, or even know the location of any other client. All messages are sent to the message server, which then relays them to their destination client(s).
The text of a message is usually in the form of an HTML-like encoding that AOL calls "text/x-aol-rtf" (MIME format notation). For all intents and purposes, it's a subset of HTML. But, just like with HTML, you don't have to use HTML to be HTML. Sending straight ASCII text works just fine as well. The AOL-sourced AIM clients always use HTML even if you don't type or use any. They will usually append at least the <HTML>, <BODY>, and <FONT> tags (and their appropriate closing tags) even if you didn't intend to use any. The server does not touch the message at all.
Sending and receiving instant messages (from now on called IMs), is really quite simple. There are some things that can make it go funny, though. I don't have all those things documented yet.
== Tutorials ==
* [[Protocols/OSCAR/Foodgroups/ICBM/Tutorials]]
== Datatypes and Classes ==
=== Datatype: Cookie ===
{| class="wikitable"
! Name
! Size
! Notes
|-
| ICBM__COOKIE
| 8 byte
| Opaque data used to link conversations
|}
=== Class: ICBM__CHANNELS ===
Messages sent between users are sent on a specific channel that narrow down how they should be processed and possible rate size parameters.
{| class="wikitable"
! Name
! Value
! Notes
|-
| ICBM__CHANNEL_AOL_IM
| 0x01
| Normal IM channel; all clients are expected to understand this channel
|-
| ICBM__CHANNEL_RENDEZVOUS
| 0x02
| For rendezvous negotiations and sending data between clients
|-
| ICBM__CHANNEL_MIME
| 0x03
| NOT CURRENTLY DOCUMENTED
|-
| ICBM__CHANNEL_ICQ
| 0x04
| NOT CURRENTLY DOCUMENTED
|-
| ICBM__CHANNEL_COBROWSER
| 0x05
| NOT CURRENTLY DOCUMENTED
|}
=== Class: ICBM__FLAGS ===
These are flags the client uses to inform the server what kinds of features it supports for the ICBM channel.
{| class="wikitable"
! Name
! Value
! Notes
|-
| ICBM__FLAG_CHANNEL_MSGS_ALLOWED
| 0x00000001
| Wants ICBMs on this channel
|-
| ICBM__FLAG_MISSED_CALLS_ENABLED
| 0x00000002
| Wants MISSED_CALLS on this channel
|-
| ICBM__FLAG_BLOCK_AUTH_MESSAGES
| 0x00000004
| NOT CURRENTLY DOCUMENTED
|-
| ICBM__FLAG_EVENTS_ALLOWED
| 0x00000008
| Wants CLIENT_EVENTs
|-
| ICBM__FLAG_SMS_SUPPORTED
| 0x00000010
| Aware of sending to SMS
|-
| ICBM__FLAG_OFFLINE_MSGS_ALLOWED
| 0x00000100
| Support offline IMs; client is capable of storing and retrieving
|}
=== TLV Class: ICBM__TAGS ===
These are the TLV tags used in TOHOST and TOCLIENT SNACs.
{| class="wikitable"
! Name
! Tag
! Type
! Notes
|-
| ICBM__TLV_TAGS_AOL_IM_DATA
| 0x02
| Array of [[Protocols/OSCAR/TLV|TLV]]
| ''[Class: [[Protocols/OSCAR/Foodgroups/ICBM#TLV_Class:_ICBM_IM_DATA_TAGS|ICBM__IM_DATA_TAGS]]]'' Message data for the IM channel only; unlike other TLVs the order of TLVs inside this tag does matter - it should be the CAPABILITIES item followed by multiple IM_TEXT items
|-
| ICBM__TLV_TAGS_REQUEST_HOST_ACK
| 0x03
| empty
| Host will acknowledge this ICBM upon sending it to the destination client; this does NOT mean the destination user received it
|-
| ICBM__TLV_TAGS_AUTO_RESPONSE
| 0x04
| empty
| This message is an auto response; this tag is not allowed with either the REQUEST_HOST_ACK or STORE tags
|-
| ICBM__TLV_TAGS_DATA
| 0x05
| [[Protocols/OSCAR/Services/Rendezvous#Datatype:_ICBM_IM_RENDEZVOUS|ICBM__IM_RENDEZVOUS]]
| Message data for all other channels
|-
| ICBM__TLV_TAGS_STORE
| 0x06
| empty
| If the user is offline then store this message for delivery the next time the user logs in when possible; AIM and ICQ use complex privacy rules that control if an offline IM delivery is allowed or not
|-
| ICBM__TLV_TAGS_ICQBLOB
| 0x07
|
| NOT CURRENTLY DOCUMENTED
|-
| ICBM__TLV_TAGS_AVATAR_INFO
| 0x08
|
| NOT CURRENTLY DOCUMENTED
|-
| ICBM__TLV_TAGS_WANT_AVATAR
| 0x09
|
| NOT CURRENTLY DOCUMENTED
|-
| ICBM__TLV_TAGS_MULTI_USER
| 0x0A
|
| NOT CURRENTLY DOCUMENTED
|-
| ICBM__TLV_TAGS_WANT_EVENTS
| 0x0B
| empty
| Used in TO_CLIENT only, it is added by the server if the sender wants client events
|-
| ICBM__TLV_TAGS_SUBSCRIPTIONS
| 0x0C
|
| NOT CURRENTLY DOCUMENTED
|-
| ICBM__TLV_TAGS_BART
| 0x0D
| [[Protocols/OSCAR/Foodgroups/BART#Datatype:_BART_ID|BART__ID]]
| If desired BART items can be sent with the ICBM, the client should override the ones in USERINFO with these
|-
| ICBM__TLV_TAGS_HOST_IM_ID
| 0x10
| u32
| Unique id for host generated IMs alerting the user of some change
|-
| ICBM__TLV_TAGS_HOST_IM_ARGS
| 0x11
| Array of string16
| String arguments used to form the host generated IM
|-
| ICBM__TLV_TAGS_SEND_TIME
| 0x16
| t70
| Time when the server received the offline IM
|-
| ICBM__TLV_TAGS_FRIENDLY_NAME
| 0x17
| string
| For WIMZI this is the friendly name of the anonymous user
|-
| ICBM__TLV_TAGS_ANONYMOUS
| 0x18
| empty
| This is an anonymous IM
|-
| ICBM__TLV_TAGS_WIDGET_NAME
| 0x19
| string
| The name of the WIMZI widget
|}
=== Data Encoding ===
==== TLV Class: ICBM__IM_DATA_TAGS ====
These are the tags inside the IM_DATA TLV of an IM channel ICBM; order matters. For the IM_CHANNEL there should be one IM_CAPABILITIES followed by one or more IM_TEXT tags.
{| class="wikitable"
! Name
! Tag
! Type
! Notes
|-
| ICBM__IM_DATA_TLV_TAGS_IM_TEXT
| 0x0101
| [[Protocols/OSCAR/Foodgroups/ICBM#Datatype:_ICBM_IM_SECTION|ICBM__IM_SECTION]]
| The actual IM text; there can be multiple of these
|-
| ICBM__IM_DATA_TLV_TAGS_IM_CAPABILITIES
| 0x0501
| uint8 (byte)
| Old client support; should just be the value 1
|-
| ICBM__IM_DATA_TLV_TAGS_MIME_ARRAY
| 0x0D01
| uint16 (word)
| Short caps
|}
==== Datatype: ICBM__IM_SECTION ====
An IM can be broken up into multiple sections and encodings. Most clients do not do this anymore and use a single section; however old AOL clients did this to save bandwidth.
{| class="wikitable"
! Name
! Type
! Notes
|-
| encoding
| uint16 (word)
| ''[Class: [[Protocols/OSCAR/Foodgroups/ICBM#Class:_ICBM__IM_ENCODING|ICBM__IM_ENCODING]]]'' Encoding of the data
|-
| language
| uint16 (word)
| Language of the data for old clients; new clients should just use 0
|-
| data
| blob
| The IM text; array of uint16 (word) if encoding is ICBM__IM_ENCODING_UNICODE, otherwise uint8 (byte)
|}
==== Class: ICBM__IM_ENCODING ====
An IM can be encoded in the following different forms:
{| class="wikitable"
! Name
! Value
! Notes
|-
| ICBM__IM_ENCODING_ASCII
| 0x00
| ANSI ASCII -- ISO 646
|-
| ICBM__IM_ENCODING_UNICODE
| 0x02
| ISO 10646.USC-2 Unicode
|-
| ICBM__IM_ENCODING_LATIN_1
| 0x03
| ISO 8859-1
|}
== SNACs ==
{{Protocols/OSCAR/Foodgroups/ICBM/SNACs}}
{{Protocols/OSCAR/Foodgroups/ICBM/SNACs}}


Latest revision as of 03:20, 27 March 2020

OSCAR Protocol
Introduction • Terms • Clients
Basic
Datatypes • FLAP • SNAC • TLV
UUIDs • Errors • Tool IDs
Host Interaction
Rate Limits • Migration • Messages
Other Services
ADMIN • ADVERT • ALERT
BART • BOS • BUCP • CHAT
CHAT_NAV
Tutorials
Sign On • BART • Rendezvous
ICBM • Locate • Buddies
Foodgroups
OSERVICE (0x0001)
LOCATE (0x0002)
BUDDY (0x0003)
ICBM (0x0004)
ADVERT (0x0005)
INVITE (0x0006)
ADMIN (0x0007)
POPUP (0x0008)
PD (0x0009)
USER_LOOKUP (0x000A)
STATS (0x000B)
TRANSLATE (0x000C)
CHAT_NAV (0x000D)
CHAT (0x000E)
ODIR (0x000F)
BART (0x0010)
FEEDBAG (0x0013)
ICQ (0x0015)
BUCP (0x0017)
ALERT (0x0018)
PLUGIN (0x0022)
UNNAMED_FG_24 (0x0024)
MDIR (0x0025)
ARS (0x044A)
ID Name Service Status Version
0x0004 ICBM BOS Active 1.25

ICBM, or Inter Client Basic Message, is a foodgroup focused around protocol messages that are sent between users or clients.

So now we get to the purpose of this whole thing: messaging. Instant messages are strings of ASCII codes that get sent in very-near-real-time between users of the Basic OSCAR Service (BOS). At no time does one client directly locate another client, or even know the location of any other client. All messages are sent to the message server, which then relays them to their destination client(s).

The text of a message is usually in the form of an HTML-like encoding that AOL calls "text/x-aol-rtf" (MIME format notation). For all intents and purposes, it's a subset of HTML. But, just like with HTML, you don't have to use HTML to be HTML. Sending straight ASCII text works just fine as well. The AOL-sourced AIM clients always use HTML even if you don't type or use any. They will usually append at least the <HTML>, <BODY>, and tags (and their appropriate closing tags) even if you didn't intend to use any. The server does not touch the message at all.

Sending and receiving instant messages (from now on called IMs), is really quite simple. There are some things that can make it go funny, though. I don't have all those things documented yet.

Tutorials

Datatypes and Classes

Datatype: Cookie

Name Size Notes
ICBM__COOKIE 8 byte Opaque data used to link conversations

Class: ICBM__CHANNELS

Messages sent between users are sent on a specific channel that narrow down how they should be processed and possible rate size parameters.

Name Value Notes
ICBM__CHANNEL_AOL_IM 0x01 Normal IM channel; all clients are expected to understand this channel
ICBM__CHANNEL_RENDEZVOUS 0x02 For rendezvous negotiations and sending data between clients
ICBM__CHANNEL_MIME 0x03 NOT CURRENTLY DOCUMENTED
ICBM__CHANNEL_ICQ 0x04 NOT CURRENTLY DOCUMENTED
ICBM__CHANNEL_COBROWSER 0x05 NOT CURRENTLY DOCUMENTED

Class: ICBM__FLAGS

These are flags the client uses to inform the server what kinds of features it supports for the ICBM channel.

Name Value Notes
ICBM__FLAG_CHANNEL_MSGS_ALLOWED 0x00000001 Wants ICBMs on this channel
ICBM__FLAG_MISSED_CALLS_ENABLED 0x00000002 Wants MISSED_CALLS on this channel
ICBM__FLAG_BLOCK_AUTH_MESSAGES 0x00000004 NOT CURRENTLY DOCUMENTED
ICBM__FLAG_EVENTS_ALLOWED 0x00000008 Wants CLIENT_EVENTs
ICBM__FLAG_SMS_SUPPORTED 0x00000010 Aware of sending to SMS
ICBM__FLAG_OFFLINE_MSGS_ALLOWED 0x00000100 Support offline IMs; client is capable of storing and retrieving

TLV Class: ICBM__TAGS

These are the TLV tags used in TOHOST and TOCLIENT SNACs.

Name Tag Type Notes
ICBM__TLV_TAGS_AOL_IM_DATA 0x02 Array of TLV [Class: ICBM__IM_DATA_TAGS] Message data for the IM channel only; unlike other TLVs the order of TLVs inside this tag does matter - it should be the CAPABILITIES item followed by multiple IM_TEXT items
ICBM__TLV_TAGS_REQUEST_HOST_ACK 0x03 empty Host will acknowledge this ICBM upon sending it to the destination client; this does NOT mean the destination user received it
ICBM__TLV_TAGS_AUTO_RESPONSE 0x04 empty This message is an auto response; this tag is not allowed with either the REQUEST_HOST_ACK or STORE tags
ICBM__TLV_TAGS_DATA 0x05 ICBM__IM_RENDEZVOUS Message data for all other channels
ICBM__TLV_TAGS_STORE 0x06 empty If the user is offline then store this message for delivery the next time the user logs in when possible; AIM and ICQ use complex privacy rules that control if an offline IM delivery is allowed or not
ICBM__TLV_TAGS_ICQBLOB 0x07 NOT CURRENTLY DOCUMENTED
ICBM__TLV_TAGS_AVATAR_INFO 0x08 NOT CURRENTLY DOCUMENTED
ICBM__TLV_TAGS_WANT_AVATAR 0x09 NOT CURRENTLY DOCUMENTED
ICBM__TLV_TAGS_MULTI_USER 0x0A NOT CURRENTLY DOCUMENTED
ICBM__TLV_TAGS_WANT_EVENTS 0x0B empty Used in TO_CLIENT only, it is added by the server if the sender wants client events
ICBM__TLV_TAGS_SUBSCRIPTIONS 0x0C NOT CURRENTLY DOCUMENTED
ICBM__TLV_TAGS_BART 0x0D BART__ID If desired BART items can be sent with the ICBM, the client should override the ones in USERINFO with these
ICBM__TLV_TAGS_HOST_IM_ID 0x10 u32 Unique id for host generated IMs alerting the user of some change
ICBM__TLV_TAGS_HOST_IM_ARGS 0x11 Array of string16 String arguments used to form the host generated IM
ICBM__TLV_TAGS_SEND_TIME 0x16 t70 Time when the server received the offline IM
ICBM__TLV_TAGS_FRIENDLY_NAME 0x17 string For WIMZI this is the friendly name of the anonymous user
ICBM__TLV_TAGS_ANONYMOUS 0x18 empty This is an anonymous IM
ICBM__TLV_TAGS_WIDGET_NAME 0x19 string The name of the WIMZI widget

Data Encoding

TLV Class: ICBM__IM_DATA_TAGS

These are the tags inside the IM_DATA TLV of an IM channel ICBM; order matters. For the IM_CHANNEL there should be one IM_CAPABILITIES followed by one or more IM_TEXT tags.

Name Tag Type Notes
ICBM__IM_DATA_TLV_TAGS_IM_TEXT 0x0101 ICBM__IM_SECTION The actual IM text; there can be multiple of these
ICBM__IM_DATA_TLV_TAGS_IM_CAPABILITIES 0x0501 uint8 (byte) Old client support; should just be the value 1
ICBM__IM_DATA_TLV_TAGS_MIME_ARRAY 0x0D01 uint16 (word) Short caps

Datatype: ICBM__IM_SECTION

An IM can be broken up into multiple sections and encodings. Most clients do not do this anymore and use a single section; however old AOL clients did this to save bandwidth.

Name Type Notes
encoding uint16 (word) [Class: ICBM__IM_ENCODING] Encoding of the data
language uint16 (word) Language of the data for old clients; new clients should just use 0
data blob The IM text; array of uint16 (word) if encoding is ICBM__IM_ENCODING_UNICODE, otherwise uint8 (byte)

Class: ICBM__IM_ENCODING

An IM can be encoded in the following different forms:

Name Value Notes
ICBM__IM_ENCODING_ASCII 0x00 ANSI ASCII -- ISO 646
ICBM__IM_ENCODING_UNICODE 0x02 ISO 10646.USC-2 Unicode
ICBM__IM_ENCODING_LATIN_1 0x03 ISO 8859-1

SNACs

Subgroup Origin Name
0x0001 Any ICBM__ERR
This is the error SNAC for the ICBM foodgroup.
0x0002 Client ICBM__ADD_PARAMETERS
This SNAC is typically sent prior to sending the OSERVICE__CLIENT_ONLINE so that the host is properly initialized with the clients' preferences.
0x0003 Client ICBM__DEL_PARAMETERS
These are the delete all parameters for a given channel.
0x0004 Client ICBM__PARAMETER_QUERY
This SNAC requests ICBM parameters from the host.
0x0005 Host ICBM__PARAMETER_REPLY
This SNAC is sent by the host in response to a ICBM__PARAMETER_QUERY.
0x0006 Client ICBM__CHANNEL_MSG_TOHOST
This is the basic inter-client message after which the group was named (Inter-Client Basic Messages).
0x0007 Host ICBM__CHANNEL_MSG_TOCLIENT
This is the ICBM__CHANNEL_MSG_TOHOST after it has been reformatted by the host and sent to the destination client.
0x0008 Client ICBM__EVIL_REQUEST
This requests that the specified user is sent an EVIL notification.
0x0009 Host ICBM__EVIL_REPLY
The reply tells the requester, the sender of an ICBM__EVIL_REQUEST SNAC, how much EVIL, if any, was applied to the recipient.
0x000A Host ICBM__MISSED_CALLS
When the host is unable to send one or more messages to the client, the host sends this SNAC to the client to let it know that it missed some messages ("calls").
0x000B Any ICBM__CLIENT_ERR
This error notice is one of the few SNACs that can be sent to the host and received by a client.
0x000C Host ICBM__HOST_ACK
This SNAC is sent by the host upon receipt of any ICBM__CHANNEL_MSG_TOHOST which includes the optional ICBM__TLV_TAGS_REQUEST_HOST_ACK TLV.
0x000D NCD ICBM__SIN_STORED
This is not currently documented. Want to contribute?
0x000E NCD ICBM__SIN_LIST_QUERY
This is not currently documented. Want to contribute?
0x000F NCD ICBM__SIN_LIST_REPLY
This is not currently documented. Want to contribute?
0x0010 Client ICBM__SIN_RETRIEVE
This requests ICBM__CHANNEL_MSG_TOCLIENT messages be generated for each of the stored ICBMs. Any message retrieved is deleted.
0x0011 NCD ICBM__SIN_DELETE
This is not currently documented. Want to contribute?
0x0012 NCD ICBM__NOTIFY_REQUEST
This is not currently documented. Want to contribute?
0x0013 NCD ICBM__NOTIFY_REPLY
This is not currently documented. Want to contribute?
0x0014 Any ICBM__CLIENT_EVENT
This SNAC is sent as a control message, sent by a client to inform the recipient of an event, or by the host informing of an event.
0x0017 Host ICBM__SIN_REPLY
The host successfully processed the request to retrieve all the offline messages.
Retrieved from "https://wiki.nina.chat/index.php?title=Protocols/OSCAR/Foodgroups/ICBM&oldid=2036"