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
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
Creating and Declaring an Instance Using C++