Work with Enhanced Presence Using Unified Communications Managed API version 2.0

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.

In Unified Communications Manage API (UCMA) version 2.0, to publish enhanced presence, the application uses the LocalOwnerPresence class from UCMA Core. This class exposes an asynchronous method, BeginPublishPresence/EndPublishPresence, to let the user publish his or her presence. The to-be-published presence information is represented by a collection of PresenceCategory or PresenceCategoryWithMetaData objects. They are the API-specific representations of the Unified Communications Enhanced Presence Schema elements documented in Unified Communications Enhanced Presence Schema Reference (2007 R2 Release). They must be passed into the BeginPublishPresence method as its first input parameter.

In the following example, the application obtains an instance of the LocalOwnerPresence class by calling the LocalOwnerPresence property on an established LocalEndpoint instance.

LocalEndpoint _localEndpoint = ...;
string userStateXmlTemplate = 
      "<state xmlns=\"http://schemas.microsoft.com/2006/09/sip/state\"" + 
      "       xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"" + 
      "       manual=\"true\" xsi:type=\"userState\">" + 
      "   <availability>{0}</availability>" + 
      "</state>";
CustomPresenceCategory userState = new CustomPresenceCategory("state", 
                          String.Format(_userStateXmlTemplate, 3500));
PresenceCategory[] presenceCategories = new PresenceCategory[] { userState };

// Assuming _localEndpoint is already established, publish the user state 
// category instance.
LocalOwnerPresence localPresence = _localEndpoint.LocalOwnerPresence;
localPresence.EndPublishPresence(
       localPresence.BeginPublishPresence(presenceCategories, null, null));

In the previous example, the last statement makes the asynchronous call in a synchronous fashion.

The presence category elements can also be generated from the Enhanced Presence Schemas (XSD) files. For more information about generating the presence data from the XSD files, see Work with Enhanced Presence Schema Files.

In the following example, to subscribe to a specified presence data of another user, the application uses the RemotePresence class from UCMA Core. As with the LocalOwnerPresence object, the application obtains an instance of RemotePresence by calling the RemotePresence property on an established LocalEndpoint instance. Before the subscription begins, the application must specify category types and remote presence owners in the subscription session. If a request to subscribe is successful, the application is notified of the presence updates issued from the remote users' endpoints, provided that the application registers appropriate event handlers with the RemotePresence object to receive and handle such notifications.

LocalEndpoint _localEndpoint = ...;

// Obtain the RemotePresence instance for category subscription.
// _localEndpoint must be established to return valid remotePresence.
RemotePresence remotePresence = _localEndpoint.RemotePresence;

// Register an event handler with remotePresence to receive subscribed 
// presence (categories)
remotePresence.PresenceNotificationReceived += 
         new EventHandler<RemotePresenceNotificateEventArgs>(
                        RemotePresenceNotificationReceivedEventHandler);

// Add remote presentities as the target of this subscription
RealTimeAddress rta = new RealTimeAddress("sip:john@contoso.com");
RemotePresentitySubscriptionTarget target = 
       new RemotePresentitySubscriptionTarget(rta, null);
remotePresence.EndAddTargets(
       remotePresence.BeginAddTargets(targetArray, null, null));

// Submit a request to subscribe "state", "note", "calendarData", 
// "contactCard", and "services" presence categories. These are specified 
// as the default categories of any RemotePresence instance. 
remotePresence.EndRefresh(remotePresence.BeginRefresh, null));

In the following example, an event handler receives presence notification. The implementer of such event handlers must understand the Enhanced Presence Schemas in order to parse the received presence category instances.

void RemotePresenceNotificationReceivedEventHandler(object sender,
                    RemotePresenceNotificateEventArgs e)
{
  foreach (RemotePresentityNotificationData notification in e.Notifications)
  {
    // Each user will send a list of updated categories. We are interested in 
    // the "state" category instances here. 
    foreach (PresenceCategoryWithMetaData category in notification.Categories)
    {
        if (category.Name.Equals("state"))
        {
            //get the xml data
            string rawXml = category.CreateInnerDataXml();
            if (rawXml == null || rawXml.Trim().Length == 0)
            {
                break;
            }

            StringReader reader = new StringReader(rawXml);
            XmlDocument metadataDocument = new XmlDocument();
            metadataDocument.Load(reader);

            XmlNodeList stateNodeList = metadataDocument.ChildNodes;
            if (stateNodeList == null || stateNodeList.Count == 0)
            {
                continue;
            }

            //find the availability value

            XmlNode stateNode = stateNodeList[0];

            if (stateNode.Name != "state")
            {
                continue;
            }

            XmlNodeList availabilityNodeList = stateNode.ChildNodes;
            if (availabilityNodeList == null || availabilityNodeList.Count == 0)
            {
                continue;
            }

            XmlNode availabilityNode = availabilityNodeList[0];
            if (availabilityNode.Name != "availability")
            {
                continue;
            }

            if (availabilityNode.InnerText == null)
            {
                continue;
            }

            int availability;

            if (Int32.TryParse(availabilityNode.InnerText, out availability))
            {
                Console.WriteLine("Availability: {0}", availability);
                break;
            }
        }
    }
  } 
}

See Also

Concepts

Work with Enhanced Presence Using Unified Communications Client API

Work with Enhanced Presence Schema Files