Basic Support Queries for Audio Properties

When specifying the data for a set-property request to a filter, pin, or node, the client frequently needs to know the valid data ranges for the value or values that it specifies for the property. Ranges can vary from device to device, and possibly even from node to node within the same device.

A number of properties are defined to allow set-property requests to specify values that are out-of-range, but miniport drivers silently clamp those values to the supported range (for example, see KSPROPERTY_AUDIO_VOLUMELEVEL). A subsequent get request for the same property retrieves the driver's actual settings for the value or values, which might be clamped versions of the values that the client specified in the set request.

However, a client might need to know the range for a property value instead of simply relying on the miniport driver to automatically clamp an out-of-range value. For example, a windowed application that presents a volume-control slider for an audio device might need to know the device's volume range in order to map that range to the full length of the slider.

The driver's handler routine for a particular property should be able to provide range information in response to a basic-support property request (KSPROPERTY_TYPE_BASICSUPPORT). When sending a basic-support property request to a driver, a client provides a value buffer into which the property handler writes the basic-support information, which consists of a KSPROPERTY_DESCRIPTION structure that might be followed by property-specific data. This data typically consists of specifications for one or more parameter ranges, depending on the property.

In general, the client does not know in advance how large this value buffer should be and must send one or two preliminary requests to the property handler to determine the value size. The format for these preliminary requests is well defined. Clients expect drivers to follow these conventions when handling a basic-support request:

• If the request specifies the value size as sizeof(ULONG) then the property handler should write the value of the AccessFlags member of the KSPROPERTY_DESCRIPTION structure into the ULONG-sized value buffer. The handler sets the KSPROPERTY_TYPE_BASICSUPPORT flag bit if it provides further support for basic-property requests.
• If the request specifies the value size as sizeof(KSPROPERTY_DESCRIPTION), the handler should write a KSPROPERTY_DESCRIPTION structure into the data buffer. The handler sets the DescriptionSize field of the structure equal to that structure's size plus the size of all of the additional, property-specific information that the handler has available to load into the data buffer following the structure. This is the size of the value buffer that the client needs to allocate to contain the property's basic-support information.
• If the request specifies a value size that is large enough to contain both the KSPROPERTY_DESCRIPTION structure and the property-specific information, the handler should write the KSPROPERTY_DESCRIPTION structure into the start of the buffer, and it should write the property-specific information into the portion of the data buffer that follows the end of the KSPROPERTY_DESCRIPTION structure. When writing the KSPROPERTY_DESCRIPTION structure, the handler should set the DescriptionSize field to that structure's size plus the size of the property-specific information that follows the structure.

If the request specifies a value size that does not match one of the three cases listed above, the property handler rejects the request and returns status code STATUS_BUFFER_TOO_SMALL.

The property-specific information that the handler writes into the value buffer might include data ranges for property values. The MembersSize member of KSPROPERTY_MEMBERSHEADER indicates whether data ranges are included:

• MembersSize is zero if no ranges are needed. This is the case, for example, if property values are of type BOOL.
• MembersSize is nonzero if the KSPROPERTY_MEMBERSHEADER structure is followed by range descriptors for one or more property values.

For a property value of type BOOL, no range descriptor is needed because the range is implicitly limited to the values TRUE and FALSE. However, range descriptors are needed to specify the ranges of property values with integer types.

For example, the basic-support request for a KSPROPERTY_AUDIO_VOLUMELEVEL property on a volume node (KSNODETYPE_VOLUME) retrieves the minimum and maximum volume settings for that node. In this case, the client needs to allocate a value buffer that is large enough to contain the following structures:

KSPROPERTY_DESCRIPTION

KSPROPERTY_MEMBERSLIST

KSPROPERTY_STEPPING_LONG

The three structures are packed into adjacent locations in the buffer in the order given above. When handling the request, the miniport driver writes the minimum and maximum volume levels into the Bounds member of the KSPROPERTY_STEPPING_LONG structure.

For an example of a basic-support request with an array of range descriptors, see the figure in Exposing Multichannel Nodes. For more information about basic-support property requests, see KS Properties. For code examples, refer to the property-handler implementations in the sample audio drivers in the Windows DDK.