This topic applies only to applications written in C++.

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

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_ReverbProps containing properties such as DSPROPERTY_REVERBPROPS_HALL and DSPROPERTY_REVERBPROPS_STADIUM.

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

Individual properties may also have associated parameters. The IKsPropertySet interface specification intentionally leaves these parameters undefined, allowing the designer of the property set to use them in a way most beneficial to the properties within the set being designed. 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 obtain a pointer to the interface if it is supported. You can do this by calling the QueryInterface method of an existing interface on a DirectSound3DBuffer object.

HRESULT hr = lpDirectSound3DBuffer->QueryInterface(
        IID_IKsPropertySet,
        (void**)&lpKsPropertySet));
 

In the example, lpDirectSound3DBuffer is a pointer to the buffer's interface and lpKsPropertySet receives the address of the IKsPropertySet interface if one is found. IID_IKsPropertySet is a GUID defined in Dsound.h.

The call will succeed only if the buffer is hardware-accelerated and the underlying driver supports property sets. If it does succeed, you can now look for a particular property using the IKsPropertySet::QuerySupport method. The value of the PropertySetId parameter is a GUID defined by the hardware vendor.

Once you've determined that support for a particular property exists, you can change the state of the property by using the IKsPropertySet::Set method and determine its present state by using the IKsPropertySet::Get method. The state of the property is set or returned in the pPropertyData parameter.

Additional property parameters may also be passed to the object in a structure pointed to by the pPropertyParams parameter to the IKsPropertySet::Set method. 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, the pPropertyParams parameter is rarely used.

Let's take a somewhat whimsical example. Suppose a sound card has the ability to play a set of songs in the voices of several famous tenors. The driver developer creates a property set, DSPROPSETID_Song, containing properties like DSPROPERTY_SONG_IRISH_EYES and DSPROPERTY_SONG_O_SOLE_MIO. The property set applies to all of the tenors, and the driver developer has specified that pPropertyParams defines the tenor instance. Now you, the application developer, want to make Caruso sing one of the songs:

/* It is assumed that the hardware vendor has also defined
   CARUSO and START in a header file. */
 
DWORD dwTenor = CARUSO;
BOOL  StartOrStop = START;
 
HRESULT hr = lpKsPropertySet->Set(
        DSPROPSETID_Song,
        DSPROPERTY_SONG_IRISH_EYES,
        &dwTenor,
        sizeof(dwTenor),
        &StartOrStop,
        sizeof(StartOrStop));