PcRegisterSubdevice function (portcls.h)

Article
10/21/2021

The PcRegisterSubdevice function registers a subdevice to make it available for use by clients.

Syntax

PORTCLASSAPI NTSTATUS PcRegisterSubdevice(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PWSTR          Name,
  [in] PUNKNOWN       Unknown
);

Parameters

[in] DeviceObject

Pointer to the adapter driver's device object. This is a system structure of type DEVICE_OBJECT.

[in] Name

Pointer to a null-terminated Unicode string that specifies the name of the subdevice. The string buffer that the Name parameter points to must remain valid for the lifetime of the device object. The string contains a short name that distinguishes the subdevice from any other subdevices registered on the same device. Each of the device's subdevices must have a unique name.

[in] Unknown

Pointer to the IPort interface of the port driver object that is bound to the subdevice.

Return value

PcRegisterSubdevice returns STATUS_SUCCESS if the call was successful. Otherwise, it returns an appropriate error code.

Remarks

The function registers the device interface instance for a filter object that represents a subdevice on an audio adapter. The I/O manager appends the string specified by the Name parameter to the reference string that it uses to identify the instance. The modified reference string is useful for distinguishing among the subdevices in the audio adapter. For more information about reference strings, see IoRegisterDeviceInterface.

For more information about the role of the PcRegisterSubdevice function in registering a subdevice, see Subdevice Creation.

An adapter driver can call the IUnregisterSubdevice::UnregisterSubdevice method to delete the registration of a physical connection that was registered by a previous call to PcRegisterSubdevice. For more information, see Dynamic Audio Subdevices.

Requirements

Requirement	Value
Minimum supported client	The PortCls system driver implements the PcRegisterSubdevice function in Microsoft Windows 98/Me and in Windows 2000 and later operating systems.
Target Platform	Universal
Header	portcls.h (include Portcls.h)
Library	Portcls.lib
IRQL	PASSIVE_LEVEL