Playlist sessions

To manage a playlist, a client must open a session on the playlist before it can seek to and play tracks or extract metadata.

To open a playlist session, the client must name the media that stores the playlist and provide the playlist's path. The client may also instruct libmmplaylist to convert the playlist entries to a certain character encoding or to validate the entries. This latter task refers to how the library identifies files that correspond to playlist entries; see the mmplaylist_open() function for details on specifying entry validation.

When libmmplaylist successfully opens a playlist session, the mmplaylist_open() call returns a session handle. Clients must provide this handle in subsequent libmmplaylist API calls to operate on the same playlist (e.g., to seek to different positions with mmplaylist_current_pos_get()).

The session handle contains a reference to the plugin chosen to manage the playlist, which allows the library to reuse that same plugin for all playlist operations. The handle also stores the preferences for encoding and validation as well as a reference (if applicable) to the active character converter used for encoding playlist entries. Storing these preferences in the session handle allows libmmplaylist to support multiple playlists concurrently because the preferences of individual sessions are stored separately and hence, they can differ from each other.

The encoding and validation preferences are used in retrieving the next playlist entry when the client calls mmplaylist_entry_next_get(). Sometimes, libmmplaylist can return playlist entries with a different encoding than what's defined in the preferences. For instance, m3u playlists are text files that don't have an official character set. These files are often encoded with the ISO-8859-1 character set; however, in many geographic regions, m3u files use alternative encodings. Because m3u doesn't have a mechanism for communicating the encoding used, the m3u plugin might report the encoding as ISO-8859-1 while the actual encoding differs.

When it's finished using a playlist, the client must close the playlist session by calling mmplaylist_close().

Concurrent sessions

Clients can open as many concurrent playlist sessions in libmmplaylist as they like, including different sessions on the same playlist (by making distinct mmplayist_open() calls with the same playlist path). Multiple concurrent sessions allow media applications to support multitasking with playlists. For example, an application can display browsing information for all the playlists on a device while at the same copying or playing tracks from one of those playlists.

CAUTION:
Multithreaded clients can open and use common playlist sessions from different threads. However, clients that share session handles between threads must carefully guard against concurrent access to those handles. For example, if two threads call mmplaylist_entry_next_get() on the same session, the playlist position gets incremented once for each call, meaning that one thread could alter the playlist state for the other thread.

Obtaining error information

While a session is active, the client can call mmplaylist_last_error_get() to obtain the numeric error code of the last error that occurred on that session. We recommend that your client check the return values of all API calls. If any value indicates an error, the client can retrieve the error code and use it to help recover.