Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

9    Multimedia Tracks

Multimedia

Exploring Palm OS®

This chapter describes multimedia structures, constants, and functions related to tracks:

Multimedia Track Structures and Types
Multimedia Track Constants
Multimedia Track Functions and Macros
Application-Defined Functions

The header file MMTrack.h declares the API that this chapter describes.

Multimedia Track Structures and Types ^TOP^

FilterCallbackInfo Struct ^TOP^

Purpose

Holds information about a buffer of data for which MMFilterCallbackFn() has been called.

Declared In

MMTrack.h

Prototype

typedef struct _FilterCallbackInfo {
   int64_t timeStamp;
   size_t bufferSize;
} FilterCallbackInfo

Fields

timeStamp
Timestamp of the data in nanoseconds. For a playback session, this indicates the actual position in the file, counting from 0 at the start.
Timestamps in a capture session are generated by the hardware driver and may be continuously incrementing even when no data is being captured. In this case, you should treat the value received in the first callback as the "base" value, and measure offsets from there.
bufferSize
Size of the buffer passed to the callback function, in bytes.

Multimedia Track Constants ^TOP^

Track Property Key Constants ^TOP^

Purpose

Values used to retrieve track object properties.

Declared In

MMTrack.h

Constants

#define P_MM_TRACK_PROP_CODEC_CLASS (P_MM_TRACK_PROP_BASE | 0x0008L)
The 32-bit ID of the class used for encoding or decoding data on the track.
#define P_MM_TRACK_PROP_CURRENT_TIME (P_MM_TRACK_PROP_BASE | 0x0009L)
The current location in the track stream identified as a time value in nanoseconds.
#define P_MM_TRACK_PROP_DEST (P_MM_TRACK_PROP_BASE | 0x0006L)
ID of the destination object associated with track's destination stream.
#define P_MM_TRACK_PROP_DEST_FORMAT (P_MM_TRACK_PROP_BASE | 0x0002L)
A string specifying the track's destination format.
#define P_MM_TRACK_PROP_DEST_RECT (P_MM_TRACK_PROP_BASE | 0x0031L)
The region of the screen to be drawn in native screen pixels.
#define P_MM_TRACK_PROP_DEST_STREAM (P_MM_TRACK_PROP_BASE | 0x0007L)
ID of the stream object associated with the track's destination.
#define P_MM_TRACK_PROP_ENABLE (P_MM_TRACK_PROP_BASE | 0x0003L)
Boolean that describes whether the track is enabled or disabled.
#define P_MM_TRACK_PROP_SOURCE (P_MM_TRACK_PROP_BASE | 0x0004L)
ID of the source object associated with the track.
#define P_MM_TRACK_PROP_SOURCE_FORMAT (P_MM_TRACK_PROP_BASE | 0x0001L)
A string specifying the track's source format.
#define P_MM_TRACK_PROP_SOURCE_RECT (P_MM_TRACK_PROP_BASE | 0x0030L)
The region of the source buffer to be displayed in native screen pixels.
#define P_MM_TRACK_PROP_SOURCE_STREAM (P_MM_TRACK_PROP_BASE | 0x0005L)
ID of the stream object associated with the track's source.
#define P_MM_TRACK_PROP_VOLUME (P_MM_TRACK_PROP_BASE | 0x0020L)
An integer from 0 to 1024 specifying the current volume level.

Multimedia Track Functions and Macros ^TOP^

MMTrackInsertCallbackFilter Function ^TOP^

Purpose

Registers a callback function to process data for a track.

Declared In

MMTrack.h

Prototype

status_t MMTrackInsertCallbackFilter (
   MMTrackID track,
   MMFilterCallbackFn callback,
   void *userdata
)

Parameters

track
A valid track ID.
callback
Pointer to the callback function (for details, see MMFilterCallbackFn()).
userdata
Pointer to arbitrary user-provided data, or NULL. This pointer is passed to the callback function.

Returns

The following result codes:

errNone
No error.
sysErrParamErr
One of the parameters is invalid.
sysErrNotAllowed
There is already a callback registered for this track.

Comments

Only one callback may be installed for a track.

See Also

MMTrackRemoveCallbackFilter()

MMTrackRemoveCallbackFilter Function ^TOP^

Purpose

Unregisters a callback function for a track.

Declared In

MMTrack.h

Prototype

status_t MMTrackRemoveCallbackFilter (
   MMTrackID track
)

Parameters

track
A valid track ID for which a callback function has been registered by MMTrackInsertCallbackFilter().

Returns

The following result codes:

errNone
No error.
sysErrParamErr
The track is invalid.
sysErrBadData
The specified callback function was not found.

Application-Defined Functions ^TOP^

MMFilterCallbackFn Function ^TOP^

Purpose

Called when the track receives a buffer of data.

Declared In

MMTrack.h

Prototype

void (
   *MMFilterCallbackFn
) (
    MMTrackID track,
   void *buffer,
   FilterCallbackInfo *info,
   void *userdata
)

Parameters

track
Track ID of the track for which the callback function is registered.
buffer
Pointer to a buffer of track data.
info
Pointer to a FilterCallbackInfo structure.
userdata
A pointer to the user data block passed to MMTrackInsertCallbackFilter() when the callback function was registered.

Returns

Nothing.

Comments

This function allows an application to customize functionality by processing track data somehow.

To register a filter callback function, call MMTrackInsertCallbackFilter().