Share via

Programming Patterns with Subscription

  • Article

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 client is provisioned with configuration information and other roaming data through a subscription to self-published category data. Until the client subscribes to and receives subscription-related events, the user's contact list and other published information is not available. The process of provisioning the client should begin immediately after the endpoint is enabled. The best place to start the process is in the OnEnable callback method.

Programming Patterns in Subscription

A subscription object is created for the enabled endpoint. The subscription object must have a set of category instances and publishing presentities before the request to subscribe is made on Unified Communications Server. When the subscription request is made, the subscribed category information is sent to the client asynchronously through a series of events that must be handled to provision the client with category data. As subscribed users publish changes to their presence categories, those changes are sent to the client in new instances of presentity, category context, and category instance events.

Before any of the following programming patterns can be executed, a subscription manager object must be instantiated by a cast from an enabled endpoint. The subscription manager is represented by the IUccSubscriptionManager interface.

Create a Subscription

  • Instantiate a subscription object by calling into CreateSubscription on the subscription manager.
  • Advise the new subscription object of implemented subscription event callback functions in your class. Advising for _IUccSubscriptionEvents allows the caller to receive the operational status after a request to Subscribe, Query, or Unsubscribe is processed in a publication. For information about advising, see Advise for and Handle Events in a Unified Communications Client API Client.
  • For each category instance subscribed, call AddCategoryName for the category of interest. Pass a string representing the category name as an argument to the method. An alternative is to use the UCC_PRESENCE_CATEGORY_TYPE enumeration that provides enumerated values for the well-known category names. The IUccPublicationManager interface provides the GetPresenceCategoryName method that takes the previously mentioned category type enumeration and returns a category name as a string.
  • For each user the client subscribes to, add an IUccPresentity object to the subscription by calling into AddPresentity.
    If you have not created a presentity object prior to this step, create one by using the SIP URI formatted string of the publishing endpoint:
    • Using a UccUriManager, call ParseUri, passing the SIP URI string as an argument.
    • Using the UccUri object returned by the call to ParseUri, call into CreatePresentity.
    • The IUccPresentity object returned by CreatePresentity is provided as an argument to the subscription method AddPresentity.
    • Advise each new presentity object of implemented callback functions in your class so that you receive presentity events. Advising for _IUccPresentityEvents is a prerequisite for an application to receive subscribed category instances. Handling this event interface is the first step in a series of event handling as part of a subscription.

Request to Subscribe

Send the subscription request to a Unified Communications Server by calling Subscribe on the subscription object. The subscription request raises subscription events that indicate the progress and result of the subscription request.

Request to Query

The query request involves the same programming steps used in a subscription request for creating a subscription. To review the programming pattern in creating a subscription, see the "Create a Subscription" section.

Note

The query request results in a snapshot of a user's published presence categories. Each query request results in a single snapshot rather than an ongoing provisioning of category data. The query is useful when the client is interested in reducing SIP traffic due to bandwidth restrictions.

Send the Query request to Office Communications Server. The query request raises OnQuery events rather than OnSubscribe events. The presence categories returned by the query are handled by the same callback functions you use to handle presence categories returned by a subscription.

Request to Cancel the Subscription

Unsubscribing to an existing subscription object requires a single method call.

Call into Unsubscribe and handle the subscription events related to the call.

Handle Events for Subscription

To receive published category instances, an application must handle at minimum the following events. Strongly type category instance events can be handled in the same way.

Category Context Added or Removed Events

The OnCategoryContextAdded event is a presentity event. Each presentity in the subscription object generates this event for each of its published categories.

Category Instance Added or Removed Events

The OnCategoryInstanceAdded event is a category context event. This class of event is raised after receiving a category context object and advising as described in the previous task. Each instance of a category in a category context raises the event. For example, if a local user has self-published his contact list with ten contacts, he receives ten individual OnCategoryInstanceAdded events in the context of the contacts category.

This event carries the actual subscribed presence information. The first argument of the callback function is an IUccCategoryContext object. This object provides a Name property and is read to get the category context. The second argument of the callback function is an object with two property members. The CategoryInstance property value is cast to the IUccCategoryInstance interface.

Evaluate the context name and execute program logic suited to the context of the category instance being handled. Strongly typed category instances from the following list require exceptional handling:

  • contacts. Cast the IUccCategoryInstance to IUccContact and advise the new contact object of the contact event handlers in your class. You must implement _IUccContactEvents in the class that handles contact events.
  • groups. Cast the IUccCategoryInstance to IUccGroup and advise the new group object of the contact event handlers in your class. You must implement _IUccGroupEvents in the class that handles group events.
  • containers. Cast the IUccCategoryInstance to IUccContainer and advise the new container object of the contact event handlers in your class. You must implement _IUccContainerEvents in the class that handles container events. You only receive this category when handling self-published events.
  • Subscribers. Cast the IUccCategoryInstance to IUccSubscriber. This category event is the best opportunity to add a newly subscribing user to the local user's own contact list. The event is normally used to acknowledge a subscribing user.
  • contactCard. Cast the IUccCategoryInstance to IUccPresenceContactCardInstance. This contact card interface exposes all published contact card data that the local user has access to. Use the interface to display contact card data for the subscribed user.
  • State. Cast the IUccCategoryInstance to IUccPresenceStateInstance. This presence state interface exposes availability state data as an integer. For a table of availability state values, see Presence Availability State.
  • Note. Cast the IUccCategoryInstance to IUccPresenceNoteInstance. This presence note interface exposes presence note as a string.
  • calendarData. Cast the IUccCategoryInstance to IUccPresenceCalendarDataInstance. This presence calendar data interface exposes a contact's free/busy and working hours information.
  • serverConfiguration. Cast the IUccCategoryInstance to the IUccServerConfigurationCategory interface. This interface provides necessary information that allows a client to configure a media connectivity server plus several other server configuration tasks.

For information about available well-known category types, see Category and Category Instances.

Category Instance Value Modified Events

This event is raised when a user publishes a change to her presence information. This is most frequently the case when a user publishes a user or machine state change. For example, a user changes her availability state from online to busy. The local client must handle this event to display updated availability for the user in the local contact list. The callback function provides the changed category instance in the first argument position.

Use the properties and methods exposed in the strongly typed interface to update cached data on the client.

See Also

Concepts

Category and Category Instances
Category Publication
Category Subscription