[This is preliminary documentation and subject to change.]
The IWbemContext interface communicates additional information to providers when submitting IWbemServices calls to CIMOM. All primary calls in IWbemServices take an optional parameter pointing to an object of this type.
In many cases, dynamic providers need more information than the information that is specified in the normal parameters of an IWbemServices method. For example, to manipulate any CIM schema objects it provides, a provider may need to know a Simple Network Management Protocol (SNMP) Community name, or an structured query language (SQL) database and table name. A client can add this information to an IWbemContext object, and send the IWbemContext object along with the call as one of the parameters.
Note It is very important that providers make as little use of this mechanism as possible. It is preferred they never require it. If a provider requires a large amount of highly specific context information to respond to a request, then all clients must be coded to provide this information, thus breaking the uniform access model that is the basis of WBEM. Nevertheless, in some cases it cannot be avoided. Therefore, this mechanism is provided to make it possible to access such providers.
An IWbemContext object, which is created using CoCreateInstance, is a simple container of named values. You can access these methods to fill in any context information required by a dynamic provider. After the call to one of the IWbemServices methods, the IWbemContext object can be reused for another call, or it can be deallocated using Release and another object created for other calls to IWbemServices methods
The information contained in an IWbemContext object is entirely determined by the underlying provider. CIMOM makes no use of the information, but simply forwards it to the provider. Providers must publish the context information they require for these service requests.
It is expected that the client application calls CoCreateInstance to create a single context object. Then, it calls SetValue one or more times to set up context values for the provider. Finally, it submits the object to one of the IWbemServices methods, which immediately calls Release on the context object after the call has returned. The other methods are for use primarily by providers that receive the context object and have to extract information.
| IUnknown Methods | Description |
|---|---|
| QueryInterface | Determines if the current object supports a given interface. |
| AddRef | Increases the object's reference count by 1. |
| Release | Decrements the object's reference count, and frees the object when the reference count is zero. |
| IWbemContext Methods | Description |
|---|---|
| Clone | Makes a complete copy of the current IWbemContext object. |
| GetNames | Retrieves the names of all of the context values available. |
| BeginEnumeration | Begins an enumeration of all context values in the IwbemContext object. |
| Next | Retrieves the next value in an enumeration of all context values beginning with BeginEnumeration. |
| EndEnumeration | Ends an enumeration begun with BeginEnumeration and Next. |
| SetValue | Sets a specific named context value. |
| GetValue | Retrieves the specified context value by name. |
| DeleteValue | Removes the specified context value. |
| DeleteAll | Removes all context values, making the IWbemContext object empty. |