mme_settrksession()

Set the current track session

Synopsis:

#include <mme/mme.h>

int mme_settrksession( mme_hdl_t *hdl,
                       uint64_t trksessionid );

Arguments:

hdl
An MME connection handle.
trksessionid
The track session ID, set by mme_newtrksession(); set to 0 to release (“unset”) the current track session.

Library:

mme

Description:

The function mme_settrksession() sets the current track session for the specified control context. Before setting the track session for a control context, you must create the track session with mme_newtrksession(). To play the track session, after you have set it, call mme_play().

A call to mme_settrksession() does the following:


Note:
  • File-based track sessions are not permanent. Their contents are lost if playback is switched to another track session.
  • Calling mme_settrksession() regenerates the list of tracks used by the MME for playback in random mode (the entries in the randomid field of the trksessionview table).

Preventing playback interruption

In order to not interrupt playback, mme_settrksession() will fail (return -1 and set errno to ECANCELED) if:

or if:

Client applications have several options for handling situations where mme_settrksession() cannot switch track sessions. These include:

Using mme_settrksession() to resume playback

If you have stopped a track session and want to use mme_trksession_resume_state() to resume playback, you must call mme_settrksession() before calling mme_trksession_resume_state(), as follows:

  1. Track session is stopped.
  2. Call mme_settrksession().
  3. Call mme_trksession_resume_state()

For more information about stopping an resuming playback of track sessions, see Stopping and resuming playback in the chapter Playing Media in the MME Developer's Guide.

Releasing or “unsetting” a track session

You can release or “unset” the current track session by calling mme_settrksession() with trksessionid set to 0 (zero). Releasing a track session reduces the memory being used by the MME.


Note:
  • You must call mme_stop() to stop the track session before you can release it.
  • A track session can not be used by more than one control context. If you attempt to set a track session already in use by another control context, mme_settrksession() returns -1 and sets errno to EINVAL. To pass control of a track session to a new control context, you must first release it from the current control context

For information about deleting a track session, see Deleting a track session in the chapter Using the MME.

Events

If the tracksession being set is not the currently active track session, the MME delivers the event MME_EVENT_TRKSESSION. If the track session specified is already set, the MME delivers no events.

If the new track session has different repeat or random settings than the current settings on the control context, the MME delivers one or both of the events MME_EVENT_REPEATCHANGE and MME_EVENT_RANDOMCHANGE.

Blocking and validation

Full validation of data; all arguments are checked before the call returns.

This function blocks on control contexts. If mme_settrksession() is called and another function is called before mme_settrksession() returns, the second function blocks on io-media until mme_settrksession() returns. If there are no other pending calls, mme_settrksession() returns without blocking on io-media.

Returns:

0
Success.
-1
An error occurred (errno is set).

Classification:

QNX Neutrino

Safety:
Interrupt handler No
Signal handler No
Thread Yes

See also:

mme_newtrksession(), mme_rmtrksession(), mme_trksessionview_update()