PcRegisterPhysicalConnection

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

PORTCLASSAPI NTSTATUS NTAPI
  PcRegisterPhysicalConnection(
    IN PDEVICE_OBJECT  DeviceObject,
    IN PUNKNOWN  FromUnknown,
    IN ULONG  FromPin,
    IN PUNKNOWN  ToUnknown,
    IN ULONG  ToPin
    );

Parameters

DeviceObject

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

FromUnknown

Pointer to the COM interface of a port object (see Introduction to Port Class). The port object that is associated with FromUnknown is bound to the subdevice (see Subdevice Creation) that supplies the connection's source pin.

FromPin

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

ToUnknown

Pointer to the COM interface of a port object. The port object that is associated with ToUnknown is bound to the subdevice that supplies the connection's sink pin.

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.

Headers

Declared in portcls.h. Include portcls.h.

Comments

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 a KSPROPERTY_PIN_PHYSICALCONNECTION property request.

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 Windows DDK.

See Also

PcRegisterPhysicalConnectionFromExternal, PcRegisterPhysicalConnectionToExternal, DEVICE_OBJECT, KSPROPERTY_PIN_PHYSICALCONNECTION