|
|
|
Clients of a WDM audio driver can send get- and set-property requests (KSPROPERTY_TYPE_GET and KSPROPERTY_TYPE_SET) to the filters and pins that the driver has instantiated. For information about sending IOCTL_KS_PROPERTY requests to filters and pins, see KS Properties.
WDM audio drivers support the four types of properties that are shown in the table below.
| Property Type | Target of Property Request |
|---|---|
| Filter property | Filter instance |
| Pin property | Pin instance |
| Filter node property | Filter instance + node ID |
| Pin node property | Pin instance + node ID |
A filter property represents a capability or control-state setting that belongs to a filter instance. A set-property request for a filter property is sent to a particular filter instance and affects the state of that filter as a whole.
A pin property represents a capability or control-state setting that belongs to an individual pin (or equivalently, a data stream) instance on a filter. In general, a set-property request to a pin affects only the state of the target pin, not the filter as a whole. However, this rule is occasionally broken. For example, when the KSPROPERTY_AUDIO_CHANNEL_CONFIG property is set on one pin instance, it affects the channel configuration for the entire filter.
When sending a filter property request, the target filter is specified by its instance handle (see Filter Factories). Similarly, when sending a pin property request, the target pin is specified by its instance handle (see Pin Factories). Either type of request contains a KSPROPERTY structure that specifies the following:
Related properties are gathered together to form a property set. A particular property is specified by its property set and by an index that identifies its position within that set.
Nodes can also have properties. A node property request contains a KSNODEPROPERTY structure, which combines a KSPROPERTY structure and a node ID.
A filter node property is a property of a node in a filter. A filter node property request specifies the target node with both a filter handle and a node ID. Similarly, a pin node property is a property of a node on a pin. That is, the node lies on a data path that begins or ends on a particular pin. A pin node property request specifies the target node with both a pin handle a node ID.
A filter can contain two or more nodes that have the same node ID. For example, in the case of a filter that performs mixing, the mixer inputs might all be instances of a sink pin from the same pin factory, and all of the pin instances can have volume nodes (see KSNODETYPE_VOLUME) that share the same node ID. A node on a particular data path is specified by the combination of a node ID and a pin instance handle.
A pin node property belongs to a node that is associated with a particular pin instance. In the case of a filter that contains a SUM or MUX node (see KSNODETYPE_SUM and KSNODETYPE_MUX), the following rules apply:
With these conventions, a particular node on a particular data path can be identified uniquely.
In contrast, a filter node property represents the default value for a node property. When instantiating a pin, the driver sets the properties for the pin's nodes to their default values. A filter node set-property request changes the default value that is used for the specified property and node ID. The request has no effect on pins that have already been instantiated. It affects only future pin instantiations.