Events as Server Updates
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.
An event represents an update on the server. An update could be the result of an execution of a Communicator Web Access Server method requested by a client or a change made by other Unified Communications-compatible clients. An update could also reflect state changes in the server. The following examples illustrate two types of events:
Execution of the queryPresence method returns a userPresence event containing the presence information of the specified user as a list of category instances.
When a user signs in using a Communicator Web Access Client or Unified Communications AJAX API Client and this user is in the Contacts list of the user of an active Unified Communications AJAX API client, the AJAX client is notified of this event in a contactGroup instance.
Events are asynchronous in nature. To catch events from a Communicator Web Access Server, a client must periodically poll the server and retrieve events as they are placed in the Communicator Web Access Server session queue. For more information about how to catch events, see Receiving Events from Communicator Web Access Server.
XML Element for an Event
An event is represented as a cwaEvents element. The name of each individual event corresponds to the name of the child element. The parameters of the event, if any, are specified as the child elements and/or their attributes. For example, the following is an example of the userPresence event in response to a queryPresence method request for another user's presence.
<cwaEvents pollWaitTime="3000" ackId="11" sid="66">
<userPresence eid="10">
<user uri="sip:jaya@contuso.com" sourceNetwork="...">
<cwaCategory name="state" instance="0">
<state xmlns="..." xmlns:xsi="..." xsi:type="...">
<availability>0</availability>
<activity token="Offline" />
</state>
</cwaCategory>
<cwaCategory name="note" instance="0">
<note xmlns="...">
<body type="personal" />
</note>
</cwaCategory>
<cwaCategory name="contactCard" instance="0">
<contactCard xmlns="...">
<identity>
<name>
<displayName>JayA</displayName>
</name>
</identity>
</contactCard>
</cwaCategory>
</user>
</userPresence>
<requestSucceeded eid="11" rid="2" />
</cwaEvents>
where the eid attribute is a server-assigned instance ID for this event. Its main purpose is to ascertain the sequence number of this event instance.
In an HTTPS response from a data channel, the message body is represented by a cwaEvents element, which can have one or more event elements. Multiple types of events may be reported within this element:
requestSucceeded This indicates that the Communicator Web Access Server has successfully finished processing the request. For example, a terminateSession request is carried out and could finish successfully synchronously.
requestFailed. This indicates that the server has aborted processing request due to an error.
Otherevents. See Events for a complete list of events.
In an HTTPS response from a data channel, the message body is represented by a cwaEvents element, which can have one or more event responses. The following code shows an example.
<cwaEvents pollWaitTime="3000" sessionTimeout="14386" ackId="9" sid="117">
<requestSucceeded eid="8" rid="3" />
<selfPresence eid="2">
<cwaCategory name="contactCard" instance="0">
<contactCard xmlns="...">
<identity>
<name>
<displayName>stevent8</displayName>
</name>
</identity>
</contactCard>
</cwaCategory>
</selfPresence>
</cwaEvents>
In an HTTPS response from the command channel, the message body is represented by a cwaResponses element, which can have one or more response elements. Multiple types of responses may be reported within this element:
requestAccepted. This indicates the request is formatted correctly and there is no other synchronous processing error. The Communicator Web Access Server continues processing the request and returns succeeded or failed status sooner or later.
requestRejected. This indicates either the request is formatted incorrectly or there is an immediate session error or other error in processing the request. The Communicator Web Access Server stops processing the request at this point.
requestSucceeded. This indicates that the Communicator Web Access Server has successfully finished processing the request. For example, a terminateSession request is carried out and could finish successfully synchronously.
Other responses. See Events for a complete list of synchronous event responses.
The following example shows a synchronous response to an initiateImSession request.
<cwaResponses>
<requestAccepted rid="12">
<imId>2</imId>
</requestAccepted>
</cwaResponses>
As another example, the following response shows that Request 4 is accepted for further processing, Request 5 is successfully processed, synchronously, and Request 6 is rejected because a dictionary key is out of bound.
<cwaResponses sid="768 ">
< requestAccepted rid="4" />
< requestSucceeded rid="5" />
< requestFailed" rid="6">
<exceptionType>Microsoft.Cwa.Service.CwaException</exceptionType>
<exceptionDetail>The given key was not present in the dictionary.</exceptionDetail>
</requestFailed>
</cwaResponses>
Valid response names and possible response parameters and their values are documented in Unified Communications AJAX API Reference.