IAudioEndpointVolume::RegisterControlChangeNotify

IAudioEndpointVolume::RegisterControlChangeNotify

The RegisterControlChangeNotify method registers a client's notification callback interface.

HRESULT RegisterControlChangeNotify(
  IAudioEndpointVolumeCallback  *pNotify
);

Parameters

pNotify

[in]  Pointer to the IAudioEndpointVolumeCallback interface that the client is registering for notification callbacks. If the RegisterControlChangeNotify method succeeds, it calls the AddRef method on the client's IAudioEndpointVolumeCallback interface.

Return Value

If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values shown in the following table.

Remarks

This method registers an IAudioEndpointVolumeCallback interface to be called by the system when the volume level or muting state of an endpoint changes. The caller implements the IAudioEndpointVolumeCallback interface.

When notifications are no longer needed, the client can call the IAudioEndpointVolume::UnregisterControlChangeNotify method to terminate the notifications.

Before the client releases its final reference to the IAudioEndpointVolumeCallback interface, it should call UnregisterControlChangeNotify to unregister the interface. Otherwise, the application leaks the resources held by the IAudioEndpointVolumeCallback and IAudioEndpointVolume objects. Note that RegisterControlChangeNotify calls the client's IAudioEndpointVolumeCallback::AddRef method, and UnregisterControlChangeNotify calls the IAudioEndpointVolumeCallback::Release method. If the client errs by releasing its reference to the IAudioEndpointVolumeCallback interface before calling UnregisterControlChangeNotify, the IAudioEndpointVolume object never releases its reference to the IAudioEndpointVolumeCallback interface. For example, a poorly designed IAudioEndpointVolumeCallback implementation might call UnregisterControlChangeNotify from the destructor for the IAudioEndpointVolumeCallback object. In this case, the client will not call UnregisterControlChangeNotify until the IAudioEndpointVolume object releases its reference to the IAudioEndpointVolumeCallback interface, and the IAudioEndpointVolume object will not release its reference to the IAudioEndpointVolumeCallback interface until the client calls UnregisterControlChangeNotify. For more information about the AddRef and Release methods, see the discussion of the IUnknown interface in the Windows SDK documentation.

In addition, the client should call UnregisterControlChangeNotify before releasing the final reference to the IAudioEndpointVolume object. Otherwise, the object leaks the storage that it allocated to hold the registration information. After registering a notification interface, the client continues to receive notifications for only as long as the IAudioEndpointVolume object exists.

For a code example that calls RegisterControlChangeNotify, see Endpoint Volume Controls.

Requirements

Client: Windows Vista

Header: Include Endpointvolume.h.

See Also

• IAudioEndpointVolume Interface
• IAudioEndpointVolume::UnregisterControlChangeNotify
• IAudioEndpointVolumeCallback Interface