Category Subscription
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 user subscribes to published category instances by submitting a request to receive specified categories by specified publishers. The publisher can be another user or the subscriber. When the category instances are published, the server notifies the subscriber of the event, provided that the subscriber is granted permission by the publisher. A subscriber can stop the subscription and cancel future publications but only a registered user can start a subscription.
Subscription Session
A Unified Communications Client API subscription is encapsulated by the IUccSubscription interface. A user can start a subscription with a call to the Subscribe method, after an IUccSubscription object is created. The user creates the subscription object by calling the CreateSubscription method on the subscription manager (IUccSubscriptionManager). The subscription object is obtained through an interface query on the registered local endpoint.
Before the Subscribe request is made, the user must specify the names of interested categories and their publishers. A client implements this process by adding category names and a list of publishers to an IUccSubscription object. Each publisher is known as a presentity and is represented by an IUccPresentity object.
A subscription session starts when an OnSubscribe is returned successfully; namely, StatusCode >= 0. The subscription session ends when the subscriber calls the Unsubscribe method. Throughout a subscription session, the subscriber is notified of any publication events where a subscribed category instance is created, modified, or deleted.
Querying Category Instances
A user can also perform one-time queries of specified category instances by specified presentities. This is done by calling the Query method on a subscription object. The programming pattern is similar to subscribing to a collection of category instances. However, the notion of session does not apply to the query operation.
Self Subscription
The user's Contact Card information, contact list, and other configuration information are provisioned to the Unified Communications client as roaming data. This roaming data is defined by a self-subscription. That is, the user specifies what categories of roaming data are provisioned to the local client by subscribing to interested categories. For example, a user maintains a contacts list by publishing a list of contacts category instances for personal use. Every time the user logs on to the server, the client can start a subscription session for the user to receive the list of contacts category instances.
To discover the categories previously published by the user, the user must start a self subscription to the categories category instances. To find the containers published, the user must start a self subscription to the containers category instances.
Typically, a Unified Communications Client API application maintains at least two subscriptions. One is to subscribe to category instances published by other users. The other is a self subscription to the contacts and other types of category instances.
Subscription Events
The _IUccSubscriptionEvents interface defines the events that a client can handle to receive the operational status after a subscription request is made (OnSubscribe) or canceled (OnUnsubscribe), or after a query is requested (OnQuery). The StatusCode >= 0 indicates that the request in question succeeded. Otherwise, the request failed. For information about the error codes, see Unified Communications Client API Error Codes. To receive the event notifications, a client must advise the IUccSession object of implemented callback functions that handle these events. For more information about advising for events, see Event Model of Unified Communications Client API.
The results of a Subscribe or Query request are returned as events defined in the _IUccPresentityEvents, _IUccCategoryContextEvents, and _IUccCategoryInstanceEvents. The sequence of events flows as follows:
- After a publisher initially publishes a category instance, the IUccPresentity object corresponding to the publisher calls the OnCategoryContextAdded.
- The subscriber who has advised for this event receives the newly added category as an IUccCategoryContext object. The subscribing client must then advise for _IUccCategoryContextEvents with the new category context object to receive newly published category instances.
- For each newly published category instance, the subscriber receives the OnCategoryInstanceAdded event with an IUccCategoryInstance object. The subscribing client must then advise for _IUccCategoryInstanceEvents with this category instance object to be notified of changes of the category instance value in the subscription session. If the received category instance has a strongly typed derived class, the category instance must be cast to that class before accessing the strongly typed data. For example, category instances of the category context "contacts" must be cast to IUccContact before gaining access to contact fields.
- Category instances cast to the IUccContact, IUccGroup, and IUccContainer interfaces expose events that must be handled. For example, the contact interface exposes events such as OnAddedToGroup and OnNameChanged. For information about these events, see _IUccContactEvents, _IUccGroupEvents, _IUccContainerEvents.
- Every time the publisher changes the value of a category instance, the subscriber receives the OnCategoryInstanceValueModified events, if the subscribing client has registered for the event with the corresponding IUccCategoryInstance object.