IWbemContext interface (wbemcli.h)

The IWbemContext interface is optionally used to communicate additional context information to providers when submitting IWbemServices calls to WMI. All primary calls in IWbemServices take an optional parameter pointing to an object of this type.

Inheritance

The IWbemContext interface inherits from the IUnknown interface. IWbemContext also has these types of members:

Methods

The IWbemContext interface has these methods.

IWbemContext::BeginEnumeration The IWbemContext::BeginEnumeration method resets the enumeration of all the context values in the object.
IWbemContext::Clone The IWbemContext::Clone method makes a logical copy of the current IWbemContext object. This method can be useful when many calls must be made which have largely identical IWbemContext objects.
IWbemContext::DeleteAll The IWbemContext::DeleteAll method removes all named context values from the current object, thus emptying the object.
IWbemContext::DeleteValue The IWbemContext::DeleteValue method deletes a named context value created by IWbemContext::SetValue.
IWbemContext::EndEnumeration The IWbemContext::EndEnumeration method ends an enumeration sequence that begins with IWbemContext::BeginEnumeration. This call is not required, but it releases as early as possible any system resources associated with the enumeration.
IWbemContext::GetNames The IWbemContext::GetNames method returns a SAFEARRAY structure of all of the names of the named context values.
IWbemContext::GetValue The IWbemContext::GetValue method is used to retrieve a specific named context value by name.
IWbemContext::Next The IWbemContext::Next method retrieves the next value in an enumeration of all context values beginning with IWbemContext::BeginEnumeration.
IWbemContext::SetValue The IWbemContext::SetValue method creates or overwrites a named context value.

Remarks

Often, dynamic providers require more information than is specified in the normal parameters of an IWbemServices method. For example, to manipulate any WMI schema objects that it provides, a provider may need to know a Simple Network Management Protocol (SNMP) community name, or a 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.

Providers should use content objects sparingly. It is recommended that it is never required. 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 WMI. Nevertheless, in some cases it cannot be avoided. Therefore, this mechanism is provided to make it possible to access such providers. Developers of such providers should provide adequate documentation so that developers of client software can successfully manipulate such CIM objects.

Providers that support the use of IWbemContext to allow clients to specify more information in a request should restrict the types of values they support to the types in the following list:

• VT_I4
• VT_R8
• VT_BOOL
• VT_BSTR
• VT_UNKNOWN
• Any of the above combined with VT_ARRAY

Note  Only objects that support IWbemClassObject can marshal their IUnknown methods in an IWbemContext instance using a variant of type VT_UNKNOWN.

 

An IWbemContext object, which is created using CoCreateInstanceEx, is a simple container of named values. Access these methods to fill in 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. WMI does not use the information, but forwards it to the provider. Providers must publish the context information they require for these service requests.

The client application calls CoCreateInstanceEx 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.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	wbemcli.h (include Wbemidl.h)

See also

COM API for WMI

Creating and Declaring an Instance Using C++

Making Calls to WMI

Requesting WMI Data on a 64-bit Platform

Retrieving Part of a WMI Instance