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.

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.

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.

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()

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()

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.

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.

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.

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.

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.

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.

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.

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.

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.

---