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) |
Contents
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 | 0x0001 | uint16 (word) | ICBM channel on which the rendezvous is to occur |
| RENDEZVOUS_TLV_TAGS_RENDEZVOUS_IP_ADDR | 0x0002 | uint32 (dword) | IP address proposed for the rendezvous |
| RENDEZVOUS_TLV_TAGS_REQUESTER_IP_ADDR | 0x0003 | uint32 (dword) | IP address of the proposing client |
| RENDEZVOUS_TLV_TAGS_VERIFIED_IP_ADDR | 0x0004 | 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 | 0x0005 | uint16 (word) | Port value of the client for rendezvous |
| RENDEZVOUS_TLV_TAGS_DOWNLOAD_URL | 0x0006 | string | URL for downloading software to support the service |
| RENDEZVOUS_TLV_TAGS_DOWNLOAD_URL2 | 0x0007 | string | NOT CURRENTLY DOCUMENTED |
| RENDEZVOUS_TLV_TAGS_VERIFIED_DOWNLOAD_URL | 0x0008 | 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 | 0x000A | 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 | 0x000B | 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 | 0x000C | string | Text inviting the other player to join |
| RENDEZVOUS_TLV_TAGS_INVITE_MIME_CHARSET | 0x000D | string | Charset used by the data |
| RENDEZVOUS_TLV_TAGS_INVITE_MIME_LANG | 0x000E | string | Language used by the data |
| RENDEZVOUS_TLV_TAGS_REQUEST_HOST_CHECK | 0x000F | empty | Requests that the server check caps for recipient |
| RENDEZVOUS_TLV_TAGS_USE_ARS | 0x0010 | empty | Requests that the Rendezvous Server be used as a transport for the data |
| RENDEZVOUS_TLV_TAGS_REQUEST_SECURE | 0x0011 | empty | Requests that SSL be used for the connection |
| RENDEZVOUS_TLV_TAGS_MAX_PROTOCOL_VERSION | 0x0012 | uint16 (word) | Maximum application protocol version supported |
| RENDEZVOUS_TLV_TAGS_MIN_PROTOCOL_VERSION | 0x0013 | uint16 (word) | Minimum application protocol version supported |
| RENDEZVOUS_TLV_TAGS_COUNTER_REASON | 0x0014 | uint16 (word) | Reason for a counter proposal |
| RENDEZVOUS_TLV_TAGS_INVITE_MIME_TYPE | 0x0015 | string | Content-type used by the data |
| RENDEZVOUS_TLV_TAGS_IP_ADDR_XOR | 0x0016 | 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 | 0x0017 | 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 | 0x0018 | Array of string08 | List of "IP port" pairs to try |
| RENDEZVOUS_TLV_TAGS_SESSION_ID | 0x0019 | string | Identifier for session |
| RENDEZVOUS_TLV_TAGS_ROLLOVER_ID | 0x001A | string | Identifier of session to rollover |
| RENDEZVOUS_TLV_TAGS_SERVICE_DATA | 0x2711 | blob | Service specific data |
