IWMSContext Interface

banner art

Previous Next

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 IWMSServer 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 IWMSClassObject 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.

  WMS_CONTENT_DESCRIPTION_CONTEXT_TYPE



    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

Previous Next
  • Last updated on