Sound Manager
 

 < 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

->creatorCreator of database in which to find MIDI records. Pass 0 for wildcard.
->multipleDBsPass true to search multiple databases for MIDI records. Pass false to search only in the first database found that meets search criteria.
<->wCountPWhen the function returns, contains the number of MIDI records found.
<->entHPWhen 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

-> channelPPointer 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.
-> cmdPPointer to a SndCommandType holding a parameter block that specifies the note to play, its duration, and amplitude.
-> noWaitBecause 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

0No error.
sndErrBadParamInvalid parameter.
sndErrBadChannelInvalid channel pointer.
sndErrQFullSound 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

<-> alarmAmpPPointer to storage for alarm amplitude.
<-> sysAmpPPointer to storage for system sound amplitude.
<-> masterAmpPPointer 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

chanPThe 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.
cmdThe operation to perform, as specified by one of the following selectors:
sndSmfCmdPlayPlay the selection synchronously.
sndSmfCmdDuration Return the duration of the entire SMF, expressed in milliseconds.
-> smfPPointer 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.
-> selPNULL 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.
-> chanRangePNULL 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.
-> callbacksPNULL 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.
bNoWaitThis 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

chanPThe 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.
cmdThe operation to perform, as specified by one of the following selectors:
sndSmfCmdPlayPlay the selection synchronously.
sndSmfCmdDuration Return the duration of the entire SMF, expressed in milliseconds.
-> smfPPointer 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.
-> selPNULL 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.
-> chanRangePNULL 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.
-> callbacksPNULL 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.
bNoWaitThis 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

-> resTypeSMF resource type.
-> resIDSMF resource ID.
-> volumeSelectorVolume 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

-> resTypeSMF resource type.
-> resIDSMF resource ID.
-> volumeSelectorVolume 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

-> beepIDSystem 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

<-> alarmAmpPPointer to storage for alarm amplitude.
<-> sysAmpPPointer to storage for system sound amplitude.
<-> defAmpPPointer 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

-> chanPThe 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.
-> dwUserDataApplication-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

-> chanPThe 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.
-> dwUserDataApplication-defined data that this function needs to access.
-> sysTicksAvailableThe 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