Protocols/OSCAR/Services/Rendezvous

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)

ICBM

Datatype: ICBM__IM_RENDEZVOUS

There are three different types of rendezvous messages - propose, cancel, and accept.

PROPOSE

This is the message that a client sends to the server to propose a rendezvous with another client. The tag values to be used in the TLV are the ones specified in RENDEZVOUS_TLV_TAGS. Proposals typically specify either a RENDEZVOUS__CHANNEL or a RENDEZVOUS_IP_ADDR/PORT pair. If neither is specified, the systems which are rendezvousing must know out-of-band how to connect to each other (e.g., a server IP_ADDR compiled into a third party client).

If specifying RENDEZVOUS_IP_ADDR, the client may also specify PROPOSER_IP_ADDR which is the IP address that it identifies itself by, as found by a call to get_local_host. If PROPOSER_IP_ADDR is used, VERIFIED_IP_ADDR is added by the server before sending the RENDEZVOUS_PROPOSAL_TO_CLIENT.

VERIFIED_IP_ADDR may not be specified by the client in RENDEZVOUS_PROPOSAL_TOHOST. Likewise, if DOWNLOAD_URL is specified and the service UUID matches a well known service, the server may add VERIFIED_DOWNLOAD_URL. The client may not specify VERIFIED_DOWNLOAD_URL itself.

Additionally, the client can send any tags specific to a given service as long as the tag values fall outside the reserved range defined above.

NOTE: Reserved tag values MUST be at the beginning of the TLV. The server will stop parsing the TLV as soon as it encounters the first non-reserved tag.

CANCEL

This message is sent by the sender of a RENDEZVOUS_PROPOSAL_TOCLIENT in order to indicate a desire to cancel the rendezvous. Note that due to timing issues, the cancel may arrive at the other client after the other client has acted on the rendezvous proposal.

In other words, cancel is an advisory message only. The sender should take other precautions to prevent a rendezvous attempt from succeeding (e.g., shut down any systems which are listening, etc.).

ACCEPT

This message is sent by the recipient of a PROPOSE in order to indicate that it has completed the rendezvous. It may contain modifications to the original PROPOSE TLVs indicating different levels of feature support (e.g., version negotiation).

Name	Type	Notes
type	uint16 (word)	[Class: ICBM__RENDEZVOUS_MESSAGE] What kind of rendezvous message is this
cookie	ICBM Cookie	Opaque data generated by conversation initiator and used to link up the conversation and errors
service	UUID	Identifies type of data message being exchanged
params	Rest of SNAC array of TLV	[Class: ICBM__RENDEZVOUS_TAGS] Message data and parameters

Class: ICBM__RENDEZVOUS_MESSAGE

This is a type of rendezvous/data message.

Name	Value	Notes
RENDEZVOUS_MESSAGE_PROPOSE	0x00	Propose a rendezvous
RENDEZVOUS_MESSAGE_CANCEL	0x01	Cancel a proposal you generated
RENDEZVOUS_MESSAGE_ACCEPT	0x02	Accept a proposal someone else generated
RENDEZVOUS_MESSAGE_NAK	0x03	NOT CURRENTLY DOCUMENTED

Class: ICBM__RENDEZVOUS_CANCEL_REASONS

These are the reasons a proposal is cancelled.

Name	Value	Notes
RENDEZVOUS_CANCEL_REASONS_UNKNOWN	0x00	Reason not specified
RENDEZVOUS_CANCEL_REASONS_USER_CANCEL	0x01	Recipient user declined
RENDEZVOUS_CANCEL_REASONS_TIMEOUT	0x02	Timeout
RENDEZVOUS_CANCEL_REASONS_ACCEPTED_ELSEWHERE	0x03	Proposal was accepted by a different instance of the user

Class: ICBM__RENDEZVOUS_NAK

Sent in ICBM__CLIENT_ERR errorInfo field

Name	Value	Notes
RENDEZVOUS_NAK_PROPOSAL_UNSUPPORTED	0x00	Proposal UUID not supported
RENDEZVOUS_NAK_PROPOSAL_DENIED	0x01	Not authorized, or user declined
RENDEZVOUS_NAK_PROPOSAL_IGNORED	0x02	DO NOT USE; 'ignores' should no-op
RENDEZVOUS_NAK_BUSTED_PARAMETERS	0x03	Proposal malformed
RENDEZVOUS_NAK_PROPOSAL_TIMED_OUT	0x04	Attempt to act on proposal (e.g. connect) timed out
RENDEZVOUS_NAK_ONLINE_BUT_NOT_AVAILABLE	0x05	Recipient away or busy
RENDEZVOUS_NAK_INSUFFICIENT_RESOURCES	0x06	Recipient had internal error
RENDEZVOUS_NAK_RATELIMITED	0x07	Recipient was ratelimited
RENDEZVOUS_NAK_NO_DATA	0x08	Recipient had nothing to send
RENDEZVOUS_NAK_NO_VERSION_MISMATCH	0x09	Incompatible versions
SECURITY_MISMATCH	0x0A	Incompatible security settings
SERVICE_SPECIFIC_REASON	0x0F	Service-specific reject defined by client

