Subscribe to Category Instances

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.

A subscription is a request on Office Communications Server for category data published by a user. Subscription requests are created as either persistent subscriptions or one-time subscriptions. A persistent subscription continues to return new and updated categories as long as the local subscribing user is signed in to Office Communications Server. A One-time subscription is also known as a query and returns a set of category instances once at the time of the query.

A user must subscribe to the specified categories, specify the publisher of the categories, and handle a chain of related events to receive updates whenever a category instance is added, modified, or removed by a publisher. A subscription object is distinct from the objects and events used to handle the results of a subscription. A developer can design one class to create and request subscriptions while another class handles the events raised by the client platform as a result of a subscription. The common thread between two such classes is the presentity representing a publishing user. Ultimately, a developer must implement subscription event handlers to track the status of the subscription request and presentity event handlers to respond to events raised when Office Communications Server returns subscribed categories.

General Programming Pattern

The general programming pattern for subscribing to category instances can be outlined as follows:

Obtain the subscription manager (IUccSubscriptionManager) object.
A client can query the IUccSubscriptionManager interface on an enabled IUccEndpoint object by calling the QueryInterface method. The endpoint object is also treated as the subscription manager for the user.

Note

There are no subscription manager related events.

If your application is written in C++ and you are implementing the ATL library, you obtain a smart pointer to the subscription manager (CComQIPtr)
```
CComQIPtr<IUccSubscriptionManager> spSessionManager = EndPoint;
```
The subscription manager is obtained from a registered local endpoint (IUccEndpoint) object. The endpoint object is also treated as the subscription manager for the user.
Create a subscription (IUccSubscription) object.
Call the CreateSubscription method on the subscription manager object.
Advise for _IUccSubscriptionEvents events on the newly created subscription object.
The client ascertains the operational status of a subscription (Subscribe) request using these event handlers. Note that a client must advise for and handle subscription requests to determine when the subscription or query has been fulfilled.
Create a presentity (IUccPresentity) object.
Call the CreatePresentity method on the subscription object, passing an instance of UccUri representing the publishing user of interest.

Note

An instance of UccUri is created by calling ParseUri and passing the SIP URI string of the publishing user.
Advise for _IUccPresentityEvents events.
These events are raised by the newly created presentity object. It is important that a client register for this type of event to receive notifications when the publisher adds a new category to or removes an existing one from its publications.
Add the presentity object of the interested publisher to the subscription object.
More than one presentity can be added to a single subscription. A single subscription to a set of categories can handle category events for multiple publishers. Note that a self-subscription (defined in Terminology) must only have a single presentity. That presentity must represent a local user as the publisher.
Add a chosen category name (AddCategoryName) to the subscription.
Multiple category names can be added to a single subscription object. The CategoryNames property exposes the collection of category names added to a subscription.
Subscribe to the specified categories instances published by the selected publishers
Call the Subscribe method on the subscription object.Subscribe should be called once per subscription after all presentities and category names have been added to the subscription. For information about receiving subscribed categories from Office Communications Server, see Receive Subscribed Categories.

Example: Self-Subscribing

The following example creates a self-subscription to category instances published by the local user. The example method accepts two parameters. endpoint is the active principal endpoint and selfURI is a string representing the SIP Uri of the subscribed category owner.

public void Subscribe(IUccEndpoint endpoint, string selfURI)
{
    try
    {
        //get subscription manager interface from endpoint instance
        IUccSubscriptionManager sm = endpoint as IUccSubscriptionManager;

        //create an Uri Manager object
        IUccUriManager _UriManager = new UccUriManagerClass();

        //create a URI instance from the SIP URI string
        UccUri u = _UriManager.ParseUri(selfURI);

        //Subscribe to "categories" and "containers"
        IUccSubscription selfSubscription = sm.CreateSubscription(null);
        UCC_Advise<_IUccSubscriptionEvents>( selfSubscription, this);

        //create presentity to represent the publishing owner of the category 
        IUccPresentity selfPres = selfSubscription.CreatePresentity(
                                  u, 
                                  null);
        //Create new instance of application presentity class, passing
        //the selfPres presentity instance to it in a class constructor
        //In the presentity class, register for presentity events:  UCC_Advise<_IUccPresentityEvents>(selfPres, this); 
        //myPresentityClass m_PresentityClass = new myPresentityClass(selfPres)


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

    }
    catch (Exception ex)
    {
        this.ShowError(ex.ToString());
    }
}

The subscription request created by the previous example is processed by a Unified Communications Server and the response carrying the subscribed categories is returned to the client asynchronously. See Receive Subscribed Categories for an example of a subscription event handler.

Example: Subscribing to Contacts and Groups Category in C#

The following example subscribes to the contacts and groups categories and defines events to handle. Note that this example creates a subscription and initiates the subscription request but does not handle presentity events containing returned category data.

public partial class ContactMan : _IUccSubscriptionEvents
                                , _IUccPresentityEvents
                                , _IUccCategoryContextEvents
                                , _IUccCategoryInstanceEvents
                                , _IUccContactEvents
                                , _IUccGroupEvents
{
   // class variables
   IUccSubscription subscription;
   IUccSubscriptionManager subscriptionManager;
   int subId = 0;

   // Class constructor
   public ContactMan(IUccEndpoint ep)
   {
      this.subscriptionManager = ep as IUccSubscriptionManager;
      this.subscription = 
              this.subscriptionManager.CreateSubscription(null);
     UCC_Advise<_IUccSubscriptionEvents>(this.subscription, this);
   }

   // Send the server a Subscribe request for contacts and groups categories
   public void SubscribeToContacts()
   {
      IUccEndpoint ep = this.subscriptionMananger as IUccEndpoint;
      string sipUri = ep.Uri;
      string[] categoryNames = { "contacts", "groups" };

      foreach (string categoryName in categoryNames)
      {
         this.subscription.AddCategoryName(categoryName);
      }

      IUccPresentity presentity = this.subscription.CreatePresentity(sipUri, null);
      // Utils.Advise is a static method defined in a class named Utils
      // An implementation of it is shown somewhere else in this 
      // document.
      UCC_Advise<_IUccPresentityEvents>(presentity, this);
      this.subscription.AddPresentity(presentity);
   
      // Submitting the SUBSCRIBE request to the server
      this.subscription.Subscribe(subId++);
   }

   // Handling events:
   // For Subscription Events:
   void _IUccSubscriptionEvents.OnQuery(UccSubscription sub, 
                        IUccSubscriptionEvent subEventInfo)
   {
       // Bubble this event up to the UI so that results are displayed
   }

   void _IUccSubscriptionEvents.OnSubscribe(UccSubscription sub, IUccSubscriptionEvent subEventInfo)
   {
        if (subEventInfo.IsComplete == true && subEventInfo.StatusCode >=0)
        {
           //Office Communications Server returned all initially subscribed categories
           //Bubble this event up to the UI so that results are displayed
        }
   }

   void _IUccSubscriptionEvents.OnUnsubscribe(UccSubscription sub, IUccSubscriptionEvent subEventInfo)
   {
        UCC_Unadvise<_IUccSubscriptionEvents>(sub, this);
   }

General Programming Pattern

Example: Self-Subscribing

Example: Subscribing to Contacts and Groups Category in C#

See Also

Concepts

Additional resources