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
112
113
114
115
|
.TH NJB_SEND_FILE 3 "January 2003"
.SH NAME
NJB_Send_File \- transfer a datafile to the jukebox
.SH LIBRARY
libnjb
.SH SYNOPSIS
#include <sys/types.h>
#include <libnjb.h>
extern int njb_error
int NJB_Send_File (njb_t
.BR *njb ", const char"
.BR *path ", const char"
.BR *name ", XferCallback"
.BR *callback ", void"
.BR *data ", u_int32_t"
.BR *fileid )
.SH DESCRIPTION
This function downloads the data file at
.B path
to the NJB. Data files are not music tracks, but general data
storage containers on the jukebox. The
.B name
parameter is not required, if it is NULL, the
.B path
parameter will be used to name the sent file. Typically
the
.B name
parameter should be sent to set a name which does not contain
any path information or delimiters (like :, / etc).
After the file is sucessfully transferred, the
.B fileid
variable is updated with the ID that was assigned by the NJB. This
allows the calling program to update any local file caches.
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.
(On NJB1, this function increments the NJB's library counter, provided it has
not been incremented previously during the session.)
.SH RETURN VALUES
If the transfer is successful, NJB_Send_File returns 0. Otherwise,
-1 is returned and
.B njb_error
is set.
.LP
.TP 10
EO_ABORTED
The transfer was aborted by the user (the callback function returned
-1).
.TP 10
EO_BADCOUNT
The library counter on the NJB could not be updated. The file transfer
was successful.
.TP 10
EO_BADDATA
.B datafiletag
contains invalid data or is not properly formed.
.TP 10
EO_BADSTATUS
A non-zero status was returned by the NJB during the file transfer.
.TP 10
EO_INVALID
A required parameter was NULL.
.TP 10
EO_NOMEM
There was not enough memory to allocate the file transfer buffer.
.TP 10
EO_NOMEM
There was not enough memory to create the "tag" for the datafile.
.TP 10
EO_RDSHORT
The NJB sent fewer bytes than expected on the bulk data pipe.
.TP 10
EO_TIMEOUT
The NJB did not verify that the transfer was complete after several
queries. The file may have still have been transferred successfully.
.TP 10
EO_TOOBIG
There is not enough free disk space on the NJB to hold the file.
.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_WRSHORT
Fewer bytes than requested were written to the USB pipe.
.TP 10
EO_XFERDENIED
Could not determie the available disk space on the NJB.
.TP 10
EO_XFERERROR
The NJB returned a non-zero status when the tag for the datafile was
transferred.
.SH SEE ALSO
NJB_Get_File(3), datafile(3), XferCallback(3)
|
