The IWbemContext interface communicates additional information to providers when submitting IWbemServices_hmm_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. Developers of such providers should provide adequate documentation so that developers of client software can succesfully manipulate such CIM objects.
An IWbemContext object, which is created using CoCreateInstanceEx, 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 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.
Methods in Vtable Order
| IUnknown Methods | Description |
| QueryInterface_hmm_IWbemContext_QueryInterface | Determines if the current object supports a given interface. |
| AddRef_hmm_IWbemContext_AddRef | Increases the object's reference count by 1. |
| Release_hmm_IWbemContext_Release | Decrements the object's reference count, and frees the object when the reference count is zero. |
| IWbemContext Methods | Description |
| Clone_hmm_IwbemContext_Clone | Makes a complete copy of the current IWbemContext object. |
| GetNames_hmm_IwbemContext_GetNames | Retrieves the names of all of the context values available. |
| BeginEnumeration_hmm_IwbemContext_BeginEnumeration | Begins an enumeration of all context values in the IwbemContext object. |
| Next_hmm_IwbemContext_Next | Retrieves the next value in an enumeration of all context values beginning with BeginEnumeration. |
| EndEnumeration_hmm_IWbemContext_EndEnumeration | Ends an enumeration begun with BeginEnumeration and Next. |
| SetValue_hmm_IWbemContext_SetValue | Sets a specific named context value. |
| GetValue_hmm_IWbemContext_GetValue | Retrieves the specified context value by name. |
| DeleteValue_hmm_IwbemContext_DeleteValue | Removes the specified context value. |
| DeleteAll_hmm_IwbemContext_DeleteAll | Removes all context values, making the IWbemContext object empty. |
‹^# $ K + ›IWbemContext::QueryInterface¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemContext::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.
HRESULT IWbemContext::QueryInterface(
[in] REFIID riid,
[out] LPVOID *ppv
);
Parameters
riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that will be filled with the interface pointer if the query succeeds.
Return Values
Returns standard COM error codes for QueryInterface. It returns WBEM_S_NO_ERROR if the call succeeds. If the call fails because the requested interface was not supported, the method returns E_NOINTERFACE.
Remarks
When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each object's existing or future functionality.
This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.
See Also
IUnknown Interface Basics_hmm_iunknown_interface_basics
‹^# $ K + ›IWbemContext::AddRef¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemContext::AddRef method increases the object's reference count by 1.
ULONG AddRef( );
Parameters
None.
Return Values
Returns the new reference count.
Remarks
When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the Release method to decrease the object's reference count by 1.
This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see IUnknown Programming Basics Interface.
For more information about this method, see the COM documentation in the Microsoft Platform SDK.
See Also
IUnknown Interface Basics_hmm_iunknown_Interface_basics
‹^# $ K + ›IWbemContext::Release¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemContext::Release method decreases the object's reference count by 1.
ULONG Release( );
Parameters
None.
Return Values
Returns the new reference count.
Remarks
The object deallocates itself when its reference count reaches zero. Use the AddRef_hmm_IWbemContext_AddRef method to increase the object's reference count by 1.
This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.
See Also
IUnknown Interface Basics_hmm_iunknown_interface_basics
‹^# $ K + ›IWbemContext::Clone¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
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.
HRESULT Clone(
[out] IWbemContext **ppNewCopy
);
Parameters
ppNewCopy
Must point to NULL on entry. It receives a pointer to the new object containing the clone of the current object. The returned pointer has a positive reference count. The caller must call Release_hmm_IWbemServices_Release on this pointer when it is no longer needed. On error, this pointer is left unmodified, and a new object is not returned.
Return Values
| WBEM_E_FAILED | There has been a general failure. |
| WBEM_E_INVALID_PARAMETER | NULL was specified as a parameter, which is not legal. |
| WBEM_E_OUT_OF_MEMORY | There is not enough memory to clone the object. |
| WBEM_S_NO_ERROR | The call succeeded. |
‹^# $ K + ›IWbemContext::GetNames¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemContext::GetNames method returns a SAFEARRAY of all of the names of the named context values. After all the names are known, GetValue_hmm_IWbemContext_GetValue can be called on each name to retrieve the value. This technique is a way of accessing the context values that is different from calling the BeginEnumeration, Next, and EndEnumeration methods.
HRESULT GetNames(
[in] LONG lFlags,
[out] SAFEARRAY (BSTR) *pNames
);
Parameters
lFlags
Reserved. It must be zero.
pNames
This parameter cannot be NULL, but on entry it must point to NULL. If no error is returned, on exit pstrNames receives a pointer to a new SAFEARRAY of type VT_BSTR containing all the context value names. The caller must call SafeArrayDestroy on the returned pointer when the array is no longer required. If an error code is returned, the pointer is left unmodified.
Note
If there are no named values in the object, the call succeeds and returns an array of length zero.
Return Values
| WBEM_E_INVALID_PARAMETER | An invalid parameter was specified. |
| WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation. |
| WBEM_S_NO_ERROR | The call succeeded. |
See Also
IWbemContext::GetValue_hmm_IWbemContext_GetValue, IWbemContext::BeginEnumeration_hmm_IWbemContext_BeginEnumeration
‹^# $ K + ›IWbemContext::BeginEnumeration¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemContext::BeginEnumeration method resets the enumeration of all the context values in the object. This method must be called before the first call to IWbemContext::Next_hmm_IWbemContext_Next to enumerate all of the context values in the object.
HRESULT BeginEnumeration(
[in] LONG lFlags
);
Parameters
lFlags
Reserved. It must be zero.
Return Values
| WBEM_E_INVALID_PARAMETER | The lFlags parameter was not valid. |
| WBEM_S_NO_ERROR | The call succeeded. |
| WBEM_E_OUT_OF_MEMORY | There was not enough memory to begin an enumeration. |
| WBEM_E_FAILED | There has been a general failure. |
See Also
IWbemContext::Next_hmm_IWbemContext_Next, IWbemContext::EndEnumeration_hmm_IWbemContext_EndEnumeration
‹^# $ K + ›IWbemContext::Next¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemContext::Next method retrieves the next value in an enumeration of all context values beginning with BeginEnumeration.
HRESULT Next(
[in] LONG lFlags,
[out] BSTR *pstrName,
[out] VARIANT *pValue
);
Parameters
lFlags
Reserved. It must be zero.
pstrName
This parameter cannot be NULL. The pointer must not point to an active BSTR on entry, and ideally it should be set to point to NULL. If no error code is returned, it is set to point to a newly allocated BSTR containing the context value name.
The caller must call SysFreeString on the returned string when it is no longer required. If WBEM_S_NO_MORE_DATA returns, pstrName is set to point to NULL, in which case SysFreeString should not be called.
Note
If pstrName points to a valid BSTR on entry, this BSTR is not freed, and a memory leak occurs.
pValue
This parameter cannot be NULL, and it must point to an empty or uninitialized VARIANT. If no error is returned, the VARIANT is initialized using VariantInit, and then set to contain the context value. The caller must call VariantClear on this pointer when the value is no longer required. If an error code is returned, the VARIANT pointed to by pValue is left unmodified.
If WBEM_S_NO_MORE_DATA returns, this parameter is set to point to a VARIANT of type VT_NULL.
It is possible that an entire IWbemClassObject may be returned inside the VARIANT. If that is the case, then VT_UNKNOWN is the VARIANT type. The caller can take the IUnknown pointer and execute QueryInterface to obtain the IWbemClassObject pointer.
Note
At the end of the enumeration, WBEM_S_NO_MORE_DATA returns. The returned VARIANT is of type VT_NULL, and the returned pstrName is NULL.
Return Values
| WBEM_E_INVALID_PARAMETER | An invalid parameter was specified. |
| WBEM_E_UNEXPECTED | Caller did not call IWbemContext::BeginEnumeration_hmm_IWbemContext_BeginEnumeration. |
| WBEM_S_NO_ERROR | The call succeeded. |
| WBEM_S_NO_MORE_DATA | No more properties are left in the enumeration. |
| WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the call. |
See Also
IWbemContext::BeginEnumeration_hmm_IWbemContext_BeginEnumeration, IWbemContext::EndEnumeration_hmm_IWbemContext_EndEnumeration
‹^# $ K + ›IWbemContext::EndEnumeration¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemContext::EndEnumeration method ends an enumeration sequence that begins with IWbemContext::BeginEnumeration_hmm_IWbemContext_BeginEnumeration. This call is not required, but it releases as early as possible any system resources associated with the enumeration.
HRESULT EndEnumeration( );
Parameters
None.
Return Values
| WBEM_S_NO_ERROR | The call succeeded. |
| WBEM_E_UNEXPECTED | This call was made without a corresponding call to IwbemContext::BeginEnumeration. |
See Also
IWbemContext::BeginEnumeration_hmm_IWbemContext_BeginEnumeration, IWbemContext::Next_hmm_IWbemContext_Next
‹^# $ K + ›IWbemContext::SetValue¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemContext::SetValue method creates or overwrites a named context value.
HRESULT SetValue(
[in] BSTR strName,
[in] LONG lFlags,
[in] VARIANT *pValue
);
Parameters
strName
Cannot be NULL. It is a read-only pointer to a valid BSTR indicating the context value name.
lFlags
Reserved. It must be zero.
pValue
Must point to a valid VARIANT, which is treated as read-only. The value in the VARIANT becomes the named context value. An entire IWbemClassObject_hmm_IWbemClassObject can be stored as well as a simple value by enclosing it in a VARIANT using the VT_UNKNOWN type. The caller must execute QueryInterface_hmm_IWbemClassObject_QueryInterface on the IWbemClassObject, asking for IID_IUnknown, and use the returned pointer in the VARIANT.
‹^# $ K + ›IWbemContext::GetValue¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemContext::GetValue method is used to retrieve a specific named context value by name.
HRESULT GetValue(
[in] BSTR strName,
[in] LONG lFlags,
[out] VARIANT *pValue
);
Parameters
strName
The name for which the value is to be retrieved. This must point to a valid BSTR. The pointer is treated as read-only.
lFlags
Reserved. It must be zero.
pValue
This parameter cannot be NULL and must point to an uninitialized VARIANT. If no error is returned, the VARIANT is initialized using VariantInit, and then set to contain the context value. The caller must call VariantClear on this pointer when the value is no longer required. If an error code is returned, the VARIANT pointed to by pValue is left unmodified.
It is possible that an entire IWbemClassObject_hmm_IWbemClassObject can be returned inside the VARIANT. If that is the case, then VT_UNKNOWN is the VARIANT type. The caller can take the IUnknown pointer and execute QueryInterface to obtain the IWbemClassObject pointer.
Return Values
| WBEM_E_NOT_FOUND | The requested value was not found. |
| WBEM_E_INVALID_PARAMETER | An invalid parameter was specified. |
| WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation. |
| WBEM_S_NO_ERROR | The call succeeded. |
See Also
IWbemContext::SetValue_hmm_IWbemContext_SetValue
‹^# $ K + ›IWbemContext::DeleteValue¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemContext::DeleteValue method deletes a named context value created by IWbemContext::SetValue.
HRESULT DeleteValue(
[in] BSTR strName,
[in] LONG lFlags
);
Parameters
strName
A pointer to a valid BSTR containing the named context value to delete. The pointer is treated as read-only.
lFlags
Reserved. It must be zero.
Return Values
| WBEM_E_FAILED | There has been a general failure. |
| WBEM_E_INVALID_PARAMETER | An invalid Name or lFlags value was specified. |
| WBEM_E_NOT_FOUND | The specified named context value does not exist. |
| WBEM_S_NO_ERROR | The call succeeded. |
See Also
IWbemContext::SetValue_hmm_IWbemContext_SetValue, IWbemContext::GetValue_hmm_IWbemContext_GetValue
‹^# $ K + ›IWbemContext::DeleteAll¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemContext::DeleteAll method removes all named context values from the current object, thus emptying the object.
HRESULT DeleteAll( );
Parameters
None.
Return Values
| WBEM_E_FAILED | There has been a general failure. |
| WBEM_S_NO_ERROR | The call succeeded. |
See Also
IWbemContext::DeleteValue_hmm_IWbemContext_DeleteValue