TLV Class: ICBM__RENDEZVOUS_TAGS

These are the tags inside the DATA TLV of the RENDEZVOUS channel in ICBM.

Name	Tag	Type	Notes
RENDEZVOUS_TLV_TAGS_RENDEZVOUS_CHANNEL	0x01	uint16 (word)	ICBM channel on which the rendezvous is to occur
RENDEZVOUS_TLV_TAGS_RENDEZVOUS_IP_ADDR	0x02	uint32 (dword)	IP address proposed for the rendezvous
RENDEZVOUS_TLV_TAGS_REQUESTER_IP_ADDR	0x03	uint32 (dword)	IP address of the proposing client
RENDEZVOUS_TLV_TAGS_VERIFIED_IP_ADDR	0x04	uint32 (dword)	IP address of the proposing client as seen by server; NOTE - this TLV may only be added by the server
RENDEZVOUS_TLV_TAGS_PORT	0x05	uint16 (word)	Port value of the client for rendezvous
RENDEZVOUS_TLV_TAGS_DOWNLOAD_URL	0x06	string	URL for downloading software to support the service
RENDEZVOUS_TLV_TAGS_DOWNLOAD_URL2	0x07	string	NOT CURRENTLY DOCUMENTED
RENDEZVOUS_TLV_TAGS_VERIFIED_DOWNLOAD_URL	0x08	string	Same as DOWNLOAD_URL, but added by server if the service is well known; Note - this TLV may only be added by the server
RENDEZVOUS_TLV_TAGS_SEQUENCE_NUM	0x0A	uint16 (word)	Identifies which proposal this is in the rendezvous conversation; the initial proposal has sequence_num 1; NOTE - this tag is required in *all* rendezvous *proposal* payloads and may only occur in proposal payloads; each proposal applying to a given rendezvous cookie increments the sequence_num by one
RENDEZVOUS_TLV_TAGS_CANCEL_REASON	0x0B	uint16 (word)	[Class: ICBM__RENDEZVOUS_CANCEL_REASONS] Reason for cancelling a rendezvous; this tag must be present in all RENDEZVOUS_CANCEL payloads.
RENDEZVOUS_TLV_TAGS_INVITATION	0x0C	string	Text inviting the other player to join
RENDEZVOUS_TLV_TAGS_INVITE_MIME_CHARSET	0x0D	string	Charset used by the data
RENDEZVOUS_TLV_TAGS_INVITE_MIME_LANG	0x0E	string	Language used by the data
RENDEZVOUS_TLV_TAGS_REQUEST_HOST_CHECK	0x0F	empty	Requests that the server check caps for recipient
RENDEZVOUS_TLV_TAGS_USE_ARS	0x10	empty	Requests that the Rendezvous Server be used as a transport for the data
RENDEZVOUS_TLV_TAGS_REQUEST_SECURE	0x11	empty	Requests that SSL be used for the connection
RENDEZVOUS_TLV_TAGS_MAX_PROTOCOL_VERSION	0x12	uint16 (word)	Maximum application protocol version supported
RENDEZVOUS_TLV_TAGS_MIN_PROTOCOL_VERSION	0x13	uint16 (word)	Minimum application protocol version supported
RENDEZVOUS_TLV_TAGS_COUNTER_REASON	0x14	uint16 (word)	Reason for a counter proposal
RENDEZVOUS_TLV_TAGS_INVITE_MIME_TYPE	0x15	string	Content-type used by the data
RENDEZVOUS_TLV_TAGS_IP_ADDR_XOR	0x16	uint32 (dword)	Contains IP_ADDR ^ 0xFFFFFFFF - Used with recent clients to ensure that the IP_ADDR tlv is not tampered with or modified by a NAT since some NATs will change the IP_ADDR tlv when the proposal is sent
RENDEZVOUS_TLV_TAGS_PORT_XOR	0x17	uint16 (word)	PORT ^ 0xFFFF - Used with recent clients to ensure that the PORT tlv is not tampered with or modified by a NAT since some NATs will change the PORT tlv when the proposal is sent
RENDEZVOUS_TLV_TAGS_ADDR_LIST	0x18	Array of string08	List of "IP port" pairs to try
RENDEZVOUS_TLV_TAGS_SESSION_ID	0x19	string	Identifier for session
RENDEZVOUS_TLV_TAGS_ROLLOVER_ID	0x1A	string	Identifier of session to rollover
RENDEZVOUS_TLV_TAGS_SERVICE_DATA	10001	blob	Service specific data