Protocols/OSCAR/Foodgroups/BART: Difference between revisions

From NINA Wiki
Jump to navigation Jump to search
 
(7 intermediate revisions by the same user not shown)
Line 9: Line 9:
{{Protocols/OSCAR/Foodgroups/BART/Description}}
{{Protocols/OSCAR/Foodgroups/BART/Description}}


== Introduction ==
For some items, the actual assets are downloaded using the BART system and in other cases, just descriptive XML files are used. Once a BART item is downloaded, it is basically cached FOREVER by the client, so updating requires publishing a new BART item. This is especially important when the BART item is an asset. When the BART item is a descriptive XML file, only the XML file is cached forever and any assets it refers to can use different caching schemes determined by the client.
For some items, the actual assets are downloaded using the BART system and in other cases, just descriptive XML files are used. Once a BART item is downloaded, it is basically cached FOREVER by the client, so updating requires publishing a new BART item. This is especially important when the BART item is an asset. When the BART item is a descriptive XML file, only the XML file is cached forever and any assets it refers to can use different caching schemes determined by the client.


Line 15: Line 16:
Having a Buddy icon with opaque data of 0x0201d20472 means the user has explicitly chosen to have no Buddy icon. This is different then not having a Buddy icon. This ID should be treated specially and does not need to be fetched from BART (although BART will return an empty GIF). This was done so clients could tell when they upgraded from old style Buddy icons to BART Buddy icons. This special ID should NOT be used for other BART types.
Having a Buddy icon with opaque data of 0x0201d20472 means the user has explicitly chosen to have no Buddy icon. This is different then not having a Buddy icon. This ID should be treated specially and does not need to be fetched from BART (although BART will return an empty GIF). This was done so clients could tell when they upgraded from old style Buddy icons to BART Buddy icons. This special ID should NOT be used for other BART types.


=== Class: BART__ID_FLAGS ===
== SNACs ==
{{Protocols/OSCAR/Foodgroups/BART/SNACs}}
 
== BART_ID ==
 
=== Datatype: BART__ID ===


These are the flags used by the client to detect how the BART ID should be processed.
This represents a BART asset and can be thought of as a "Tiny URL" equivalent. Some BART IDs contain the data while some are pointers to the data and must be downloaded using the BART server.


