Query Category Instances

  • 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.

Whereas a category subscription is considered a permanent request for category updates, a query is a one-time request for category data. It is a one-time receipt of a set of categories and category instances published by the remote users specified in the query. The query expires after a single execution.

Query Presentities

A single query represented by an instance of the UccSubscription class, contains a collection of IUccPresentity instances. Each presentity in the collection is a publishing user whose published category instances are of interest to the local querying user. The collection of presentity instances must contain at least one presentity. If the query is for the local user's own published categories, the collection must contain only one presentity, that of the local user.

Important

An instance of IUccPresentity created for a given subscription or query cannot be re-used for an additional subscription or query. A new instance must be created even when the user represented by the instance is the same across multiple subscriptions or queries.

The query for category data is duplicated for each presentity added to a query. If the local user creates a query for presence information published by remote user A, B, and C, Office Communicator Server executes the query three times. Each execution is targeted to a presentity in the collection of query presentities. It is possible for some of these individual queries to fail while others succeed. The OnQuery event returns an event data argument whose structure includes a presentity collection. The GetOperationInfo method returns the operational status of each presentity query. Iterating on the presentity collection and calling GetOperationInfo with each presentity provides the individual query status information.

Query Programming Pattern

Querying category instances follows the same programming patterns as subscribing to the category instances with one difference. Instead of calling the Subscribe method on an IUccSubscription object, an application calls the Query method. Advising for and monitoring the OnCategoryContextAdded event is still necessary to receive the queried category information. On a query, the related presentity events are raised with the query response. If published category data is changed after the query response is received, no additional presentity events are raised. For information about event handling programming patterns, see Receive Subscribed Categories.

The application can verify the operational status of a query request by handling the OnQuery event.

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

  1. Obtain the subscription manager (IUccSubscriptionManager) object from a registered local endpoint (IUccEndpoint) object.

  2. Create a subscription (IUccSubscription) object by calling the CreateSubscription method on the subscription manager object.

  3. Advise for _IUccSubscriptionEvents events on the newly created subscription object, if the client wants to ascertain the operational status of a query (Query) request. Once Office Communications Server has returned the results of a query, OnQuery is raised.

  4. Specify the SIP URI of a category publisher and create a presentity (IUccPresentity) object representing the publisher by calling the CreatePresentity method on the subscription object.

  5. Advise for _IUccPresentityEvents events that can be raised by the newly created presentity object. Unlike the Subscribe request on the subscription, the Query request results in a one-time set of presentity events for the presentities added to the subscription object.

  6. 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.

  7. Add a chosen category name (AddCategoryName) to the subscription. More than one category name can be added to a single subscription session.

  8. Query the specified categories instances published by the selected publishers by calling the Query method on the subscription object.

    Note

    A query to your own published categories must only have a single presentity. That presentity must represent you as the publisher.

  9. Handle presentity events to access the returned categories.
    For information about handling presentity events raised when Office Communications Server returns queried data, see Receive Subscribed Categories

  10. Handle OnQuery.
    When this event has been received, Office Communications Server has completed the query request and no further presentity events are raised. This event should be used to un-advise for both query subscription and presentity events on the subscription and presentity objects used for the query.

Example

The following example queries for the server configuration category. This is a self-query because the single presentity added to the subscription object is the local user's own URI. In this example, the code is creating a context object intended to provide information to the OnQuery callback function. The context object is received as a property of IUccSubscriptionEvent.

//add categories to server configuration subscription
selfSubForConfig.AddCategoryName("ServerConfiguration");
selfSubForConfig.AddCategoryName("meetingPolicy");

//add presentity (self) to subscription object for server configuration
UccPresentity presentity = selfSubForConfig.CreatePresentity(sipUri, null);
selfSubForConfig.AddPresentity(presentity);
UccContext selfSubCnfg = null;

//QUERY for server configuration
try
{
    selfSubCnfg = new UccContext();
    selfSubCnfg.AddNamedProperty("operation", "selfSubCnfg");
    selfSubForConfig.Query(
                     UccpAppUtils.CreateOperationContext(
                     operationId++, selfSubCnfg));
}
catch { }

/// <summary>
/// Handle OnQuery event raised when Office Communications Server has returned
/// the queried categories
/// </summary>
/// <param name="pEventSource">UccSubscription the subscription object used in the query</param>
/// <param name="pEventData">UccSubscriptionEvent the query status</param>
void _IUccSubscriptionEvents.OnQuery(
    UccSubscription pEventSource, 
    UccSubscriptionEvent pEventData)
{
    if (pEventData.IsComplete == true)
    {
        foreach (IUccPresentity p in pEventSource.Presentities)
        {
            if (pEventData.GetOperationInfo(p).StatusCode >= 0)
            {
                MessageBox.Show("Query results returned for " + p.Uri.User);
            }
            UCC_Unadvise<_IUccPresentityEvents>(p, this);
        }
        UCC_Unadvise<_IUccSubscriptionEvents>(pEventSource, this);
    }
}

See Also

Concepts

Publish Category Instances
Subscribe to Category Instances
Receive Subscribed Categories