mmplaylist_entry_next_get()

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:

Get 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:
  1. Retrieves the next entry from the playlist file.
  2. 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).
  3. 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 on success (the entry was retrieved)

0 on end of playlist

-1 on error (use mmplaylist_last_error_get() to get error information)