API Guide Home
(Online version only)

Header Files » Incs » 68k » libraries » sndfilestream

palmOneSndFileStream.h File Reference

Detailed Description

Public 68K include file for sound files stream support for Treo 600 and Treo 650 smartphones.

This header file and associated header files support the specific sound functionality of the Treo smartphones. You should use the Palm OS Sound Manager APIs for most of your work.

Notes: The calling application should always load this library with SysLibLoad() before use, even if it is already open by another application(ie, SysLibFind() returns a valid refnum). When the application is done with the library, it should be unloaded with SysLibRemove(). We do this because there is no good way to synchronize loading and unloading of libraries among multiple applications. It also greatly simplifies internal synchronization.

Definition in file palmOneSndFileStream.h.

Include dependency graph for palmOneSndFileStream.h:

Go to the source code of this file.

Data Structures

Defines

Type and creator of the Sound File Stream library
Used with FtrGet.

Utility macros
These macros take care of opening and closing the sound file stream library in various situations.

Error codes
These macros take care of opening and closing the sound file stream library in various situations.

Play back sound file stream
Use for playbackCount parameter of tagSndFileStreamData to play back a stream indefinitely.

File Flags
File stream database types
File stream databases opened using kSndFileStreamFileSpecFlagFileStream.

Library traps

Typedefs

Enumerations

Functions

Define Documentation

#define kSndFileStreamFileSpecFlagFileStream   (0x0002)

File stream

Definition at line 280 of file palmOneSndFileStream.h.

#define kSndFileStreamFileSpecFlagVFS   (0x0001)

VFS file

Definition at line 279 of file palmOneSndFileStream.h.

#define kSndFileStreamLibCreator   'sfsL'

Creator ID of the sound file stream library.

Definition at line 60 of file palmOneSndFileStream.h.

#define kSndFileStreamLibErrAlreadyOpen   1

Definition at line 146 of file palmOneSndFileStream.h.

#define kSndFileStreamLibErrCancel   7

Definition at line 152 of file palmOneSndFileStream.h.

#define kSndFileStreamLibErrCantOpenFile   5

Definition at line 150 of file palmOneSndFileStream.h.

#define kSndFileStreamLibErrNone   errNone

Definition at line 145 of file palmOneSndFileStream.h.

#define kSndFileStreamLibErrNotOpen   2

Definition at line 147 of file palmOneSndFileStream.h.

#define kSndFileStreamLibErrOperationNotSupported   8

Definition at line 153 of file palmOneSndFileStream.h.

#define kSndFileStreamLibErrOutOfMemory   4

Definition at line 149 of file palmOneSndFileStream.h.

#define kSndFileStreamLibErrStillOpen   3

Definition at line 148 of file palmOneSndFileStream.h.

#define kSndFileStreamLibErrUnsupportedFile   6

Definition at line 151 of file palmOneSndFileStream.h.

#define kSndFileStreamLibName   "SndFileStream-sfsL"

Name of the sound file stream library.

Definition at line 61 of file palmOneSndFileStream.h.

#define kSndFileStreamLibPlaybackForever   0xFFFF

Definition at line 163 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapClose   (sysLibTrapCustom + 3)

Definition at line 317 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapCreate   (sysLibTrapCustom + 1)

Definition at line 315 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapDeviceControl   (sysLibTrapCustom + 9)

Definition at line 323 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapGetCurrentStreamData   (sysLibTrapCustom + 8)

Definition at line 322 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapGetPan   (sysLibTrapCustom + 13)

Definition at line 327 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapGetVolume   (sysLibTrapCustom + 11)

Definition at line 325 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapOpen   (sysLibTrapCustom + 2)

Definition at line 316 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapPause   (sysLibTrapCustom + 5)

Definition at line 319 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapSeek   (sysLibTrapCustom + 7)

Definition at line 321 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapSetPan   (sysLibTrapCustom + 12)

Definition at line 326 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapSetVolume   (sysLibTrapCustom + 10)

Definition at line 324 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapStart   (sysLibTrapCustom + 4)

Definition at line 318 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapStop   (sysLibTrapCustom + 6)

Definition at line 320 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapUIPlay   (sysLibTrapCustom + 14)

Definition at line 328 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapUIRecord   (sysLibTrapCustom + 15)

Definition at line 329 of file palmOneSndFileStream.h.

#define kSndFileStreamLibTrapVersion   (sysLibTrapCustom + 0)

Definition at line 314 of file palmOneSndFileStream.h.

#define kSndFileStreamLibType   sysFileTLibrary

Type of the sound file stream library.

Definition at line 59 of file palmOneSndFileStream.h.

#define kSndFileStreamLibVersion   sysMakeROMVersion(1, 4, 0, sysROMStageRelease, 20)

Version of the sound file stream library.

