Audio Property Requests

Clients of a Microsoft Windows Driver Model (WDM) audio driver can send requests for KS properties to the KS filters and pins that the driver has instantiated. For example, a user-mode client can send a KS property request by calling the DeviceIoControl function (see the Microsoft Windows SDK documentation) with an I/O-control code of IOCTL_KS_PROPERTY. This function sends an IRP containing the property request to the specified filter or pin object.

Audio drivers support get, set, and basic-support requests on properties (KSPROPERTY_TYPE_GET, KSPROPERTY_TYPE_SET, and KSPROPERTY_TYPE_BASICSUPPORT). For more information, see Audio Drivers Property Sets.

A client can send requests for three kinds of properties: filter properties, pin properties, and node properties. For more information, see Filter, Pin, and Node Properties.

When sending a filter-property request to a filter object, the client specifies the target filter by its instance handle (see Filter Factories). Similarly, when sending a pin-property request to a pin object, the target pin is specified by its instance handle (see Pin Factories). Either type of request contains a KSPROPERTY structure that specifies the following:

• A GUID that identifies the property set

• An index that identifies a property item within the specified property set

• Flags that indicate the type of property request (get, set, or basic-support)

Related properties are gathered together to form a property set. A particular property is identified by its property set and by an index that specifies its position within that set.

A node-property request contains a KSNODEPROPERTY structure, which combines a KSPROPERTY structure and a node ID. Depending on the node property, the target for the property request is either a filter instance or a pin instance.

If a filter can create more than one instance of a particular node type, the target for the request is specified by a pin handle. The handle identifies the pin instance at the beginning or end of the data path on which the node instance resides. In the case of a filter containing a SUM or MUX node (see KSNODETYPE_SUM and KSNODETYPE_MUX), the following rules apply:

• If the property belongs to a node that lies downstream from a sink (input) pin and upstream from the SUM or MUX node, the property request is sent to the sink pin.

• If the property belongs to a node that lies downstream from a SUM or MUX node and upstream from a source (output) pin, the property request is sent to the source pin. (Also, a property request for a SUM or MUX node is sent to the source pin.)

With these conventions, a particular node on a particular data path can be identified uniquely.

For information about using the mixer API to traverse the nodes in a data path, see Kernel Streaming Topology to Audio Mixer API Translation.