This chapter provides reference material for the sound manager.
Sound Manager Data Structures
Application-Defined Functions
Sound Manager Functions
The header file SoundMgr.h declares the API that this chapter describes. For more information on the sound manager, see the section "Sound" in the Palm OS Programmer's Companion, vol. I.
Sound Manager Data Structures

This section describes the data structures that define the MIDI records and parameter blocks used by sound manager functions. Figure 46.1 depicts a Palm OS® MIDI record graphically.
Figure 46.1 Palm OS Midi Record
SndCallbackInfoType

The SndCallbackInfoType structure wraps the sound manager callback functions that you implement. See "Application-Defined Functions" for more information.
typedef struct SndCallbackInfoType {
MemPtr funcP;
UInt32 dwUserData;
} SndCallbackInfoType;
Field Descriptions
funcP |
Pointer to the callback function (NULL = no function). |
dwUserData |
Value to pass in dwUserData parameter of callback function. |
SndCmdIDType

The SndCmdIDType enumerated type defines the commands that may be specified in the cmd field of the SndCommandType. Each command defines its own specific use of the param1, param2, and param3 fields.
typedef enum SndCmdIDType {
sndCmdFreqDurationAmp = 1,
sndCmdNoteOn,
sndCmdFrqOn,
sndCmdQuiet
} SndCmdIDType;
Value Descriptions
sndCmdFreqDurationAmp |
Play a sound, blocking for the entire duration (except for zero amplitude). |
|
param1 = frequency in Hz |
|
param2 = duration in milliseconds |
|
param3 = amplitude (0 to sndMaxAmp) |
|
If value of param3 is 0, returns immediately. |
sndCmdNoteOn |
Play sound at specified MIDI key index with max duration and velocity; return immediately, without waiting for playback to complete. Any other sound play request made before this one completes will interrupt it. |
|
param1 = MIDI key index (0-127) |
|
param2 = maximum duration in milliseconds |
|
param3 = velocity (0 to 127) to be interpolated as amplitude. |
sndCmdFrqOn |
Similar to sndCmdNoteOn except note to play is specified as frequency in Hz. |
|
param1 = frequency in Hz |
|
param2 = maximum duration in milliseconds |
|
param3 = amplitude (0 - sndMaxAmp) |
sndCmdQuiet |
Stop playback of current sound. |
|
param1 = 0 |
|
param2 = 0 |
|
param3 = 0 |
IMPORTANT: SndDoCmd in versions of Palm OS before 3.0 will generate a fatal error on anything other than sndCmdFreqDurationAmp. For this reason, applications wishing to take advantage of these new commands while staying compatible with the earlier version of the OS, must avoid using these commands when running on OS versions less than v3.0. Beginning with v3.0, SndDoCmd returns sndErrBadParam when an unknown command is passed.
SndCommandType

The SndCommandType structure is passed as the value of the cmdP parameter to the SndDoCmd function. Its parameters are defined by the SndCmdIDType.
typedef struct SndCommandType {
SndCmdIDType cmd;
UInt8 reserved;
Int32 param1;
UInt16 param2;
UInt16 param3;
} SndCommandType;
Field Descriptions
cmd |
Command ID. |
reserved |
Reserved for future use. |
param1, param2, param3 |
Use varies according to value of cmd. |
SndMidiListItemType

When the SndCreateMidiList function returns true, its entHP parameter holds a handle to a memory chunk containing an array of SndMidiListItemType structures.
typedef struct SndMidiListItemType{
Char name[sndMidiNameLength];
UInt32 uniqueRecID;
LocalID dbID;
UInt16 cardNo;
} SndMidiListItemType;
Field Descriptions
name |
MIDI name including null terminator. |
uniqueRecID |
Unique ID of the record containing the MIDI file. |
dbID |
Database (file) ID. |
cardNo |
Number of the memory card on which the MIDI file resides. |
SndMidiRecHdrType

The SndMidiRecHdrType structure defines the fixed-size portion of a Palm OS MIDI record. (See SndCallbackInfoType.)
typedef struct SndMidiRecHdrType {
UInt32 signature;
UInt8 bDataOffset;
UInt8 reserved;
} SndMidiRecHdrType;
Field Descriptions
signature |
Set to sndMidiRecSignature. |
bDataOffset |
Offset from the beginning of the record to the Standard MIDI File data stream. |
reserved |
Set to zero. |
SndMidiRecType

