3.4.5.2.4.12 IVdsService::Advise (Opnum 15)

  • Article

The Advise method registers a notification callback with the server. Clients pass the callback object to the server to receive notifications.

 HRESULT Advise(
   [in] IVdsAdviseSink* pSink,
   [out] DWORD* pdwCookie
 );

pSink: A pointer to an IVdsAdviseSink interface of the callback object to register with the server for notification of object changes.

pdwCookie: A pointer to a variable that, if the operation is successfully completed, receives a unique cookie value that the client can later use to unregister the callback object from receiving notification changes from the service. For information about how to register callback objects, see section 3.3.1.1.

Return Values: The method MUST return zero or a non-error HRESULT (as specified in [MS-ERREF]) to indicate success, or return an implementation-specific nonzero error code to indicate failure. For the HRESULT values predefined by the Virtual Disk Service Remote Protocol, see section 2.2.3.

When the server receives this message, it MUST validate the following parameters:

  • Verify that pSink is not NULL.

  • Verify that pdwCookie is not NULL.

The server MUST perform the following:

  • Point pdwCookie to a unique cookie value that is associated with the IVdsAdviseSink interface that pSink specifies.

  • Add the IVdsAdviseSink interface that pSink specifies to the list of callback objects.

  • Return an HRESULT indicating failure or success.