Methods as Client Requests
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.
A client request represents an attempt by the client to ask the Communicator Web Access Server to perform tasks. Such tasks might be:
Changing the presence of a logged-on user from online to busy.
Starting, accepting, or closing an instant messaging session with another user logged on to the Unified Communications service through another Unified Communications AJAX API client application.
Querying for the presence of another user.
To do these tasks, the client sends the request to the Communicator Web Access Server using HTTPS POST.
In the current release of the Unified Communications AJAX API, method requests are expressed as XML-formatted messages. In the HTTP requests, the content type is marked as "text/xml".
XML Element for Method
A method is represented as a cwaRequests element. The name of each request corresponds to the name of a method using camel casing as spelling convention (the first part of a name that consists of two parts in lower case, and the second part starting with an uppercase letter). The parameters of the method, if any, are specified as the child elements or attributes. For example, the following is an example of the queryPresence method. For all cwaRequests Element except the initial logon Request, the attribute value pair 'xmlns=" http://schemas.microsoft.com/2006/09/rtc/cwa"' is required.
<cwaRequests xmlns="http://schemas.microsoft.com/2006/09/rtc/cwa">
<queryPresence rid="45">
<uris>
<uri>sip:john@contoso.com</uri>
<uri>sip:adam@contoso.com</uri>
</uris>
</queryPresence>
</cwaRequests>
The rid attribute of the queryPresence element is a client-assigned instance ID for this request. Its main purpose is to provide a means to ascertain the sequence number of this request instance. The Communicator Web Access Server sends a response to the request asynchronously on the data channel. The Unified Communications AJAX API client application can pair this event response with the original request by matching the rid attribute in the event response with the rid attribute in the original request.
In a single HTTPS request, a message body is represented by a cwaRequests element, which can have one or more request elements.
<cwaRequests xmlns="http://schemas.microsoft.com/2006/09/rtc/cwa">
<initiateSession rid="1">
<securityMode>private</securityMode>
<userStateAvailability>3500</userStateAvailability>
<options autoPublishMachineState="true"</options>
</initiateSession>
< queryPresence rid="2">
<uris>
<uri>sip:john@contoso.com</uri>
<uri>sip:adam@contoso.com</uri>
</uris>
</queryPresence>
</cwaRequests>
The name and value of XML elements and attributes are case-sensitive. The first letter of element names and attributes are not capitalized. For more information, see Unified Communications AJAX API Reference. rid is used to identify the originating request when an exception is thrown by the server. A client specifies a RequestId value in each method call. When encountering an error on executing a method, the server throws an exception and returns the error message, along with originating request ID, in some event element.