The SndMidiRecType structure defines a variable-length header precedes the actual MIDI data in a Palm OS MIDI record. It consists of a fixed-size MIDI record header followed by the name of the MIDI track.
typedef struct SndMidiRecType {
SndMidiRecHdrType hdr;
Char name[1];
} SndMidiRecType;
Field Descriptions
hdr |
Fixed-size portion of the Palm OS MIDI record header. See SndMidiRecHdrType. |
name |
Track name: 1 or more characters including null terminator. The length of name, including null terminator, must not be greater than sndMidiNameLength. The null character must always be provided, even for tracks that have no name. |
SndSmfCallbacksType

The SndSmfCallbacksType structure is passed as the value of the callbacksP parameter to the SndPlaySmf function.
typedef struct SndSmfCallbacksType {
SndCallbackInfoType completion;
SndCallbackInfoType blocking;
SndCallbackInfoType reserved;
} SndSmfCallbacksType;
Field Descriptions
completion |
Completion callback function (see SndComplFuncType). |
blocking |
Blocking hook callback function (see SndBlockingFuncType). |
reserved |
Reserved. Set to 0 before passing. |
SndSmfChanRangeType

This SndSmfChanRangeType structure is passed as the value of the chanRangeP parameter to the SndPlaySmf function. It specifies a range of enabled channels. Events for channels outside this range are ignored.
If this structure is not passed, all channels in the track are ignored.
typedef struct SndSmfChanRangeType {
UInt8 bFirstChan;
UInt8 bLastChan;
} SndSmfChanRangeType;
Field Descriptions
bFirstChan |
First MIDI channel (0-15 decimal). |
bLastChan |
Last MIDI channel (0-15 decimal). |
SndSmfOptionsType

The SndSmfOptionsType structure is passed as the value of the selP parameter to the SndPlaySmf function.
typedef struct SndSmfOptionsType {
UInt32 dwStartMilliSec;
UInt32 dwEndMilliSec;
UInt16 amplitude;
Boolean interruptible;
UInt8 reserved1;
UInt32 reserved;
} SndSmfOptionsType;
Field Descriptions
dwStartMilliSec |
Position at which to begin playback, expressed as number of milliseconds from beginning of the track. 0 means start from the beginning of the track. |
|
This field is used as input for sndSmfCmdPlay and output for sndSmfCmdDuration. |
dwEndMilliSec |
Position at which to stop playback, expressed as number of milliseconds from beginning of track. sndSmfPlayAllMilliSec means play the entire track; the default is to play the entire track if this structure is not passed in. |
|
This field is used as input for sndSmfCmdPlay and output for sndSmfCmdDuration. |
amplitude |
Used only for sndSmfCmdPlay. Specifies relative volume. Possible values range from 0 to sndMaxAmp, inclusively. The default is sndMaxAmp if this structure is not passed in. If 0, the sound is not played and the call returns immediately. |
interruptible |
Used only for sndSmfCmdPlay. If true, sound play will be interrupted if user interacts with the controls (digitizer, buttons, etc.) even if the interaction does not generate a sound command. If false, playback is not interrupted. The default behavior is true if this structure is not passed in. |
reserved1 |
Reserved for future use. |
reserved |
Reserved. Set to 0 before passing. |
Sound Manager Functions

SndCreateMidiList

Purpose
Generate a list of MIDI records having a specified creator.
Prototype
Boolean SndCreateMidiList (UInt32 creator, Boolean multipleDBs, UInt16* wCountP, MemHandle *entHP)
Parameters
->creator | Creator of database in which to find MIDI records. Pass 0 for wildcard. |
->multipleDBs | Pass true to search multiple databases for MIDI records. Pass false to search only in the first database found that meets search criteria. |
<->wCountP | When the function returns, contains the number of MIDI records found. |
<->entHP | When the function returns, this handle holds a a memory chunk containing an array of SndMidiListItemType if MIDI records were found. |
Result
Returns false if no MIDI records were found, true if MIDI records were found. When this function returns true, it updates the wCountP parameter to hold the number of MIDI records found and updates the entHP parameter to hold a handle to an array of SndMidiListItemType structures. Each record of this type holds the name, record ID, database ID, and card number of a MIDI record. The order of entries in entHP is not specified and should not be relied upon.
Comments
This function is useful for displaying lists of sounds residing on the PalmTM device as MIDI records.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
DmFindRecordByID, DmOpenDatabase, DmQueryRecord, DmOpenDatabaseByTypeCreator,"Rock Music" sample code
SndDoCmd

