PCCONNECTION_DESCRIPTOR

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.

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.

Headers

Declared in portcls.h. Include portcls.h.

Comments

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 PCCONNECTION_DESCRIPTOR 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 Miniport Topology.

See Also

IMiniport::GetDescription, KSPROPERTY_TOPOLOGY_CONNECTIONS, KSTOPOLOGY_CONNECTION, PCFILTER_NODE, PCFILTER_DESCRIPTOR