IWMSContext Interface

Article
09/04/2009

Note

This interface is available only on Windows Server 2003, Enterprise Edition; Windows Server 2003, Datacenter Edition; and Windows Server 2008.

The IWMSContext interface provides methods for retrieving, adding, or updating a context. A context is a collection of name-value pairs or properties used by the server to store information. The server creates and maintains the contexts that are described in the following sections.

Section	Description
Archive Context	Contains information about the file used to archive a presentation.
Cache Content Information Context	Contains information about the content stored in a cache.
Command Context	Contains information about requests issued by the client to the server and the responses issued by the server to the client.
Content Description Context	Contains descriptive information about an item of content such as the name of the author and the genre.
Presentation Context	Contains information about the presentation sent to a client.
Server Context	Contains information about the server.
User Context	Contains information about the client

You use contexts when creating custom plug-ins. The server creates and populates the preceding contexts and passes pointers to them when it calls interfaces on your plug-in. However, you can also create temporary contexts inside of your plug-in or add temporary values to the existing contexts created by the server. The server, of course, cannot use these custom contexts and values, but your plug-in can use them to persist information.

The public context properties are identified in WmsContextNames.h. The file contains a macro, DEFINE_NAME_AND_HINT, that creates an internal table that associates the name of a property with an enumeration value and a key. When specifying or retrieving a public context property, it is recommended that you use the enumeration value and key. The key, called a hint in this document, enables you to access context properties more efficiently. The following example uses a pointer to the server context to retrieve a pointer to the IWMSServerIWMSServer Interface and demonstrates how to use the enumeration value, WMS_SERVER, and the hint, WMS_SERVER_ID. A hint always consists of the enumeration value followed by _ID.

if (NULL != pServerContext)
{
   hr = pServerContext->GetAndQueryIUnknownValue( 
                                              WMS_SERVER,
                                              WMS_SERVER_ID,
                                              IID_IWMSServer, 
                                              (IUnknown**)&pServerUnk, 
                                              0 );
    if (FAILED(hr)) goto EXIT;
}

EXIT:
    // TODO: Release temporary objects.

A plug-in can also add temporary properties to an existing context. The following example illustrates how to add a pointer to a user-defined object, CCacheEntry, to the presentation context. When you are adding a custom property to a context, it is recommended that you use the WMS_CONTEXT_NO_NAME_HINT value, defined in WMS_CONTEXT_HINT_CONSTANTS, to indicate that there is no hint associated with the specified name. Also, you must use the value, WMS_CONTEXT_SET_PROPERTY_NAME_BY_VALUE, defined in WMS_CONTEXT_OPTIONS, to indicate that you are not passing the name by reference.

if (NULL != pPresentationContext)
{
    hr = pPresentationContext->SetIUnknownValue( 
                                   L"CacheEntry", 
                                   WMS_CONTEXT_NO_NAME_HINT,
                                   pCacheEntry,
                                   WMS_CONTEXT_SET_PROPERTY_NAME_BY_VALUE
                                                );
    if (FAILED(hr)) goto EXIT;
}

EXIT:
    // TODO: Release temporary objects.

Finally, you can use the IWMSClassObjectIWMSClassObject Interface to create a custom context. The server sends your plug-in a pointer to an IWMSClassObject interface when it calls the IWMSBasicPlugin::InitializePlugin method. The following example illustrates how to use the pointer to create a content description context.

IWMSContext* pIContext = NULL;
if (NULL != pClassFactory)
{
    hr = pClassFactory->AllocIWMSContext( 
                             IID_IWMSContext,
                             WMS_CONTENT_DESCRIPTION_CONTEXT_TYPE,
                             NULL,
                             ( void ** ) &pIContext);

    if (FAILED(hr)) goto EXIT;
}

EXIT:
    // TODO: Release temporary objects.

In addition to the methods inherited from IUnknown, the IWMSContext interface exposes the following methods.

Method	Description
CopyValues	Copies the specified properties from one context to another.
GetAndQueryIUnknownValue	Retrieves an IUnknown pointer and calls QueryInterface to retrieve a pointer to the specified interface.
GetArrayValue	Retrieves a pointer to a SAFEARRAY of BSTR values.
GetContextType	Retrieves an enumeration value that indicates the context type.
GetDateValue	Retrieves a DATE value from the context.
GetIndexedValue	Retrieves a specific name-value pair from the context by index.
GetIUnknownValue	Retrieves an IUnknown value for the specified context.
GetLongValue	Retrieves a long value for the specified context.
GetQwordValue	Retrieves a QWORD value for the specified context.
GetStringValue	Retrieves a BSTR value for the specified context.
GetValue	Retrieves a VARIANT containing a value.
GetValueCount	Retrieves the number of values in the context.
RemoveAllValues	Removes all name-value pairs from a context.
RemoveValue	Removes a specific name-value from a context.
SetArrayValue	Specifies a pointer to a SAFEARRAY value.
SetDateValue	Specifies a DATE value for the context.
SetIUnknownValue	Specifies an IUnknown value for the context.
SetLongValue	Specifies a long value for the context.
SetQwordValue	Specifies a QWORD value for the context.
SetStringValue	Specifies a String value for the context.
SetValue	Specifies a context value.

Share via

IWMSContext Interface

See Also

Concepts

Additional resources