Purpose
Send a sound manager command to a specified sound channel.
Prototype
Err SndDoCmd (void* channelP, SndCommandPtr cmdP, Boolean noWait)
Parameters
-> channelP | Pointer to sound channel. Present implementation doesn't support multiple channels. Must be NULL. |
| Passing NULL for the channel pointer causes the command to be sent to the shared sound channel; currently, this is the only option. |
-> cmdP | Pointer to a SndCommandType holding a parameter block that specifies the note to play, its duration, and amplitude. |
-> noWait | Because asynchronous mode is not yet supported for all commands, you must pass 0 for this value. |
| In the future, pass 0 to await completion (synchronous) and pass a nonzero value to specify immediate return (asynchronous). |
Result
sndErrBadParam | Invalid parameter. |
sndErrBadChannel | Invalid channel pointer. |
sndErrQFull | Sound queue is full. |
Comments
This function is useful for simple sound playback applications, such as playing a single note to provide user feedback. In addition to providing the same behavior it did in versions 1.0 and 2.0 of Palm OS, (specify the frequency, duration, and amplitude of a single note to be played) new command selectors provided in Palm OS 3.0 and higher allow you to use MIDI values to specify pitch, duration, and amplitude of the note to play, and to stop the note currently being played.
Compatibility
Commands (see SndCmdIDType) other than sndCmdFreqDurationAmp are implemented only if 3.0 New Feature Set is present.
See Also
SndPlaySmf
SndGetDefaultVolume

Purpose
Return default sound volume levels cached by sound manager.
Prototype
void SndGetDefaultVolume (UInt16* alarmAmpP, UInt16* sysAmpP, UInt16* masterAmpP)
Parameters
<-> alarmAmpP | Pointer to storage for alarm amplitude. |
<-> sysAmpP | Pointer to storage for system sound amplitude. |
<-> masterAmpP | Pointer to storage for master amplitude. |
Result
Returns nothing.
Comments
Any pointer arguments may be passed as NULL. In that case, the corresponding setting is not returned.
New SndInterruptSmfIrregardless

Purpose
Interrupts any currently playing SMF file, even if the interruptible flag is false.
Prototype
Err SndInterruptSmfIrregardless (void)
Parameters
Result
Returns errNone.
Comments
This function is similar to the SndPlaySmfIrregardless and SndPlaySmfResourceIrregardless functions except that it doesn't play a sound after interrupting the current sound.
Implemented only if 4.0 New Feature Set is present.
See Also
SndPlaySmf, SndPlaySmfResourceIrregardless
SndPlaySmf

Purpose
Performs the operation specified by the cmd parameter: play the specified standard MIDI file (SMF) or return the number of milliseconds required to play the entire SMF.
Prototype
Err SndPlaySmf (void* chanP, SndSmfCmdEnum cmd, UInt8* smfP, SndSmfOptionsType* selP, SndSmfChanRangeType* chanRangeP, SndSmfCallbacksType* callbacksP, Boolean bNoWait)
Parameters
chanP | The sound channel used to play the sound. This value must always be NULL because current versions of Palm OS provide only one sound channel that all applications share. |
cmd | The operation to perform, as specified by one of the following selectors: |
sndSmfCmdPlay | Play the selection synchronously. |
sndSmfCmdDuration | Return the duration of the entire SMF, expressed in milliseconds. |
-> smfP | Pointer to the SMF data in memory. This pointer can reference a valid SndCallbackInfoType followed by MIDI data, or it can point directly to the beginning of the SMF data. |
-> selP | NULL or a pointer to a SndSmfOptionsType specifying options for playback volume, position in the SMF from which to begin playback, and whether playback can be interrupted by user interaction with the display. See the SndSmfOptionsType for the default behavior specified by a NULL value. |
-> chanRangeP | NULL or a pointer to a SndSmfChanRangeType specifying a continuous range of MIDI channels 0 -15 to use for playback. If this value is NULL, all tracks are played. |
bNoWait | This value is ignored. This function always finishes playing the SMF selection before returning; however, you can execute a callback function while the SMF is playing. |
Result
Returns 0 if no error. When an error occurs, this function returns one of the following values; for more information see the SoundMgr.h file included with the Palm OS SDK:
sndErrBadParam |
Bogus value passed to this function. |
sndErrBadChannel |
Invalid sound channel. |
sndErrMemory |
Insufficient memory. |
sndErrOpen |
Tried to open channel that's already open. |
sndErrQFull |
Can't accept more notes. |
sndErrQEmpty |
Internal use; never returned to applications. |
sndErrFormat |
Unsupported data format. |
sndErrBadStream |
Invalid data stream. |
sndErrInterrupted |
Play was interrupted. |
Comments
Although this call is synchronous, a callback function can be called while a note is playing. If the callback does not return before the number of system ticks required to play the current sound have elapsed, the next note in the SMF will not start on time.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
SndInterruptSmfIrregardless, SndPlaySmfIrregardless, SndPlaySmfResource, SndDoCmd, SndCreateMidiList
New SndPlaySmfIrregardless

