Protocols/OSCAR/TLV

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)

TLVs notes from another

TLVs are a very common structure used in the OSCAR protocol to represent dynamically typed data. Parsers should always ignore unknown tags as to not break old clients when new protocol items are added. Possible values for tags are determined by where the TLV is in the protocol; these possible values belong to a TLV class. In the wild, the term type is sometimes used interchangeably with tag, however this document uses tag to reference the integer value associated with the TLV and type as the datatype associated with that tag.

Name	Size	Notes
Type	uint16 (word)	Numeric type or "tag" of the data, possible values are defined in the TLV class for the group of TLVs
Length	uint16 (word)	Length in bytes of the variable data
Value	blob	The data inside the TLV of len length; usually another datatype is used to represent the data - this is described in the TLV class

TLVs are usually used in an array of TLV form, allowing the protocol to easily be expanded. Having just one TLV without an array does not gain much since it only allows one item to be described. There are two common methods for adding an array of TLVs to datatypes and SNACs. An additional method also exists to add an array of TLVs to SNACs.

The most common is a tlvBlock which is a u16 number of TLVs followed by that many TLVs. The less common is a tlvLBlock which instead of counting the number of TLVs, counts the size of all the TLVs. The third, which is only available in SNACs, is the tlvRestBlock which says any remaining bytes in the SNAC are TLVs.

Name	Size	Notes
tlvBlock	uint16 (word) + data	Two byte number of elements, followed by that many elements
tlvLBlock	uint16 (word) + data	Two byte length of elements, followed by that many bytes of elements

Common TLVs

From Aleksandr Shutko: Common tlv set.

Common tlv set.

