mme_newtrksession()

Create a new track session

Synopsis:

#include <mme/mme.h>

int mme_newtrksession( mme_hdl_t *hdl,
                       char *statement,
                       short int mode,
                       uint64_t *trksessionid );

Arguments:

hdl
An MME connection handle.
statement
An SQL statement that defines the track session you want to create.
mode
The track session mode. This mode can be either MME_PLAYMODE_LIBRARY (0) or MME_PLAYMODE_FILE (1).
trksessionid
The pointer to the location where the function can store the new track session ID. Pass this value to mme_settrksession() to activate the track session.

Library:

mme

Description:

The function mme_newtrksession() creates a new track session for the specified control context.

The SQL query passed to this function can select tracks from the library table, the playlist table, or any other valid source. The MME adds each new track session created by mme_newtrksession() to the trksessions table in the MME library.

The SQL statement should not end with a semicolon. The statement is actually a sub-statement, which mme_newtrksession() places into a larger statement. The result for the statement you pass to mme_newtrksession() must include a fid column.

For best performance, compose the query to look for media files only on available mediastores. For example, for library-mode track sessions, compose the query:

SELECT fid FROM library WHERE msid IN
    (SELECT msid FROM mediastores WHERE available=1)

For file-based track sessions, compose a query that returns the FTYPE_DEVICE fid for the mediastore with the files discovered through the explorer API. For example:

SELECT fid FROM library WHERE ftype=5 AND msid=3

For more information about library-mode and file-based track sessions, see Working with track sessions in the MME Developer's Guide.

After you have created a new track session, you need to:


Note: A new track session inherits its random and repeat modes from the control context in which it is created. For more information about these modes, see mme_setrandom() and mme_setrepeat().

You can call mme_trksession_get_info() to get the ID of the active track session in a specific control context.

Events

None delivered.

Blocking and validation

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

Returns:

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

Examples:

// Create a new track session of all songs from a playlist
//  that are currently available
sql = qdb_mprintf(
        "SELECT fid FROM playlistdata WHERE "
        "plid = (SELECT plid FROM playlists WHERE name = '%q') "
        "AND msid IN (SELECT msid FROM mediastores WHERE available=1)",
        playlistname);
if (sql == NULL) {
    fprintf(stderr, "error with select statement;");
    exit(1);
}

rc = mme_newtrksession( &mme, sql, MME_PLAYMODE_LIBRARY, &trksessionid );
if (rc == -1) {
    fprintf(stderr, "error creating new track session;");
    exit(1);
}

rc = mme_settrksession( &mme, trksessionid );
if (rc == -1) {
    fprintf(stderr, "error setting track session;");
    exit(1);
}

// pass in a fid of 0 to start from the beginning.
rc = mme_play(&mme, 0);
if (rc == -1) {
    fprintf(stderr, "error starting playback;");
    exit(1);
}

Classification:

QNX Neutrino

Safety:
Interrupt handler No
Signal handler No
Thread Yes

See also:

mme_trksession_get_info(), mme_rmtrksession(), mme_settrksession()