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.
| |
| |
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 |
|
|
|
|
| |
| |
|
| |
| 00 0C |
|
word |
|
TLV.Type(0x0C) - debug data |
| xx xx |
|
word |
|
TLV.Length |
|
|
|
|
| |
| |
|
| |
| 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 |
|
|
|
|
|
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.
|
|
|
|
|
