libnjb: The playlist manipulation API

libnjb 2.2.7

- Main Page
- Modules
- Data Structures
- Files
- Examples

Macros | Functions
The playlist manipulation API

## Macros
#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)

## Detailed Description

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