3.16.4.5.3 Advise (Opnum 5)
The Advise method is received by the server in an RPC_REQUEST packet. In response, the server MUST register a client's callback object to receive event notifications.
-
HRESULT Advise( [in] IUnknown* pUnkSink, [out] DWORD* pdwCookie );
pUnkSink: A pointer to an IUnknown (as specified in [MS-DCOM] section 3.1.1.5.8) interface for the client object.
pdwCookie: A pointer to a unique DWORD value that uniquely identifies the new element in the ConnectionCollection instance variable.
Return Values: The method MUST return S_OK (0x00000000) on success or an implementation-specific error HRESULT on failure.<94>
When processing this call, the server MUST follow these guidelines:
If the pUnkSink input parameter equals NULL:
Return E_POINTER (0x80000005), and take no further action.
If the pdwCookie output parameter equals NULL:
Return E_POINTER (0x80000005), and take no further action.
If the number of elements in the ConnectionCollection instance variable is equal to the ConnectionLimit instance variable:
Return CONNECT_E_ADVISELIMIT (0x80040201), and take no further action.
Attempt to obtain a pointer to the _DMSMQEventEvents interface by calling IUnknown::QueryInterface (refer to section 3.1) on the pUnkSink input parameter.
If the IUnknown::QueryInterface method returns an error:
Set the pdwCookie value to zero (0x00000000).
Return CONNECT_E_CANNOTCONNECT (0x80040202), and take no further action.
Set the value of the pdwCookie pointer output parameter to a DWORD "cookie" that is a unique key within the ConnectionCollection instance variable.
Add a new item to the ConnectionCollection instance variable, using the value of the pdwCookie as the ConnectionCookie and the interface pointer acquired earlier as the associated value.