Definition at line 62 of file palmOneSndFileStream.h.

#define kSndFileTypeAAC   'AACf'

AAC file -> kSndFileFormatAAC

Definition at line 294 of file palmOneSndFileStream.h.

#define kSndFileTypeAMR   'AMRf'

AMR file -> kSndFileFormatTreoAMR.

Definition at line 292 of file palmOneSndFileStream.h.

#define kSndFileTypeMP3   'MP3f'

MP3 file -> kSndFileFormatMP3

Definition at line 293 of file palmOneSndFileStream.h.

#define kSndFileTypeQCP   'QCPf'

QCELP file -> kSndFileFormatTreoQCP.

Definition at line 291 of file palmOneSndFileStream.h.

#define kSndFileTypeWAV   'WAVf'

WAV file -> kSndFileFormatWAV .

Definition at line 290 of file palmOneSndFileStream.h.

#define SNDFILESTREAM_TRAP ( x   )     SYS_TRAP( x )

Helper macro.

Definition at line 46 of file palmOneSndFileStream.h.

#define SndFileStreamCloseLibrary ( refNum,
err   ) 

Value:

{                                                           \
        if ( sysInvalidRefNum == (refNum) )                     \
        {                                                       \
            (err) = sysErrParamErr;                             \
        }                                                       \
        else                                                    \
        {                                                       \
            (err) = SndFileStreamLibClose( (refNum) );          \
            if ( errNone == (err) )                             \
            {                                                   \
                (err) = SysLibRemove( (refNum) );               \
                (refNum) = sysInvalidRefNum;                    \
            }                                                   \
            else if ( kSndFileStreamLibErrStillOpen == (err) )  \
            {                                                   \
                (err) = errNone;                                \
            }                                                   \
        }                                                       \
    }

Definition at line 115 of file palmOneSndFileStream.h.

#define sndFileStreamNotifyRecComplete   'RecC'

Notification broadcast by SndFileStream when it exceeds the recording limit. Currently this notification is handled by the libary itself, for example, stop the recording stream. The application should NOT expect to recieve this notification even it register it. Instead it should expect sndFileStreamNotifyStreamComplete notification to indicate that the recording limit has been reached.

Definition at line 186 of file palmOneSndFileStream.h.

#define sndFileStreamNotifyStreamComplete   'StrC'

Notification broadcast by SndFileStream when it has completed playing a stream. This is an alternative to using callbacks in the case where SndFileStream is used by an ARM app (eg. Blazer) or by a 68K app.

In playback mode, it means that the file has completely played. In recording mode, it means that it reaches the recording limit.

Definition at line 175 of file palmOneSndFileStream.h.

#define SndFileStreamOpenLibrary ( refNum,
err   ) 

Value:

{                                                           \
        Boolean loaded;                                         \
                                                                \
        loaded = false;                                         \
        (err) = SysLibFind( kSndFileStreamLibName, &(refNum) ); \
        if ( sysErrLibNotFound == (err) )                       \
        {                                                       \
            (err) = SysLibLoad( kSndFileStreamLibType,          \
                kSndFileStreamLibCreator, &(refNum) );          \
            loaded = true;                                      \
        }                                                       \
                                                                \
        if ( errNone == (err) )                                 \
        {                                                       \
            (err) = SndFileStreamLibOpen( (refNum) );           \
            if ( errNone != (err) )                             \
            {                                                   \
                if ( loaded )                                   \
                {                                               \
                    SysLibRemove( (refNum) );                   \
                }                                               \
                                                                \
                (refNum) = sysInvalidRefNum;                    \
            }                                                   \
        }                                                       \
        else                                                    \
        {                                                       \
            (refNum) = sysInvalidRefNum;                        \
        }                                                       \
    }

Definition at line 84 of file palmOneSndFileStream.h.

Typedef Documentation

typedef enum tagSndFileFormatEnum SndFileFormatType

Sound file format

The sound file format of the stream.

typedef Err(*) SndFileStreamCallbackPtr(SndFileStreamRef stream, SndFileStreamDataPtr streamDataP, Boolean *customDataModified)

Callback function passed when calling SndFileStreamCreate() and SndFileStreamOpen(). It will be called during playback and recording.

Parameters:
stream,: IN: Reference to stream returned by SndFileStreamCreate()/SndFileStreamOpen().
streamDataP,: IN:
See also:
SndFileStreamData
Parameters:
customDataModified,: OUT: If true, custom data has been modified.
Return values:
Err Error code.

Definition at line 253 of file palmOneSndFileStream.h.

typedef struct tagSndFileStreamData SndFileStreamData

Holds data about a sound file stream.

typedef struct tagSndFileStreamData * SndFileStreamDataPtr

Holds data about a sound file stream.

typedef struct tagSndFileStreamFileSpec SndFileStreamFileSpec

