< Home < Developers < Development Support < Documentation

## 46 Sound Manager

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 46 Sound Manager Sound Manager Data Structures SndCallbackInfoType SndCmdIDType SndCommandType SndMidiListItemType SndMidiRecHdrType SndMidiRecType SndSmfCallbacksType SndSmfChanRangeType SndSmfOptionsType Sound Manager Functions SndCreateMidiList SndDoCmd SndGetDefaultVolume SndInterruptSmfIrregardless SndPlaySmf SndPlaySmfIrregardless SndPlaySmfResource SndPlaySmfResourceIrregardless SndPlaySystemSound SndSetDefaultVolume Application-Defined Functions SndComplFuncType SndBlockingFuncType |  |  |  | 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 #####
0 | No error.
#####
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 #####
None.
#### 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.
#####
-> callbacksP | NULL or a pointer to a SndSmfCallbacksType that holds your callback functions. Functions of type SndBlockingFuncType execute periodically while a note is playing, and functions of type SndComplFuncType execute after playback of the SMF completes. For more information, see the "Application-Defined Functions" section.
#####
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.
#####
-> callbacksP | NULL or a pointer to a SndSmfCallbacksType that holds your callback functions. Functions of type SndBlockingFuncType execute periodically while a note is playing, and functions of type SndComplFuncType execute after playback of the SMF completes. For more information, see the "Application-Defined Functions" section.
#####
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.
#####
-> resID | SMF resource ID.
#####
-> 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.
#####
-> resID | SMF resource ID.
#####
-> 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 |