cwaCategory Element

Article
05/23/2014

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.

This element is an envelope that contains well-known enhanced presence category data. A well-known presence category is a category of data whose structure is defined by Office Communicator for interoperability with a Unified Communications Server. A Unified Communications client application that implements the Unified Communications AJAX API is able to interoperate with an Office Communicator client by publishing these well-known presence categories.

Syntax

<cwaCategory name="string value" instance="integer value"/>

Attributes

Attribute	Data Type	Description
effectiveAt	integer	Event Messages: The time when this category should take effect.
Expires	Boolean	Requests: Category is not static.
Name	string	Requests, events: The name of the category. This is a required attribute.
Instance	integer	Requests, events: The unique instance ID assigned to this category. This attribute is present in the element when part of a userPresence event returned by a Communicator Web Access Server.
instanceMask	integer	Requests: The unique instance ID assigned to this category. This attribute is required in the element when part of a publishSelfPresence request on a Communicator Web Access Server
publishTime	integer	Event Messages: The time when this category was published.
Version		Event Messages:Category version. This attribute is not available for legacy clients.

Element Information

Parent Element

Element	Description
selfPresence Element	Envelope for receiving the logged-on users presence categories.
userPresence	Envelope for receiving another user's presence categories.

Child elements

Element	Occurrences	Description
any	0 or more	Holds an XML tree fragment with a namespace attribute. The fragment is passed through the Communicator Web Access server to an endpoint.
contactCard	0 or more	Contains user contact card information.
calendarData	0 or more	Contains user free/busy and calendar state information.
Note	0 or more	Represents the user customizable note that appears on their contact card.
Routing	0 or more	Contains a user's call routing rules.
Services	0 or more	Contains the services configured for user.
State	0 or more	Contains the aggregate state of the user. The instanceMask attribute of the parent cwaCategory element is 536870912.
Alerts	0 or more	Contains the user-specified alert options.
otherOptions	0 or more	Contains permissions set by the user.
userInformation	0 or more	Contains the users contact telephone information.

Remarks

When a user makes an initiateSession request and the Communicator Web Access server has processed the requested method, a selfPresence Element element is returned on the data channel asynchronously. Within the selfPresence Element element are a set of cwaCategory elements. Each cwaCatgory element is designated to contain a specific type of information. For example, there is a cwaCategory that holds contact card information. The child elements table above is a complete listing of the types of cwaCategory elements that can be returned.

The following list of well-known categories are defined by Office Communicator and are used by the Communicator Web Access Server for interoperability with Office Communicator. For a detailed explanation of presence categories, refer to the Unified Communications Client API SDK documentation.

ContactCard category

The contact card category contains enhanced presence information for subscribed or queried remote users. Namespace:"http://schemas.microsoft.com/2006/09/sip/contactCard"

Identity. The e-mail and display name of the contact. Instance Id is 0 (zero).
Address. The street address of the contact. Instance Id is 2. Street
- City
- State
- Zipcode
- countryCode
Company. The company name of the contact. Instance Id is 3
Department. The department name of the contact. Instance Id is 3
Title. The contact's job title. Instance Id is 3
Office. The office telephone of the contact. Instance Id is 3
url. An Url pointing to the contact's personal Web page. Instance Id is 2
phone. A list of phone numbers belonging to the contact. The instance Id is 1.

alerts category

The alerts category holds user configuration data alert options. This category is for provisioning a local user with her configuration. The category is not published for subscribing users. Namespace: "http://schemas.microsoft.com/2006/09/sip/options"

notifyAdditionToContactList. Local user is notified when added to remote user contact list.
displayStatusAlertsForAllContacts. Local user is alerted when subscribed user presence changes.
alertsForIncomingConversation. Local user is alerted on incoming conversation
displaySubjectInConversationAlerts. Display message text in incoming instance message alerts when local user has chosen alertsForIncomingConversation.
alertsWhenDoNotDisturb. Specify desired alerts when local user status is Do Not Disturb (DND). phone type can be of following tokens: "displayAllAlerts", "displayAlertsFromHighPresence", "noAlerts".
playSoundFeedback. Sounds are played for feedback.
suspendSoundWhenBusy. Suspend sound when local user status is Busy if local user has chosen to play sounds for feedback.
suspendSoundWhenDND. Suspend sound when local user status is Do Not Disturb if playing sounds for feedback.
suspendSoundWhenConversationWindowInForeground. Alert sounds are suspended if local user focus is on conversation window.

userInformation category

The User Information category contains a list of all of a local user's telephone numbers. The category itself is not published to subscribing users but telephone numbers from this category provide values for the contact card category. Namespace: "http://schemas.microsoft.com/2006/09/sip/options"

phones
callHandlingList

state category

The state category is used to publish and receive state information. Namespace: " http://schemas.microsoft.com/2006/09/sip/state ". Instance Id is 1.

state. Element holds state value of one of the following types.
userState. This state type is published by the local user. InstanceMask = 536870912 (0x20000000)
machineState. This state type is published by the local user in an HTTP GET operation. See Setting Up Data Channels for more information. InstanceMask is 805306368 (0x30000000)
aggregateState. This state type is published by the Communicator Web Access Server based on an aggregation of user published userState and machineState. The instance Id is 0.

To review the availability ranges, see userStateAvailability

CalendarData category

The Calendar Data category provides a view of a user calendar. Namespace: http://schemas.microsoft.com/2006/09/sip/calendarData. Instance Id is not required.

WorkingHours. Normal workweek hours. Instance Id is 0
freeBusy. Blocks of time marked as free or busy. Instance Id is 0x40000000 | (MD5Hash(SMTP address) & 0x3FFFFFFF)

Note Category

The Note category provides a presence note for publication to subscribing users. Namespace: http://schemas.microsoft.com/2006/09/sip/note. Instance mask is 0 (zero)

body. Text of the note. If type attribute is personal, instance Id is 0. instanceMask attribute of request is 0. OOF notes cannot be published.

Although camel casing (that is, workPhone) is recommended for the name attribute value of a cwaCategory Element element, the server assumes that the values are case-insensitive when it compares the names of two categories.

Examples

Example1

The logged-on user is updating his personal note. Despite the fact that the cwaCategory Element used is a well-defined category, the xmlns (XML namespace) attribute is required for the note element itself. The expires attribute has a value of -1, which indicates that this category does not expire.

<publishSelfPresence rid="2">
   <cwaCategory name="note" instanceMask="0" expires="-1">
      <note xmlns="http://schemas.microsoft.com/2006/09/sip/note">
         <body type="personal">This is a personal note</body>
      </note>
    </cwaCategory>
</publishSelfPresence>

Example 2

The user is publishing her work and mobile telephone numbers. The expires attribute indicates that the category does not expire.

<publishSelfPresence rid="3">
   <cwaCategory name="userInformation" expires="-1">
      <userInformation xmlns= "http://schemas.microsoft.com/2006/09/sip/options" >
         <phone type="work">
            <uri>tel:+12225556666</uri>
            <displayString>222 555-6666</displayString>
         </phone>
         <phone type="mobile">
            <uri>tel:+12225555555</uri>
            <displayString>222 555-5555</displayString>
         </phone>
      </userInformation>
   </cwaCategory>
</publishSelfPresence>

Share via