Descriptions of the stream file.

Used with SndFileStreamCreate()/SndFileStreamOpen()

typedef struct tagSndFileStreamFileSpec * SndFileStreamFileSpecPtr

Descriptions of the stream file.

Used with SndFileStreamCreate()/SndFileStreamOpen()

typedef struct tagSndFileStreamHsSoundCommandParam SndFileStreamHsSoundCommandParam

SndFileStreamDeviceControl param when cmd == hsSoundLibCreatorID.

Contains hsFormat/hsCmd pair to be used with PmSndStream() calls.

typedef struct tagSndFileStreamHsSoundCommandParam * SndFileStreamHsSoundCommandParamPtr

SndFileStreamDeviceControl param when cmd == hsSoundLibCreatorID.

Contains hsFormat/hsCmd pair to be used with PmSndStream() calls.

typedef void* SndFileStreamRef

Reference to sound file stream returned by SndFileStreamCreate()/Open()

Definition at line 206 of file palmOneSndFileStream.h.

Enumeration Type Documentation

enum tagSndFileFormatEnum

Sound file format

The sound file format of the stream.

Enumerator:
kSndFileFormatRaw  Raw bytes.
kSndFileFormatWAV  RIFF-WAVE.
kSndFileFormatTreoQCP  RIFF-QLCM.
kSndFileFormatTreoAMR  Raw RTP packets.
kSndFileFormatMP3  MP3 format
kSndFileFormatAAC  AAC format

Definition at line 194 of file palmOneSndFileStream.h.

00195 {
00196     kSndFileFormatRaw = 0,  /**<Raw bytes. */
00197     kSndFileFormatWAV,      /**<RIFF-WAVE. */
00198     kSndFileFormatTreoQCP,  /**<RIFF-QLCM. */
00199     kSndFileFormatTreoAMR,  /**<Raw RTP packets. */
00200     kSndFileFormatMP3,      /**<MP3 format */
00201     kSndFileFormatAAC       /**<AAC format */
00202 }

Function Documentation

Err SndFileStreamClose ( UInt16  libRefNum,
SndFileStreamRef  stream 
)

Close the reference to the file stream.

Parameters:
libRefNum,: IN: Library reference number
stream,: IN: Reference to the sound stream, returned when creating/opening file stream.
Return values:
Err Error code.

Err SndFileStreamCreate ( UInt16  libRefNum,
SndFileStreamRef *  streamP,
SndFileStreamDataPtr  streamDataP,
SndFileStreamFileSpecPtr  fileSpecP,
SndFileStreamCallbackPtr  callbackP 
)

Create a new sound file stream.

Parameters:
libRefNum,: IN: Library reference number
streamP,: OUT: Reference to the created sound stream
streamDataP,: IN:
See also:
SndFileStreamData
Parameters:
fileSpecP,: IN: Description of the file to be created
callbackP,: IN: User defined callback function, to be called on playback/recording.
Return values:
Err Error code.

Err SndFileStreamDeviceControl ( UInt16  libRefNum,
SndFileStreamRef  stream,
Int32  cmd,
void *  param,
Int32  size 
)

Control device when streaming.

Parameters:
libRefNum,: IN: Library reference number
stream,: IN: Reference to the sound stream, returned when creating/opening stream.
cmd,: IN: No definition.
param,: IN: No definition.
size,: IN: No definition.
Return values:
Err Error code.

Err SndFileStreamGetCurrentStreamData ( UInt16  libRefNum,
SndFileStreamRef  stream,
SndFileStreamDataPtr  streamDataP 
)

Get streaming data.

Parameters:
libRefNum,: IN: Library reference number
stream,: IN: Reference to the sound stream, returned when creating/opening stream.
streamDataP,: OUT:
See also:
SndFileStreamData
Return values:
Err Error code.

Err SndFileStreamGetPan ( UInt16  libRefNum,
SndFileStreamRef  stream,
Int32 *  panPositionP 
)

Get stereo balance. See SndStreamGetPan() documented under Palm OS Sound Manager API.

Parameters:
libRefNum,: IN: Library reference number
stream,: IN: Reference to the sound stream.
panPositionP,: OUT: Range [-1024, 1024]
Return values:
Err Error code.

Err SndFileStreamGetVolume ( UInt16  libRefNum,
SndFileStreamRef  stream,
Int32 *  volumeP 
)

See SndStreamGetVolume() documented under Palm OS Sound Manager API.

Parameters:
libRefNum,: IN: Library reference number
stream,: IN: Reference to the sound stream, returned when creating/opening stream.
volumeP,: OUT: Range 0 - 32k. See Palm OS SoundMgr API documentation for more details.
Return values:
Err Error code.

Err SndFileStreamLibClose ( UInt16  libRefNum  ) 

