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.