NAME
The track and tag (song ID metadata) manipulation API -
Defines
#define NJB_Songid_Frame_New_Title(a)
NJB_Songid_Frame_New_String(FR_TITLE, a)
#define NJB_Songid_Frame_New_Album(a)
NJB_Songid_Frame_New_String(FR_ALBUM, a)
#define NJB_Songid_Frame_New_Genre(a)
NJB_Songid_Frame_New_String(FR_GENRE, a)
#define NJB_Songid_Frame_New_Artist(a)
NJB_Songid_Frame_New_String(FR_ARTIST, a)
#define NJB_Songid_Frame_New_Length(a)
NJB_Songid_Frame_New_Uint16(FR_LENGTH, a)
#define NJB_Songid_Frame_New_Filesize(a)
NJB_Songid_Frame_New_Uint32(FR_SIZE, a)
#define NJB_Songid_Frame_New_Tracknum(a)
NJB_Songid_Frame_New_Uint16(FR_TRACK, a)
#define NJB_Songid_Frame_New_Year(a)
NJB_Songid_Frame_New_Uint16(FR_YEAR, a)
#define NJB_Songid_Frame_New_Filename(a)
NJB_Songid_Frame_New_String(FR_FNAME, a)
#define NJB_Songid_Frame_New_Protected(a)
NJB_Songid_Frame_New_Uint16(FR_PROTECTED, a)
#define NJB_Songid_Frame_New_Bitrate(a)
NJB_Songid_Frame_New_Uint32(FR_BITRATE, a)
#define NJB_Songid_Frame_New_Comment(a)
NJB_Songid_Frame_New_String(FR_COMMENT, a)
#define NJB_Songid_Frame_New_Folder(a)
NJB_Songid_Frame_New_String(FR_FOLDER, a)
Functions
njb_songid_t * NJB_Songid_New (void)
void NJB_Songid_Destroy (njb_songid_t *song)
void NJB_Songid_Addframe (njb_songid_t *song, njb_songid_frame_t
*frame)
void NJB_Songid_Reset_Getframe (njb_songid_t *song)
njb_songid_frame_t * NJB_Songid_Getframe (njb_songid_t *song)
njb_songid_frame_t * NJB_Songid_Findframe (njb_songid_t *song, const
char *label)
njb_songid_frame_t * NJB_Songid_Frame_New_String (const char *label,
const char *value)
njb_songid_frame_t * NJB_Songid_Frame_New_Uint16 (const char *label,
u_int16_t value)
njb_songid_frame_t * NJB_Songid_Frame_New_Uint32 (const char *label,
u_int32_t value)
njb_songid_frame_t * NJB_Songid_Frame_New_Codec (const char *value)
void NJB_Songid_Frame_Destroy (njb_songid_frame_t *frame)
void NJB_Get_Extended_Tags (njb_t *njb, int extended)
void NJB_Reset_Get_Track_Tag (njb_t *njb)
njb_songid_t * NJB_Get_Track_Tag (njb_t *njb)
int NJB_Replace_Track_Tag (njb_t *njb, u_int32_t trackid, njb_songid_t
*songid)
int NJB_Get_Track (njb_t *njb, u_int32_t trackid, u_int32_t size, const
char *path, NJB_Xfer_Callback *callback, void *data)
int NJB_Get_Track_fd (njb_t *njb, u_int32_t trackid, u_int32_t size,
int fd, NJB_Xfer_Callback *callback, void *data)
int NJB_Send_Track (njb_t *njb, const char *path, njb_songid_t *songid,
NJB_Xfer_Callback *callback, void *data, u_int32_t *trackid)
int NJB_Delete_Track (njb_t *njb, u_int32_t trackid)
Function Documentation
int NJB_Delete_Track (njb_t * njb, u_int32_t trackid) This deletes a track
from the device.
Parameters:
njb a pointer to the njb_t jukebox object to use
trackid the track ID for the track to delete
Returns:
0 on success, -1 on failure
Examples:
deltr.c.
References njb_struct::device_type, EO_BADCOUNT, and NJB_DEVICE_NJB1.
void NJB_Get_Extended_Tags (njb_t * njb, int extended) This configures
libnjb to retrieve extended tags from the device. For the NJB1 this is
the default behaviour anyway so it need not be set, but for the series
3 devices, retrieving the extended tag information is a costly
operation that will slow down the initial track scanning by orders of
magnitude and irritate the user. Make sure end-users can configure
whether they want to use this or not.
The extended tags will include things like the filename and folder that
the file used on the host before it was transfered to the device.
Parameters:
njb a pointer to the njb_t object to set this mode for
extended use 0 for non-exetended tags (default), 1 for extended
tags
Examples:
tracks.c.
References njb_struct::protocol_state.
int NJB_Get_Track (njb_t * njb, u_int32_t fileid, u_int32_t size, const
char * path, NJB_Xfer_Callback * callback, void * data) This retrieves
(’uploads’) a track from the device to the host computer.
Parameters:
njb a pointer to the njb_t object to get the track from
fileid the unique trackid (also known as file ID, they are the same
things) as reported by the device from e.g. NJB_Get_Track_Tag().
size the size of the track in bytes. You know this size from
previous calls to NJB_Get_Track_Tag() and it is needed among other
things for displaying a progress bar and for determining that all
bytes have been correctly retrieved.
path the path where the resulting file should be written. If this
parameter is null, the blocks are delivered via the callback’s buf
parameter.
callback a function that will be called repeatedly to report
progress during transfer, used for e.g. displaying progress bars
data a voluntary parameter that can associate some user-supplied
data with each callback call. It is OK to set this to NULL of
course.
Returns:
0 on success, -1 on failure
See also:
NJB_Get_Track_fd()
Examples:
gettr.c.
References EO_TMPFILE, and NJB_Get_Track_fd().
int NJB_Get_Track_fd (njb_t * njb, u_int32_t fileid, u_int32_t size, int
fd, NJB_Xfer_Callback * callback, void * data) This retrieves
(’uploads’) a track from the device to the host computer by way of a
file descriptor, which is good for e.g. streaming stuff. The daring
type can start playing back audio from the file descriptor before it is
finished. This is also good for fetching to temporary files, which are
often only given as file descriptors.
Parameters:
njb a pointer to the njb_t object to get the track from
fileid the unique trackid (also known as file ID, they are the same
things) as reported by the device from e.g. NJB_Get_Track_Tag().
size the size of the track in bytes. You know this size from
previous calls to NJB_Get_Track_Tag() and it is needed among other
things for displaying a progress bar and for determining that all
bytes have been correctly retrieved.
fd the file descriptor that shall be fed with the track contents.
The file descriptor must be writable. On win32 make sure it is a
binary descriptor and not textual.
callback a function that will be called repeatedly to report
progress during transfer, used for e.g. displaying progress bars
data a voluntary parameter that can associate some user-supplied
data with each callback call. It is OK to set this to NULL of
course.
Returns:
0 on success, -1 on failure
See also:
NJB_Get_Track()
References njb_struct::device_type, EO_ABORTED, EO_NOMEM, EO_WRFILE,
EO_XFERDENIED, EO_XFERERROR, njb3_get_file_block(),
njb3_request_file_chunk(), NJB_DEVICE_NJB1, njb_receive_file_block(),
NJB_TURBO_OFF, njb_verify_last_command(), njb_struct::protocol_state,
and njb3_state_t::turbo_mode.
Referenced by NJB_Get_Track().
njb_songid_t* NJB_Get_Track_Tag (njb_t * njb) This gets a track tag (song
ID) from the device. The device should first be rewound using the
NJB_Reset_Get_Track_Tag() function.
Notice that there is no function for getting the tag for a single
track, there is just this function that dumps out the entire database
in one big go. The recommended approach is to keep an internal track
cache of all tracks and use this for getting metadata for single
tracks. There is as far as we know no function in the Creative
firmwares for getting the metadata of a single track, so access through
this function is the only option.
Parameters:
njb a pointer to the njb_t object to reset the track retrieveal
pointer for
Returns:
a track tag (song ID) or NULL if the last track tag has already
been retrieved
See also:
NJB_Reset_Get_Track_Tag()
Examples:
gettr.c, and tracks.c.
References njb_struct::device_type, NJB_DEVICE_NJB1, and
njb_struct::protocol_state.
int NJB_Replace_Track_Tag (njb_t * njb, u_int32_t trackid, njb_songid_t *
songid) This routine will replace the track tag or parts of a track tag
for a track that already exist on the device. On the NJB1 the whole
metadata set must be specified for this routine to work properly, but
on the series 3 devices you can specify incremental updates (only parts
of the metadata set). Be sure to either specify the full set all the
time, or check if we are handling an NJB1 before submitting an
incremental update (see example below).
Parameters:
njb a pointer to the jukebox object to use
trackid the track ID to replace the tag for
songid the new tag
Typical usage:
njb_t *njb;
njb_songid_t *songid;
njb_songid_frame_t *frame;
songid = NJB_Songid_New();
// On NJB1 incremental update is not possible, so a full
// metadata set must always be specified.
if (njb->device_type == NJB_DEVICE_NJB1) {
frame = NJB_Songid_Frame_New_Codec(meta->codec);
NJB_Songid_Addframe(songid, frame);
frame = NJB_Songid_Frame_New_Filesize(meta->size);
NJB_Songid_Addframe(songid, frame);
}
frame = NJB_Songid_Frame_New_Codec(NJB_CODEC_MP3);
NJB_Songid_Addframe(songid, frame);
frame = NJB_Songid_Frame_New_Title(’MyTitle’);
NJB_Songid_Addframe(songid, frame);
frame = NJB_Songid_Frame_New_Album(’MyAlbum’);
NJB_Songid_Addframe(songid, frame);
frame = NJB_Songid_Frame_New_Artist(’MyArtist’);
NJB_Songid_Addframe(songid, frame);
frame = NJB_Songid_Frame_New_Genre(’MyGenre’);
NJB_Songid_Addframe(songid, frame);
frame = NJB_Songid_Frame_New_Year(2004);
NJB_Songid_Addframe(songid, frame);
frame = NJB_Songid_Frame_New_Tracknum(1);
NJB_Songid_Addframe(songid, frame);
// The length of the track should typically be given, or such things
// as progress indicators will stop working. If you absolutely want to
// upload a file of unknown length and break progress indicators, set
// length to 1 second.
frame = NJB_Songid_Frame_New_Length(123);
NJB_Songid_Addframe(songid, frame);
// This one is optional, the track will survive without it.
frame = NJB_Songid_Frame_New_Filename(’Foo.mp3’);
NJB_Songid_Addframe(songid, frame);
if (NJB_Replace_Track_Tag(njb, 123456, songid) == -1) {
NJB_Error_Dump(stderr);
}
NJB_Songid_Destroy(songid);
Examples:
tagtr.c.
References njb_songid_frame_struct::data, njb_struct::device_type,
EO_BAD_NJB1_REPLACE, EO_BADCOUNT, FR_CODEC,
njb_songid_frame_struct::label, njb3_update_tag(), NJB_DEVICE_NJB1,
NJB_Songid_Addframe(), NJB_Songid_Destroy(),
NJB_Songid_Frame_New_String(), NJB_Songid_Frame_New_Uint16(),
NJB_Songid_Frame_New_Uint32(), NJB_Songid_Getframe(), NJB_Songid_New(),
NJB_Songid_Reset_Getframe(), NJB_TYPE_STRING, NJB_TYPE_UINT16,
NJB_TYPE_UINT32, songid_pack(), songid_pack3(), songid_sanity_check(),
njb_songid_frame_struct::strval, njb_songid_frame_struct::type,
njb_songid_frame_struct::u_int16_val, and
njb_songid_frame_struct::u_int32_val.
void NJB_Reset_Get_Track_Tag (njb_t * njb) This resets the track tag (song
ID) retrieveal function. The track tags can then be retrieved one by
one using the NJB_Get_Track_Tag() function.
Typical usage:
njb_t *njb;
njb_songid_t *song;
NJB_Songid_Reset_Get_Track_Tag(njb);
while ( (song = NJB_Get_Track_Tag(njb)) != NULL ) {
// Do something with all the songs...
}
Parameters:
njb a pointer to the njb_t object to reset the track retrieveal
pointer for
See also:
NJB_Get_Track_Tag()
Examples:
gettr.c, and tracks.c.
References njb_struct::device_type, NJB_DEVICE_NJB1, and
njb_struct::protocol_state.
int NJB_Send_Track (njb_t * njb, const char * path, njb_songid_t * songid,
NJB_Xfer_Callback * callback, void * data, u_int32_t * trackid) This
sends (’downloads’) a track (playable music file) to the device.
Typical usage:
njb_t *njb;
njb_songid_t *songid;
njb_songid_frame_t *frame;
u_int32_t id;
songid = NJB_Songid_New();
frame = NJB_Songid_Frame_New_Codec(NJB_CODEC_MP3);
NJB_Songid_Addframe(songid, frame);
// This one is optional - libnjb will fill it in if not specified
frame = NJB_Songid_Frame_New_Filesize(12345678);
NJB_Songid_Addframe(songid, frame);
frame = NJB_Songid_Frame_New_Title(’MyTitle’);
NJB_Songid_Addframe(songid, frame);
frame = NJB_Songid_Frame_New_Album(’MyAlbum’);
NJB_Songid_Addframe(songid, frame);
frame = NJB_Songid_Frame_New_Artist(’MyArtist’);
NJB_Songid_Addframe(songid, frame);
frame = NJB_Songid_Frame_New_Genre(’MyGenre’);
NJB_Songid_Addframe(songid, frame);
frame = NJB_Songid_Frame_New_Year(2004);
NJB_Songid_Addframe(songid, frame);
frame = NJB_Songid_Frame_New_Tracknum(1);
NJB_Songid_Addframe(songid, frame);
// The length of the track should typically be given, or such things
// as progress indicators will stop working. If you absolutely want to
// upload a file of unknown length and break progress indicators, set
// length to 1 second.
frame = NJB_Songid_Frame_New_Length(123);
NJB_Songid_Addframe(songid, frame);
// This one is optional - libnjb will fill it in if not specified
frame = NJB_Songid_Frame_New_Filename(’Foo.mp3’);
NJB_Songid_Addframe(songid, frame);
if (NJB_Send_Track (njb, ’foo.mp3’, songid, NULL, NULL, &id) == -1) {
NJB_Error_Dump(stderr);
}
NJB_Songid_Destroy(songid);
Parameters:
njb a pointer to the njb_t object to send the track file to.
path the filesystem path on the local host to use as indata
songid the tag for this track, which has to be built separately
before the transfer is started with a call to this function.
callback a function that will be called repeatedly to report
progress during transfer, used for e.g. displaying progress bars.
This may be NULL if you don’t want any callbacks.
data a voluntary parameter that can associate some user-supplied
data with each callback call. It is OK to set this to NULL of
course.
trackid a pointer to an integer that will hold the resulting track
ID after this transfer has commenced successfully.
Returns:
0 on success, -1 on failure
See also:
NJB_Send_File()
Examples:
sendtr.c.
References _file_size(), njb_struct::device_type, EO_INVALID,
EO_SRCFILE, EO_TOOBIG, EO_XFERDENIED, FR_FNAME, FR_SIZE,
NJB_DEVICE_NJB1, NJB_Get_Disk_Usage(), NJB_Songid_Addframe(),
NJB_Songid_Findframe(), songid_pack(), songid_pack3(), and
songid_sanity_check().
void NJB_Songid_Addframe (njb_songid_t * song, njb_songid_frame_t * frame)
This adds a song ID frame to a song ID.
Parameters:
song the song ID to add the frame to
frame the frame to add to this song ID
Examples:
sendtr.c, and tagtr.c.
References njb_songid_struct::cur, njb_songid_struct::first,
njb_songid_struct::last, njb_songid_frame_struct::next, and
njb_songid_struct::nframes.
Referenced by NJB_Replace_Track_Tag(), NJB_Send_Track(),
songid_sanity_check(), and songid_unpack().
void NJB_Songid_Destroy (njb_songid_t * songid) This destroys an entire
song ID structure and free the memory used by it.
Parameters:
songid the song ID structure to destroy
Examples:
gettr.c, sendtr.c, tagtr.c, and tracks.c.
References NJB_Songid_Frame_Destroy(), NJB_Songid_Getframe(), and
NJB_Songid_Reset_Getframe().
Referenced by NJB_Replace_Track_Tag(), and songid_unpack().
njb_songid_frame_t* NJB_Songid_Findframe (njb_songid_t * song, const char *
label) This locates a particular song ID frame inside a song ID, by
using the textual label given.
Parameters:
song the song ID to look in
label the textual label of the frame to look for
Returns:
the song ID frame if found, else NULL
Examples:
gettr.c.
References njb_songid_frame_struct::label, NJB_Songid_Getframe(), and
NJB_Songid_Reset_Getframe().
Referenced by NJB_Send_Track().
void NJB_Songid_Frame_Destroy (njb_songid_frame_t * frame) This destroys a
song ID frame and free any memory used by it.
Parameters:
frame the song ID frame to destroy
References njb_songid_frame_struct::data,
njb_songid_frame_struct::label, NJB_TYPE_STRING,
njb_songid_frame_struct::strval, and njb_songid_frame_struct::type.
Referenced by NJB_Songid_Destroy().
njb_songid_frame_t* NJB_Songid_Frame_New_Codec (const char * value) This is
a wrapper function to fix a common mistake made when creating codec
frames: lowercase codec names and other strange mistakes.
Examples:
sendtr.c, and tagtr.c.
References FR_CODEC, NJB_CODEC_MP3, NJB_CODEC_WAV, NJB_CODEC_WMA, and
NJB_Songid_Frame_New_String().
njb_songid_frame_t* NJB_Songid_Frame_New_String (const char * label, const
char * value) Creates a new string frame.
Parameters:
label the label of this string frame
value the string contained in this string frame
Returns:
valid string frame on success, NULL on failure
References njb_songid_frame_struct::data,
njb_songid_frame_struct::label, NJB_TYPE_STRING,
njb_songid_frame_struct::strval, and njb_songid_frame_struct::type.
Referenced by NJB_Replace_Track_Tag(), NJB_Songid_Frame_New_Codec(),
and songid_unpack().
njb_songid_frame_t* NJB_Songid_Frame_New_Uint16 (const char * label,
u_int16_t value) Creates a new unsigned 16-bit integer frame.
Parameters:
label the label of this unsigned 16-bit integer frame
value the unsigned 16-bit integer contained in this frame
Returns:
valid unsigned 16-bit integer frame on success, NULL on failure
References njb_songid_frame_struct::data,
njb_songid_frame_struct::label, NJB_TYPE_UINT16,
njb_songid_frame_struct::type, and
njb_songid_frame_struct::u_int16_val.
Referenced by NJB_Replace_Track_Tag(), and songid_unpack().
njb_songid_frame_t* NJB_Songid_Frame_New_Uint32 (const char * label,
u_int32_t value) Creates a new unsigned 32-bit integer frame.
Parameters:
label the label of this unsigned 32-bit integer frame
value the unsigned 32-bit integer contained in this frame
Returns:
valid unsigned 32-bit integer frame on success, NULL on failure
References njb_songid_frame_struct::data,
njb_songid_frame_struct::label, NJB_TYPE_UINT32,
njb_songid_frame_struct::type, and
njb_songid_frame_struct::u_int32_val.
Referenced by NJB_Replace_Track_Tag(), and songid_unpack().
njb_songid_frame_t* NJB_Songid_Getframe (njb_songid_t * song) This gets the
next song ID frame from a song ID structure.
Parameters:
song the song ID to get frames from
Returns:
a song ID frame, or NULL if the last frame has already been
returned.
See also:
NJB_Songid_Reset_Getframe()
Examples:
tracks.c.
References njb_songid_struct::cur, and njb_songid_frame_struct::next.
Referenced by NJB_Replace_Track_Tag(), NJB_Songid_Destroy(),
NJB_Songid_Findframe(), songid_pack(), songid_pack3(), and
songid_sanity_check().
njb_songid_t* NJB_Songid_New (void) This creates a new song ID holder
structure. (A songid in turn contains several frames represening
different metadata.)
Returns:
a new song ID structure
Examples:
sendtr.c, and tagtr.c.
References njb_songid_struct::next.
Referenced by NJB_Replace_Track_Tag(), and songid_unpack().
void NJB_Songid_Reset_Getframe (njb_songid_t * song) This resets the
internal pointer in the song ID so that it points to the first frame of
the song ID. It should typically be called before subsequent calls to
NJB_Songid_Getframe().
Typical usage:
njb_songid_t *song;
njb_songid_frame_t *frame;
// Get a song ID into ’song’...
NJB_Songid_Reset_Getframe(song);
while ( (frame = NJB_Songid_Getframe(song)) != NULL ) {
// Do something with all the frames...
}
Parameters:
song the song ID structure whose internal frame pointer shall be
reset.
See also:
NJB_Songid_Getframe()
Examples:
tracks.c.
References njb_songid_struct::cur, and njb_songid_struct::first.
Referenced by NJB_Replace_Track_Tag(), NJB_Songid_Destroy(),
NJB_Songid_Findframe(), songid_pack(), songid_pack3(), and
songid_sanity_check().
Author
Generated automatically by Doxygen for libnjb from the source code.
Version 2.2.5 The track and tag (song ID metadata) manipulation API(3)