IPart::RegisterControlChangeCallback method (devicetopology.h)

Article
10/13/2021

The RegisterControlChangeCallback method registers the IControlChangeNotify interface, which the client implements to receive notifications of status changes in this part.

Syntax

HRESULT RegisterControlChangeCallback(
  [in] REFGUID              riid,
  [in] IControlChangeNotify *pNotify
);

Parameters

[in] riid

The function-specific control interface that is to be monitored for control changes. For more information, see Remarks.

[in] pNotify

Pointer to the client's IControlChangeNotify interface. If the method succeeds, it calls the AddRef method on the client's IControlChangeNotify 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.

Return code	Description
E_INVALIDARG	Parameter riid is not a valid control-interface identifier.
E_POINTER	Pointer pNotify is NULL.

Remarks

Set parameter riid to one of the following GUID values:

IID_IAudioAutoGainControl
IID_IAudioBass
IID_IAudioChannelConfig
IID_IAudioInputSelector
IID_IAudioLoudness
IID_IAudioMidrange
IID_IAudioMute
IID_IAudioOutputSelector
IID_IAudioPeakMeter
IID_IAudioTreble
IID_IAudioVolumeLevel
IID_IDeviceSpecificProperty
IID_IKsFormatSupport
IID_IKsJackDescription

To obtain the interface ID of the function-specific control interface for a part, call the part's IControlInterface::GetIID method. To obtain the interface ID of a function-specific control interface type, use the __uuidof operator. For example, the interface ID of IAudioAutoGainControl is defined as follows:


const IID IID_IAudioAutoGainControl  __uuidof(IAudioAutoGainControl)

For more information about the __uuidof operator, see the Windows SDK documentation.

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

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	devicetopology.h