Interface IWbemObjectSink
The IWbemObjectSink interface is a sink interface used for all types of notifications within the CIMOM programming model. Clients must implement this interface to receive both the results of the asynchronous methods
_hmm_making_an_asynchronous_call of IWbemServices and certain types of event notifications. Providers use, but do not implement, this interface to provide events and objects to CIMOM.Typically, providers call an implementation provided to them by CIMOM. In these cases, you call Indicate to provide objects to COMOM. After that, call SetStatus to indicate the end of the notification sequence. You can also call SetStatus to indicate errors when the sink does not have any objects.
When programming asynchronous clients of CIMOM, the user provides the implementation. CIMOM calls the methods to deliver objects and set the status of the result.
Methods in Vtable Order
| IUnknown Methods | Description |
| QueryInterface_hmm_IWbemObjectSink_QueryInterface | Determines if the current object supports a given interface. |
| AddRef_hmm_IwbemObjectSink_AddRef | Increases the object's reference count by 1. |
| Release_hmm_IwbemObjectSink_Release | Decrements the object's reference count, and frees the object when the reference count is zero. |
| IWbemObjectSink Methods | Description |
| Indicate_hmm_IwbemObjectSink_Indicate | Receives notification objects. |
| SetStatus_hmm_IwbemObjectSink_SetStatus | Receives notification status. |
Sample Code
The following is a simple implementation of an object sink. This sample could be used in conjunction with IWbemServices::ExecQueryAsync or IWbemServices::CreateInstanceEnumAsync to receive the returned instances:
class QuerySink : public IWbemObjectSink
{
LONG m_lRef;
Bool bDone;
public:
QuerySink() { m_lRef = 0; }
~QuerySink() { bDone = TRUE; }
virtual ULONG STDMETHODCALLTYPE AddRef();
virtual ULONG STDMETHODCALLTYPE Release();
virtual HRESULT STDMETHODCALLTYPE QueryInterface(REFIID riid, void** ppv);
virtual HRESULT STDMETHODCALLTYPE Indicate(
/* [in] */ LONG lObjectCount,
/* [size_is][in] */ IWbemClassObject __RPC_FAR *__RPC_FAR *apObjArray
);
virtual HRESULT STDMETHODCALLTYPE SetStatus(
/* [in] */ LONG lFlags,
/* [in] */ HRESULT hResult,
/* [in] */ BSTR strParam,
/* [in] */ IWbemClassObject __RPC_FAR *pObjParam
);
};
ULONG QuerySink::AddRef()
{
return InterlockedIncrement(&m_lRef);
}
ULONG QuerySink::Release()
{
LONG lRef = InterlockedDecrement(&m_lRef);
if(lRef == 0)
delete this;
return lRef;
}
HRESULT QuerySink::QueryInterface(REFIID riid, void** ppv)
{
if (riid == IID_IUnknown || riid == IID_IWbemObjectSink)
{
*ppv = (IWbemObjectSink *) this;
AddRef();
return WBEM_S_NO_ERROR;
else return E_NOINTERFACE;
}
HRESULT QuerySink::Indicate(long lObjCount, IWbemClassObject **pArray)
{
for (long i = 0; i < lObjCount)
{
IWbemClassObject *pObj = pArray[i];
// ... use the object
// AddRef() only required if the object will be held after
// the return to the caller.
i++;
}
return WBEM_S_NO_ERROR;
}
HRESULT QuerySink::SetStatus(
/* [in] */ LONG lFlags,
/* [in] */ HRESULT hResult,
/* [in] */ BSTR strParam,
/* [in] */ IWbemClassObject __RPC_FAR *pObjParam
)
{
printf("QuerySink::SetStatus hResult = 0x%X\n", hResult);
return WBEM_S_NO_ERROR;
}
‹^# $ K + ›IWbemObjectSink::QueryInterface¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemObjectSink::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 IWbemObjectSink::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 + ›IWbemObjectSink::AddRef¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemObjectSink::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.
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 + ›IWbemObjectSink::Release¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemObjectSink::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_IWbemObjectSink_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 + ›IWbemObjectSink::Indicate¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemObjectSink::Indicate method is called by a source to provide a notification. Typically, CIMOM calls the client's implementation of this interface after the client executes one of the asynchronous methods of IWbemServices. In other cases, various types of providers call an implementation exported by CIMOM in order to deliver events. Therefore, client code may have to implement this interface in some cases, and use a different component's implementation in other cases.
Use this interface and method in conjunction with the asynchronous methods of the IWbemServices interface.
Clients and providers must implement this interface to receive notifications or to execute the asynchronous methods of IWbemServices_hmm_making_an_asynchronous_call.
HRESULT IWbemObjectSink::Indicate(
[in] LONG lObjectCount,
[in, size_is(lObjectCount)] IWbemClassObject **ppObjArray
);
Parameters
lObjectCount
The number of objects in the following array of pointers.
ppObjArray
An array of pointers to IWbemClassObject_hmm_IWbemClassObject interfaces. The array memory itself is read-only, and is owned by the caller of the method. Since this is an in-parameter, the implementation has the option of calling IWbemClassObject::AddRef_hmm_IWbemClassObject_AddRef on any object pointer in the array and holding it before returning if the objects will be used after the method has returned, in accordance with COM rules. If the objects will only be used for the duration of the Indicate call, then you do not need to call AddRef on each object pointer. For more information on the IUnknown Interface see IUnknown Interface Basics_hmm_IUnknown_Interface_Basics.
.
Return Values
| WBEM_E_FAILED | The receiver was not able to process the notification properly. |
| WBEM_E_INVALID_PARAMETER | An invalid parameter was specified, such as a NULL ppObjArray pointer. |
| WBEM_S_NO_ERROR | The call succeeded; the receiver acknowledges the notification. |
| WBEM_E_UNKNOWN_OBJECT_TYPE | Marshaling received an invalid object type. |
| WBEM_E_UNKNOWN_PACKET_TYPE | Marshaling received an invalid packet type. |
| WBEM_E_MARSHAL_VERSION_MISMATCH | Marshaling version mismatch error. |
| WBEM_E_MARSHAL_INVALID_SIGNATURE | Packet received by marshaling had an invalid (unrecognized) signature. |
‹^# $ K + ›IWbemObjectSink::SetStatus¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemObjectSink::SetStatus method is called by sources either to indicate the end of a notification sequence or to send other status codes to the sink. IWbemObjectSink::Indicate_hmm_IWbemObjectSink_Indicate may or may not have been called before the call to SetStatus.
Normally, a client implements the IWbemObjectSink interface, and executes IWbemServices methods that return their results using the IWbemObjectSink interface. During this operation, CIMOM calls Indicate as many times as required, followed by a final call to SetStatus, and in many cases, Release.
HRESULT IWbemObjectSink::SetStatus(
[in] LONG lFlags,
[in] HRESULT hResult,
[in] BSTR strParam,
[in] IWbemClassObject *pObjParam
);
Parameters
lFlags
The lFlags parameter is a bitmask of status information. WBEM_STATUS_COMPLETE indicates the operation has completed.
WBEM_STATUS_PROGRESS indicates the operation is still in progress. The status of the operation can be obtained by examining the hResult parameter.
hResult
This parameter is set to the HRESULT of the asynchronous operation or notification. This will be either an error code, if an error occurred, or the amount of progress that has been made on an asynchronous call. Only callers that requested status reports by specifying WBEM_SEND_STATUS as a lFlags parameter will receive status updates. The exact status can be determined by examining the HIWORD and LOWORD of the hResult separately. The LOWORD(hResult) contains the amount of progress that has been made so far and the HIWORD(hResult) contains the total..
strParam
Receives a pointer to a read-only BSTR, if the original asynchronous operation returns a string. For example, when using PutInstanceAsync, IWbemObjectSink::SetStatus is called with this parameter set to the object path of the newly created instance.
pObjParam
In cases where a complex error or status object is returned, this contains a pointer to the error object. If the object is required after SetStatus returns, the called object must use the AddRef method on the pointer before the called object returns.
Return Values
| WBEM_E_FAILED | The receiver was not able to process the notification properly. |
| WBEM_E_INVALID_PARAMETER | An invalid parameter was specified. |
| WBEM_S_NO_ERROR | The call succeeded; the receiver acknowledges the notification. |