Receiving Events from Communicator Web Access Server
This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.
When a user requests a method such as starting an IM session, corresponding events are generated on the server and queued for interested clients to poll. For valid events, see Events.
Coordinating with the Server to Get all Events Once
The ackIdcwaEvents element attribute is used to provide some reliability to the underlying HTTP protocol. The client must read and cache the ackId attribute every time a cwaEvents element is received from the Communicator Web Access Server. The server uses ackId to indicate the history of updates occurring on the server. The client uses ackId to verify that it has received the latest events from the Communicator Web Access Server. As an event bound for the Unified Communications session occurs, the Communicator Web Access Server increments the ackId by 1. When a client makes an HTTP GET request to receive events, it submits the latest ackId that it is aware of. The server compares the client-supplied value with the one maintained by itself. If the client-side ackId is equal to or greater than the server-side ackId, the server determines that the client has already received all the events and no further updates are pushed to the client. If the client-side token value is less than the server-side token value, the server returns all the updates that occurred after those represented by the last client ackId. This way the server can ensure that an interested client gets all the events the client should get, provided that the client passes the latest ackId cooperatively. If a client cheats by raising the token above the server-side value, the client does not receive any events until the server-side token catches up. If the client-side token is always set to zero, the client gets every update up to the current point every time an HTTP GET is made.
Dedicated a Thread to a Poll Server for Events
Events can be the result of a method request from the logged-on client or from user actions originated from other Communicator-compatible clients. Due to the asynchronous nature of the event process, a client cannot foresee when an event might be available. This means that the client must poll the server frequently and retrieves data whenever the data becomes available. If synchronous HTTP requests are used, they must be called in a loop from a dedicate thread.
The pollWaitTime period is set by the server and is load-dependent. When the server becomes busy, it increases the pollWaitTime value. When it is less busy, it decreases the pollWaitTime value. The server passes this time-out value to the client in every cwaEvents element. It is the best practice to write the client code in such a way that the next GET request is not made until the specified wait time elapses.
Receive Events Using Asynchronous Requests
With asynchronous HTTP requests, a client is not required to create a polling thread for receiving events from a Communicator Web Access Server.
Parsing Events
A client is responsible for parsing events, which can be accomplished by using various commonly used XML APIs.
Multiple-Point-of-Presence
A user can log on to a Communicator Web Access Server from multiple computers concurrently. This is called Multiple-Point-of-Presence (MPOP). In this situation, the Communicator Web Access Server must determine, on which computer (endpoint) the user is currently active. To aid Communicator Web Access Server in this determination, the Unified Communications API client must publish a machine state periodically. This state tells the Communicator Web Access Server if the user has been idle on the computer for a period of time, or if they are actively using the computer. Machine state is published whenever a client executes an HTTP GET request on the asynchronous data channel to poll for events. For more information, see Setting Up Data Channels.