Miniport Driver Property Item Requests

This section is a brief introduction to DirectMusic property item requests. A complete overview of this and other kernel-streaming concepts can be found in Kernel Streaming.

DirectMusic miniport drivers must handle audio drivers property sets. A property request comes in two parts. The first part is the property set that is defined by the KSPROPERTY structure. The second is a data buffer that contains instance data that is specific to the property item.

The KSPROPERTY structure contains the following:

• A predefined GUID specifying the set (such as KSPROPSETID_Synth_Dls).

• An item ID specifying the property item within the set (such as KSPROPERTY_SYNTH_DLS_DOWNLOAD).

• Flags specifying the requested operation.

The Flags member of KSPROPERTY may contain exactly one of the following flags to specify the operation requested of the miniport driver:

KSPROPERTY_TYPE_GET
To retrieve the given property item's value.

KSPROPERTY_TYPE_SET
To set the given property item's value.

KSPROPERTY_TYPE_BASICSUPPORT
To determine the type of support available for the property set. The data returned in *pvPropertyData is a DWORD containing one or both of KSPROPERTY_TYPE_GET and KSPROPERTY_TYPE_SET, indicating which operations are possible.

The second part of the property item request is the instance data, which is a buffer that can be used to pass data to or from the miniport driver. How this buffer is used is dependent on whether the request is a SET or a GET:

• If the request is a KSPROPERTY_TYPE_SET, the instance data is sent to the miniport driver but is not returned to the requester.

• If the request is a KSPROPERTY_TYPE_GET, the instance data is filled out in the miniport driver and returned to the requester.

A property item request can be directed to a particular node in the miniport driver topology. The miniport driver topology describes the layout of the driver and the underlying hardware. Within the topology can be nodes where property items can be sent, whether there are pin instances available at the time of the request.

A pin instance must be created for DirectMusic playback. DirectMusic data is sent to the node of type KSNODETYPE_DMSYNTH. The following is an example of a miniport driver connection:

• Connect stream in to synth:

  PCFILTER_NODE Pin 0 (out) -> Node 0 Pin 1 (in)

• Connect synth to audio out:

  Node 0 Pin 0 (out) -> PCFILTER_NODE Pin 1 (in)

The supported data formats are a data range that specifies what format a pin can receive data in.

The DirectMusic format (STATIC_KSDATAFORMAT_SUBTYPE_DIRECTMUSIC) must be defined in the miniport driver's topology so that DirectMusic can send its data to the miniport driver. This format is defined by the DMUS_EVENTHEADER structure (see the Microsoft Windows SDK documentation) in dmusbuff.h. When the miniport driver specifies that it supports this particular data range, DirectMusic can expose that data range to the user (through a pin on the port itself).