Receive List of Remote Subscribers

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.

The local client can access a list of all the remote users who have subscribed to the presence of the local user. To receive this list, the client application must subscribe to the "subscribers" category. The IUccCategoryInstance returned must be cast to IUccSubscriber to obtain necessary subscriber information. IUccSubscriber contains a UccUri instance, an acknowledgement flag, and the source network of the subscribing user. Using the UccUri instance of a subscriber from this list, the local user can restrict or expand the remote users access to the local user's published presence. In addition, the subscribing user can be added to the local user's contact list.

To receive subscription notifications, the local application must add the "subscribers" category to the self-subscription object. For information about self-subscription, see Subscribe to Category Instances.

Receiving a Subscribers List

A local user must handle the OnCategoryInstanceAdded event for this category.

Adding the subscriber to a local user's contact list can be handled by the same callback function. For information about adding the subscriber to the local contact list, see Add a Contact to the Contact List. The callback function can be used to create an exception to the access rules setup in the user's published ACL containers for the subscriber. For example, if the subscribing user belongs to a domain that has access to published category data at the organizational level, the local user might want to restrict the access of the subscriber. This is done by adding the subscriber to an existing ACL container representing the desired access level. As custom ACL containers are allowed by Unified Communications Server, the local application can create a new container, add the subscriber and a set of published categories, and publish the custom container. For more information, see Manage ACL Container Membership. The following example is a partial callback method that handles the subscribers category instance.

void _IUccCategoryContextEvents.OnCategoryInstanceAdded(
    IUccCategoryContext pCategoryCtx, 
    UccCategoryInstanceEvent pCategory)
{
    StringComparer strComparer = StringComparer.Create(System.Globalization.CultureInfo.CurrentCulture, true);
    IUccCategoryInstance ci = pCategory.CategoryInstance;
    switch (pCategoryCtx.Name.ToLower().Trim())
    { 
        case "contacts":
            break;
        case "groups":
            break;
        case "subscribers":
            IUccSubscriber subscriber = ci as IUccSubscriber;
            Console.WriteLine(subscriber.Uri.UserAtHost);
            Console.WriteLine(subscriber.SourceType.ToString());
            // acknowledge subscriber
            // add subscriber to local contact list
            // assign ACL container membership
            break;
        case "containers":
            break;
        default:
            break;
    }
}

Acknowledge a Subscriber

The callback method in the previous example is a good place to acknowledge the subscribing user. The subscription to the local user's presence cannot be rejected. Failing to handle this event has no effect on the remote user's subscription.

The C# sample uses the following programming pattern:

1. Cast the generic IUccCategoryInstance interface to the IUccSubscriber interface.

2. Read the Acknowledged property to determine whether this subscriber needs to be acknowledged.

3. Create a publishable category instance of the subscriber by calling into CreatePublishableCategoryInstance.

   Note

   The acknowledged property can only be set on a publishable subscriber interface. Attempting to set the property on the original subscriber interface results in a COM exception.

4. Create a publication object.

5. Advise for publication events.

6. Add the new publishable IUccCategoryInstance to the publication.

7. Publish the category.

// publish acknowlegement
    if (subscribingUser.Acknowledged == false)
    {
       IUccCategoryInstance subCI = ci.CreatePublishableCategoryInstance();
       IUccSubscriber sub = subCI as IUccSubscriber;
       sub.Acknowledged = true;
       subCI.PublicationOperation = UCC_PUBLICATION_OPERATION_TYPE.UCCPOT_ADD;
       IUccPublication pub = (IUccPublication)pubMgr.CreatePublication();
       if (pub != null)
       {
          UCC_Advise<_IUccPublicationEvent>(pub, this);
          pub.AddPublishableCategoryInstance(subCI);
          pub.Publish(null);
       }
   }

See Also

Concepts

Create Contact List Subscription
Receive Contact List
Remove a Contact from the Contact List
Receive User's Presence States
Presence Availability State
Sample Contact Presence Handling Class
Manage ACL Container Membership
Contact Group Management