INTERNET-DRAFT Avshalom Houri draft-houri-sametime-community-client-00.txt Ubique/Lotus Expires February 28, 2000 Ittai Golde Ubique/Lotus Sametime (TM) Community - Client Protocol draft-houri-sametime-community-client-00.txt This document is an Internet-Draft and is NOT offered in accordance with Section 10 of RFC2026, and the authors do not provide the IETF with any rights other than to publish it as an Internet-Draft. In particular, commercial use of this protocol requires licensing. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet - Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This document and related documents are discussed on the impp mailing list. To join the list, send mail to impp-request@iastate.edu. To contribute to the discussion, send mail to impp@iastate.edu. The archives are at http://lists.fsck.com/cgi-bin/wilma/pip. The IMPP working group charter, including the current list of group documents, can be found at: http://www.ietf.org/html.charters/impp-charter.html. page 1 Sametime Community - Client Protocol Page 1 1. Table of Contents 1. Table of Contents 2. Abstract 3. Introduction 3.1. Background 3.2. Terms & Definitions 3.3. Sametime Community Architecture 4. User model 4.1 Persistent User Data 4.2 Runtime User Structures 5. Protocol Elements 5.1. Community 5.2. User-ID 5.3. Login-ID 5.4. Channels 5.5 Master Channel 5.6. Channel-ID 5.7. Service Providers 5.8. Encryption 6. Protocol Overview 6.1 Login 6.2 Creating a Channel 6.3 Subscribing and Getting Notifications on Presences 6.4 Changing Privacy List 6.5 Initiating and responding to IMs 6.6 Resolving User-Names 6.7 Sensing Services 7. The Sametime Message format 7.1 Layering and message encapsulation 7.1.1 The Sametime Message Header 7.1.2 The Message Body 7.1.3 Protocol Layers 8. Master Protocol Reference 8.1 Basic Data Types 8.2 Common Structures 8.2.1 Login Info block 8.2.2 Privacy Info Block 8.2.3 User Status Block 8.2.4 ID Block 8.2.5 Encryption Block 8.3 Constants 8.3.1 Error Codes 8.3.1.1 General error/success codes 8.3.1.2 Connection/disconnection errors 8.3.1.3 Client error codes page 2 Sametime Community - Client Protocol Page 2 8.3.1.4 IM error codes 8.3.1.5 Resolve error codes 8.3.2 Service Types 8.3.3 Protocol Types 8.3.4 Version Constants 8.3.5 User Status Types 8.3.6 Login Types 8.3.7 Authentication Types 8.3.8 Awareness Constants 8.3.8.1 Awareness Context Constants 8.3.8.2 Awareness Presence Types 8.4 Messages 8.4.1 Basic Community Messages 8.4.1.1 Handshake 8.4.1.2 HandshakeAck 8.4.1.3 Login 8.4.1.4 LoginAck 8.4.1.5 LoginCont 8.4.1.6 AuthPassed 8.4.1.7 CreateCnl 8.4.1.8 AcceptCnl 8.4.1.9 SendOnCnl 8.4.1.10 DestroyCnl 8.4.1.11 setUserStatus 8.4.1.12 SetPrivacyList 8.4.1.13 SetPrivacyDenied 8.4.1.14 SenseService 8.4.2 Awareness Messages 8.4.2.1 Awareness ID Block 8.4.2.2 AddWatch 8.4.2.3 RemoveWatch 8.4.2.4 Snapshot 8.4.2.5 Update 8.4.3 Instant Messaging 8.4.3.1 IM channel creation 8.4.3.2 IM channel accepting 8.4.3.3 Data Message 8.4.3.4 Text Message 8.4.4 8.4.4.1 Resolve Request 8.4.4.2 Resolve Response 9. Acknowledgements 10. Authors Addresses page 3 Sametime Community - Client Protocol Page 3 2. Abstract This document describes the protocol used by a client in a Sametime (TM) community. The protocol enables users connecting to a Sametime community to be aware each other and to send Instant Messages (IMs) to other users in the community. While this protocol does not meet many of the requirements of the IMPP working group, it is provided as background information on existing Instant Messaging and Presence implementations. This protocol is provided 'as is' without warranty of any kind. In particular, commercial use of this protocol requires licensing. The protocol described in this document should enable implementing a client program that can interoperate with Sametime communities, given the user has registered with the community. 3. Introduction 3.1. Background The Sametime community architecture was designed and implemented by Ubique as part of the Sametime architecture of Lotus. Ubique has been dealing with awareness since 1990, when it produced Virtual Places (tm). Virtual Places enable users viewing a web page to be aware of other users viewing the same page. In addition to Lotus Sametime Connect, Ubique produced an earlier buddy list client that is in use at well-known portals and community sites. At the time of writing, the largest such installation supports ???? users. The largest number of concurrent users of a community running Ubique's software is 50K. 3.2. Terms & Definitions - Community - A set of servers and service providers supplying presence management to a group of users that are authenticated by the same authentication authority. - User - A person getting services from a community. - Client - A program used by a user for interacting with the community. - Service - A functionality supplied by the Community. - Server - A community component to which the client connects for getting community services. - Home Server - The server defined as the default server of the user. The persistent storage of a community defines the home server for each user. - Service Provider - A community component providing services to the page 4 Sametime Community - Client Protocol Page 4 community. - Login - An active connection of a user or other community component to a server. - Presence - A set of properties/attributes of a user that are managed by the community. 3.3. Sametime Community Architecture A Sametime user can have multiple logins to the community. Each login is done via a different TCP connection. The community synchronizes between the various logins of the User to maintain a consistent presence. For example, when a user updates its details through one of her/his logins, the community reports to the other logins about the change. The user can inform the community how that user's visibility should be limited. The user informs the system either by supplying a list of others to whom the user's presence should not be published, or by supplying a list of others who are the only ones to whom the user's presence should be published. This feature is called Privacy. Privacy is also synchronized between the multiple logins of the user if they exist. Multiple logins are needed when the user runs two or more Sametime applications and the applications are not able (or were not written to) share the same TCP connection. We call these type of applications non- cooperative applications. The ability to have different logins enables using such applications without letting the user feel that they are using different logins. Each login in a Sametime community can use many services in the community. Each service may be used by a different application that is run by the user. Upon connecting to the community, the login connects with the basic service of the community - the Community Service. Using the community service, it is possible to locate other services in the community and connect with them. Traffic on a TCP connection is divided into channels. A channel is a virtual connection between two entities (login, server or service provider). Upon connecting to the community a default master channel is created between the client and the server. Using the master channel, other channels can be created. When a client connects to some service in the community or interacts with a login of another user, a channel is created for the interaction. A channel may be encrypted. Upon creation of the channel, a method of encryption is selected by its two endpoints. After selecting an encryption method, messages passing on the channel may be encrypted. This document does not describe how an encrypted channel is created and what encryption methods are supported. This document does not cover the architecture of the server side of the Sametime community. In general, we can say that a Sametime community is page 5 Sametime Community - Client Protocol Page 5 composed of multiple servers acting in concert. The Sametime community is scalable and distributed. Scalability means that the number of users that can be served by a community is larger than the number of the users that can be served by a single server. Distribution means that the community is composed of multiple servers, where each server is in a different location. A user connected to one community may get services from other Sametime communities. This is achieved via a community-to-community connection. When a service from another community is requested, the community of the user can connect to the other community and get services for the user from there. Of course, the ability to get inter-community services is dependent on agreements between the communities. 4. User model The Sametime user and login model supports multiple logins of the same user to the community. The user model is divided into persistent and runtime parts. 4.1 Persistent User Data Each user in a Sametime community has the following basic properties. These properties are persistent across server shutdowns. - Home server - The default server into which the user should usually login. - User ID - A string representing an identifier of a user in the community. This string is unique among all the users in the community. - Login Params - Set of fields used for the creation of a login into the community. Common fields will be a login name and a password. The login name is a string that has no further usage beyond the login phase. - User-Name - A name under which other users see the user. A user might have different user-names for different logins (4.2) - Description - A descriptive text about the user. Again, a description may be different for different logins. - Privacy List - A list of user IDs that may or may not know that the user is online. A privacy list is maintained per user. If a user logs into the community several times simultaneously, the server synchronizes the privacy list of the user between its different logins. 4.2 Runtime User Structures The runtime user model of Sametime enables each user to create multiple concurrent logins to the community. As shown in the example below, a single User-ID may have multiple Login Params, each of which may have multiple Login-IDs. page 6 Sametime Community - Client Protocol Page 6 +-------------------+ | User-ID | +-------------------+ | +---------------+ =>| Login Params | | +---------------+ | | +----------+ | =>| Login-ID | | +----------+ | | +---------------+ =>| Login Params | +---------------+ | +----------+ =>| Login-ID | | +----------+ | | +----------+ =>| Login-ID | +----------+ Each TCP/IP connection of a user creates a single login of the user to the community. A login ID that is unique throughout the community is assigned to each login. Sametime applications may be written by different vendors, or may be written by the same vendor using different programming environments (e.g. Java and OCX). Therefore it is not possible in all cases that the various Sametime applications run by the user will share the same TCP connection to the community. For this reason a Sametime community supports multiple logins of a user. Multiple logins enable the various Sametime applications run by the user to be independent on each other. Even though there are multiple logins of the user, the Sametime community synchronizes various updates (e.g. privacy) between the logins. In current implementations of the Sametime community, it is not possible to create different simultaneous logins from different user machines. The restriction is enforced by the Sametime community by logging out an "old" login. 5. Protocol Elements This section defines the elements used in the Sametime protocol. 5.1. Community A string uniquely identifying a Sametime community. Usually this string will be a domain name or some other identifier that is guaranteed to be unique. 5.2. User-ID A string uniquely identifying a user in a community. user-ID is saved page 7 Sametime Community - Client Protocol Page 7 in a persistent storage and is not affected by server restarts. At runtime the user-id is augmented to conatain also the community name. 5.3. Login-ID Every entity logged into a community has a runtime login-ID. The login- ID is unique over all the Sametime communities. This uniqueness is achieved by having the login-ID be composed of the following: - A string uniquely identifying the community - A unique string constructed from the IP address of the server into which the user is logged and a number assigned by the server. The login-ID is the primary handle for referencing logins in the Community. When a channel to another user in the community is to be created, someone (either the client or some community component) first has to find a login-ID of the user and only then can the channel be created. 5.4. Channels A Sametime community is composed from multiple servers and service providers - hence, the network path between two community entities (login or community component) may span several hops. Each hop is a TCP connection. A Channel is a virtual connection between two community entities. The channel spans over the route of network connections that exist between the two sides of the channel. Hence the channel supplies the following functions: - Defines the routing path between the two sides of the channel. - Ensures order of messages. - Supplies notifications to both sides of the channel when some network connection along the path is broken. Channels are also used for efficient propagation of messages. When there is a need (e.g. in a N-way chat) to send a message to multiple recipients, the sender can send a single instance of the message with the list of recipients channels. Upon receiving the message, the server sends the message along the appropriate network connections where each network connection gets a single copy of the message and a list of channels that are contained in the network connection. This method of message propagation is called: multi-send on channel. 5.5 Master Channel When a TCP connection from a client to a server is initiated, a default channel named Master-Channel is created. The master-channel serves the following purposes: - Authentication (Handshake and Login messages) - Creation of other Channels - Sending Broadcast messages - Sending One Time messages page 8 Sametime Community - Client Protocol Page 8 - Sending utility messages - Sending Privacy and Status messages 5.6. Channel-ID Channel-ID numbers are unsigned words (32 bits). The numbering of channels is local to the TCP connection between each pair of community entities along the channel path. The channel creator can be on either side of the TCP connection. In order to avoid using the same ID when creating a channel, the range of possible IDs is divided between the two sides of the TCP connection. The initiator of the TCP connection (the ACTIVE side) is allocated the numbers with the Most Significant Bit (MSB) at zero. The other side (the PASSIVE side) is allocated the numbers with the Most Significant Bit (MSB) at one. Due to the locality of the channel numbering, channel-IDs can be reused immediately after the channel is closed. 5.7. Service Providers Clients connected to a Sametime community are served by Service Providers. Each service provider is responsible for a certain functionality. We refer to these functionalities as Services. The following services are among those offered by Sametime service providers, and are relevant to this protocol documentation: * Who Is Online - Widely known as the buddy list service. This service supplies users with notifications about status & properties of other users in the community. * Authenticate - Authenticates users against the database for its server. * Resolve - Resolves a user-name into zero or more user-IDs * N-Way Chat - Supplies chat-rooms, where several users can participate. The Instant Messages (IM) are supplied directly by the Sametime server. 5.8. Encryption Encryption is supported in the Sametime community. When a channel is created it can be specified as encrypted. The parameters specifying the encryption method to be used are sent in the channel creation phase. So immediately after the channel is created, the channel is either encrypted or not. There are no messages for converting a non-encrypted channel to an encrypted one or vice versa. It is possible to send a non-encrypted message on an encrypted channel. A flag in the messages indicates whether the message is encrypted or not. page 9 Sametime Community - Client Protocol Page 9 Encryption is also supported in a N-way chat. The channel of each chat participant is encrypted. The encryption method and keys used are local to each participant in the chat. Therefore, each message sent by the chat service provider has to be encrypted per each participant. The current chat service provider encrypts only the text sent by the chat participants. Messages indicating updates to the participant list of the chat are not encrypted. This document describes only the parameters required for creating a non-encrypted channel. 6. Protocol Overview The Sametime client protocol can be divided into several phases. Following is a short description of each phase. Subsequent sections will detail state transitions of each phase. - Login - The user is authenticated with the community and is assigned a login-ID to be used in the login session. - Creating a channel - A channel is created to another entity in the community. - Subscribing and getting notifications on presences - Messages are sent to the awareness service, requesting notification on state changes of certain users. - Changing attributes - The user (actually one of its logins) requests a change in an attribute of its presence. - Changing privacy list - The user (actually one of its logins) requests a change in the content of its privacy list. Note that change in privacy list is separated from a change in an attribute since the privacy list is stored in a persistent storage in the server and the request for a change may be denied when the change can not be written. - Initiating and responding to IMs - Creating or accepting a channel for the purpose of interchanging instant messages. This phase include also the messages for the actual IMs - Resolving User-Names - Since the same user-name can be used by different users, user-names have to be resolved to user-IDs prior to usage. This phase describes how it is done. - Sensing service - When a service provider can not be located, a client may request to be notified when the service is available. This method frees the client from polling on the availability of the service. 6.1 Login This is the phase in which the client moves from being merely connected to the server via TCP to being a part of the community. State Transitions (assumes TCP connection is already established): page 10 Sametime Community - Client Protocol Page 10 Step | Action | Next | | Step -----+--------------------------------+---------- 1. | Client Sends Handshake | 2 2. | Server Sends HandshakeAck | 3 3. | Client Sends Login | 4 or 5 or 6 4. | Server Sends LoginAck | Finish 5. | Server Sends AuthPassed | 1 or 7 6. | Server Destroys Master Channel | Finish 7. | Client Sends LoginCont | 8 8. | Server Sends HandshakeAck | 4 State Description 1. The client (after establishing a TCP connection), sends a Handshake message as described in 8.4.1.1 to the server 2. The server sends a HandshakeAck message as described in 8.4.1.2. 3. The client sends a Login message as described in 8.4.1.3 4. If the user is permitted in the community and does not need to be redirected, the server sends the LoginAck message as described in 8.4.1.4 . 5. If the user needs to be redirected to another server, the server sends the client an AuthPassed message as described in 8.4.1.6. The client can then either issue a LoginCont message (Step 7), or disconnect and attempt a direct connection to the other server. 6. If the user fails to authenticate, the server destroys the Master Channel with the appropriate error code (for values, see 8.3.1). 7. The client chooses not to reconnect to the other server. It issues a LoginCont message notifying the server to go on with the login procedure (though redirected to the other server). LoginCont message is described in 8.4.1.5. 8. The server sends the client a HandshakeAck message, telling the client it is being processed by the remote server; the protocol being provided to it by the local server will be the remote one's (see HandshakeAck in 8.4.1.2), and proceeds to step 4. 6.2 Creating a Channel In this phase the client creates a channel (as described in CreateCnl on 8.4.1.7) to some other community entity. From the point of view of the client, the entities that participate in a channel creation are the creator and the acceptor. The channel path may traverse additional community components but the server architecture and protocol are beyond the scope of this document. State Transitions: page 11 Sametime Community - Client Protocol Page 11 Step | Action | Next | | Step -----+------------------------------------+---------- 1. | The creator sends a CreateCnl | 2 or 3 | message to the acceptor. | 2. | The acceptor or some other | Finish | component sends a DestroyCnl | | message to the acceptor | 3. | The acceptor sends a AcceptCnl | Finish | message to the creator | State Description 1. The creator sends a CreateCnl message as described in 8.4.1.7. 2. The CreateCnl message is rejected either by some community component in the route to the acceptor or by the acceptor itself. The CreateCnl message may be rejected by some community components other then the acceptor due to various reasons as permissions or the unavailability of the acceptor. 3. The acceptor is willing to accept the channel, and sends an AcceptCnl back to the creator thus establishing a channel with the creator. 6.3 Subscribing and Getting Notifications on Presences After a channel between the client and the awareness service provider is established, the client has to supply its awareness list to the awareness service in order to be notified on users in the list. State Transitions: Step | Action | Next | | Step -----+--------------------------------------+---------- 1. | The client sends AddWatch with a | 2 | list of user-IDs to the service | | provider | 2. | The service provider sends a Snapshot| [3] | message to the client | 3. | Upon any change in the state of | | of a presence, the service sends | ... | Update message to the client | 4. | The client sends removeWatch with a | ... | list of user-IDs State Description 1. The client sends AddWatch (as described in 8.4.2.2) to the Awareness service provider. The message contains the list of user-IDs the watcher is interested in their presence status. 2. On receiving the AddWatch message, the service provider synchronizes the client with the current status of the presences with a Snapshot message, as described in 8.4.2.4. page 12 Sametime Community - Client Protocol Page 12 3. When a presence changes state, the Awareness service provider sends an Update Message (as described in 8.4.2.5) to the watcher client. 4. When the watcher stops "watching" the presence, it sends a RemoveWatch message (as described in 8.4.2.3) to the Awareness service provider. 6.4 Changing Privacy List User privacy list is saved in a database at the server side for future logins. This is the reason the privacy change request might fail (if there's a problem in updating the privacy). State Transitions: Step | Action | Next | | Step -----+---------------------------------------+---------- 1. | The client sends a setPrivacyList | 2 or 3 | to the server. | 2. | If the database update fails, the | Finish | server replies with a setPrivacyDenied| | message. | 3. | If the database update succeeds, the | Finish | server sends a setPrivacyList message | | to all the logins of the user. | State Description: 1. Whenever a client wants to change its privacy list the client sends a setPrivacyList message to the server as described in 8.4.1.12. The server in turn updates the database with the new mode. 2. If the database update fails, the server sends a setPrivacyDenied Message to the login, as described in 3. If the database update succeeds, the server sends setPrivactList message to all the logins of the user, with the new Privacy List. 6.5 Initiating and responding to IMs IMs are actually messages being sent on a given channel. State Transitions: Step | Action | Next | | Step -----+---------------------------------------+---------- 1. | Create an IM channel to the target | 2 or 3 | client | 2. | Target client destroys channel | Finish 3. | Target client accepts channel | 4 4. | Either clients sends an IM message | 4 or 5 5. | Either client destroys channel | Finish page 13 Sametime Community - Client Protocol Page 13 State Description 1. The clients creates an IM channel to the target client, as described in 8.4.1.7. This channel differs from regular channel by the fact that it has additional data (description of the additional data is in 8.4.3). 2. The target client can either destroy the channel as described in 8.4.1.10 , or... 3. The client accepts the channel, as described in 8.4.1.8. 4. Either clients can now send and receive messages on that channel, as described in 8.4.3. Note that there are two types of messages. 5. Either client destroys the channel, as described in 8.4.1.10. 6.6 Resolving User-Names Since users may have non-unique user-names, it is necessary to resolve user-names to user-IDs which are unique. The client creates a channel to the resolve service provider and sends a list of user-names in a resolve message (As described in 8.4.4.1 ). The resolver resolves the names to user-IDs (in a message described in 8.4.4.2 ). Note that each user-name may be resolved to several user-IDs. State Transitions: It is assumed that the channel to the resolve service provider is already established. Step | Action | Next | | Step -----+--------------------------------+---------- 1. | Client sends MultiResolve on | 2 | the channel to the resolver | | | 2. | The resolver returns a response| Finish | containing a list of answers | | per each resolved name. Each | | answer contains the name that | | was resolved, an error code | | and the list of matching names.| 6.7 Sensing Services Services are provided by service providers that connect to the server. When a user logs into a community it might be that not all service providers are present. Therefore as an optimization, instead of polling the server, the login may request to be notified when a certain service is available. In this phase the login requests its server to be notified when a page 14 Sametime Community - Client Protocol Page 14 certain service provider is active. It is done once per notification, meaning once a notification has been sent to the client about a service, the client has to re-issue the message in order to sense it again. State Transitions : Step | Action | Next | | Step -----+--------------------------------+---------- 1. | Client sends SenseService | 2 or Finish | | 2. | [When the service is up] The | Finish | server sends SenseService to | | the client | State Description: 1. The client sends a SenseService message to the server as described in 8.4.1.14. 2. When (and if) the service being sensed is activated, the server sends the SenseService message back to the client, as described in 8.4.1.14 7. The Sametime Message format Every Sametime message is preceded by an extra single byte. This byte is a counter, which is incremented by one for each message on a connection from 0x81-0xFF and then starting again at 0x81 (MSB is always 1). This extra byte is used as additional assurance of order preservation and reliable transfer of messages on TCP connections. A single byte with the MSB set to 1 and the other bits set to 0 (0x80) is used as a keep-alive byte. A Sametime system may be configured to send a keep-alive byte at regular intervals. This allows the system to close connections that are no longer in use and keep connections open where necessary. When an application receives a leading byte from 0x81-0xFF, it understands that a Sametime message follows. When an entity receives 0x80, it recognizes it as a single keep-alive byte. 7.1 Layering and message encapsulation The Sametime communication layer handles the routing of messages between logins in a community. The communication layer is one layer above the TCP layer and it relies on underlying TCP connections. The following figure illustrates the use of layering and encapsulation in Sametime: +--------------+ Service Protocols ............................... |Service Fields| +--------------+ | | v v +----------------+--------------+ page 15 Sametime Community - Client Protocol Page 15 Master Protocol .................. | Message Fields |Message Data | +t--------------+--------------+ | | v v +---------------+-------------------------------+ Sametime Message .. |Sametime Header| Message Body | +---------------+-------------------------------+ | | v v +-----------+-----------------------------------------------+ TCP ... |TCP Header | TCP Data Area | Message +-----------+-----------------------------------------------+ 7.1.1 The Sametime Message Header The message header has the following format: 0 8 16 24 31 +---------+---------+---------+---------+ | Length (4 bytes) | +-------------------+-------------------+ | Message Type [2] | Options [2] | +-------------------+-------------------+ | Channel-ID [4] | +-------------------+-------------------+ | Attributes Length [4] | +-------------------+-------------------+ |Attributes (optional) [AttributeLength]... +-------------------+-------------------+ Fields Description: Length A 4-byte field containing the size of the message in bytes. Message Type A 2-byte field containing the type of the message. This field specifies the Master protocol (8) message type to be used to interpret the message body. Options A 2-byte field containing options. Various options are specified by setting bits to zero or one. The following bits are currently in use (LSB is numbered as zero): * Bit 0 - If set to 1 indicates the presence of an attribute section in the message. * Bit 1 - Indicates encryption of the message. Channel-ID A 4-byte field that specifies the channel on which the message is sent. Depending on the type of message, the ID represents either a master channel or a regular channel. page 16 Sametime Community - Client Protocol Page 16 Attributes Length A 4-byte field that specifies the length of the attributes part of the message. This field exists only if the Options field indicates that the message contains attributes. Attributes Varies in content according to message type. The length of this field is specified by the Attributes Length field. 7.1.2 The Message Body Message body format is dependent on the message type. See "Master Protocol Reference" (8) for a description of each message type and its body format. A message type may also have subtypes. The message subtype may determine how the message data is interpreted. 7.1.3 Protocol Layers The Sametime protocol is built on a model of message encapsulation and protocol layering. The following figure shows the order of the Sametime protocol layers in relation to the TCP layer: +------------------------+ | Service Protocol Layer | +------------------------+ | Master Protocol Layer | +------------------------+ | Communication Layer | +------------------------+ - Communication Layer - Responsible for routing messages between community elements through the use of channels on top of TCP. Messages at the Communication layer have a Sametime header and a message body. Master Protocol Layer - Interprets the data in the message body according to the message type specified in the Sametime header. The Master Protocol is used to interpret all Sametime messages. The following activities are handled at the Master protocol level: * Handshake * Login and authentication * Channel creation and destruction * Sending messages on other channels. These messages are not interpreted at the master protocol. They are interpreted by the particular service protocol associated with the channel on which the message was sent. * Sending broadcast messages * Sending one time messages * Sending utility messages (such as, "service up" and "service down") * Sending privacy and status messages - Service Protocol Layer - Interprets the message data that is sent within certain master protocol messages on established channels. The particular service protocol used is determined for all communication on page 17 Sametime Community - Client Protocol Page 17 that channel when the channel is created. 8. Master Protocol Reference Each message type is described separately in this section. For each message type, there is a description of its function and a diagram of the message body. All messages have the Sametime header, as described above (see "Sametime Header" on 7.1.1). Note: Unless explicitly specified, fields do not necessarily start at a word boundry as can be understood from the following diagrams. 8.1 Basic Data Types The following types are used in field descriptions: Flag (Boolean) - 1 byte char - 1 byte Ulong - 4 bytes Ushort - 2 bytes Opaque - A large binary object, with its length in the header, the length is an unsigned long ( = 4 bytes) String - A null terminated string, with its length in the header, the length is short (= 2 bytes), The length does not include the null character terminating the string. 8.2 Common Structures The following blocks of fields appear in several message types. These blocks are described separately for reasons of clarity, conciseness, and improved understanding of their purpose. 8.2.1 Login Info block The Login Info block appears in messages when a complete description of an entity is passed. The portion of the block following the Full Flag is optionally present depending on the message type. Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | Login ID [String] +-------------------+-------------------+ | Login Type [2] | +-------------------+-------------------+ | User ID [String] +-------------------+-------------------+ | User Name [String] +-------------------+-------------------+ | Community Name [String]| +---------+---------+---------+---------+ ----- |Full Flag| ^ | [1] | | +---------+-------------------+---------+ page 18 Sametime Community - Client Protocol Page 18 | Description [String] optional segment +-------------------+-------------------+ | IP Address [4] | | +-------------------+-------------------+ | | Server ID [String] v +---------------------------------------- ----- Description of Fields: Login ID A string containing the unique (within the community) ID of the login described. Login Type A 2-byte field. Specifies the type of Sametime login described. See "User Model" on 8.3.6 for a list of established constants. User ID A string containing the unique (within the community) ID of the user. User Name A string containing the name of the user. This is the string that appears as the user's name on the screen. It is stored in a database and is looked up according to the login name. Community-Name A string containing the name of the community. The community name can be any string, but the Internet domain name is usually used. Full Flag A single byte. If the value equals 1, the rest of the Login Info block (Description, IP Address, and Server ID fields) is transmitted. If the value equals 0, the rest of the block is not present. Description A string field. The description can be any string data. The current implementation does not place any information in this field. IP Address A 4-byte field containing the IP address of the login described. Server ID A string containing the unique ID of the login's server (where the login is held). 8.2.2 Privacy Info Block The Privacy Info block consists of a list of user-IDs. The portion following the "Count of List" represents one item (user item) in the user-ID list. This portion is repeated the number of times equal to "Count." The User Name portion of each User Item is an optional segment, which page 19 Sametime Community - Client Protocol Page 19 appears depending on the Full flag. Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | Internal Use |Excluding| Count of| | [2] |Flag [1] | List [4]| +-------------------+---------+---------+ ----- | Count of List (cont) |Full Flag| ^ | | [1] | | +-------------------+---------+---------+ | | User ID [String] X count of List +-------------------+-------------------+ | | User Name [String] v Optional +-------------------+-------------------+ ----- Description of Fields Internal Use Byte Reserved for internal use Excluding Flag A single byte. If the value equals 1, the list of users that follows represents the users who are excluded from seeing the user whose privacy is described (all other users are permitted). If the value equals 0, the list contains the users who may see the user whose privacy is described (all others are excluded). User List A list of users representing either the users who are excluded from seeing the user whose privacy is described or the users who are permitted to see the user whose privacy is described. The list begins with a 4-byte field specifying the number of items in the list. Each item in the list is a User Item. Each User Item contains a Full Flag, which indicates whether the item is full or not, a User ID string, and if the item is full, a User Name string. The User ID is a string containing the unique (within the community) ID of the user. The User Name is a string containing the name of the user, which is the name displayed on the screen in the user interface. 8.2.3 User Status Block This block contains information about the user's status. It is used in messages that contain user status information. Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | User Status Type | Time | | [2] | [4] | +-------------------+-------------------+ | Time (cont.) | +-------------------+-------------------+ | Description [String] +---------------------------------------- page 20 Sametime Community - Client Protocol Page 20 Description of Fields User Status Type A 2-byte field indicating the status of the user. See 8.3.5 for a list of established constants. Time A 4-byte field containing the time of the last change in the user's status in minutes. Not set by Sametime 1.0 and 1.5 servers. Description A string containing the message associated with the status type for this user. The user's server saves the message customized by the user for certain status types. 8.2.4 ID Block This block is used for addressing messages. This combination of two strings uniquely identifies a user or login in a multi-community environment. 0 8 16 24 31 +---------+---------+---------+---------+ | User or Login ID [String] +---------+---------+---------+---------+ | Community Name [String] +---------------------------------------- Description of Fields: Target ID A string that can be either a User ID or a Login ID or an empty string. * If it is a User ID, the ID block specifies a user. A user may have more than one associated login. The server may decide which login will be the ultimate target. * If it is an Login ID, the ID block specifies a single login. * If it is an empty string, the message target will be decided on the basis of alternative criteria - service type. Community Name A string specifying the community name. This may be an empty string if the target is on the same community. 8.2.5 Encryption Block This document does not contain description of how to create encrypted channels. Following are the values that are sent on non-encrypted channel creation. 0 8 16 24 31 +---------+---------+---------+---------+ | No-Encryption [Opaque] +---------+---------+---------+---------+ page 21 Sametime Community - Client Protocol Page 21 The No-Encryption opaque contains only a short (2-byte) of value zero. 8.3 Constants 8.3.1 Error Codes 8.3.1.1 General error/success codes operation succeeded --- 0x00000000 operation failed --- 0x80000000 request accepted but will be served later --- 0x00000001 request is invalid due to invalid state --- 0x80000001 or parameters not logged in to community --- 0x80000002 unauthorized to perform an action or access --- 0x80000003 a resource operation has been aborted --- 0x80000004 the element is non-existent --- 0x80000005 the user is non-existent --- 0x80000006 the data are invalid or corrupted --- 0x80000007 the requested feature is not implemented --- 0x80000008 not enough resources to perform the operation --- 0x8000000A the requested channel is not supported --- 0x8000000B the requested channel already exists --- 0x8000000C the requested service is not supported --- 0x8000000D the requested protocol is not supported --- 0x8000000E the requested protocol is not supported --- 0x8000000F the version is not supported --- 0x80000010 user is invalid or not trusted --- 0x80000011 already initialized --- 0x80000013 not an owner of the requested resource --- 0x80000014 invalid token --- 0x80000015 token has expired --- 0x80000016 page 22 Sametime Community - Client Protocol Page 22 token IP mismatch --- 0x80000017 WK port is in use --- 0x80000018 low-level network error occurred --- 0x80000019 no master channel exists --- 0x8000001A already subscribed to object(s) or event(s) --- 0x8000001B not subscribed to object(s) or event(s) --- 0x8000001C encryption is not supported or failed --- 0x8000001D unexpectedly encryption mechanism has not been initialized yet --- 0x8000001E the requested encryption level is unacceptably --- 0x8000001F low the encryption data passed are invalid or --- 0x80000020 or corrupted there is no common encryption method --- 0x80000021 the channel is destroyed after a recommendation --- 0x80000022 is made connect elsewhere the channel has been redirected to another --- 0x00000023 destination 8.3.1.2 Connection/disconnection errors versions don't match --- 0x80000200 not enough resources for connection (buffers) --- 0x80000201 not in use --- 0x80000202 not enough resources for connection (socket id) --- 0x80000203 hardware error occurred --- 0x80000204 network down --- 0x80000205 host down --- 0x80000206 host unreachable --- 0x80000207 TCP/IP protocol error --- 0x80000208 the message is too large --- 0x80000209 proxy error --- 0x8000020A page 23 Sametime Community - Client Protocol Page 23 server is full --- 0x8000020B server is not responding --- 0x8000020C cannot connect --- 0x8000020D user has been removed from the server --- 0x8000020E VP protocol error --- 0x8000020F cannot connect because user has been restricted --- 0x80000210 incorrect login --- 0x80000211 encryption mismatch --- 0x80000212 user is unregistered --- 0x80000213 verification service down --- 0x80000214 user has been idle for too long --- 0x80000216 the guest name is currently being used --- 0x80000217 the user is already signed on --- 0x80000218 the user has signed on again --- 0x80000219 the name cannot be used --- 0x8000021A the registration mode is not supported --- 0x8000021B user does not have appropriate privilege level --- 0x8000021C email address must be used --- 0x8000021D error in DNS --- 0x8000021E fatal error in DNS --- 0x8000021F server name not found --- 0x80000220 the connection has been broken --- 0x80000221 an established connection was aborted by the --- 0x80000222 software in the host machine the connection has been refused --- 0x80000223 the connection has been reset --- 0x80000224 the connection has timed out --- 0x80000225 the connection has been closed --- 0x80000226 disconnected due to login in two Sametime --- 0x80000227 page 24 Sametime Community - Client Protocol Page 24 servers concurrently maps to 0x80000227 retained for compatibility with--- 0x80000228 disconnected due to login from another computer. --- 0x80000229 unable to log in because you are already logged --- 0x8000022A on from another computer unable to log in because the server is eother --- 0x8000022B unreachable, or not configured properly. unable to log in to home Sametime server through --- 0x8000022C the requested server, since your home server needs to be upgraded. the applet was logged out with this reason. --- 0x8000022D Perform relogin and you will return to the former state. 8.3.1.3 Client error codes the user is not online --- 0x80002000 the user is in do not disturb mode --- 0x80002001 can not login because already logged in --- 0x80002002 with a different user name (Java only) 8.3.1.4 IM error codes cannot register a reserved type --- 0x80002003 the requested type is already registered --- 0x80002004 the requested type is not registered --- 0x80002005 8.3.1.5 Resolve error codes the resolve process was not completed, but --- 0x00010000 a partial response is available the name was found, but is not unique (request --- 0x80020000 was for unique only) the name is not resolvable due to its format, for --- 0x80030000 example an Internet email address 8.3.2 Service Types The service type of the buddylist server --- 0x00000011 application The service type of the resolver server --- 0x00000015 application page 25 Sametime Community - Client Protocol Page 25 The service type of the IM channel --- 0x00001000 8.3.3 Protocol Types The protocol type of the buddylist server --- 0x00000011 application The protocol type of the resolver server --- 0x00000015 application The protocol type of the IM channel --- 0x00001000 8.3.4 Version Constants Major Version value --- 0x001E Minor Version value --- 0x0018 Buddy List Protocol Version --- 0x00030005 Resolve Protocol Version --- 0x0 8.3.5 User Status Types User is active --- 0x0020 User is idle --- 0x0040 User is away --- 0x0060 User request not to be desturbed --- 0x0080 8.3.6 Login Types Login is using a C++ Component (i.e. ActiveX) --- 0x1000 Login is using a Java Applet --- 0x1001 Login is using a binary executable --- 0x1002 Login is using a Java Application --- 0x1003 8.3.7 Authentication Types Plain Password Authentication --- 0x0000 Notes Token Authentication --- 0x0001 Encrpyted Password Authentication --- 0x0002 8.3.8 Awareness Constants 8.3.8.1 Awareness Context Constants The following are Awareness context constants (all are 2 byte unsigned short) : page 26 Sametime Community - Client Protocol Page 26 ADD 0x0068 REMOVE 0x0069 SNAPSHOT 0x01F4 UPDATE 0x01F5 UPDATE_ID 0x01F7 8.3.8.2 Awareness Presence Types The following are Awareness presence types (all are 2 byte unsigned short) : User 0x0002 8.4 Messages 8.4.1 Basic Community Messages 8.4.1.1 Handshake This message is sent by the initiator of a TCP connection when the TCP connection is created. This message creates a new master channel from the initiator to the recipient (a server). The message structure includes two fields for the client IP address: one is calculated locally and one is calculated at the server end of the TCP connection. This allows for differences that may result when, for example, the client uses a proxy. Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | Major Version [2] | Minor Version [2] | +-------------------+-------------------+ | Master Channel ID [4] | +-------------------+-------------------+ | Server Calculated IP Address [4] | +-------------------+-------------------+ | Login Type |Local calculated IP| | [2] | Address [4] | +-------------------+-------------------+ |Local calculated IP| |Address (cont.) | +-------------------+ Description of Fields Major/Minor Version Two 2-byte fields containing the originator's Sametime major and minor version numbers. The version number of the handshake requestor is checked by the server to determine whether the protocols are compatible, for values used in Sametime 1.5 see 8.3.4. page 27 Sametime Community - Client Protocol Page 27 Master Channel ID A 4-byte field containing the Master Channel ID (MCID) of the new channel. When the message is sent from the originator, the MCID is 0. server-calculated Client IP Address A 4-byte field containing the IP address of the originator as calculated at the server end of the TCP connection. When the message is sent from the originator, this field is 0. This number is replaced by the server before the message is routed to the next station. The IP address seen by the server may be different than that calculated locally by the originator (for example, when the client uses a proxy). Login Type A 2-byte field representing the type of login originating the TCP connection. See 8.3.6 for values. Local-calculated Client IP Address A 4-byte field containing the IP address of the originator as calculated locally. 8.4.1.2 HandshakeAck This message is sent from the server to the initiator of the connection. It is an acknowledgement of a successful handshake and the creation of a master channel between the initiator and the server. This message also informs the initiator of the version number of the server and the initiator's IP address as calculated by the server. Note: The Master Channel ID is included in the message header. Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | Major Version [2] | Minor Version [2] | +-------------------+-------------------+ | server calculated client IP Address[4]| +-------------------+-------------------+ Description of Fields Major/Minor Version Two 2-byte fields containing the server's Sametime major and minor version numbers. The version number of the handshake requestor enables the server to determine if it can support the protocol version. The server also might use different protocols according to the version sent by the requestor. For values used in Sametime 1.5 see 8.3.4. server-calculated Client IP Address A 4-byte field containing the IP address of the originator as calculated at the server end of the TCP connection. The IP address seen by the server may be different than that calculated locally by page 28 Sametime Community - Client Protocol Page 28 the originator (for example, when the client uses a proxy). 8.4.1.3 Login This message provides login data to the server. The Login Type field determines the format and interpretation of the remainder of the message body. For a client, the message contains the Login Name and authentication data (see "Login" on 8.4.1.3). Note: The Master Channel ID is included in the message header. Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | Login Type [2] | +-------------------+-------------------+ | Login Name [String] +-------------------+-------------------+ |Authentication Type| | [2] | +-------------------+-------------------+ | Authentication Data [Opaque] +---------------------------------------+ Description of Fields: Login Type A 2-byte field. Specifies the type of Sametime login sending the message. See 8.3.6. Login Name A string containing the user's login name. The login name is used in conjunction with the authentication data to identify and authenticate the user. The first two bytes specify the total length of the string. Authentication Type A two-byte field indicating the type of authentication. See 8.3.7. The authentication type determines the interpretation of the authentication data. Authentication Data An opaque containing data used for authentication of the user (e.g., a password or a token). The meaning of this data is determined by the authentication type. 8.4.1.4 LoginAck This message is sent by the server to the login that requested a login after a successful login has been accomplished. It returns information about the requestor stored in the server to the requestor. Note: The Master Channel ID is included in the message header. page 29 Sametime Community - Client Protocol Page 29 Message Body +--------------------+ | Login Info Block | +--------------------+ | Privacy Info Block | +--------------------+ | User Status Block | +--------------------+ Description of Fields: Login Info Block The login described in this block (see "Login Info Block" in 8.2.1) is the login requestor. The Full flag is always TRUE. The IP address In this block is the IP address as seen from the server side. Therefore, if the client is using a proxy, the IP address will be the proxy's IP address. Privacy Info Block This block (see "Privacy Info Block" on 8.2.2) is used to send the user's privacy information, which the server retrieves, to the client. User Status Block This block (see "Status Info Block" on 8.2.3) is used to send the user's status information. This information is based on other (current) logins of the same user. 8.4.1.5 LoginCont This message has no body. It just notifies the server that the client wishes to be redirected (by the current server) to the remote server. This message is a response to a AuthPassed message sent to the client by the server, as described in 8.4.1.6. 8.4.1.6 AuthPassed When a client logs into a server, and the server decides to redirect the client to another server, for any reason (the home server of the user is different or the user already has a login in another server), the server sends an AuthPassed message to the client, notifying it about a redirection possibility. The message indicates that the client can disconnect and connect to the specified server, or continue and have its connection redirected to the remote server by the current server. Should the client decide to continue with the current server, a LoginCont message should be sent to the server (as described in 8.4.1.5). Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | Home Server ID [String] +---------------------------------------+ page 30 Sametime Community - Client Protocol Page 30 | Home Server Version [4] | +---------------------------------------+ Description of Fields: Home Server ID The server the client should connect to (or will be redirected to). Home Server Version A 4-byte long describing the version of the remote server. 8.4.1.7 CreateCnl All interactions between community entities take place over channels (that is, additional channels on top of the master channel). When a login needs to create a new channel to another entity, the channel creator sends a CreateCnl message to the target. A new channel is created for every interaction. E.g. for every IM session and for every service. A new channel will be created for every N-way chat even though all the N-way chats that the login is participating in, are supplied by the same service provider. Note: The Master Channel ID is included in the message header. Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | Reserved [4] | +---------------------------------------+ | Channel ID [4] | +---------+-------------------+---------+ | ID Block | +---------+-------------------+---------+ | Service Type [4] | +---------------------------------------+ | Protocol Type [4] | +---------------------------------------+ | Protocol Version [4] | +---------------------------------------+ | Options [4] | +-------------------+-------------------+ | Additional Data [Opaque] +---------+-------------------+---------+ |Creator | Login Info Block | |Flag [1] | | +---------+-------------------+ | Encryption Block | +-------------------+ Description of Fields: Reserved A 4-byte field. Reserved for future use. Must be set to zero in this version of the protocol. Channel ID page 31 Sametime Community - Client Protocol Page 31 The channel-ID (4 bytes long) of the channel. ID Block A block of two strings that describes the target entity (single login) or user of the channel. If the ID string is empty, the channel is targeted based on the Service Type. For more details about this block, see "ID Block" on 8.2.4. Service Type A 4-byte field indicating the type of service that the channel creator is requesting from the target. For a list of all service types, see 8.3.2. Protocol Type A 4-byte field indicating the type of service protocol that will be used on the channel. For a list of all protocol types, see 8.3.3. Protocol Version A 4-byte field indicating the version number of the specified service protocol. This number is used for synchronizing both sides the channel on the same version of the protocol Options A 4-byte field. Reserved for future use. Must be set to zero in this version of the protocol. Additional Data Opaque data that further specifies the purpose of the channel. This information may be used by the target entity for various purposes. Creator Flag A single byte field, which indicates the presence of and Login Info block in the message. This allows the message size to be adjusted as necessary. For example, when the message originator is a client, the Login Info block is 0 (since the client does not send the information) and the Creator Flag is FALSE. When the message is routed through the client's server, the server adds the login Info block and the Creator Flag becomes TRUE. Login Info Block An optional block. Describes the channel creator (message originator). The Full flag is always TRUE. See "Login Info Block" in 8.2.1. Encryption Block See "Encryption Block" in 5.8. 8.4.1.8 AcceptCnl This message is sent from the channel acceptor to the channel creator as an acknowledgement of the channel creation. The message may also provide information about the acceptor, which is stored on the server. In the Login Info block in this message type, the Full flag is always page 32 Sametime Community - Client Protocol Page 32 TRUE, and the login described is the channel acceptor. Note: The Local Channel ID is included in the message header. Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | Service Type [4] | +---------------------------------------+ | Protocol Type [4] | +---------+---------+---------+---------+ | Additional Data [Opaque] +---------+-------------------+---------+ |Acceptor | Login Info Block | |Flag [1] | | +---------+-------------------+ | Encryption Block | +-------------------+ Description of Fields Service Type A 4-byte field indicating the type of service that the channel acceptor is providing. For a list of all service types, see 8.3.2. Protocol Type A 4-byte field indicating the type of service protocol that will be used on the channel. For a list of all protocol types, see 8.3.3. Protocol Version A 4-byte field indicating the version number of the specified service protocol. This number is used to synchronize both ends of the channel to use a compatible service protocol version. See 8.3.4. Additional Data Opaque data that further specifies the purpose of the channel. Acceptor Flag A single byte field, which indicates the presence of a Login Info Block in the message. This allows the message size to be adjusted as necessary. For example, when the message originator is a client, the Login Info block is 0 (since the client does not send the information) and the Acceptor Flag is FALSE. When the message is routed through the client's server, the server adds the Login Info Block and the Acceptor Flag becomes TRUE. Login Info Block An optional block. Describes the channel acceptor (message originator). The Full Flag is always TRUE. See "Login Info Block" on 8.2.1. Encryption Block See "Encryption Block" on 5.8. page 33 Sametime Community - Client Protocol Page 33 8.4.1.9 SendOnCnl This message sends enclosed message data from one login to another on an existing channel. The Message Data field is interpreted using the Service Protocol that is specified for the channel. Note that on encrypted channels the Message Data may be encrypted, however encrypted channels are not documented in this document. Note: The Local Channel ID is included in the message header. Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | Message Type | Length of Message | | [2] | Data [4] | +-------------------+-------------------+ |Length of Msg Data | Message Data | | (cont.) | [Len] | +-------------------+-------------------+ | Message Data (cont.) .... +---------------------------------------- Description of Fields: Message Type A two-byte field specifying the message type within the established service protocol. For definitions, refer to the individual protocol chapter. Message Data Opaque data (preceded by a 4-byte length field), which is interpreted by the service protocol established for the channel. 8.4.1.10 DestroyCnl This is the last message on a channel. It contains enclosed message data. Note: The Channel ID is included in message header. Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | Reason Code [4] | +-------------------+-------------------+ | Message Data [Opaque] +-------------------+-------------------+ Description of Fields Reason Code page 34 Sametime Community - Client Protocol Page 34 A 4-byte field specifying the reason for the destruction of the channel. This reason code is understood at the Master protocol level. For code reference, see "Constants" in 8.3. Message Data Opaque data (preceded by a 4-byte length field), which is interpreted by the service protocol established for the channel. 8.4.1.11 setUserStatus This message informs the server of any changes in the user's status. This same message is also used by the server to inform other logins belonging to the same user of the status change. Note: The Master Channel ID is included in the message header. Message Body +-------------------+ | User Status Block | +-------------------+ Description of Fields User Status Block Describes the new user status. For details about this block, see "User Status Block" on 8.2.3. 8.4.1.12 SetPrivacyList This message is sent from a client to request that the server set new privacy list options for the user. The privacy list is a list of users who are either permitted to, or prohibited from, seeing presence information about the requesting user ("Who Can See Me" options). The server is responsible for storing the change in a database by means outside the scope of this document. This same message is also used by the server to inform other logins, belonging to the same user, of the privacy list options change. The server sends the notification message after the change has been entered successfully in the database. Note: The Master Channel ID is included in the message header. Message Body 0 8 16 24 31 +---------+---------+---------+---------+ |Excluding| Length of User IDs List [4] | |Flag [1] | | +---------+---------+-------------------+ ---------------- |Len User | Full | ^ |ID List | Flag | | | (cont.) | [1] | | +---------+---------+-------------------+ | | User ID [String] | +-------------------+-------------------+ x Length of User | Community Name [String] ID List page 35 Sametime Community - Client Protocol Page 35 +-------------------+-------------------+ ----- | | User Name [String] if Full Flag v +---------------------------------------- ---------------- Description of Fields: Excluding Flag A single byte. If the value equals 1, the list of users that follows represents the users who are excluded from seeing the user whose privacy is described (all other users are permitted). If the value equals 0, the list contains the users who may see the user whose privacy is described (all others are excluded). User List A list of users representing either the users who are excluded from seeing the user whose privacy is described, or the users who are permitted to see the user whose privacy is described. The list begins with a 4-byte field specifying the number of items in the list. Each item in the list is a User Item. Each User Item contains a Full Flag, which indicates whether the item is full or not, a User ID string, and if the item is full, a User Name string. The User ID is a string containing the unique (within the community) ID of the user. The User Name is a string containing the name of the user, which is the name displayed on the screen in the user interface. 8.4.1.13 SetPrivacyDenied This message is sent by the server to notify the client that a previous SetPrivacyList action (see 8.4.1.12) was not successful (that is, the server attempted to save the changes using a server application, and the changes were not saved successfully). Note: The Master Channel ID is included in the message header. Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | Error Code [4] | +---------------------------------------+ Description of Fields Error Code A 4-byte field indicating the reason for the denial of the request. This error code is understood at the Master protocol level. For code reference, see 8.3.1. 8.4.1.14 SenseService This message is sent by a client to a server to request a notification when a specified service becomes available. This same message is sent by the server to the client as a notification when the service is available. The notification on availability of a service provider is page 36 Sametime Community - Client Protocol Page 36 possible only within a single community. Note: The Master Channel ID is included in the message header. Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | Service Type [4] | +---------------------------------------+ Description of Fields Service Type A 4-byte field indicating the type of service on which the client is requesting notification. For a list of all service types, see 8.3.2. 8.4.2 Awareness Messages Awareness messages are "transported" over an Awareness channel. These messages are used to subscribe (addWatch) to, and unsubscribe (removeWatch) from other users. 8.4.2.1 Awareness ID Block This block is used as the IDs in the Awareness context. It is a combination of a presence type and a regular ID Block (see 8.2.4). For values of Presence Types see 8.3.8.2. 0 8 16 24 31 +---------+---------+---------+---------+ |Presence Type [2] | Length of ID [2] | +-------------------+-------------------+ | ID [Len] ... +---------+---------+---------+---------+ |Length of Community| Community Name | | Name [2] | [Len] | +-------------------+-------------------+ | Community Name (cont.) ... +---------------------------------------- 8.4.2.2 AddWatch This message "subscribes" the initiator to a presence. It is sent from the client to the Awareness server application. Message Type is ADD. (For hexadecimal values, see 8.3.8.1). Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | Count of Awareness IDs Blocks [4] | +-------------------+-------------------+ | Awareness ID Block | x times count of page 37 Sametime Community - Client Protocol Page 37 +-------------------+-------------------+ Awareness id block Description of Fields: Count of Awareness IDs Block The number of Awareness ID Blocks that follows in the message. Awareness ID Block The presence to subscribe to. See "Awareness ID Block" on 8.4.2.1. 8.4.2.3 RemoveWatch This message "unsubscribes" the initiator from a presence. It is sent from the client to the Awareness server application. Message Type is REMOVE. (For hexadecimal values, see 8.3.8.1). Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | Count of Awareness ID Blocks [4] | +-------------------+-------------------+ | Awareness ID Block | x times count of +-------------------+-------------------+ Awareness ID block Description of Fields: Message Context The message context is a two-byte unsigned short. For this message the value is "REMOVE" (for hexadecimal values, see 8.3.8.1). Count of Awareness IDs Block The number of Awareness ID Blocks that follow in the message. Awareness ID Block The presence to see subscribe to. See "Awareness ID Block" on 8.4.2.1. 8.4.2.4 Snapshot This is sent from the Awareness service application to the clients. For each subscribe request, the Awareness service synchronizes the subscriber with the current Awareness knowledge of the presence. Message Body 0 8 16 24 31 +---------+---------+---------+---------+ | Count of Snapshot messages Blocks [4] | +---------------------------------------+ -------------- | End of Block offset [4] | ^ +---------+-------------------+---------+ | |Awareness ID Block | | page 38 Sametime Community - Client Protocol Page 38 +-------------------+ | | Empty | | |Awareness ID Block | | +---------+-------------------+---------+ ----- x Count of Snapshot |Online | ^ Messages blocks |Flag [1] | | | +---------+-------------------+---------+ | | | Alternate User ID [String] If Online | +---------+-------------------+---------+ Flag is | | Status Block | TRUE | +---------+---------+---------+---------+ | | | User Name [String] v v +---------------------------------------+ ------------ Description of Fields: Count of Snapshot Messages Blocks The number of Snapshot messages to follow. End Of Block Offset The offset (in bytes) of the end of the current block. Used for future compatibility. Awareness ID Block The presence in question. See "Awareness ID Block" on 8.4.2.1. Empty Awareness ID Block For internal use. Should be empty. See "Awareness ID Block" on 8.4.2.1. Online Flag The current presence of the user. If TRUE, the user is online and the rest of the block contains details of the user. If FALSE, this is the end of the block. Alternate User ID A string, for internal use. Should not be used. Status Block The current status of the user. See "Status Info Block" on 8.2.3. User Name The display name of the user. Should not be used; this information should be known to the client. 8.4.2.5 Update Every time the presence changes it's status, or logs off, an update is sent to it's subscribers. It is sent from the awareness service provider to the client. Message Body 0 8 16 24 31 +---------------------------------------+ page 39 Sametime Community - Client Protocol Page 39 | End of Block offset [4] | +---------+-------------------+---------+ |Awareness ID Block | +-------------------+ | Empty | |Awareness ID Block | +---------+-------------------+---------+ |Online | |Flag [1] | +---------+-------------------+---------+ | Alternate User ID [String] +---------+-------------------+---------+ | Status Block | +---------+---------+---------+---------+ | User Name [String] +---------------------------------------+ Description of Fields: End Of Block Offset The offset (in bytes) of the end of the current block. Used for future compatibility. Awareness ID Block The presence in question. See "Awareness ID Block" on 8.4.2.1. Empty Awareness ID Block For internal use. Should be empty. See "Awareness ID Block" on 8.4.2.1. Online Flag The current presence of the user. If TRUE the user is online, and the rest of the block contains details of the user. If FALSE, this is the end of the block. Alternate User ID A string, for internal use. Should not be used. Status Block The current status of the user. See "Status Info Block" on 8.2.3. User Name The display name of the user. Should not be used, this information should be usually known to the client. 8.4.3 Instant Messaging Instant Messages are sent over an "Instant Message Channel". Messages are typed in order to convey various types of data. When the IM channel is created, certain values should be sent in the opaque that is contained in the channel creation. 8.4.3.1 IM channel creation page 40 Sametime Community - Client Protocol Page 40 When creating an IM channel, the opaque that is sent as part of the channel creation should contain two 4-byte words each of them containing 1. Create IM channel requests that contain other values are beyond the scope of this document and should be rejected by clients that their implementation is based on this document. 8.4.3.2 IM channel accepting When accepting an IM channel, the opaque that is sent as part of the channel acceptance should contain the following: 0 8 16 24 31 +---------------------------------------+ | 1 | +---------------------------------------+ | 1 | +---------------------------------------+ | 2 | +--------+-------------------+----------+ | User Status Block | +-------------------+ User Status Block should be filled with the current status of the user to whome the IM channel was created. 8.4.3.3 Data Message Message Body 0 8 16 24 31 +---------------------------------------+ | Data Message Identifier [4] | +---------------------------------------+ | Message Type[4] | +---------------------------------------+ | Message SubType[4] | +---------------------------------------+ | Data [Opaque] +---------------------------------------+ Description of Fields: Data Message Identifier The Value is 0x00000001. It identifies the message (to the receiver) as a "Data Message". Message Type Used to identify the type of the data sent. Message SubType Used to further identify the type of the data sent. Data Length The length of the data sent. page 41 Sametime Community - Client Protocol Page 41 Data The raw data. 8.4.3.4 Text Message Message Body 0 8 16 24 31 +-------------------+-------------------+ | Data Message Identifier [4] | +-------------------+-------------------+ | Text [String] +---------------------------------------+ Description of Fields: Data Message Identifier The Value is 0x00000002. It identifies the message (to the receiver) as a text message. Text Length The length of the text message Text The message itself. 8.4.4 start talking - data with 0 bytes. 8.4.4.1 Resolve Request Used to request the Resolver Service to resolve user name(s) to user ID(s). Message Body 0 8 16 24 31 +---------------------------------------+ | Length of Request [4] | +---------------------------------------+ | Request Id [4] | +---------------------------------------+ | Number or Names to Resolve [4] | +-------------------+-------------------+ | Name [String] X Times number of names +-------------------+-------------------+ | Request Options [4] | +---------------------------------------+ Description of Fields: Length of Request Size of Message Body in bytes including this field. Request Id Issued by the client, used to identify the request. page 42 Sametime Community - Client Protocol Page 42 Number of Names to resolve Indicates how much names there are to follow... Names Strings of names to resolve. Appears as times as indicated before. Options A bit mask of the following options: 0x00000001 - Return only unique matches (if number if matches <> 1, return empty list of matches 0x00000002 - Return first match only 0x00000004 - Search all available directories (otherwise do not search beyond the directory were the first match was found 0x00000008 - Users bit (should always be on). 8.4.4.2 Resolve Response The response for the clients ResolveRequest. This message is a list of results, each result being a list of matches. --- Message Body 0 8 16 24 31 +---------------------------------------+ | Internal Use Bytes [4] | +---------------------------------------+ | Request Id [4] | +---------------------------------------+ | Return Code [4] | +---------------------------------------+ | Number of Results [4] | +---------------------------------------+ ------------- | Internal Use Bytes [4] | ^ +---------------------------------------+ | | Result Return Code [4] | | +-------------------+-------------------+ | | Name [String] X Number +-------------------+-------------------+ of Results | Number of Matches [4] | | +-------------------+-------------------+ -------- | | Id [String] ^ | +-------------------+-------------------+ | | | Community Name [String] X Number | +-------------------+-------------------+ of | | Name [String] Matches | +-------------------+-------------------+ | | Description [String] | | +-------------------+-------------------+ | | | Match Type [4] | v v page 43 Sametime Community - Client Protocol Page 43 +---------------------------------------+ ------------- Description of fields: Internal Use Bytes These bytes are used for backward / forward compatability. These bytes should be ignored in the resolve response. Request Id Identifies the response for the request Id'ed by the client Return Code Of the entire response. Number of Results Number of nested results to follow Result Return Code A return code for a specific name. Number of matches Number of matches to follow Id & Community Created for the UserId resolved Name The "official" user name Description Description of the user as kept in the database Match Type Should always be 0x00000001. 9. Acknowledgements The authors of this document wish to acknowledge the following that contirbuted to this document: Mark Day, Alon Kleinman, Maxim Kovalenko & Marjorie Schejter. 10. Authors Addresses Avshalom Houri Ubique/Lotus Building 18/D, Sceince Park Kiryat Weizmann, POB 2523 Rehovot 76123 Israel avshalom@ubique.com Ittai Golde Ubique/Lotus Building 18/D, Sceince Park Kiryat Weizmann, POB 2523 Rehovot 76123 Israel ittai@ubique.com page 44 Sametime Community - Client Protocol Page 44