Closes the Sound File Stream library.

Parameters:
libRefNum,: IN: Library reference number
Return values:
Err Error code.

Err SndFileStreamLibOpen ( UInt16  libRefNum  ) 

Opens the Sound File Stream library.

Parameters:
libRefNum,: IN: Library reference number
Return values:
Err Error code.

Err SndFileStreamLibSleep ( UInt16  libRefNum  ) 

Standard library sleep routine.

Parameters:
libRefNum,: IN: Library reference number
Return values:
Err Error code.

Err SndFileStreamLibVersion ( UInt16  libRefNum,
UInt32 *  versionP 
)

Retrieve the library version number.

Parameters:
libRefNum,: IN: Library reference number
*versionP,: OUT: Library version number.
Return values:
Err Error code.

Err SndFileStreamLibWake ( UInt16  libRefNum  ) 

Standard library wake routine.

Parameters:
libRefNum,: IN: Library reference number
Return values:
Err Error code.

Err SndFileStreamOpen ( UInt16  libRefNum,
SndFileStreamRef *  streamP,
SndFileStreamDataPtr  streamDataP,
SndFileStreamFileSpecPtr  fileSpecP,
SndFileStreamCallbackPtr  callbackP 
)

Open an already existing sound file stream.

Parameters:
libRefNum,: IN: Library reference number
streamP,: OUT: Reference to the opened sound stream.
streamDataP,: IN:
See also:
SndFileStreamData
Parameters:
fileSpecP,: IN: Description of the file to be opened.
callbackP,: IN: User defined callback function, to be called on playback/recording.
Return values:
Err Error code.

Err SndFileStreamPause ( UInt16  libRefNum,
SndFileStreamRef  stream,
Boolean  pause 
)

Pause sound streaming.

Parameters:
libRefNum,: IN: Library reference number
stream,: IN: Reference to the sound stream, returned when creating/opening stream.
pause,: IN: If true, pause. Otherwise, resume.
Return values:
Err Error code.

Err SndFileStreamSeek ( UInt16  libRefNum,
SndFileStreamRef  stream,
UInt32  seekMilliseconds 
)

Move the pointer to the stream to a user-defined offset.

Parameters:
libRefNum,: IN: Library reference number
stream,: IN: Reference to the sound stream, returned when creating/opening stream.
seekMilliseconds IN: Offset in milliseconds.
Return values:
Err Error code.

Err SndFileStreamSetPan ( UInt16  libRefNum,
SndFileStreamRef  stream,
Int32  panPosition 
)

Set stereo balance. See SndStreamSetPan() documented under Palm OS Sound Manager API.

Parameters:
libRefNum,: IN: Library reference number
stream,: IN: Reference to the sound stream.
panPosition,: IN: Range [-1024, 1024]
Return values:
Err Error code.

Err SndFileStreamSetVolume ( UInt16  libRefNum,
SndFileStreamRef  stream,
Int32  volume 
)

See SndStreamSetVolume() documented under Palm OS Sound Manager API.

Parameters:
libRefNum,: IN: Library reference number
stream,: IN: Reference to the sound stream, returned when creating/opening stream.
volume,: IN: No definition.
Return values:
Err Error code.

Err SndFileStreamStart ( UInt16  libRefNum,
SndFileStreamRef  stream 
)

Start streaming sound into file.

Parameters:
libRefNum,: IN: Library reference number
stream,: IN: Reference to the sound stream, returned when creating/opening stream.
Return values:
Err Error code.

Err SndFileStreamStop ( UInt16  libRefNum,
SndFileStreamRef  stream 
)

Stop sound streaming.

Parameters:
libRefNum,: IN: Library reference number
stream,: IN: Reference to the sound stream, returned when creating/opening stream.
Return values:
Err Error code.

Err SndFileStreamUIPlay ( UInt16  libRefNum,
SndFileStreamFileSpecPtr  fileSpecP,
Boolean  allowRerecord 
)

Play sound stream with UI

Parameters:
libRefNum,: IN: Library reference number
fileSpecP,: IN: Pointer to the sound file to be played.
allowRerecord,: IN: No definition.
Return values:
Err Error code.

Err SndFileStreamUIRecord ( UInt16  libRefNum,
SndFileStreamDataPtr  streamDataP,
SndFileStreamFileSpecPtr  fileSpecP,
Boolean  allowRerecord 
)

Record sound stream with UI

Parameters:
libRefNum,: IN: Library reference number
streamDataP,: IN: Stream data to be used for recording.
fileSpecP,: IN: Pointer to the sound file to be recorded.
allowRerecord,: IN: No definition.
Return values:
Err Error code.

Top Palm Developer Network
© 2004-2008, Palm, Inc. All rights reserved.
Generated on Fri Jun 13 10:07:55 2008 for Palm API Guide