IWMSContext Interface

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.

See Also

Concepts

Contexts

Custom Plug-in Interfaces (C++)