njb_get_track(3)

NAME

NJB_Get_Track - Upload a copy of a song from the NJB to

the host

LIBRARY

libnjb

SYNOPSIS

#include <sys/types.h> #include <libnjb.h>
extern int njb_error
int   NJB_Get_Track   (njb_t   *njb,   u_int32_t  trackid,
u_int32_t size, const char *path,  XferCallback  *callback,  void
*data)

DESCRIPTION

This function uploads a song track from the NJB (without

deleting it from the NJB) and saves it to the filename specified

by *path.

The desired song's track ID is stored in trackid. Note

that the calling program must also know the size of the file to

be transferred, and sent in the size parameter. Both the track

ID and the file size can be found in the song tag for the desired

track, as returned by NJB_Get_Track_Tag (3). Generally, the

calling program should fetch (and cache) the complete track list

from the NJB, so that all of this information is readily avail

able.

For reliability, the track is first downloaded to a tempo

rary directory (see NJB_Get_TmpDir(3)) before being copied into

place. By default, the temporary directory is /tmp, but it can

be changed by the NJB_Set_TmpDir(3) function.

The callback parameter is actually a pointer to a function

of type XferCallback, and is called after each file block is

transferred. The definition for XferCallback is found in libn

jb.h:

typedef int XferCallback(off_t sent, off_t total);

This callback function gives the calling program the abil

ity to maintain a status bar, showing bytes transferred (the sent

paramater), and the total size of the file being sent (in total).

It also provides an "abort" capability, in case the end user

wishes to cancel the file transfer: if the callback function re

turns -1, then the file transfer is aborted and the temporary

copy of the file is removed.

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.

RETURN VALUES

If the transfer is successful, 0 is returned. Otherwise,

-1 is returned and njb_error is set as follows:

EO_ABORTED

The transfer was aborted by the user (the call

back function returned -1).

EO_BADSTATUS

A non-zero status was returned by the NJB during

the file transfer.

EO_CANTMOVE

The transferred track could not be moved from

the temporary directory to the specified location (see the *path

parameter).

EO_NOMEM There was not enough memory to allocate the file

transfer buffer.

EO_NULLTMP

The temporary directory is undefined (a NULL

pointer).

EO_RDSHORT

The NJB sent fewer bytes than expected on the

bulk data pipe.

EO_TMPFILE

The temporary transfer file could not be created

in the temporary directory.

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

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

EO_WRFILE An error occurred while writing to the temporary

transfer file.

EO_XFERDENIED

The NJB returned a non-zero status when the file

transfer was requested. The track may be write protected, or the

given track ID may not exist.

EO_XFERERROR

The NJB returned a non-zero status when the host

requested verification of the file transfer.

SEE ALSO

NJB_Get_TmpDir(3), NJB_Get_Track_Tag(3), NJB_Set_Tm

pDir(3), XferCallback(3)

January 2003

NJB_GET_TRACK(3)