Inside Macintosh: Sound /

Chapter 5 - Sound Components / Sound Components Reference

Sound Manager Utilities / Saving and Restoring Sound Component Preferences

SetSoundPreference

A sound component can use the SetSoundPreference function to have the Sound Manager store a block of preferences data in a resource file. You're most likely to use this function in a sound output device component, although other types of sound components can use it also.

pascal OSErr SetSoundPreference (OSType type, Str255 name, 
                                    Handle settings);

type

The resource type to be used to create the preferences resource.

name

The resource name to be used to create the preferences resource.

settings

A handle to the data to be stored in the preferences resource.

DESCRIPTION

The SetSoundPreference function causes the Sound Manager to attempt to create a new resource that contains preferences data for your sound component. You can use this function to maintain a structure of any format across subsequent startups of the machine. You'll retrieve the preferences data by calling the GetSoundPreference function. The data is stored in a resource with the specified type and name in a resource file in the Preferences folder in the System Folder. In general, the resource type and name should be the same as the sound component subtype and name.

The settings parameter is a handle to the preferences data you want to store. It is the responsibility of your component to allocate and initialize the block of data referenced by that handle. The Sound Manager copies the handle's data into a resource in the appropriate location. Your sound component should dispose of the handle when SetSoundPreference returns.

The format of the block of preferences data referenced by the settings parameter is defined by your sound component. It is recommended that you include a field specifying the version of the data format; this allows you to modify the format of the block of data while remaining compatible with previous formats you might have defined.

SPECIAL CONSIDERATIONS

The SetSoundPreference function is available only in versions 3.0 and later of the Sound Manager.