A client must open a session on a 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. When libmmplaylist successfully opens a playlist session, the mmplaylist_open() call returns a session handle, which the client must provide in subsequent calls to operate on the same playlist (e.g., seeking to different positions with mmplaylist_current_pos_set()).
The session handle contains a reference to the plugin chosen to manage the playlist; this design allows the library to reuse the 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. By storing these preferences in session handles, libmmplaylist allows applications to define different preferences for different playlists and hence, establish multiple concurrent playlist sessions.
When it's finished using a playlist, the client must close the related session by calling mmplaylist_close().
When opening a session, the client may 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).
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.
Clients can open as many concurrent playlist sessions in libmmplaylist as they like, including different sessions on the same playlist (by making distinct mmplaylist_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 time copying or playing tracks from one of those playlists.