IWMSContext Interface
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 |