IUccSubscriptionManager.CreateSubscription Method

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.

Creates a subscription to category context published by specified presentities.

Namespace: Microsoft.Office.Interop.UccApi
Assembly: Microsoft.Office.Interop.UccApi (in microsoft.office.interop.uccapi.dll)

Syntax

'Declaration
Function CreateSubscription ( _
    pContext As UccContext _
) As UccSubscription

UccSubscription CreateSubscription (
    UccContext pContext
)

UccSubscription^ CreateSubscription (
    UccContext^ pContext
)

UccSubscription CreateSubscription (
    UccContext pContext
)

function CreateSubscription (
    pContext : UccContext
) : UccSubscription

Parameters

• pContext
  A value of the IUccContext* (UccContext, for a .NET application) type. This specifies the application-specific context for the to-be-created subscription.

Return Value

A value of the IUccSubscription** (IUccSubscription, for a .NET application) type. This returns an empty subscription to which the subscriber must add the names of the desired categories and their publishers.

Remarks

Each endpoint can have multiple subscriptions in which the subscriber receives notifications of the updates of the subscribed category instances by specified publishers. To allow a client to receive category instances published by other users, an application must create at least three subscriptions for the local user endpoint. Two are for subscribing to category instances self-published by the local user: One for the "categories" and "containers" category instances and the other for the local user's own contact list. Using the received contact list category instances, the application can create additional subscriptions to receive interested category instances published by other users.

Win32 COM/C++ Syntax

HRESULT CreateSubscription
(
   IUccContext* pContext,
   IUccSubscription** ppSubscription
);

Example

The following example drawn from an application class designed to handle subscription related functionality. The example method accepts the IUccSubscriptionManager interface of an endpoint instance, a context property name string, a context value string, and the class instance which implements subscription events as the event sink for the created subscription.

This example enforces a good development practice of creating application context for the subscription as well as advising for subscription events.

For information about assigning categories and presentities to the created subscription, see IUccSubscription

/// <summary>
/// creates a new subscription object with associated
/// metadata context
/// </summary>
/// <param name="pSubScriptionManager">endpoint as subscription manager</param>
/// <param name="pSubContextPropertyName">context property name</param>
/// <param name="pSubContext">context value</param>
/// <param name="pEventSink">Class instance implementing event handler for subscription events</param>
/// <returns>new IUccSubscription with context</returns>
private UccSubscription MakeSubscription(
    IUccSubscriptionManager pSubScriptionManager,
    string pSubContextPropertyName,
    string pSubContext,
    _IUccSubscriptionEvents pEventSink)
{
    UccSubscription returnValue = null;
    if (pSubScriptionManager == null)
    {
        throw new ArgumentNullException(
            "pSubscriptionManager", 
            "Subscription mananger cannot be null");
    }
    if (pEventSink == null)
    {
        throw new ArgumentNullException(
            "pEventSink", 
            "Event Sink cannot be null");
    }
    try
    {
        UccContext subContext = new UccContextClass();
        if (pSubContextPropertyName.Length > 0 && pSubContext.Length > 0)
        {
            subContext.AddNamedProperty(
                pSubContextPropertyName, 
                pSubContext);
        }
        returnValue = pSubScriptionManager.CreateSubscription(subContext);
        UCC_Advise<_IUccSubscriptionEvents>(
            returnValue, 
            pEventSink);
    }
    catch (COMException)
    {}
    return returnValue;
}

Thread Safety

All public static (Shared in Visual Basic) members of this type are thread-safe. Instance members are not guaranteed to be thread-safe.

Platforms

Development Platforms

Windows XP Professional with Service Pack 2 (SP2), Windows Server 2000 with Service Pack 4, Windows Server 2003, Windows Vista Ultimate Edition, Windows Vista Business Edition, Windows Vista Enterprise Edition

Target Platforms

See Also

Reference

IUccSubscriptionManager Interface
IUccSubscriptionManager Members
Microsoft.Office.Interop.UccApi Namespace

Other Resources

Code Listing: Basic Event Registration and Other Helper Methods in C#