Get the next entry from a playlist
Synopsis:
#include <mm/mmplaylist.h>
int mmplaylist_entry_next_get( mmplaylist_t *pl,
mmplaylist_entry_t **entry )
Arguments:
- pl
- A valid session handle.
- entry
- A pointer for storing a reference to the entry pointer defined by this function.
Library:
libmmplaylist
Description:
This function gets the next entry from a playlist. The data structure filled in by this function contains
the next entry from the playlist file and a flag field that describes the properties of this
entry.
When an application requests the next playlist entry, the selected plugin:
- Retrieves the next entry from the playlist file.
- Identifies and possibly modifies the character encoding of the entry, based on the
preferences given when the playlist session was created.
The actual encoding of the playlist entry returned to the caller might differ from what's
specified in the preferences (see "Playlist sessions" for an explanation).
- If necessary, attempts to identify the entry's track file by validating the entry with
either the specified callback or the stat() function (see mmplaylist_entry_validated_t
for the list of properties that the validation function can set).
This last step repeats until either the callback determines that the entry is valid or the
playlist manager has iterated through the character conversion and/or validation routines.
At this point, the function returns the raw entry to the caller.
Callers must use mmplaylist_entry_release() to free the memory for a playlist
entry when they're done with it. They must not free the memory themselves; doing so will
result in unpredictable behavior.
Returns:
- 1
- The entry was successfully retrieved.
- 0
- The end of the playlist was reached.
- -1
- An error occurred (call mmplaylist_last_error_get() for details).