---
name: "NJB_Get_Track"
section: "3"
platform: "linux"
package: "libnjb1-doc"
version: "1.1-2"
release: "Debian 4.0 (Etch)"
platforms: ["linux"]
url: "https://new.carta.tech/NJB_Get_Track"
---

# NJB\_Get\_Track(3)

Upload a copy of a song from the NJB to the host

## 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 available.

For reliability, the track is first downloaded to a temporary directory (see [**NJB\_Get\_TmpDir**(3)](/NJB_Get_TmpDir/3.md)) before being copied into place.  By default, the temporary directory is /tmp, but it can be changed by the [**NJB\_Set\_TmpDir**(3)](/NJB_Set_TmpDir/3.md) 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 libnjb.h:

typedef int XferCallback(off\_t sent, off\_t total);

This callback function gives the calling program the ability 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 returns -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 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.**

## 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 callback 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_TmpDir/3.md), [NJB\_Get\_Track\_Tag(3)](/NJB_Get_Track_Tag/3.md), [NJB\_Set\_TmpDir(3)](/NJB_Set_TmpDir/3.md), [XferCallback(3)](/XferCallback/3.md)