Create Contact List Subscription

Article
06/14/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.

When the user endpoint is enabled, a Unified Communications Client API application should request a subscription to the local user's contact list. The subscription request results in the client application receiving the user's contact list. The returned contact list gives the local user the enhanced presence of individual remote users in the contact list. For information about how to enable a user endpoint, see Sign a User into Office Communications Server.

This section covers how to:

Enable a subscription to the contact list.
Receive the contact list entries and enable monitoring contacts' presence. See Receive Contact List.
Monitor contact presence..

Enable Subscription to Contact List

The first step toward retrieving the contact list and monitoring contact presence is to enable three subscription sessions by creating and maintaining the required subscription objects. One subscription is to receive the list of contacts in the caller's contact list (see selfSubscriptionForContactList in the following code example) and the other is to receive the information or updates of interested contacts (see contactsSubscription). An application can also enable a third subscription session to discover all the published information about the caller herself (see selfSubscription). This subscription session is necessary when a user wants to publish the self presence.

The following C# code snippet illustrates how to create or enable the subscription sessions in order to retrieve a contact list and monitor the contacts' presence.

partial class ContactManager
{
    private void SubscribeToContacts()
    {
        try
        {
            // Subscribe to "contacts", "categories"
            // and "containers" to receive 
            // self data that may be useful in the application. This
            // requires 
            //  1. creating a new subscription session and 
            //  2. registering for interested events to be raised by 
            //     this subscription object.  
            //  3. adding self presentity and the category names
            //     to the subscription and 
            //  4. calling the Subscribe method on the subscription
            //     object.
            selfSubscription = subscriptionManager.CreateSubscription(null);
            UCC_Advise<_IUccSubscriptionEvents>(selfSubscription, this);

            // Create a self presentity to represent the user of this
            // application and register for events that will be raised
            // by the self presentity object. This event registration
            // necessary if the application is to be notified of any 
            // category added by the presentity.
            selfPresentity = selfSubscription.CreatePresentity(
                               selfURI, 
                               null);
            UCC_Advise<_IUccPresentityEvents>(selfPresentity, this);

            selfSubscription.AddPresentity(selfPresentity);
            selfSubscription.AddCategoryName("categories");
            selfSubscription.AddCategoryName("containers");
            selfSubscription.AddCategoryName("contacts");
            selfSubscription.Subscribe(null);


            // Subscribe to category instances related to contact info 
            // and presence info published by specified contacts. This 
            // enables the application to receive the contacts' info 
            // and to monitor the contacts' presence. The application 
            // is required to do the following:
            //  1. creating a new subscription session,
            //  2. registering for interested events to be raised by
            //     this subscription session,
            //  3. adding interested category names ("state" and
            //     "contactCard" in this example) to the subscription
            //  4. adding a contact as the presentity to this
            //     subscription (This step is deferred until a 
            //     a "contacts" category instance is returned by
            //     the selfSubscriptionForContactList object. See
            //     "Receive Contact List and Enable Presence 
            //     Monitoring" below.)
            //  5. calling the Subscribe method on the subscription
            //     object. (This step is deferred until a
            //     "contacts" category instance is returned by
            //     the selfSubscriptionForContactList object. See
            //     "Receive Contact List and Enable Presence 
            //     Monitoring" below.)
            contactsSubscription = subscriptionManager.CreateSubscription(null);
            UCC_Advise<_IUccSubscriptionEvents>(contactsSubscription, this);
            contactsSubscription.AddCategoryName("contactCard");
            contactsSubscription.AddCategoryName("state");
        }
        catch (COMException ex)
        {
            // A primitive error reporting mechanism for the 
            // purpose of illustration.
            MessageBox.Show(ex.ToString());
        }
    }
}

Create Contact List Subscription

Enable Subscription to Contact List

See Also

Concepts

Additional resources