njb_send_track(3)

NAME

NJB_Send_Track - transfer a music track to the jukebox

LIBRARY

libnjb

SYNOPSIS

#include <sys/types.h> #include <libnjb.h>
extern int njb_error
int NJB_Send_Track (njb_t *njb, const  char  *path,  const
char  *codec,  const  char  *title, const char *album, const char
*genre, const char *artist, u_int32_t length, u_int32_t tracknum,
const  char  *year,  int  protected, XferCallback *callback, void
*data, u_int32_t *trackid)

DESCRIPTION

This function downloads the music file at path to the NJB.

The codec parameter is required, and cannot be NULL, since it

tells the NJB what audio format the song track is stored in. The

title, album, genre, artist, length , tracknum , year, and

protected parameters are optional, and can be NULL (pointers) or

0 (integers). However, as the NJB organizes tracks by artist,

album, title and genre, is is strongly recommended that these pa

rameters be provided. If title is NULL, then the title will be

substituted with the file name when transferred.

After the track is sucessfully transferred, the trackid

variable is updated with the ID that was assigned by the NJB.

This allows the calling program to update any local file caches.

The callback parameter is a pointed to a callback func

tion, as described in NJB_Get_Track(3).

The data parameter is a pointer to user data of any kind

that the user of the library wants to associate with this trans

fer. This pointer is used for example when accessing several dif

ferent jukeboxes from withing one program. The XferCallback will

also be delivering this pointer to the target routine for deref

erencing. If this parameter is not used (in for example single

device, single-threaded programs) it may be set to NULL.

(On the NJB1, this function increments the NJB's library

counter, provided it has not been incremented previously during

the session.)

RETURN VALUES

If the transfer is successful, NJB_Send_Track returns 0.

Otherwise, -1 is returned and njb_error is set.

EO_ABORTED

The transfer was aborted by the user (the call

back function returned -1).

EO_BADCOUNT

The library counter on the NJB could not be up

dated. The track transfer was successful.

EO_BADDATA

songtag contains invalid data or is not properly

formed.

EO_BADSTATUS

A non-zero status was returned by the NJB during

the file transfer.

EO_INVALID

A required parameter was NULL.

EO_NOMEM There was not enough memory to allocate the file

transfer buffer.

EO_NOMEM There was not enough memory to create the "tag"

for the audio track.

EO_RDSHORT

The NJB sent fewer bytes than expected on the

bulk data pipe.

EO_TIMEOUT

The NJB did not verify that the transfer was

complete after several queries. The track may have still have

been transferred successfully.

EO_TOOBIG There is not enough free disk space on the NJB

to hold the track.

EO_USBBLK An I/O error occurred on the bulk data pipe.

EO_USBCTL An I/O error occurred on the control pipe.

EO_WRSHORT

Fewer bytes than requested were written to the

USB pipe.

EO_XFERDENIED

Could not determie the available disk space on

the NJB.

EO_XFERERROR

The NJB returned a non-zero status when the tag

for the track was transferred.

SEE ALSO

NJB_Get_Track(3), NJB_Replace_Track_Tag(3), songid(3),

XferCallback(3)

January 2003

NJB_SEND_TRACK(3)