Documentation  |   Table of Contents   |  < Previous   |  Next >  

105    SoundMgr.h

Porting Applications to Palm OS® Cobalt

Exploring Palm OS®

The Sound Manager APIs in Palm OS Cobalt are largely unchanged from their Palm OS Garnet counterparts (for the most notable exceptions, see Table 105.4, "Modified functions," on page 420).


NOTE: Don't use the streaming sound callbacks to cause sounds to play after an application has quit. Instead, create a background thread and play the sounds from within that thread.

Deleted APIs ^TOP^

Table 105.1  Deleted functions

Deleted API

Use instead

SndInit()

Nothing; this function was documented as System Use Only, so it should not have been used by Palm OS applications.

SndInterruptSmfIrregardless()

SndInterruptSmf().

SndPlaySmfIrregardless()

SndPlaySmf(), or spawn a background thread and play the MIDI sound in that thread.

SndPlaySmfResourceIrregardless()

SndPlaySmfResource(), or spawn a background thread and play the MIDI sound in that thread.

Table 105.2  Deleted structures

Deleted API

Use instead

SndMidiRecType

Nothing. This structure was not used by any of the publicly-exported APIs.

Table 105.3  Deleted enumerated types

Deleted API

Use instead

SndFormatTag

The unnamed enum that contains all of the former SndFormatTag's values.

SndSampleTag

The audio_type_t enum.

Modified APIs ^TOP^

Table 105.4  Modified functions

Modified API

Description of change

status_t SndPlaySmfResource (uint32_t, DmOpenRef, int16_t, SystemPreferencesChoice)

Because Palm OS Cobalt doesn't have the concept of a resource search chain, you now must explicitly identify the resource database containing the MIDI sound being played. Accordingly, this function now takes a new parameter: a DmOpenRef.

status_t SndStreamCreate (SndStreamRef *, SndStreamMode, uint32_t, SndSampleType, SndStreamWidth, SndStreamBufferCallback, void *, uint32_t)

In Palm OS Cobalt a parameter was added to this function prototype indicating whether or not the callback function was an ARM-native function. In Palm OS Cobalt this parameter is unnecessary; it has been removed.

status_t SndStreamCreateExtended (SndStreamRef *, SndStreamMode, SndFormatType, uint32_t, SndSampleType, SndStreamWidth, SndStreamVariableBufferCallback, void *, uint32_t)

In Palm OS Cobalt a parameter was added to this function prototype indicating whether or not the callback function was an ARM-native function. In Palm OS Cobalt this parameter is unnecessary; it has been removed.

Table 105.5  Modified structures

Modified API

Description of change

SndCommandType

A padding field has been added before param1 for alignment purposes.

SndMidiListItemType

The dbID and cardNo fields used in prior Palm OS releases to identify the database containing the MIDI file have been replaced with a single DatabaseID named dbH.

SndMidiRecHdrType

A padding field has been added to the end of the structure for alignment purposes.

Table 105.6  Modified types

Modified API

Description of change

typedef audio_type_t SndSampleType

Formerly an Int16, SndSampleType is now an enum.

Table 105.7  Modified enumerated types

Modified API

Description of change

SndSysBeepTag

The Palm OS Cobalt version of this enum has two additional enum values: sndCardInserted and sndCardRemoved, used to signal that an external storage card has been inserted or removed from the device's slot.

Unchanged APIs ^TOP^

Table 105.8  Unchanged functions

SndCreateMidiList()

SndDoCmd()

SndGetDefaultVolume()

SndPlayResource()

SndPlaySmf()

SndPlaySystemSound()

SndSetDefaultVolume()

SndStreamDelete()

SndStreamDeviceControl()

SndStreamGetPan()

SndStreamGetVolume()

SndStreamPause()

SndStreamSetPan()

SndStreamSetVolume()

SndStreamStart()

SndStreamStop()

Table 105.9  Unchanged structures

SndCallbackInfoType

SndSmfCallbacksType

SndSmfChanRangeType

SndSmfOptionsType

Table 105.10  Unchanged types

SndBlockingFuncPtr

SndCmdIDType

SndCommandPtr

SndComplFuncPtr

SndFormatType

SndPtr

SndSmfCmdEnum

SndStreamMode

SndStreamRef

SndStreamWidth

SndSysBeepType

Table 105.11  Unchanged #defines

sndDefaultAmp

sndErrBadChannel

sndErrBadParam

sndErrBadStream

sndErrFormat

sndErrInterrupted

sndErrInvalidStream

sndErrMemory

sndErrNotImpl

sndErrOpen

sndErrQEmpty

sndErrQFull

sndFlagAsync

sndFlagNormal

sndFlagSync

sndFtrIDVersion

sndMaxAmp

sndMgrVersionNum

sndMidiNameLength

sndMidiRecSignature

sndPanCenter

sndPanFullLeft

sndPanFullRight

sndSmfPlayAllMilliSec

Table 105.12  Unchanged enumerated types

SndCmdIDTag

SndSmfCmdEnumTag

SndStreamModeTag

SndStreamWidthTag

sndSystemVolume/sndGameVolume/sndAlarmVolume "cookie" values enum

Table 105.13  Unchanged application-defined functions

SndBlockingFuncType()

SndComplFuncType()

SndStreamBufferCallback()

SndStreamVariableBufferCallback()