man NJB_Get_File (Fonctions bibliothèques) - upload a copy of a file from the NJB to the host


NJB_Get_File - upload a copy of a file from the NJB to the host




#include <sys/types.h> #include <libnjb.h>

extern int njb_error

int NJB_Get_File (njb_t *njb, u_int32_t fileid, u_int32_t size, const char *path, XferCallback *callback, void *data)


This function uploads a datafile from the NJB (without deleting it from the NJB) and saves it to the filename specified by *path. Data files are not music tracks, but general data storage containers on the jukebox.

The desired datafile's file ID is stored in fileid. Note that the calling program must also know the size of the file to be transferred, and sent in the size parameter. Both the datafile ID and the file size can be found in the datafile tag for the desired datafile, as returned by NJB_Get_Datafile_Tag (3). Generally, the calling program should fetch (and cache) the complete datafile list from the NJB, so that all of this information is readily available.

For reliability, the datafile is first downloaded to a temporary 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 a pointed to a callback function, as described in NJB_Get_File(3).

The data parameter is a pointer to user data of any kind that the user of the library wants to associate with this transfer. This pointer is used for example when accessing several different jukeboxes from withing one program. The XferCallback will also be delivering this pointer to the target routine for dereferencing. If this parameter is not used (in for example single-device, single-threaded programs) it may be set to NULL.


If the transfer is successful, 0 is returned. Otherwise, -1 is returned and njb_error is set as follows:

The transfer was aborted by the user (the callback function returned -1).
A non-zero status was returned by the NJB during the file transfer.
The transferred datafile could not be moved from the temporary directory to the specified location (see the *path parameter).
There was not enough memory to allocate the file transfer buffer.
The temporary directory is undefined (a NULL pointer).
The NJB sent fewer bytes than expected on the bulk data pipe.
The temporary transfer file could not be created in the temporary directory.
An I/O error occurred on the bulk data pipe.
An I/O error occurred on the control pipe.
An error occurred while writing to the temporary transfer file.
The NJB returned a non-zero status when the file transfer was requested. The datafile may be write protected, or the given track ID may not exist.
The NJB returned a non-zero status when the host requested verification of the file transfer.