Here is a common set of widely used tlvs:  00 01   word   TLV.Type(0x01) - screen name (uin)  xx xx   word   TLV.Length  xx ..   string   screen name (uin)  00 02   word   TLV.Type(0x02) - new password  xx xx   word   TLV.Length  xx ..   array   new password string  00 03   word   TLV.Type(0x03) - client identity string  xx xx   word   TLV.Length  xx ..   string   client identity string (name, version)  00 04   word   TLV.Type(0x04) - error description url  xx xx   word   TLV.Length  xx ..   string   error description url string  00 05   word   TLV.Type(0x05) - reconnect here  xx xx   word   TLV.Length  xx ..   string   server address & port string  00 06   word   TLV.Type(0x06) - authorization cookie  xx xx   word   TLV.Length  xx ..   array   authorization cookie  00 07   word   TLV.Type(0x07) - snac version  xx xx   word   TLV.Length         ?  00 08   word   TLV.Type(0x08) - error subcode  xx xx   word   TLV.Length  xx xx   word   error subcode (family specific)  00 09   word   TLV.Type(0x09) - disconnect reason  xx xx   word   TLV.Length  xx xx   word   disconnect reason (see table below)  00 0A   word   TLV.Type(0x0A) - reconnect hostname  xx xx   word   TLV.Length         ?  00 0B   word   TLV.Type(0x0B) - url  xx xx   word   TLV.Length  xx ..   string   url  00 0C   word   TLV.Type(0x0C) - debug data  xx xx   word   TLV.Length  xx xx   word   debug data  00 0D   word   TLV.Type(0x0D) - service (family) id  xx xx   word   TLV.Length  xx xx   word   service (family) id  00 0E   word   TLV.Type(0x0E) - client country (2 symbols)  xx xx   word   TLV.Length  xx ..   string   client country  00 0F   word   TLV.Type(0x0F) - client language (2 symbols)  xx xx   word   TLV.Length  xx ..   string   client language  00 10   word   TLV.Type(0x10) - script  xx xx   word   TLV.Length         ?  00 11   word   TLV.Type(0x11) - user email  xx xx   word   TLV.Length  xx ..   string   user email string  00 12   word   TLV.Type(0x12) - old password  xx xx   word   TLV.Length  xx ..   string   old password string  00 13   word   TLV.Type(0x13) - registration status  xx xx   word   TLV.Length  xx xx   word   registration status (1 - no disclosure, 2 - limit disclosure, 3 - full disclosure (?))  00 14   word   TLV.Type(0x14) - distribution number  00 04   word   TLV.Length  xx xx xx xx   dword   distribution number  00 15   word   TLV.Type(0x15) - personal text  xx xx   word   TLV.Length         ?  00 16   word   TLV.Type(0x16) - client id  00 02   word   TLV.Length  xx xx   word   client id number  00 17   word   TLV.Type(0x17) - client major version  00 02   word   TLV.Length  xx xx   word   client major version  00 18   word   TLV.Type(0x18) - client minor version  00 02   word   TLV.Length  xx xx   word   client minor version  00 19   word   TLV.Type(0x19) - client lesser version  00 02   word   TLV.Length  xx xx   word   client lesser version  00 1A   word   TLV.Type(0x1A) - client build number  00 02   word   TLV.Length  xx xx   word   client build number  00 25   word   TLV.Type(0x25) - password hash (MD5)  00 10   word   TLV.Length  xx xx xx xx  xx xx xx xx  xx xx xx xx  xx xx xx xx   array   password hash (MD5)  00 40   word   TLV.Type(0x40) - latest beta build number  xx xx   word   TLV.Length  xx xx xx xx   dword   latest beta build number  00 41   word   TLV.Type(0x41) - latest beta install url  xx xx   word   TLV.Length  xx ..   string   latest beta install url  00 42   word   TLV.Type(0x42) - latest beta info url  xx xx   word   TLV.Length  xx ..   string   latest beta info url  00 43   word   TLV.Type(0x43) - latest beta version  xx xx   word   TLV.Length  xx ..   string   latest beta version  00 44   word   TLV.Type(0x44) - latest release build number  xx xx   word   TLV.Length  xx xx xx xx   dword   latest release build number  00 45   word   TLV.Type(0x45) - latest release install url  xx xx   word   TLV.Length  xx ..   string   latest release install url  00 46   word   TLV.Type(0x46) - latest release info url  xx xx   word   TLV.Length  xx ..   string   latest release info url  00 47   word   TLV.Type(0x47) - latest release version  xx xx   word   TLV.Length  xx ..   string   latest release version  00 48   word   TLV.Type(0x48) - beta digest signature (MD5)  00 20   word   TLV.Length  xx ...   string   hexadecimal string for beta digest signature (MD5)  00 49   word   TLV.Type(0x49) - release digest signature (MD5)  00 20   word   TLV.Length  xx ...   string   hexadecimal string for release digest signature (MD5)  00 54   word   TLV.Type(0x54) - change password url  xx xx   word   TLV.Length  xx ...   string   change password url

From Aleksandr Shutko: Basic OSCAR information: TLV

TLV (Type-Length-Value) tuple description         TLVs are a very convenient and efficient method of putting data into an organized format, especially variable length strings, etc. TLV literally stands for "Type, Length, Value". And that's exactly what it is: a 16bit Type code, a 16bit value for the length of the Value field, and then the actual data in the Value field (variable length). Here is TLV format:  xx xx   word   TLV type number  xx xx   word   TLV length value  ...... TLV data      TLVs can be be in SNACs, but that's not required. TLVs often are used directly in the FLAP Data Field, but normally are inside of SNACs. More than one TLV of each Type code may exist in a single FLAP command (SNAC or not). TLVs must follow the strict tuple-rule, or they're really not TLVs, they're raw data. One tlv may contain nested tlv chain inside.      TLVs are a big win. They make sending a variable length string like, e.g., "afritz@iname" as simple as defining a TLV with values {0x0011, 0x000c, "afritz@iname.com"}. (The type 0x0011 is used throughout the authorization process as the "email address type".) A side note about strings: strings in this protocol are never NULL-terminated. If they look like they are, that's probably a word-length value behind it.