PcRegisterPhysicalConnectionFromExternal function (portcls.h)

The PcRegisterPhysicalConnectionFromExternal function registers a physical connection to an audio adapter filter from an external audio adapter filter.

Syntax

PORTCLASSAPI NTSTATUS PcRegisterPhysicalConnectionFromExternal(
  [in] PDEVICE_OBJECT  DeviceObject,
  [in] PUNICODE_STRING FromString,
  [in] ULONG           FromPin,
  [in] PUNKNOWN        ToUnknown,
  [in] ULONG           ToPin
);

Parameters

[in] DeviceObject

Pointer to the device object for the device. This is a system structure of type DEVICE_OBJECT.

[in] FromString

Pointer to a null-terminated Unicode string containing the symbolic link name of the external filter that supplies the connection's source pin.

[in] FromPin

Specifies a pin ID. This parameter identifies the source (output) pin on the external filter named by FromString.

[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

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

Remarks

An adapter driver calls PcRegisterPhysicalConnectionFromExternal 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.

This function is useful for specifying a topology link between two audio adapters that are controlled by different adapter drivers. The function registers a physical connection between a filter object representing a subdevice in the local audio adapter and a filter object representing a subdevice in an external adapter.

The FromString parameter is a symbolic link to the subdevice that is exposed by the external adapter driver.

The information that is required to register an external physical connection must be supplied to the two drivers. This can be done during an initial coordinated install of the two devices, or it can be done dynamically by a user-mode configuration program that coordinates changes to the configurations of both devices.

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

Requirements

See also

DEVICE_OBJECT

IPort

IUnregisterPhysicalConnection::UnregisterPhysicalConnectionFromExternal

KSPROPERTY_PIN_PHYSICALCONNECTION

PcRegisterPhysicalConnection

PcRegisterPhysicalConnectionToExternal