1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
.TH NJB_GET_FILE 3 "January 2003"
.SH NAME
NJB_Get_File \- upload a copy of a file from the NJB to the host
.SH LIBRARY
libnjb
.SH SYNOPSIS
#include <sys/types.h>
#include <libnjb.h>
extern int njb_error
int NJB_Get_File (njb_t
.BR *njb ", u_int32_t"
.BR fileid ", u_int32_t"
.BR size ", const char"
.BR *path ", XferCallback"
.BR *callback ", void"
.BR *data)
.SH DESCRIPTION
This function uploads a datafile from the NJB (without deleting it from
the NJB) and saves it to the filename specified by
.BR *path "."
Data files are not music tracks, but general data
storage containers on the jukebox.
The desired datafile's file ID is stored in
.BR fileid "."
Note that the calling program must also know the size of the file to
be transferred, and sent in the
.B 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
.BR NJB_Get_TmpDir (3))
before being copied into place. By default, the temporary directory
is /tmp, but it can be changed by the
.BR NJB_Set_TmpDir (3)
function.
The
.B callback
parameter is a pointed to a callback function, as described in
.BR NJB_Get_File (3).
The
.B 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
.B NULL.
.SH RETURN VALUES
If the transfer is successful, 0 is returned. Otherwise, -1 is returned
and
.B njb_error
is set as follows:
.LP
.TP 10
EO_ABORTED
The transfer was aborted by the user (the callback function returned -1).
.TP 10
EO_BADSTATUS
A non-zero status was returned by the NJB during the file transfer.
.TP 10
EO_CANTMOVE
The transferred datafile could not be moved from the temporary directory
to the specified location (see the
.B *path
parameter).
.TP 10
EO_NOMEM
There was not enough memory to allocate the file transfer buffer.
.TP 10
EO_NULLTMP
The temporary directory is undefined (a NULL pointer).
.TP 10
EO_RDSHORT
The NJB sent fewer bytes than expected on the bulk data pipe.
.TP 10
EO_TMPFILE
The temporary transfer file could not be created in the temporary directory.
.TP 10
EO_USBBLK
An I/O error occurred on the bulk data pipe.
.TP 10
EO_USBCTL
An I/O error occurred on the control pipe.
.TP 10
EO_WRFILE
An error occurred while writing to the temporary transfer file.
.TP 10
EO_XFERDENIED
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.
.TP 10
EO_XFERERROR
The NJB returned a non-zero status when the host requested verification
of the file transfer.
.SH SEE ALSO
NJB_Get_TmpDir(3), NJB_Get_Datafile_Tag(3), NJB_Set_TmpDir(3),
XferCallback(3)
|