Purpose
Performs the operation specified by the cmd parameter: play the specified standard MIDI file (SMF) or return the number of milliseconds required to play the entire SMF. Unlike SndPlaySmf, this function interrupts any currently playing SMF file to play the new sound, even if the interruptible flag was false when the currently playing SMF file was started.
Prototype
Err SndPlaySmfIrregardless (void *chanP, SndSmfCmdEnum cmd, UInt8 *smfP, SndSmfOptionsType *selP, SndSmfChanRangeType *chanRangeP, SndSmfCallbacksType *callbacksP, Boolean bNoWait)
Parameters
chanP | The sound channel used to play the sound. This value must always be NULL because current versions of Palm OS provide only one sound channel that all applications share. |
cmd | The operation to perform, as specified by one of the following selectors: |
sndSmfCmdPlay | Play the selection synchronously. |
sndSmfCmdDuration | Return the duration of the entire SMF, expressed in milliseconds. |
-> smfP | Pointer to the SMF data in memory. This pointer can reference a valid SndCallbackInfoType followed by MIDI data, or it can point directly to the beginning of the SMF data. |
-> selP | NULL or a pointer to a SndSmfOptionsType specifying options for playback volume, position in the SMF from which to begin playback, and whether playback can be interrupted by user interaction with the display. See the SndSmfOptionsType for the default behavior specified by a NULL value. |
-> chanRangeP | NULL or a pointer to a SndSmfChanRangeType specifying a continuous range of MIDI channels 0 -15 to use for playback. If this value is NULL, all tracks are played. |
bNoWait | This value is ignored. This function always finishes playing the SMF selection before returning; however, you can execute a callback function while the SMF is playing. |
Result
Returns 0 if no error. When an error occurs, this function returns one of the following values; for more information see the SoundMgr.h file included with the Palm OS SDK:
sndErrBadParam |
Bogus value passed to this function. |
sndErrBadChannel |
Invalid sound channel. |
sndErrMemory |
Insufficient memory. |
sndErrOpen |
Tried to open channel that's already open. |
sndErrQFull |
Can't accept more notes. |
sndErrQEmpty |
Internal use; never returned to applications. |
sndErrFormat |
Unsupported data format. |
sndErrBadStream |
Invalid data stream. |
sndErrInterrupted |
Play was interrupted. |
Comments
Although this call is synchronous, a callback function can be called while a note is playing. If the callback does not return before the number of system ticks required to play the current sound have elapsed, the next note in the SMF will not start on time.
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
SndInterruptSmfIrregardless, SndPlaySmf, SndPlaySmfResourceIrregardless, SndDoCmd, SndCreateMidiList
SndPlaySmfResource

Purpose
Plays a MIDI sound read out of an open resource database.
Prototype
Err SndPlaySmfResource (UInt32 resType, Int16 resID, SystemPreferencesChoice volumeSelector)
Parameters
-> resType | SMF resource type. |
-> volumeSelector | Volume setting to use. The volume is read out of the system preferences. Possible values for this parameter are: |
| prefSysSoundVolume prefGameSoundVolume prefAlarmSoundVolume |
Result
Returns 0 upon success, otherwise one of the following:
sndErrBadParam |
The volumeSelector parameter has an invalid value or the SMF resource has invalid data. |
dmErrCantFind |
The specified resource does not exist on the specified card. |
or any error code returned by SndPlaySmf.
Comments
This is a convenience function to be used in place of SndPlaySmf. It plays an SMF sound stored in a resource database. This function plays the entire sound on all MIDI channels at the volume specified and allows the sound to be interrupted by a key down event or a digitizer event. No callbacks are specified.
Compatibility
Implemented only if 3.2 New Feature Set is present.
See Also
SndPlaySmfResourceIrregardless
New SndPlaySmfResourceIrregardless

