Previous Page Table of Contents Index Next Page

Palm OS SDK Reference

Palm Logo 42 Sound Manager

This chapter provides reference material for the sound manager.

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.

Sound Manager Data Structures

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

Figure 42.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.

Comments

This function is useful for displaying lists of sounds residing on the Palm 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.



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 3.X 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

SndPlaySmfResource, 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
 Card number of the database containing the SMF resource.
  -> resID
 Resource ID of the SMF resource.
  -> volumeSelector
 Volume setting to use. The volume is read out of the system preferences. Possible values for this parameter are:
  prefSysSoundVolumeprefGameSoundVolume
 prefSysSoundVolumeprefGameSoundVolumeprefAlarmSoundVolume

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.



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.

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


Palm OS SDK Reference

  Previous Page Table of Contents Index Next Page  

This is page 44 of 85 in this book

Palm Computing Platform Development Zone
Copyright © 2000, Palm, Inc. All rights reserved.