{| class="wikitable"
{| class="wikitable"
! Name
! Name
! Value
! Type
! Notes
! Notes
|-
|-
| BART__FLAGS_KNOWN
| type
| 0x00
| uint16 (word)
| NOT CURRENTLY DOCUMENTED
| ''[Class: [[Protocols/OSCAR/Foodgroups/BART#Class:_BART_ID_TYPES|BART__ID_TYPES]]]'' Kind of asset this BART ID represents
|-
|-
| BART__FLAGS_CUSTOM
| flags
| 0x01
| uint8 (byte)
| This is a custom blob; the opaque data will also be 16 bytes
| ''[Class: [[Protocols/OSCAR/Foodgroups/BART#Class:_BART_ID_FLAGS BART__ID_FLAGS]]]'' Any flags associated with the BART item; DATA is important since it means the BART__ID holds the data and the BART server is not needed
|-
|-
| BART__FLAGS_URL
| len
| 0x02
| uint8 (byte)
| Contains URL to BART content
| Length of the opaque data
|-
| BART__FLAGS_DATA
| 0x04
| The opaque field is really data the client knows how to process; these items do not need to be downloaded from BART
|-
| BART__FLAGS_UNKNOWN
| 0x40
| Used in OSERVICE__BART_REPLY; BART does not know about this ID, please upload
|-
|-
| BART__FLAGS_REDIRECT
| opaque
| 0x80
| Array of uint8 (byte) length len
| Used in OSERVICE__BART_REPLY; BART says use this ID instead for the matching type
| Opaque data; if the DATA flag is set then this is the actual data to use
|-
| BART__FLAGS_BANNED
| 0xC0
| BART is disallowed by hash
|}
|}


Line 102: Line 96:
| NOT CURRENTLY DOCUMENTED
| NOT CURRENTLY DOCUMENTED
|-
|-
| BART__TYPES_BIG_ICON
| BART__TYPES_BUDDY_ICON_BIG
| 0x0C
| 0x0C
| SWF
| SWF
Line 183: Line 177:
|}
|}


== SNACs ==
=== Class: BART__ID_FLAGS ===
{{Protocols/OSCAR/Foodgroups/BART/SNACs}}
 
These are the flags used by the client to detect how the BART ID should be processed.
 
{| class="wikitable"
! Name
! Value
! Notes
|-
| BART__FLAGS_KNOWN
| 0x00
| NOT CURRENTLY DOCUMENTED
|-
| BART__FLAGS_CUSTOM
| 0x01
| This is a custom blob; the opaque data will also be 16 bytes
|-
| BART__FLAGS_URL
| 0x02
| Contains URL to BART content
|-
| BART__FLAGS_DATA
| 0x04
| The opaque field is really data the client knows how to process; these items do not need to be downloaded from BART
|-
| BART__FLAGS_UNKNOWN
| 0x40
| Used in OSERVICE__BART_REPLY; BART does not know about this ID, please upload
|-
| BART__FLAGS_REDIRECT
| 0x80
| Used in OSERVICE__BART_REPLY; BART says use this ID instead for the matching type
|-
| BART__FLAGS_BANNED
| 0xC0
| BART is disallowed by hash
|}
 
== For Query Responses ==
 
=== Datatype: BART__QUERY_REPLY_ID ===
 
This links a queried BART ID with an error code and a replyId.
 
{| class="wikitable"
! Name
! Type
! Notes
|-
| queryId
| [[Protocols/OSCAR/Foodgroups/BART#Datatype:_BART_ID|BART__ID]]
| Initial ID that is queried or used
|-
| code
| uint8 (byte)
| ''[Class: [[Protocols/OSCAR/Foodgroups/BART#Class:_BART_REPLY_CODES|BART__REPLY_CODES]]]'' Result code of the query
|-
| replyId
| [[Protocols/OSCAR/Foodgroups/BART#Datatype:_BART_ID|BART__ID]]
| ID that will be used; might be different then queryId
|}
 
=== Class: BART__REPLY_CODES ===
 
These are the result codes of uploads, downloads, and queries.
 
{| class="wikitable"
! Name
! Value
! Notes
|-
| BART__REPLY_CODES_SUCCESS
| 0x00
| Operation was a success
|-
| BART__REPLY_CODES_INVALID
| 0x01
| ID is malformed
|-
| BART__REPLY_CODES_NOCUSTOM
| 0x02
| Custom blobs are not allowed for this type
|-
| BART__REPLY_CODES_TOSMALL
| 0x03
| Item uploaded is too small for this type
|-
| BART__REPLY_CODES_TOBIG
| 0x04
| Item uploaded is too big for this type
|-
| BART__REPLY_CODES_INVALIDTYPE
| 0x05
| Item uploaded is the wrong type
|-
| BART__REPLY_CODES_BANNED
| 0x06
| Item uploaded has been banned
|-
| BART__REPLY_CODES_NOTFOUND
| 0x07
| Item downloaded was not found
|}
 
=== Datatype: BART__ID_TO_USERNAME ===
 
This links a BART ID and a username.
 
{| class="wikitable"
! Name
! Type
! Notes
|-
| username
| string08
| User who is using the asset
|-
| numIds
| uint8 (byte)
| Number of assets being requested
|-
| ids
| Array of [[Protocols/OSCAR/Foodgroups/BART#Datatype:_BART_ID|BART__ID]] length numIds
| BART IDs to fetch
|}


[[Category:Stub]]
[[Category:Stub]]

Latest revision as of 12:42, 24 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
0x0010 BART BOS Active 1.9

The Buddy Art, or BART, server provides access to the client for downloading image, sound, and xml assets for expressions for their buddies and themselves. Examples of BART items include Buddy icons, Buddy arrival sounds, and immersive wallpapers.

Introduction

For some items, the actual assets are downloaded using the BART system and in other cases, just descriptive XML files are used. Once a BART item is downloaded, it is basically cached FOREVER by the client, so updating requires publishing a new BART item. This is especially important when the BART item is an asset. When the BART item is a descriptive XML file, only the XML file is cached forever and any assets it refers to can use different caching schemes determined by the client.

All BART items are represented by a BART ID. A BART ID is a 5 byte to 20 byte binary value that represents the BART item and is sent around by the client and the servers. One simple way to think of the BART ID is as a compressed URL. When the client receives a BART ID, either from another client or from the server, it checks its cache or uses the BART server to download the item. The BART server also has a cache and connects to the various partners to download the assets if it does not have them. It is expected that each BART ID points to a unique item. The backend will collapse duplicate items into a single ID. The BART server also will store custom items for some asset types.

Having a Buddy icon with opaque data of 0x0201d20472 means the user has explicitly chosen to have no Buddy icon. This is different then not having a Buddy icon. This ID should be treated specially and does not need to be fetched from BART (although BART will return an empty GIF). This was done so clients could tell when they upgraded from old style Buddy icons to BART Buddy icons. This special ID should NOT be used for other BART types.

SNACs

Subgroup Origin Name
0x0001 Any BART__ERR
This is the error SNAC for the BART foodgroup.
0x0002 Client BART__UPLOAD_QUERY
This SNAC uploads a custom item to the BART host. Only certain types allow custom items.
0x0003 Host BART__UPLOAD_REPLY
These are the results for an item requested with BART__UPLOAD_QUERY.
0x0004 Client BART__DOWNLOAD_QUERY
Legacy request buddy icon from host.
0x0005 Host BART__DOWNLOAD_REPLY
Legacy host response to a buddy icon request.
0x0006 Client BART__DOWNLOAD2_QUERY
This SNAC downloads an asset from the BART host.
0x0007 Host BART__DOWNLOAD2_REPLY
These are the results for an item requested with BART__DOWNLOAD2_QUERY.

BART_ID

Datatype: BART__ID

This represents a BART asset and can be thought of as a "Tiny URL" equivalent. Some BART IDs contain the data while some are pointers to the data and must be downloaded using the BART server.

Name Type Notes
type uint16 (word) [Class: BART__ID_TYPES] Kind of asset this BART ID represents
flags uint8 (byte) [Class: Protocols/OSCAR/Foodgroups/BART#Class:_BART_ID_FLAGS BART__ID_FLAGS] Any flags associated with the BART item; DATA is important since it means the BART__ID holds the data and the BART server is not needed
len uint8 (byte) Length of the opaque data
opaque Array of uint8 (byte) length len Opaque data; if the DATA flag is set then this is the actual data to use

Class: BART__ID_TYPES

These are all the different BART ID types that are known about and their restrictions.

Name Value Notes
BART__TYPES_BUDDY_ICON_SMALL 0x00 GIF/JPG/BMP, <= 32 pixels and 2k
BART__TYPES_BUDDY_ICON 0x01 GIF/JPG/BMP, <= 64 pixels and 7k
BART__TYPES_STATUS_STR 0x02 StringTLV format; DATA flag is always set
BART__TYPES_ARRIVE_SOUND 0x03 WAV/MP3/MID, <= 10K
BART__TYPES_RICH_NAME 0x04 byte array of rich text codes; DATA flag is always set
BART__TYPES_SUPER_ICON 0x05 XML
BART__TYPES_RADIO_STATION 0x06 Opaque struct; DATA flag is always set
BART__TYPES_SUPER_ICON_TRIGGER 0x07 NOT CURRENTLY DOCUMENTED
BART__TYPES_STATUS_TEXT_LINK 0x09 NOT CURRENTLY DOCUMENTED
BART__TYPES_LOCATION 0x0B NOT CURRENTLY DOCUMENTED
BART__TYPES_BUDDY_ICON_BIG 0x0C SWF
BART__TYPES_STATUS_TEXT_TIMESTAMP 0x0D Time when the status string is set
BART__TYPES_CURRENT_AVTRACK 0x0F XML file; Data flag should not be set
BART__TYPES_DEPART_SOUND 0x60 WAV/MP3/MID, <= 10K
BART__TYPES_IM_BACKGROUND 0x80 NOT CURRENTLY DOCUMENTED
BART__TYPES_IM_CHROME 0x81 GIF/JPG/BMP wallpaper
BART__TYPES_IM_SKIN 0x82 NOT CURRENTLY DOCUMENTED
BART__TYPES_IM_SOUND 0x83 WAV/MP3, <= 10K
BART__TYPES_BADGE 0x84 NOT CURRENTLY DOCUMENTED
BART__TYPES_BADGE_URL 0x85 NOT CURRENTLY DOCUMENTED
BART__TYPES_IM_INITIAL_SOUND 0x86 NOT CURRENTLY DOCUMENTED
BART__TYPES_FLASH_WALLPAPER 0x88 XML
BART__TYPES_IMMERSIVE_WALLPAPER 0x89 Immersive Expressions
BART__TYPES_BUDDYLIST_BACKGROUND 0x100 NOT CURRENTLY DOCUMENTED
BART__TYPES_BUDDYLIST_IMAGE 0x101 NOT CURRENTLY DOCUMENTED
BART__TYPES_BUDDYLIST_SKIN 0x102 NOT CURRENTLY DOCUMENTED
BART__TYPES_SMILEY_SET 0x400 Set of default Emoticons
BART__TYPES_ENCR_CERT_CHAIN 0x402 Cert chain for encryption certs
BART__TYPES_SIGN_CERT_CHAIN 0x403 Cert chain for signing certs
BART__TYPES_GATEWAY_CERT 0x404 Cert for enterprise gateway

Class: BART__ID_FLAGS

These are the flags used by the client to detect how the BART ID should be processed.

Name Value Notes
BART__FLAGS_KNOWN 0x00 NOT CURRENTLY DOCUMENTED
BART__FLAGS_CUSTOM 0x01 This is a custom blob; the opaque data will also be 16 bytes
BART__FLAGS_URL 0x02 Contains URL to BART content
BART__FLAGS_DATA 0x04 The opaque field is really data the client knows how to process; these items do not need to be downloaded from BART
BART__FLAGS_UNKNOWN 0x40 Used in OSERVICE__BART_REPLY; BART does not know about this ID, please upload
BART__FLAGS_REDIRECT 0x80 Used in OSERVICE__BART_REPLY; BART says use this ID instead for the matching type
BART__FLAGS_BANNED 0xC0 BART is disallowed by hash

For Query Responses

Datatype: BART__QUERY_REPLY_ID

This links a queried BART ID with an error code and a replyId.

Name Type Notes
queryId BART__ID Initial ID that is queried or used
code uint8 (byte) [Class: BART__REPLY_CODES] Result code of the query
replyId BART__ID ID that will be used; might be different then queryId

Class: BART__REPLY_CODES

These are the result codes of uploads, downloads, and queries.

Name Value Notes
BART__REPLY_CODES_SUCCESS 0x00 Operation was a success
BART__REPLY_CODES_INVALID 0x01 ID is malformed
BART__REPLY_CODES_NOCUSTOM 0x02 Custom blobs are not allowed for this type
BART__REPLY_CODES_TOSMALL 0x03 Item uploaded is too small for this type
BART__REPLY_CODES_TOBIG 0x04 Item uploaded is too big for this type
BART__REPLY_CODES_INVALIDTYPE 0x05 Item uploaded is the wrong type
BART__REPLY_CODES_BANNED 0x06 Item uploaded has been banned
BART__REPLY_CODES_NOTFOUND 0x07 Item downloaded was not found

Datatype: BART__ID_TO_USERNAME

This links a BART ID and a username.

Name Type Notes
username string08 User who is using the asset
numIds uint8 (byte) Number of assets being requested
ids Array of BART__ID length numIds BART IDs to fetch
Retrieved from "https://wiki.nina.chat/index.php?title=Protocols/OSCAR/Foodgroups/BART&oldid=1868"