Purpose
Plays a MIDI sound read out of an open resource database. Unlike SndPlaySmfResource, this function interrupts any currently playing SMF file to play the new sound, even if the interruptible flag was false when the currently playing SMF file was started.
Prototype
Err SndPlaySmfResourceIrregardless (UInt32 resType, Int16 resID, SystemPreferencesChoice volumeSelector)
Parameters
-> resType | SMF resource type. |
-> volumeSelector | Volume setting to use. The volume is read out of the system preferences. Possible values for this parameter are: |
| prefSysSoundVolume prefGameSoundVolume prefAlarmSoundVolume |
Result
Returns 0 upon success, otherwise one of the following:
sndErrBadParam |
The volumeSelector parameter has an invalid value or the SMF resource has invalid data. |
dmErrCantFind |
The specified resource does not exist on the specified card. |
or any error code returned by SndPlaySmf.
Comments
This is a convenience function to be used in place of SndPlaySmfIrregardless. It plays an SMF sound stored in a resource database. This function plays the entire sound on all MIDI channels at the volume specified and allows the sound to be interrupted by a key down event or a digitizer event. No callbacks are specified.
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
SndInterruptSmfIrregardless, SndPlaySmfResource
SndPlaySystemSound

Purpose
Play a standard system sound.
Prototype
void SndPlaySystemSound (SndSysBeepType beepID)
Parameters
-> beepID | System sound to play. |
Result
Returns nothing.
Comments
The SndSysBeepType enum is defined in SoundMgr.h as follows:
typedef enum SndSysBeepType {
sndInfo = 1,
sndWarning,
sndError,
sndStartUp,
sndAlarm,
sndConfirmation,
sndClick
} SndSysBeepType;
Note that in versions of Palm OS prior to 3.0, all of these sounds were synchronous and blocking. In Palm OS 3.0 and higher, sndAlarm still blocks, but the rest of these system sounds are implemented asynchronously.
The SndPlaySystemSound function uses the system volume setting when playing the sound.
SndSetDefaultVolume

Purpose
Sets the default sound volume levels cached by sound manager.
Prototype
void SndSetDefaultVolume (UInt16* alarmAmpP, UInt16* sysAmpP, UInt16* defAmpP)
Parameters
<-> alarmAmpP | Pointer to storage for alarm amplitude. |
<-> sysAmpP | Pointer to storage for system sound amplitude. |
<-> defAmpP | Pointer to storage for default amplitude. |
Result
Returns nothing.
Comments
Any pointer arguments may be passed as NULL. In that case, the corresponding setting is not altered.
Application-Defined Functions

This section describes callback functions to be executed by the SndPlaySmf function.
SndComplFuncType

Purpose
Executed after playback of the SMF completes.
Prototype
void SndComplFuncType (void* chanP, UInt32 dwUserData)
Parameters
-> chanP | The sound channel used to play the sound. This value must always be NULL because current versions of Palm OS provide only one sound channel that all applications share. |
-> dwUserData | Application-defined data that this function needs to access, or NULL. |
Result
Returns nothing.
See Also
SndSmfCallbacksType
SndBlockingFuncType

Purpose
A non-blocking callback function that is executed periodically during playback of the SMF.
Prototype
Boolean SndBlockingFuncType (void* chanP, UInt32 dwUserData, Int32 sysTicksAvailable)
Parameters
-> chanP | The sound channel used to play the sound. This value must always be NULL because current versions of Palm OS provide only one sound channel that all applications share. |
-> dwUserData | Application-defined data that this function needs to access. |
-> sysTicksAvailable | The maximum amount of time available for completion of this function, or NULL. |
Result
Returns true to continue playback, or false to cancel playback.
Comments
Suggested uses for this function include updating the user interface or checking for user input.
See Also
SndSmfCallbacksType, SndPlaySmf
|