PcRegisterPhysicalConnection function (portcls.h)

Article
10/21/2021

The PcRegisterPhysicalConnection function registers a physical connection between two audio adapter filters that are instantiated by the same adapter driver.

Syntax

PORTCLASSAPI NTSTATUS PcRegisterPhysicalConnection(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PUNKNOWN       FromUnknown,
  [in] ULONG          FromPin,
  [in] PUNKNOWN       ToUnknown,
  [in] ULONG          ToPin
);

Parameters

[in] DeviceObject

Pointer to the device object for the adapter device. This parameter must point to a system structure of type DEVICE_OBJECT.

[in] FromUnknown

Pointer to the IPort interface of a port driver object. The port driver object that is associated with FromUnknown is bound to the subdevice that supplies the connection's data source (output) pin.

[in] FromPin

Specifies a pin ID. This parameter identifies the source (output) pin on the filter that is associated with the FromUnknown interface.

[in] ToUnknown

Pointer to the IPort interface of a port driver object. The port driver object that is associated with ToUnknown is bound to the subdevice that supplies the connection's data sink (input) pin.

[in] ToPin

Specifies a pin ID. This parameter identifies the sink (input) pin on the filter that is associated with the ToUnknown interface.

Return value

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

Remarks

An adapter driver calls PcRegisterPhysicalConnection to register a physical connection with the PortCls system driver. PortCls stores this information so that the port driver can subsequently use the information to respond to KSPROPERTY_PIN_PHYSICALCONNECTION property requests.

The parameters that the caller provides to the PcRegisterPhysicalConnection function describe a physical connection between two subdevices (represented as individual filters) on the same adapter card.

Unlike a logical connection between two pins, which can be configured under software control, a physical connection is hardwired. For example, a typical adapter card might have a physical connection that carries the analog signal from the output pin of its wave-output filter to the input pin of its topology filter.

For an example of an adapter driver's device-startup routine (see Startup Sequence) that uses the PcRegisterPhysicalConnection call to register an adapter's physical connections, see the source code for the SB16 sample audio driver in the Microsoft Windows Driver Kit (WDK).

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

Requirements

Requirement	Value
Minimum supported client	The PortCls system driver implements the PcRegisterPhysicalConnection 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

Share via