NAME
The playlist manipulation API -
Defines
#define NJB_PL_END 0
#define NJB_PL_START 1
Functions
void NJB_Reset_Get_Playlist (njb_t *njb)
njb_playlist_t * NJB_Get_Playlist (njb_t *njb)
int NJB_Delete_Playlist (njb_t *njb, u_int32_t plid)
int NJB_Update_Playlist (njb_t *njb, njb_playlist_t *pl)
njb_playlist_t * NJB_Playlist_New (void)
void NJB_Playlist_Destroy (njb_playlist_t *pl)
void NJB_Playlist_Addtrack (njb_playlist_t *pl, njb_playlist_track_t
*track, unsigned int pos)
void NJB_Playlist_Reset_Gettrack (njb_playlist_t *pl)
njb_playlist_track_t * NJB_Playlist_Gettrack (njb_playlist_t *pl)
int NJB_Playlist_Set_Name (njb_playlist_t *pl, const char *name)
void NJB_Playlist_Deltrack (njb_playlist_t *pl, unsigned int pos)
void NJB_Playlist_Deltrack_TrackID (njb_playlist_t *pl, u_int32_t
trackid)
njb_playlist_track_t * NJB_Playlist_Track_New (u_int32_t trackid)
void NJB_Playlist_Track_Destroy (njb_playlist_track_t *track)
Function Documentation
int NJB_Delete_Playlist (njb_t * njb, u_int32_t plid) This deletes a
playlist from the device.
Parameters:
njb a pointer to the njb_t object to delete the playlist from
plid the playlist ID as reported from NJB_Get_Playlist().
Returns:
0 on success, -1 on failure.
Examples:
pl.c.
References njb_struct::device_type, and NJB_DEVICE_NJB1.
njb_playlist_t* NJB_Get_Playlist (njb_t * njb) This gets a playlist from
the device. The device should first be rewound using the
NJB_Reset_Get_Playlist() function. The playlists are newly allocated
and should be destroyed with NJB_Playlist_Destroy() after use.
Parameters:
njb a pointer to the njb_t object to get playlists from
Returns:
a playlist or NULL if the last playlist has already been returned
See also:
NJB_Reset_Get_Playlist()
NJB_Playlist_Destroy()
Examples:
pl.c, and playlists.c.
References njb_struct::device_type, NJB_DEVICE_NJB1, and
njb_struct::protocol_state.
void NJB_Playlist_Addtrack (njb_playlist_t * pl, njb_playlist_track_t *
track, unsigned int pos) This function adds a playlist track (a data
structure representing a track that is part of a playlist) to a
playlist data structure.
Parameters:
pl the playlist that the track shall be added to
track the track to add
pos the position in the playlist where this track should be added
See also:
NJB_Playlist_Deltrack()
Examples:
pl.c.
References njb_playlist_struct::_state, njb_playlist_struct::cur,
njb_playlist_struct::first, njb_playlist_struct::last,
njb_playlist_track_struct::next, NJB_PL_CHTRACKS, NJB_PL_NEW,
NJB_Playlist_Gettrack(), NJB_Playlist_Reset_Gettrack(),
njb_playlist_struct::ntracks, and njb_playlist_track_struct::prev.
Referenced by playlist_unpack().
void NJB_Playlist_Deltrack (njb_playlist_t * pl, unsigned int pos) This
function deletes a track from a playlist.
Parameters:
pl the playlist that the track shall be removed from
pos the position in the playlist to be deleted
See also:
NJB_Playlist_Addtrack()
NJB_Playlist_Deltrack_TrackID()
References njb_playlist_struct::_state, njb_playlist_struct::first,
njb_playlist_struct::last, njb_playlist_track_struct::next,
NJB_PL_CHTRACKS, NJB_Playlist_Gettrack(),
NJB_Playlist_Reset_Gettrack(), NJB_Playlist_Track_Destroy(),
njb_playlist_struct::ntracks, and njb_playlist_track_struct::prev.
void NJB_Playlist_Deltrack_TrackID (njb_playlist_t * pl, u_int32_t trackid)
This function removes a track from a playlist by way of the track ID
(as opposed to the position in the playlist). This function can be
called even on playlists that don’t have this track in them - this is
useful for e.g. looping through all playlists and removing a certain
track before deleting the track itself from the device.
You need to call the NJB_Update_Playlist() function for each playlist
that has been manipulated by this function, to assure that any changes
are written back to the playlist on the device.
Typical use to remove a track with ID id from all playlists on a
device:
njb_playlist_t *playlist;
NJB_Reset_Get_Playlist(njb);
while (playlist = NJB_Get_Playlist(njb)) {
NJB_Playlist_Deltrack_TrackID(playlist, id);
// If the playlist changed, update it
if (NJB_Update_Playlist(njb, playlist) == -1)
NJB_Error_Dump(njb, stderr);
}
NJB_Playlist_Destroy(playlist);
}
if (NJB_Error_Pending(njb)) {
NJB_Error_Dump(njb, stderr);
}
Parameters:
pl the playlist that the track shall be removed from, if present.
trackid the track ID to remove from this playlist
See also:
NJB_Playlist_Deltrack()
NJB_Update_Playlist()
References njb_playlist_struct::_state, njb_playlist_struct::first,
njb_playlist_track_struct::next, NJB_PL_CHTRACKS,
NJB_Playlist_Gettrack(), NJB_Playlist_Reset_Gettrack(),
NJB_Playlist_Track_Destroy(), njb_playlist_struct::ntracks,
njb_playlist_track_struct::prev, and
njb_playlist_track_struct::trackid.
void NJB_Playlist_Destroy (njb_playlist_t * pl) This function destroys a
playlist and frees up the memory used by it. All tracks that are part
of the playlist will also be destroyed.
Parameters:
pl the playlist to destroy
Examples:
pl.c.
References njb_playlist_struct::cur, njb_playlist_struct::first,
njb_playlist_struct::name, njb_playlist_track_struct::next, and
NJB_Playlist_Track_Destroy().
Referenced by playlist_unpack().
njb_playlist_track_t* NJB_Playlist_Gettrack (njb_playlist_t * pl) Returns a
track from a playlist. The playlist has an internal structure to keep
track of the constituent tracks, so the tracks will be retrieved in
order. This function should typically be called repeatedly after an
initial NJB_Playlist_Reset_Gettrack() call.
Parameters:
pl the playlist to get tracks from.
Returns:
a track or NULL of the last track from a playlist has already been
returned
See also:
NJB_Playlist_Reset_Gettrack()
Examples:
pl.c, and playlists.c.
References njb_playlist_struct::cur, and
njb_playlist_track_struct::next.
Referenced by NJB_Playlist_Addtrack(), NJB_Playlist_Deltrack(),
NJB_Playlist_Deltrack_TrackID(), and NJB_Update_Playlist().
njb_playlist_t* NJB_Playlist_New (void) This function creates a new
playlist data structure to hold a name and a number of tracks.
Returns:
a new playlist structure
Examples:
pl.c.
References njb_playlist_struct::_state, and NJB_PL_NEW.
Referenced by playlist_unpack().
void NJB_Playlist_Reset_Gettrack (njb_playlist_t * pl) Resets the internal
counter used when retrieveing tracks from a playlist. Should typically
be called first, before any subsequent calls to
NJB_Playlist_Gettrack().
Parameters:
pl the playlist to be reset
See also:
NJB_Playlist_Gettrack()
Examples:
pl.c, and playlists.c.
References njb_playlist_struct::cur, and njb_playlist_struct::first.
Referenced by NJB_Playlist_Addtrack(), NJB_Playlist_Deltrack(),
NJB_Playlist_Deltrack_TrackID(), and NJB_Update_Playlist().
int NJB_Playlist_Set_Name (njb_playlist_t * pl, const char * name) This
function sets the name of the playlist. The name will be duplicated and
stored internally, so the string is only needed during the function
call.
Parameters:
pl the playlist to set the name for
name the name to set for the playlist
Examples:
pl.c.
References njb_playlist_struct::_state, njb_playlist_struct::name,
NJB_PL_CHNAME, and NJB_PL_UNCHANGED.
void NJB_Playlist_Track_Destroy (njb_playlist_track_t * track) This
destroys a playlist track entry and frees any memory used by it.
Parameters:
track the track entry to destroy.
Referenced by NJB_Playlist_Deltrack(), NJB_Playlist_Deltrack_TrackID(),
and NJB_Playlist_Destroy().
njb_playlist_track_t* NJB_Playlist_Track_New (u_int32_t trackid) This
creates a new track entry for playlists. The trackid used should be the
same as retrieved from libnjb track reading functions.
Parameters:
trackid the ID of the new track
Returns:
the new playlist track entry
Examples:
pl.c.
References njb_playlist_track_struct::trackid.
Referenced by playlist_unpack().
void NJB_Reset_Get_Playlist (njb_t * njb) This resets the playlist
retrieveal function. The playlists can then be retrieved one by one
using the NJB_Get_Playlist() function.
Typical usage:
njb_t *njb;
njb_playlist_t *pl;
NJB_Reset_Get_Playlist(njb);
while ( (pl = NJB_Get_Playlist(njb)) != NULL ) {
// Do something with all the playlists...
NJB_Playlist_Destroy(pl);
}
Parameters:
njb a pointer to the njb_t object to reset the playlist retrieveal
pointer for
See also:
NJB_Get_Playlist()
Examples:
pl.c, and playlists.c.
References njb_struct::device_type, njb3_reset_get_playlist_tag(),
NJB_DEVICE_NJB1, and njb_struct::protocol_state.
int NJB_Update_Playlist (njb_t * njb, njb_playlist_t * pl) This writes back
an updated (modified) or new playlist to the device.
This function may modify the playlist ID, i.e. the plid member of the
njb_playlist_t struct, which means that if your program has cached this
number anywhere, you need to update it using the value from pl->plid
afterwards. This stems from the fact that playlists are sometimes
updated by deleting the old playlist and creating a new one.
Parameters:
njb a pointer to the njb_t object to update the playlist on
pl the playlist to update.
Returns:
0 on success, -1 on failure.
Examples:
pl.c.
References njb_playlist_struct::_state, njb_struct::device_type,
EO_NOMEM, njb_playlist_struct::name,
njb3_add_multiple_tracks_to_playlist(), njb3_create_playlist(),
njb3_update_string_frame(), NJB_DEVICE_NJB1, NJB_PL_CHNAME,
NJB_PL_CHTRACKS, NJB_PL_NEW, NJB_PL_UNCHANGED, NJB_Playlist_Gettrack(),
NJB_Playlist_Reset_Gettrack(), NJB_UC_UTF8, njb_verify_last_command(),
njb_playlist_struct::ntracks, njb_playlist_struct::plid, strtoucs2(),
njb_playlist_track_struct::trackid, and utf8tostr().
Author
Generated automatically by Doxygen for libnjb from the source code.