Property Sets

  • Article

DirectSound is able to support extended services offered by sound cards, and their associated drivers, through the IKsPropertySet interface.

Properties are arranged in sets. A GUID identifies a set, and a ULONG identifies a particular property within the set. For example, a hardware vendor might design a card capable of reverberation effects and define a property set DSPROPSETID_ReverbProperties containing properties such as DSPROPERTY_REVERBPROPERTIES_HALL and DSPROPERTY_REVERBPROPERTIES_STADIUM.

Typically, the property identifiers are defined using a C language enumeration starting at ordinal 0.

Individual properties can also have associated parameters. The IKsPropertySet interface specification intentionally leaves these parameters undefined. This allows the designer of the property set to optimize the parameters' use within their property set. The precise meaning of the parameters is defined with the definition of the properties.

To make use of extended properties on sound cards, you must first determine whether the driver supports the IKsPropertySet interface, and then obtain a pointer to the interface if it is supported.

Once you have determined that support for a particular property exists, you can determine its present state by using the IKsPropertySet::Get method. You can change the state of the property by using the IKsPropertySet::Set method.

The IKsPropertySet::Set method allows you to pass additional property parameters through a parameter that points to a structure. The exact way in which this parameter is to be used is defined in the hardware vendor's specifications for the property set, but typically it would be used to define the instance of the property set. In practice, this technique is rarely used.

For example, suppose a sound card has the ability to play famous arias in the voices of several tenors. The driver developer can create a property set, DSPROPSETID_Aria, containing properties such as DSPROPERTY_ARIA_VESTI_LA_GIUBBA and DSPROPERTY_ARIA_CHE_GELIDA_MANINA that apply to all tenors supported by the sound card. The driver developer can specify that the pPropertyParam parameter of IKsPropertySet::Set method identifies a particular tenor. With this driver support, your application can access the special feature of the sound card using the following code to produce the sound of Caruso singing the great aria from Pagliacci.

DWORD WhichTenor = CARUSO;
BOOL  StartOrStop = START;

HRESULT hr = lpKsPropertySet->Set(
                     DSPROPSETID_Aria,
                     KSPROPERTY_ARIA_VESTI_LA_GIUBBA,
                     &WhichTenor,
                     sizeof(WhichTenor),
                     &StartOrStop),
                     sizeof(StartOrStop));

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.