This chapter describes the session management API in the Multimedia Library. It covers:
Multimedia Session Structures and Types
Multimedia Session Constants
Multimedia Session Launch Codes
Multimedia Session Functions and Macros
Application-Defined Functions
The header files MMSession.h
and MMSessionClass.h
declare the API that this chapter describes.
Multimedia Session Structures and Types
MMSessionEvent Struct
Purpose
Defines a notification that an event has occurred.
Declared In
MMSession.h
Prototype
typedef struct MMSessionEventTag { MMSessionID sessionRef; MMEvent eventCode; int32_t eventCause; } MMSessionEvent
Fields
-
sessionRef
- The session's unique identifier.
-
eventCode
- Identifies the event that occurred. This is one of the Session Notifications.
-
eventCause
- Identifies the cause of the event. This is one of the Session Event Causes.
Comments
This structure defines the parameter block for the sysAppLaunchCmdMultimediaEvent
launch code and an event for the MMSessionCallbackFn()
callback function.
Multimedia Session Constants
Camera Flash Mode Values Enum
Purpose
Flash modes for a digital camera, used as a value for the P_MM_SOURCE_PROP_CAMERA_FLASH_MODE property key. These constants specify whether the camera uses a flash when taking a picture.
Declared In
MMSession.h
Constants
-
P_MM_FLASH_MODE_OFF
- Never use flash.
-
P_MM_FLASH_MODE_AUTO
- Automatically detect when a flash is needed.
-
P_MM_FLASH_MODE_FRONT
- Fill flash mode, which illuminates the front part of the image.
-
P_MM_FLASH_MODE_SLOW
- Slow synchronization flash mode, which preserves the background.
-
P_MM_FLASH_MODE_REAR
- Rear flash mode. Flashes at the end of the picture. Useful for action shots.
Camera Focus Values Enum
Purpose
Specifies the focus for a camera. Values for the P_MM_SOURCE_PROP_CAMERA_FOCUS property key.
Declared In
MMSession.h
Constants
Camera Property Key Constants
Purpose
Constants used to identify properties within a source that represents a camera. The descriptions below explain the value stored for the key and give the type for the value.
Declared In
MMSession.h
Constants
-
#define P_MM_SOURCE_PROP_CAMERA_APERTURE (P_MM_SOURCE_PROP_BASE | 0x0012L)
- The camera's aperture as a 32-bit integer.
-
#define P_MM_SOURCE_PROP_CAMERA_EXPOSURE (P_MM_SOURCE_PROP_BASE | 0x0010L)
- A 32-bit integer specifying the reciprocal of the exposure in seconds or the constant
P_MM_EXPOSURE_AUTO
. -
#define P_MM_SOURCE_PROP_CAMERA_EXPOSURE_SCALE (P_MM_SOURCE_PROP_BASE | 0x0011L)
- A 32-bit integer by which the exposure is modified.
-
#define P_MM_SOURCE_PROP_CAMERA_FLASH_MODE (P_MM_SOURCE_PROP_BASE | 0x0013L)
- One of the Camera Flash Mode Values.
-
#define P_MM_SOURCE_PROP_CAMERA_FOCUS (P_MM_SOURCE_PROP_BASE | 0x0016L)
- One of the Camera Focus Values.
-
#define P_MM_SOURCE_PROP_CAMERA_ISO_SENSITIVITY (P_MM_SOURCE_PROP_BASE | 0x0018L)
- A 32-bit integer specifying an ISO ASA number or the constant
P_MM_ISO_SENSITIVITY_AUTO
. -
#define P_MM_SOURCE_PROP_CAMERA_RED_EYE_REDUCTION (P_MM_SOURCE_PROP_BASE | 0x0014L)
- A Boolean value specifying whether red-eye reduction is on or off.
-
#define P_MM_SOURCE_PROP_CAMERA_WHITE_BALANCE (P_MM_SOURCE_PROP_BASE | 0x0015L)
- One of the Camera White Balance Values.
-
#define P_MM_SOURCE_PROP_CAMERA_ZOOM (P_MM_SOURCE_PROP_BASE | 0x0017L)
- A 32-bit integer specifying the zoom level.
Camera White Balance Values Enum
Purpose
White balance values for digital camera, values for the P_MM_SOURCE_PROP_CAMERA_WHITE_BALANCE property key. White balance adjusts the color synchronization for various lighting conditions.
Declared In
MMSession.h
Constants
-
P_MM_WHITE_BALANCE_AUTO
- Automatically adjust white balance.
-
P_MM_WHITE_BALANCE_INDOOR
- Indoor lighting.
-
P_MM_WHITE_BALANCE_OUTDOOR
- Outdoor lighting.
-
P_MM_WHITE_BALANCE_FLUORESCENT
- Fluorescent lighting.
Default Session Class IDs
Purpose
Used to identify default session classes within the Movie Server.
Declared In
MMSessionClass.h
Constants
-
#define P_MM_SESSION_CLASS_DEFAULT_CAPTURE (P_MM_STANDARD_SESSION_CLASS_BASE | 0x0002L)
- The class ID for the default recording (capture) session class.
-
#define P_MM_SESSION_CLASS_DEFAULT_PLAYBACK (P_MM_STANDARD_SESSION_CLASS_BASE | 0x0001L)
- The class ID for the default playback session class.
See Also
Default URLs
Purpose
Default URLs used to instantiate sources or destinations within a session.
Declared In
MMSession.h
Constants
-
#define P_MM_NULL_URL "palmdev:///Media/Null"
- Represents no device.
-
#define P_MM_DEFAULT_AUDIO_CAPTURE_URL "palmdev:///Media/Default/AudioIn"
- Any audio recording device.
-
#define P_MM_DEFAULT_AUDIO_RENDER_URL "palmdev:///Media/Default/AudioOut"
- Any audio playback device.
-
#define P_MM_DEFAULT_STILL_CAPTURE_URL "palmdev:///Media/Default/StillIn"
- Any still capture input (such as a camera).
-
#define P_MM_DEFAULT_VIDEO_CAPTURE_URL "palmdev:///Media/Default/VideoIn"
- Any video recording device.
-
#define P_MM_DEFAULT_VIDEO_RENDER_URL "palmdev:///Media/Default/VideoOut"
- Any video playback device.
Comments
The CAPTURE_URLs
instantiate a Movie Server object that represents the source of recorded input, and the RENDER_URLs
instantiate a Movie Server object that represents the destination for recorded material, within the default recording sessions. In playback sessions, the RENDER_URLs
instantiate a Movie Server object that represents the destination for played content.
See Also
MMSessionAddDest()
, MMSessionAddSource()
Destination Property Key Constants
Purpose
Constants used to identify properties in a destination object. The descriptions below explain the value for each key and give the type for the value.
Declared In
MMSession.h
Constants
-
#define P_MM_DEST_PROP_FILE_FORMAT (P_MM_DEST_PROP_BASE | 0x0002L)
- An
MMFormat
type specifying the format written to the destination object. -
#define P_MM_DEST_PROP_URL (P_MM_DEST_PROP_BASE | 0x0001L)
- A string representing the URL used to create a destination object.
ISO Sensitivity Value Enum
Purpose
Possible value for the camera's ISO sensitivity level.
Declared In
MMSession.h
Constants
Miscellaneous Session Constants
Purpose
Other constants defined in MMSession.h
.
Declared In
MMSession.h
Constants
-
#define P_MM_EXPOSURE_AUTO 0
- Automatically adjust the exposure for a camera. This is a possible value for the property
P_MM_SOURCE_PROP_CAMERA_EXPOSURE
. -
#define P_MM_DEFAULT_DEST 0
- Specifies a default destination device should be instantiated.
-
#define P_MM_DEFAULT_SOURCE 0
- Specifies a default source device should be instantiated.
MMSessionControlOpcode Typedef
Purpose
Session control operation codes. A multimedia client application sends these to the session object to have the session perform an action.
Declared In
MMDefs.h
Prototype
typedef int32_t MMSessionControlOpcode
Constants
-
P_MM_SESSION_CTL_RUN = 0x01
- Start or continue recording or playback.
-
P_MM_SESSION_CTL_PAUSE = 0x02
- Pause recording or playback.
-
P_MM_SESSION_CTL_STOP = 0x03
- Stop recording or playback.
-
P_MM_SESSION_CTL_PREFETCH = 0x04
- Begin buffering data from the source.
-
P_MM_SESSION_CTL_GRAB = 0x05
- Grab a still image from a video playback or recording session.
-
P_MM_SESSION_CTL_REFRESH = 0x06
- Refresh the display.
-
P_MM_SESSION_CTL_CUSTOM_BASE = 0x1000
- Base value where a licensee can add its own control op codes.
See Also
MMSessionState Typedef
Purpose
Constants that describe the session object state.
Declared In
MMDefs.h
Prototype
typedef int32_t MMSessionState
Constants
-
P_MM_SESSION_NOT_INITIALIZED = 0x01
- The session exists but has not been initialized with the information it needs to playback or record.
-
P_MM_SESSION_READY = 0x02
- The session has been initialized and is ready to begin.
MMSessionFinalize()
puts the session in this state. -
P_MM_SESSION_PREFETCHING = 0x03
- The session is buffering data.
-
P_MM_SESSION_PAUSED = 0x04
- The session has been paused.
-
P_MM_SESSION_RUNNING = 0x05
- The session has begun.
See Also
Session Class Constants Enum
Purpose
Defines values for the high-order 16 bits of a session class ID.
Declared In
MMSessionClass.h
Constants
-
P_MM_STANDARD_SESSION_CLASS_BASE = 0x10010000L
- The high-order bits for a PalmSource-defined session class ID.
-
P_MM_USER_SESSION_CLASS_BASE = 0x10020000L
- The high-order bits for a licensee-defined session class ID.
-
P_MM_PRIVATE_SESSION_CLASS_BASE = 0x10030000L
- A private session class ID defined by either PalmSource or one of its licensees.
Comments
The function MMSessionClassEnumerate()
returns a list of all standard and user sessions. It never enumerates the private classes. Declaring a session class as private is useful if it is tightly integrated with the application that uses it.
Session Class Properties
Purpose
Defines property keys that can be used to access information about a session class.
Declared In
MMSessionClass.h
-
#define P_MM_SESSION_CLASS_PROP_CREATOR (P_MM_SESSION_CLASS_PROP_BASE | 0x0003L)
- The session class's creator ID.
-
#define P_MM_SESSION_CLASS_PROP_NAME (P_MM_SESSION_CLASS_PROP_BASE | 0x0001L)
- The session's name.
-
#define P_MM_SESSION_CLASS_PROP_VERSION (P_MM_SESSION_CLASS_PROP_BASE | 0x0002L)
- The session's version number.
Session Creation Constants Enum
Purpose
Used in the MMSessionCreate()
function to determine where to create the session.
Declared In
MMSession.h
Constants
-
P_MM_SESSION_CREATE_ANY_PROCESS
- Creates a session in any process. The Movie Server typically creates the session in the Background process.
-
P_MM_SESSION_CREATE_LOCAL_PROCESS
- Creates a session in the local process.
Session Default Property Key Constants
Purpose
Property keys for session default properties. These are passed to a track when a track is added to a session. The descriptions below explain the value for each key and give the type for the value.
Declared In
MMSession.h
Constants
-
#define P_MM_SESSION_DEFAULT_AUDIO_ENABLE (P_MM_SESSION_PROP_BASE | 0x0020L)
- Boolean that specifies whether an audio track is enabled or disabled.
-
#define P_MM_SESSION_DEFAULT_AUDIO_VOLUME (P_MM_SESSION_PROP_BASE | 0x0024L)
- A 32-bit integer specifying the volume level.
-
#define P_MM_SESSION_DEFAULT_DEST_RECT (P_MM_SESSION_PROP_BASE | 0x0023L)
- The default destination rectangle to use for a video frame. The rectangle specifies both the position and the size.
-
#define P_MM_SESSION_DEFAULT_SOURCE_RECT (P_MM_SESSION_PROP_BASE | 0x0022L)
- The default source rectangle to use for a video frame. The rectangle specifies both the position and the size.
-
#define P_MM_SESSION_DEFAULT_VIDEO_ENABLE (P_MM_SESSION_PROP_BASE | 0x0021L)
- A Boolean value specifying whether a video track should be enabled.
Session Property Key Constants
Purpose
Constants used to identify properties stored in a session. The descriptions below explain the value for each key and give the type for the value.
Declared In
MMSession.h
Constants
-
#define P_MM_SESSION_PROP_CURRENT_TIME (P_MM_SESSION_PROP_BASE | 0x0002L)
- Current recording or playback position given in nanoseconds. The value is a 64-bit signed integer.
-
#define P_MM_SESSION_PROP_END_TIME (P_MM_SESSION_PROP_BASE | 0x0008L)
- Ending playback position given in nanoseconds. The value is a 64-bit signed integer.
-
#define P_MM_SESSION_PROP_IS_LOCAL (P_MM_SESSION_PROP_BASE | 0x0005L)
- A Boolean specifying if the session is running local to the application process.
-
#define P_MM_SESSION_PROP_MARKER (P_MM_SESSION_PROP_BASE | 0x0006L)
- A
nsecs_t
value specifying a marker within a track. -
#define P_MM_SESSION_PROP_PLAYBACK_RATE (P_MM_SESSION_PROP_BASE | 0x0003L)
- A 16-bit integer specifying the audio playback rate, where 1 specifies normal speed, 2 double speed, and so on.
-
#define P_MM_SESSION_PROP_PREFETCH_TIME (P_MM_SESSION_PROP_BASE | 0x0004L)
- The amount of data, given in nanoseconds, to buffer.
-
#define P_MM_SESSION_PROP_PUBLIC (P_MM_SESSION_PROP_BASE | 0x0001L)
- A Boolean value of
true
if the session is public orfalse
if it is private. -
#define P_MM_SESSION_PROP_REPEAT_ENABLE (P_MM_SESSION_PROP_BASE | 0x0009L)
- A Boolean that indicates that playback should repeat when the end time is reached.
-
#define P_MM_SESSION_PROP_SESSION_CLASS (P_MM_SESSION_PROP_BASE | 0x000AL)
- A 32-bit integer ID of the session class used.
-
#define P_MM_SESSION_PROP_START_TIME (P_MM_SESSION_PROP_BASE | 0x0007L)
- Starting playback position given in nanoseconds. The value is a 64-bit signed integer.
Source Property Key Constants
Purpose
Constants used to identify properties within a source. The descriptions below explain the value for each key and give the type for the value.
Declared In
MMSession.h
-
#define P_MM_SOURCE_PROP_FILE_FORMAT (P_MM_SOURCE_PROP_BASE | 0x0002L)
- An
MMFormat
specifying the format that the source produces. -
#define P_MM_SOURCE_PROP_URL (P_MM_SOURCE_PROP_BASE | 0x0001L)
- A string representing the URL used to create a source.
- Set to the empty string.
Stream Content Keys
Purpose
Keys set for an audio or video stream property set.
Declared In
MMSession.h
Constants
-
#define P_MM_CONTENT_PROP_ALBUM (P_MM_CONTENT_PROP_BASE | 0x0006L)
- String containing the album or CD for a track.
-
#define P_MM_CONTENT_PROP_ARTIST (P_MM_CONTENT_PROP_BASE | 0x0003L)
- String containing the artist that recorded a track.
-
#define P_MM_CONTENT_PROP_DURATION (P_MM_CONTENT_PROP_BASE | 0x0001L)
- An
int32_t
describing the length of a track in milliseconds. -
#define P_MM_CONTENT_PROP_GENRE (P_MM_CONTENT_PROP_BASE | 0x0005L)
- String containing the genre of a track.
-
#define P_MM_CONTENT_PROP_PLAYLIST (P_MM_CONTENT_PROP_BASE | 0x0004L)
- String containing the play list for a track.
-
#define P_MM_CONTENT_PROP_TITLE (P_MM_CONTENT_PROP_BASE | 0x0002L)
- String containing the title of a track.
-
#define P_MM_CONTENT_PROP_TRACK_NUMBER (P_MM_CONTENT_PROP_BASE | 0x0007L)
- An
int32_t
giving the track number within the album or CD.
Comments
Both playback and recording sessions in the Movie Server set these keys, and they are written to encoded output. The descriptions explain the value for each key and give the type for the value.
A given codec may not support all of these properties. Currently, only the PalmSource MPEG audio extractor supports these properties, but other third-party codecs may also support them.
Stream Property Key Constants
Purpose
Constants used to identify properties in a stream object. The descriptions below explain the value for each key and give the type for the value.
Declared In
MMSession.h
Constants
-
#define P_MM_STREAM_PROP_FORMAT (P_MM_STREAM_PROP_BASE | 0x0001L)
- An
MMFormat
specifying the stream's format. -
#define P_MM_STREAM_PROP_IS_PREVIEW (P_MM_STREAM_PROP_BASE | 0x0003L)
- A Boolean value that, if
true
, identifies the stream as a preview stream. -
#define P_MM_STREAM_PROP_LANGUAGE (P_MM_STREAM_PROP_BASE | 0x0002L)
- A string specifying the language of the stream.
Multimedia Session Launch Codes
sysAppLaunchCmdMultimediaEvent
Purpose
Sent when multimedia session events occur.
Declared In
CmnLaunchCodes.h
Prototype
Parameters
The launch code's parameter block pointer references a MMSessionEvent
structure.
Comments
Some applications may need to be informed of events relating to a persistent session, even when the application is no longer running. You can use the function MMSessionRegisterLaunch()
to register an application to be associated with a session. When session events occur, that application is sublaunched with this launch command.
Multimedia Session Functions and Macros
MMDestEnumerateStreams Function
Purpose
Enumerates the streams available in a destination object.
Declared In
MMSession.h
Prototype
status_t MMDestEnumerateStreams ( MMDestIDdest
, int32_t*ioIterator
, MMStreamID*outStream
)
Parameters
-
→ dest
- A valid multimedia destination object ID.
-
↔ ioIterator
- Pointer to the value returned by the previous call to this function. On the first call to this function, set this value to
P_MM_ENUM_BEGIN
. When the set of iterated values is exhausted, this function sets this value toP_MM_ENUM_END
. -
← outStream
- Pointer to the ID of the next stream in the set. The stream ID remains valid until the session is deleted or
MMSessionRemoveAll()
is called.
Returns
-
errNone
- No error.
-
sysErrParamErr
- One of input parameters is invalid.
-
sysErrBadIndex
- The iterator value is invalid or past the last item in the set.
Comments
Before calling this function, the destination object must be finalized by calling MMDestFinalize()
.
MMDestFinalize Function
Purpose
Opens the given destination and creates streams.
Declared In
MMSession.h
Prototype
status_t MMDestFinalize (
MMDestID dest
)
Parameters
Returns
Other multimedia errors can also be returned.
Comments
On success, the streams may be enumerated with MMDestEnumerateStreams()
.
MMSessionAcquireOwnership Function
Purpose
Makes the calling process acquire ownership of a session.
Declared In
MMSession.h
Prototype
status_t MMSessionAcquireOwnership (
MMSessionID session
)
Parameters
-
→ session
- A valid multimedia session ID, on which
MMSessionReleaseOwnership()
was previously called.
Returns
-
errNone
- No error.
-
sysErrParamErr
- The session is invalid.
-
sysErrNotAllowed
- The session is owned by another process.
Comments
The session must not be owned by another process.
The session will be deleted automatically when the acquiring process exits.
MMSessionAddDefaultTracks Function
Purpose
Adds all tracks applicable to this session, using the given source and/or destination.
Declared In
MMSession.h
Prototype
status_t MMSessionAddDefaultTracks ( MMSessionIDsession
, MMSourceIDsource
, MMDestIDdest
)
Parameters
-
→ session
- A valid multimedia session ID.
-
→ source
- A valid multimedia source ID, or
P_MM_DEFAULT_SOURCE
. -
→ dest
- A valid multimedia destination ID, or
P_MM_DEFAULT_DEST
.
Returns
Comments
A playback session can use this function to add all of the tracks that it can play concurrently.
After a call to this function succeeds, the caller can use MMSessionEnumerateTracks()
to inspect the created tracks and further configure them prior to calling MMSessionFinalize()
.
If P_MM_DEFAULT_SOURCE
or P_MM_DEFAULT_DEST
are passed for source or destination, sources and/or destinations will be added and finalized as necessary. The caller can use MMSessionEnumerateSources()
and MMSessionEnumerateDests()
to retrieve source and destination IDs for those objects.
See Also
MMSessionAddTrack()
, MMSessionRemoveTracks()
MMSessionAddDest Function
Purpose
Adds a data destination to the session.
Declared In
MMSession.h
Prototype
status_t MMSessionAddDest ( MMSessionIDsession
, const char*destURL
, MMDestID*outDest
)
Parameters
-
→ session
- A valid multimedia session ID.
-
→ destURL
- Pointer to a URL of the destination to add to the session.
-
← outDest
- Pointer to a valid multimedia destination ID, if the function succeeds.
Returns
-
errNone
- No error.
-
sysErrParamErr
- The session or the URL is invalid.
-
sysErrUnsupported
- No more destinations may be added to this session.
Comments
Some session classes may expose additional destination properties that can be set before calling MMDestFinalize()
to open the destination and create streams.
See Also
MMSessionAddSource Function
Purpose
Adds a data source to the session.
Declared In
MMSession.h
Prototype
status_t MMSessionAddSource ( MMSessionIDsession
, const char*sourceURL
, MMSourceID*outSource
)
Parameters
-
→ session
- A valid multimedia session ID.
-
→ sourceURL
- Pointer to a URL of the data source to add to the session.
-
← outSource
- Pointer to the multimedia source ID, if the function succeeds.
Returns
-
errNone
- No error.
-
sysErrParamErr
- The session or the URL is invalid.
-
sysErrUnsupported
- No more source may be added to this session.
Comments
Some session classes may expose additional source properties that can be set before calling MMSourceFinalize()
to open the source and create streams.
See Also
MMSessionAddTrack Function
Purpose
Declared In
MMSession.h
Prototype
status_t MMSessionAddTrack ( MMSessionIDsession
, MMStreamIDsourceStream
, MMFormatsourceFormat
, MMStreamIDdestStream
, MMFormatdestFormat
, MMTrackID*outTrack
)
Parameters
-
→ session
- A valid multimedia session ID.
-
→ sourceStream
- A valid multimedia source ID.
-
→ sourceFormat
- A valid source media format ID, or
P_MM_INVALID_FORMAT
. -
→ destStream
- A valid multimedia destination ID.
-
→ destFormat
- A valid destination media format ID, or
P_MM_INVALID_FORMAT
. -
← outTrack
- Pointer to the multimedia track ID for the created track, if the function succeeds.
Returns
Comments
A track represents a particular data-processing route, which, depending on the session class, may be used for playback (rendering) or capture (storage to a local file or network stream).
See Also
MMSessionAddDefaultTracks()
, MMSessionEnumerateTracks()
, MMSessionRemoveTracks()
MMSessionClassEnumerate Function
Purpose
Iterates through the available session classes.
Declared In
MMSessionClass.h
Prototype
status_t MMSessionClassEnumerate ( int32_t*ioIterator
, MMSessionClassID*outSessionClassID
)
Parameters
-
↔ ioIterator
- Pointer to the value returned by the previous call to this function. On the first call to this function, set this value to
P_MM_ENUM_BEGIN
. When the set of iterated values is exhausted, this function sets this value toP_MM_ENUM_END
. -
← outSessionClassID
- Pointer to the ID of the next available session class.
Returns
-
errNone
- No error.
-
sysErrParamErr
- The iterator is invalid.
-
sysErrBadIndex
- The iterator value is invalid or past the last item in the set.
MMSessionControl Function
Purpose
Sends control opcodes to the Movie Server for playback, capture, and preview.
Declared In
MMSession.h
Prototype
status_t MMSessionControl ( MMSessionIDsession
, MMSessionControlOpcodesessionCtl
)
Parameters
-
→ session
- A valid multimedia session ID.
-
→ sessionCtl
- The opcode. Specify one of the constants listed in "MMSessionControlOpcode."
Returns
-
errNone
- No error.
-
sysErrParamErr
- The session is invalid.
-
sysErrNotAllowed
- Operation not allowed for this session.
See Also
MMSessionCreate Function
Purpose
Declared In
MMSession.h
Prototype
status_t MMSessionCreate ( MMSessionClassIDsessionClass
, int32_tflags
, MMSessionID*outSession
)
Parameters
-
→ sessionClass
- A valid multimedia session class ID. Specify one of the constants listed in "Default Session Class IDs."
-
→ flags
- Flag that determines in what process to create the session. Specify one of the constants listed in "Session Creation Constants."
-
↔ outSession
- A valid multimedia session ID, if the function succeeds. On input, this must be 0.
Returns
-
errNone
- No error.
-
sysErrParamErr
- The
outSession
parameter is not 0 on input. -
sysErrNoFreeResource
- Operation not allowed for this session.
See Also
MMSessionDelete Function
Purpose
Declared In
MMSession.h
Prototype
status_t MMSessionDelete (
MMSessionID session
)
Parameters
Returns
Comments
On success, session
will no longer be valid.
See Also
MMSessionEnumerate Function
Purpose
Iterates through the current public sessions (only the sessions for which the value of P_MM_SESSION_PROP_PUBLIC
is nonzero).
Declared In
MMSession.h
Prototype
status_t MMSessionEnumerate ( int32_t*ioIterator
, MMSessionID*outSession
)
Parameters
-
↔ ioIterator
- Pointer to the value returned by the previous call to this function. On the first call to this function, set this value to
P_MM_ENUM_BEGIN
. When the set of iterated values is exhausted, this function sets this value toP_MM_ENUM_END
. -
← outSession
- Pointer to a valid multimedia session ID for the next session in the set.
Returns
-
errNone
- No error.
-
sysErrParamErr
- The iterator value is 0.
-
sysErrBadIndex
- The iterator value is invalid or past the last item in the set.
MMSessionEnumerateDests Function
Purpose
Iterates through the destinations in this session.
Declared In
MMSession.h
Prototype
status_t MMSessionEnumerateDests ( MMSessionIDsession
, int32_t*ioIterator
, MMDestID*outDest
)
Parameters
-
→ session
- A valid multimedia session ID.
-
↔ ioIterator
- Pointer to the value returned by the previous call to this function. On the first call to this function, set this value to
P_MM_ENUM_BEGIN
. When the set of iterated values is exhausted, this function sets this value toP_MM_ENUM_END
. -
← outDest
- Pointer to the next destination in the set. This destination ID will remain valid until the session is deleted or
MMSessionRemoveAll()
is called.
Returns
-
errNone
- No error.
-
sysErrParamErr
- The session is invalid or the iterator value is 0.
-
sysErrBadIndex
- The iterator value is invalid or past the last item in the set.
MMSessionEnumerateSources Function
Purpose
Iterates through the sources in this session.
Declared In
MMSession.h
Prototype
status_t MMSessionEnumerateSources ( MMSessionIDsession
, int32_t*ioIterator
, MMSourceID*outSource
)
Parameters
-
→ session
- A valid multimedia session ID.
-
↔ ioIterator
- Pointer to the value returned by the previous call to this function. On the first call to this function, set this value to
P_MM_ENUM_BEGIN
. When the set of iterated values is exhausted, this function sets this value toP_MM_ENUM_END
. -
← outSource
- Pointer to the next source in the set. This source ID will remain valid until the session is deleted or
MMSessionRemoveAll()
is called.
Returns
-
errNone
- No error.
-
sysErrParamErr
- The session is invalid or the iterator value is 0.
-
sysErrBadIndex
- The iterator value is invalid or past the last item in the set.
MMSessionEnumerateTracks Function
Purpose
Iterates through the tracks in this session.
Declared In
MMSession.h
Prototype
status_t MMSessionEnumerateTracks ( MMSessionIDsession
, int32_t*ioIterator
, MMTrackID*outTrack
)
Parameters
-
→ session
- A valid multimedia session ID.
-
↔ ioIterator
- Pointer to the value returned by the previous call to this function. On the first call to this function, set this value to
P_MM_ENUM_BEGIN
. When the set of iterated values is exhausted, this function sets this value toP_MM_ENUM_END
. -
← outTrack
- Pointer to the next track in the set. This track ID will remain valid until the session is deleted or
MMSessionRemoveAll()
is called.
Returns
-
errNone
- No error.
-
sysErrParamErr
- The session is invalid or the iterator value is 0.
-
sysErrBadIndex
- The iterator value is invalid or past the last item in the set.
MMSessionFinalize Function
Purpose
Finalize the set of tracks for this session.
Declared In
MMSession.h
Prototype
status_t MMSessionFinalize (
MMSessionID session
)
Parameters
Returns
-
errNone
- No error.
-
sysErrParamErr
- The session is invalid.
-
sysErrBadIndex
- One or more tracks depends on a source or destination which could not be added.
Comments
Calling this function is the final step in preparing a session to run; after this call succeeds, the session enters the P_MM_SESSION_READY
state and you may call MMSessionControl()
to begin playback or capture.
After MMSessionFinalize()
is called, the following functions may not be called for the session: MMSessionAddDest()
, MMSessionAddSource()
, MMSessionAddTrack()
, and MMSessionAddDefaultTracks()
.
MMSessionGetState Function
Purpose
Returns the current state of a session.
Declared In
MMSession.h
Prototype
status_t MMSessionGetState ( MMSessionIDsession
, MMSessionState*outState
)
Parameters
-
→ session
- A valid multimedia session ID.
-
↔ outState
- The current state of the session. One of the constants listed in "MMSessionState."
Returns
MMSessionRegisterCallback Function
Purpose
Registers a callback function to monitor this session by handling events.
Declared In
MMSession.h
Prototype
status_t MMSessionRegisterCallback ( MMSessionIDsession
, MMSessionCallbackFncallback
, void*userdata
, uint32_teventFlags
)
Parameters
-
→ session
- A valid multimedia session ID.
-
→ callback
- Pointer to the callback function (for details, see
MMSessionCallbackFn()
). -
→ userdata
- Pointer to arbitrary user-provided data, or
NULL
. This pointer is passed to the callback function. -
→ eventFlags
- Unused; must be set to 0.
Returns
-
errNone
- No error.
-
sysErrParamErr
- One of the parameters is invalid.
-
sysErrNotAllowed
- There are too many callbacks registered for this session.
Comments
The Multimedia Library calls your function asynchronously, meaning that it's safe to make other multimedia calls from your function.
You can register multiple callback functions for one session.
See Also
MMSessionRegisterLaunch Function
Purpose
Registers a handler application to be sublaunched when a multimedia event occurs.
Declared In
MMSession.h
Prototype
status_t MMSessionRegisterLaunch ( MMSessionIDsession
, DatabaseIDdbID
, uint32_teventFlags
)
Parameters
-
→ session
- A valid multimedia session ID.
-
→ dbID
- Application resource database ID.
-
→ eventFlags
- Unused; must be set to 0.
Returns
Comments
The registered application will be sublaunched with the launch command sysAppLaunchCmdMultimediaEvent
, with a pointer to a MMSessionEvent
.
See Also
MMSessionReleaseOwnership Function
Purpose
Makes a multimedia session persist after the calling process exits.
Declared In
MMSession.h
Prototype
status_t MMSessionReleaseOwnership (
MMSessionID session
)
Parameters
Returns
Comments
When a session is created, and the process that created it exits, the session is automatically deleted. Call this function to make the session persist after the calling process exits. The session will persist in the background, where it is owned by the Movie Server, until it is explicitly deleted or MMSessionAcquireOwnership()
is called.
MMSessionRemoveAll Function
Purpose
Removes from a session all sources, destinations, and the tracks that connect them.
Declared In
MMSession.h
Prototype
status_t MMSessionRemoveAll (
MMSessionID session
)
Parameters
Returns
Comments
This function resets the session state to P_MM_SESSION_NOT_INITIALIZED
. Non-content properties remain unchanged.
MMSessionRemoveTracks Function
Purpose
Declared In
MMSession.h
Prototype
status_t MMSessionRemoveTracks (
MMSessionID session
)
Parameters
Returns
Comments
This function resets the session state to remove sources, destinations, and the tracks that connect them.
Existing source and destination streams may be used to create new tracks.
This function resets the session state to P_MM_SESSION_NOT_INITIALIZED
. Non-content properties remain unchanged.
See Also
MMSessionSeek Function
Purpose
Seeks to a different location in the current session.
Declared In
MMSession.h
Prototype
status_t MMSessionSeek ( MMSessionIDsession
, MMSeekOriginorigin
, int64_tposition
)
Parameters
-
→ session
- A valid multimedia session ID.
-
→ origin
- Point to seek from; the seek location is measured from this point. Specify one of the constants listed in "MMSeekOrigin."
-
→ position
- The distance to seek, in nanoseconds. A positive value means to seek forward and a negative value means to seek backward.
Returns
-
errNone
- No error.
-
sysErrParamErr
- The session is invalid.
-
sysErrOutOfRange
-
position
is out of range. -
sysErrUnsupported
- Seeking is not supported in this session; some streaming types don't support seeking, or it is a capture session.
Comments
This function skips forward or backward in the media.
After a successful seek operation the session is stopped (it enters the P_MM_SESSION_READY
state), whether or not it was playing previous to the call.
See Also
MMSessionUnregisterCallback Function
Purpose
Unregisters a callback function for a session.
Declared In
MMSession.h
Prototype
status_t MMSessionUnregisterCallback ( MMSessionIDsession
, MMSessionCallbackFncallback
, void*userdata
)
Parameters
-
→ session
- A valid multimedia session ID.
-
→ callback
- Pointer to a callback function that was previously registered by
MMSessionRegisterCallback()
. -
→ userdata
- Unused.
Returns
-
errNone
- No error.
-
sysErrParamErr
- The session is invalid.
-
sysErrBadData
- The specified callback function was not found.
MMSessionUnregisterLaunch Function
Purpose
Unregisters a registered event handler.
Declared In
MMSession.h
Prototype
status_t MMSessionUnregisterLaunch ( MMSessionIDsession
, DatabaseIDdbID
)
Parameters
-
→ session
- A valid multimedia session ID.
-
→ dbID
- Application resource database ID that was previously registered by
MMSessionRegisterLaunch()
.
Returns
-
errNone
- No error.
-
sysErrParamErr
- The session is invalid.
-
sysErrBadData
- A matching registration was not found.
MMSourceEnumerateStreams Function
Purpose
Iterates through the streams available in a source.
Declared In
MMSession.h
Prototype
status_t MMSourceEnumerateStreams ( MMSourceIDsource
, int32_t*ioIterator
, MMStreamID*outStream
)
Parameters
-
→ source
- A valid source ID.
-
↔ ioIterator
- Pointer to the value returned by the previous call to this function. On the first call to this function, set this value to
P_MM_ENUM_BEGIN
. When the set of iterated values is exhausted, this function sets this value toP_MM_ENUM_END
. -
← outStream
- Pointer to the next stream in the set. This stream ID will remain valid until the session is deleted or
MMSessionRemoveAll()
is called.
Returns
-
errNone
- No error.
-
sysErrParamErr
- The session is invalid or the iterator value is 0.
-
sysErrBadIndex
- The iterator value is invalid or past the last item in the set.
Comments
The source must be finalized for this call to succeed (MMSourceFinalize()
must have been called).
MMSourceFinalize Function
Purpose
Opens the given data source and creates streams.
Declared In
MMSession.h
Prototype
status_t MMSourceFinalize (
MMSourceID source
)
Parameters
Returns
Comments
On success, the streams may be enumerated by MMSourceEnumerateStreams()
.
Application-Defined Functions
MMSessionCallbackFn Function
Purpose
Called when multimedia events occur.
Declared In
MMSession.h
Prototype
void ( *MMSessionCallbackFn ) ( const MMSessionEvent*event
, void*userdata
)
Parameters
-
→ event
- A pointer to a multimedia event; see
MMSessionEvent
. -
→ userdata
- A pointer to the user data block passed to
MMSessionRegisterCallback()
when the callback function was registered.
Returns
Comments
To register a callback function, call MMSessionRegisterCallback()
.