PCCONNECTION_DESCRIPTOR structure

The PCCONNECTION_DESCRIPTOR structure describes a single data-path connection inside a KS filter. A filter's internal topology can be specified by an array of PCCONNECTION_DESCRIPTOR structures. A WDM audio adapter driver returns an array of these structures in response to a IMiniport::GetDescription call or a KSPROPERTY_TOPOLOGY_CONNECTIONS get-property request. PCCONNECTION_DESCRIPTOR is an alias for KSTOPOLOGY_CONNECTION.

Syntax

typedef struct {
  ULONG FromNode;
  ULONG FromNodePin;
  ULONG ToNode;
  ULONG ToNodePin;
} PCCONNECTION_DESCRIPTOR, *PPCCONNECTION_DESCRIPTOR;

Members

  • FromNode
    Specifies a node ID. This member identifies the node on the upstream end of the connection. If this end of the connection is an input (sink) pin on the filter--not a logical pin on a node--set this member to the null node-ID value, PCFILTER_NODE.

  • FromNodePin
    Specifies a pin ID. This member identifies the pin on the upstream end of the connection. If the FromNode member is set to PCFILTER_NODE, the pin on this end of the connection is an input (sink) pin on the filter. Otherwise, it is a logical pin on an internal node.

  • ToNode
    Specifies a node ID. This member identifies the node on the downstream end of the connection. If this end of the connection is an output (source) pin on the filter--not a logical pin on a node--set this member to the null node-ID value, PCFILTER_NODE.

  • ToNodePin
    Specifies a pin ID. This member identifies the pin on the downstream end of the connection. If the ToNode member is set to PCFILTER_NODE, the pin on this end of the connection is an output (source) pin on the filter. Otherwise, it is a logical pin on an internal node.

Remarks

The PCCONNECTION_DESCRIPTOR structure specifies a single connection inside a filter. The connection can be one of the following:

  • A connection between two internal nodes

  • A connection between an internal node and a pin on the filter

  • A connection between two pins on the filter

The last type of connection occurs when an input pin on a filter streams data directly to an output pin on the same filter.

An adapter driver uses an array of structures to specify the internal topology of a filter.

The data stream flows from the FromNode end to the ToNode end of the connection.

To use the PCCONNECTION_DESCRIPTOR structure, the driver writer assigns "logical" pins to the nodes inside the filter. These "pins" are connection points on the nodes and are analogous to the external pins that the filter uses to connect to other filters. However, logical pins on nodes are used solely to specify the connections inside the filter.

A simple node with a single input and a single output typically numbers its input and output pins one and zero, respectively. By convention, this numbering is based on the direction of IRP flow rather than data flow.

More complex nodes might require standardized pin IDs in order to allow clients to more easily determine the assignment of functions to specific pins. For example, the KSNODETYPE_ACOUSTIC_ECHO_CANCEL node uses standardized IDs for its four pins.

When the pin on one end of a connection is an input or output pin on the filter rather than a logical pin on a node, set the FromNode or ToNode member (depending on which end of the connection you are specifying) to the null node-ID value, PCFILTER_NODE.

Avoid confusing logical pins, which are used solely to describe connection points on nodes within a filter, with the external pins that filters use to connect to other filters. Logical pins are rarely used outside of the PCCONNECTION_DESCRIPTOR structure. In this document, the term pin refers to a pin on a KS filter rather than a logical pin on a node unless noted otherwise.

The IMiniport::GetDescription method outputs a PCFILTER_DESCRIPTOR structure that contains a pointer to a PCCONNECTION_DESCRIPTOR array.

For a simple code example that shows how the PCCONNECTION_DESCRIPTOR structure is used, see Exposing Filter Topology.

The PCFILTER_NODE constant is the null node ID for the FromNode or ToNode field in a PCCONNECTION_DESCRIPTOR structure.

If the structure's FromNode or ToNode member is set toPCFILTER_NODE, the pin on this end of the connection is an input or output pin on the filter. Otherwise, it is a logical pin on a node inside the filter.

PCFILTER_NODE is defined to be the value ((ULONG)-1).

Requirements

Header

Portcls.h (include Portcls.h)

See also

IMiniport::GetDescription

KSPROPERTY_TOPOLOGY_CONNECTIONS

KSTOPOLOGY_CONNECTION

PCFILTER_NODE

PCFILTER_DESCRIPTOR

 

 

Send comments about this topic to Microsoft