NAME
The basic device management and information API -
Functions
int NJB_Discover (njb_t *njbs, int limit, int *n)
int NJB_Open (njb_t *njb)
void NJB_Close (njb_t *njb)
int NJB_Capture (njb_t *njb)
int NJB_Release (njb_t *njb)
void NJB_Ping (njb_t *njb)
int NJB_Get_Disk_Usage (njb_t *njb, u_int64_t *btotal, u_int64_t
*bfree)
char * NJB_Get_Owner_String (njb_t *njb)
int NJB_Set_Owner_String (njb_t *njb, const char *name)
int NJB_Get_Bitmap_Dimensions (njb_t *njb, int *x, int *y, int *bytes)
int NJB_Set_Bitmap (njb_t *njb, const unsigned char *bitmap)
njb_keyval_t * NJB_Get_Keys (njb_t *njb)
u_int64_t NJB_Get_NJB1_Libcounter (njb_t *njb)
int NJB_Send_Firmware (njb_t *njb, const char *path, NJB_Xfer_Callback
*callback, void *data)
int NJB_Get_Battery_Level (njb_t *njb)
int NJB_Get_Battery_Charging (njb_t *njb)
int NJB_Get_Auxpower (njb_t *njb)
int NJB_Get_SDMI_ID (njb_t *njb, u_int8_t *sdmiid)
const char * NJB_Get_Device_Name (njb_t *njb, int type)
int NJB_Get_Firmware_Revision (njb_t *njb, u_int8_t *major, u_int8_t
*minor, u_int8_t *release)
int NJB_Get_Hardware_Revision (njb_t *njb, u_int8_t *major, u_int8_t
*minor, u_int8_t *release)
int NJB_Set_Turbo_Mode (njb_t *njb, u_int8_t mode)
Function Documentation
int NJB_Capture (njb_t * njb) This captures a device for usage after
opening.
Parameters:
njb a pointer to the njb_t object to capture
Returns:
0 on success, -1 on failure
Examples:
cursesplay.c, delfile.c, deltr.c, dumpeax.c, dumptime.c, files.c,
fwupgrade.c, getfile.c, gettr.c, pl.c, play.c, playlists.c,
sendfile.c, sendtr.c, setpbm.c, settime.c, tagtr.c, and tracks.c.
References njb_struct::device_type, EO_BADCOUNT, njb_capture(),
NJB_DEVICE_NJB1, njb_get_library_counter(), and
njb_struct::protocol_state.
void NJB_Close (njb_t * njb) This closes a previously opened and used NJB
object.
Parameters:
njb a pointer to the njb_t object to close.
Examples:
cursesplay.c, delfile.c, deltr.c, dumpeax.c, dumptime.c, files.c,
fwupgrade.c, getfile.c, getowner.c, gettr.c, getusage.c,
handshake.c, pl.c, play.c, playlists.c, sendfile.c, sendtr.c,
setowner.c, setpbm.c, settime.c, and tracks.c.
References njb_struct::device_type, njb3_destroy_state(), njb_close(),
NJB_DEVICE_NJB3, and NJB_DEVICE_NJBZEN.
int NJB_Discover (njb_t * njbs, int limit, int * n) This scans the USB
buses for available devices, i.e. jukeboxes.
Parameters:
njbs a pointer to an array of njb_t objects that can be used for
storing up to limit objects.
limit the maximum number of njb_t device objects to retrieve
(currently unused).
n a pointer to a variable that will hold the number of objects
actually retrieved.
Returns:
0 on success, -1 on failure.
Examples:
cursesplay.c, delfile.c, deltr.c, dumpeax.c, dumptime.c, files.c,
fwupgrade.c, getfile.c, getowner.c, gettr.c, getusage.c,
handshake.c, pl.c, play.c, playlists.c, sendfile.c, sendtr.c,
setowner.c, setpbm.c, settime.c, tagtr.c, and tracks.c.
References njb_discover().
int NJB_Get_Auxpower (njb_t * njb) This function determines if we are on
auxiliary power (charger connected) or not. (It will also signify if
the USB power is connected on devices that support it.) One most
typical use of this function is to determine the status before any
firmware upgrade commence.
Parameters:
njb a pointer to the njb_t object to get the auxiliary power status
for.
Returns:
1 if we are connected to auxiliary power, 0 if we’re not, and -1 if
the call failed.
Examples:
handshake.c.
References njb_struct::device_type, njb3_power_status(),
NJB_DEVICE_NJB1, NJB_Ping(), njb_state_t::power, and
njb_struct::protocol_state.
int NJB_Get_Battery_Charging (njb_t * njb) This function determines if we
are charging the battery or not.
Parameters:
njb a pointer to the njb_t object to get the charging status for.
Returns:
1 if we are charging, 0 if we’re not charging, and -1 if the call
failed.
Examples:
handshake.c.
References njb_struct::device_type, njb3_power_status(),
NJB_DEVICE_NJB1, NJB_Ping(), njb_state_t::power, and
njb_struct::protocol_state.
int NJB_Get_Battery_Level (njb_t * njb) This function returns the current
battery level between 0 and 100. The hardware will typically prevent
the device from working properly if the battery level is too low, so
figures above 50 are the most common.
Parameters:
njb a pointer to the njb_t object to get the battery level for.
Returns:
the battery level between 0 and 100, or -1 if the function call
fails.
Examples:
handshake.c.
References njb_struct::device_type, njb3_power_status(),
NJB_DEVICE_NJB1, NJB_Ping(), njb_state_t::power, and
njb_struct::protocol_state.
int NJB_Get_Bitmap_Dimensions (njb_t * njb, int * x, int * y, int * bytes)
EXPERIMENTAL: This function returns the dimensions for the bitmap image
on the device, in case the bitmap can be set. Returns -1 if the device
does not support setting the bitmap. Currently this command only
supports sending bitmap to the NJB2, other models are unsupported, so
this needs some development.
Parameters:
njb a pointer to the jukebox object to use
x Number of pixels on the X axis
y Number of pixels on the Y axis
bytes number of bytes for the entire bitmap image
Returns:
0 on success, -1 if setting bitmap is not possible
See also:
NJB_Set_Bitmap()
Examples:
setpbm.c.
References njb_struct::device_type, njb3_state_t::fwMajor,
njb3_state_t::fwMinor, njb3_state_t::fwRel, NJB_DEVICE_NJB2,
NJB_DEVICE_NJB3, NJB_DEVICE_NJBZEN, NJB_DEVICE_NJBZEN2,
NJB_DEVICE_NJBZENNX, NJB_DEVICE_NJBZENTOUCH, NJB_DEVICE_NJBZENXTRA, and
njb_struct::protocol_state.
Referenced by NJB_Set_Bitmap().
const char* NJB_Get_Device_Name (njb_t * njb, int type) This function
returns the name of the jukebox device as a string.
char *name;
name = NJB_Get_Device_Name(njb, 0);
if (name != NULL) {
printf(’Device name: %s\n’, name);
}
Parameters:
njb a pointer to the njb_t object to get the device name for.
type decides whether libnjb should decide what kind of device this
is, or if the string from the device itself should be used. 0 = use
libnjb detection (based on USB device IDs), 1 = get the string from
the device itself. If you set this to type 1, you must first call
NJB_Open() on the njb_t object pointer, so this is not suitable
when you want to display a selection list of available devices
prior to opening one of them.
Returns:
a pointer to a string that contains the device name string after a
call to this function. The string must not be freed by the caller,
because this is a pointer into a string holder inside libnjb! On
error, NULL will be returned.
Examples:
handshake.c.
References njb_struct::device_type, NJB_DEVICE_NJB1,
njb_get_usb_device_name(), njb3_state_t::product_name,
njb_state_t::productName, and njb_struct::protocol_state.
int NJB_Get_Disk_Usage (njb_t * njb, u_int64_t * btotal, u_int64_t * bfree)
This retrieves the amount of currently used disk space in bytes.
Parameters:
njb a pointer to the njb_t object to get usage for
btotal a pointer to a 64 bit integer that shall hold the number of
total bytes on the device after the call
bfree a pointer to a 64 bit integer that shall hold the number of
free bytes on the device after the call
Returns:
0 on success, -1 on failure
Examples:
getusage.c.
References njb_struct::device_type, NJB_DEVICE_NJB1, and
njb_get_disk_usage().
Referenced by NJB_Send_Track().
int NJB_Get_Firmware_Revision (njb_t * njb, u_int8_t * major, u_int8_t *
minor, u_int8_t * release) This function returns the firmware revision
for a certain jukebox device. The release parameter will not be valid
for the NJB1 since this only has two version numbers. Example usage:
uint8 major;
uint8 minor;
uint8 release;
NJB_Get_Firmware_Revision(njb, &major, &minor, &release);
printf(’Firmware revision: %d.%d.%d\n’, major, minor, release);
Parameters:
njb a pointer to the njb_t object to get the firmware revision for.
major will hold the major revision number for the firmware after
the call, if the call was successful.
minor will hold the minor revision number for the firmware after
the call, if the call was successful.
release will hold the release number for the firmware after the
call, if the call was successful.
Returns:
0 if the call was successful, -1 on failure.
Examples:
handshake.c.
References njb_struct::device_type, njb3_state_t::fwMajor,
njb_state_t::fwMajor, njb3_state_t::fwMinor, njb_state_t::fwMinor,
njb3_state_t::fwRel, NJB_DEVICE_NJB1, and njb_struct::protocol_state.
int NJB_Get_Hardware_Revision (njb_t * njb, u_int8_t * major, u_int8_t *
minor, u_int8_t * release) This function returns the hardware revision
for a certain jukebox device. This information is hardcoded to ’1.0.0’
for the NJB1 since that device does not support retrieving the hardware
revision.
Parameters:
njb a pointer to the njb_t object to get the hardware revision for.
major will hold the major revision number for the hardware after
the call, if the call was successful.
minor will hold the minor revision number for the hardware after
the call, if the call was successful.
release will hold the release number for the hardware after the
call, if the call was successful.
Returns:
0 if the call was successful, -1 on failure.
Examples:
handshake.c.
References njb_struct::device_type, njb3_state_t::hwMajor,
njb3_state_t::hwMinor, njb3_state_t::hwRel, NJB_DEVICE_NJB1, and
njb_struct::protocol_state.
njb_keyval_t* NJB_Get_Keys (njb_t * njb) On series 3 devices, this command
retrieves some key/value pairs that are believed to be used for DRM
schemes. We have no idea of how to use these, just that they make
possible to do proper signing of protected WMA files before transfer.
Parameters:
njb a pointer to the jukebox object to get the keys from.
Examples:
handshake.c.
u_int64_t NJB_Get_NJB1_Libcounter (njb_t * njb) This retrieves the library
counter for the Nomad Jukebox 1 (D.A.P., the original). The library
counter can be used to validate a track cache for this device, but not
for any other devices. If you have a cache with all tracks, datafiles
and playlists (in some self-defined format) you can store it along with
this number when your program exits. When you restart your program you
can check if the numbers are still the same, and if they are, you can
keep using your old track/file/playlist cache and need not re-read that
information.
Note that you have to take action to make sure that you do not
accidentally lock out series 3 devices! If this function returns zero,
always re-read the entire library.
Parameters:
njb a pointer to the jukebox object to get the library counter
from.
Returns:
a library counter, if this is 0, the tracks, playlists and
datafiles need to be re-read, i.e. the cached database is invalid.
Examples:
handshake.c.
References njb_struct::device_type, NJB_DEVICE_NJB1, and
njb_struct::protocol_state.
char* NJB_Get_Owner_String (njb_t * njb) This retrieves the owner string
for the device, a string representing the owners name.
Parameters:
njb a pointer to the njb_t object to get the owner string for
Returns:
a valid owner string or NULL on failure. The string is newly
allocated on the heap and should be freed by the caller after use.
Examples:
getowner.c, and setowner.c.
References njb_struct::device_type, EO_NOMEM, NJB_DEVICE_NJB1,
NJB_UC_UTF8, and strtoutf8().
int NJB_Get_SDMI_ID (njb_t * njb, u_int8_t * sdmiid) This function returns
the unique SDMI ID of 16 bytes for a jukebox device. Example:
u_int8_t sdmiid[16];
int result;
result = NJB_Get_SDMI_ID(njb, &sdmiid);
Parameters:
njb a pointer to the njb_t object to get the SDMI ID for.
sdmiid a pointer to a byte array of 16 bytes (declare this as
u_int8_t foo[16];) that will hold the SDMI ID if the function
completed successfully.
Returns:
0 on success, -1 on failure.
Examples:
handshake.c.
References njb_struct::device_type, NJB_DEVICE_NJB1,
njb_struct::protocol_state, and njb_state_t::sdmiid.
int NJB_Open (njb_t * njb) This opens a device for use. This routine will
initialize the USB endpoints and interfaces, and allocate an error
stack so that error reporting routines can be used after this call.
Parameters:
njb a pointer to the NJB object to open
Returns:
0 on success, -1 on failure
Examples:
cursesplay.c, delfile.c, deltr.c, dumpeax.c, dumptime.c, files.c,
fwupgrade.c, getfile.c, getowner.c, gettr.c, getusage.c,
handshake.c, pl.c, play.c, playlists.c, sendfile.c, sendtr.c,
setowner.c, setpbm.c, settime.c, tagtr.c, and tracks.c.
References njb_struct::device_type, njb3_init_state(), NJB_DEVICE_NJB1,
NJB_DEVICE_NJB3, NJB_DEVICE_NJBZEN, NJB_Handshake(), njb_init_state(),
and njb_open().
void NJB_Ping (njb_t * njb) This sends a ping (’are you there?’) command to
the device.
Parameters:
njb a pointer to the jukebox object to ping.
Examples:
handshake.c.
References njb_struct::device_type, NJB_DEVICE_NJB1, and njb_ping().
Referenced by NJB_Get_Auxpower(), NJB_Get_Battery_Charging(), and
NJB_Get_Battery_Level().
int NJB_Release (njb_t * njb) This releases a captured NJB object after
use.
Parameters:
njb a pointer to the njb_t object to release
Returns:
0 on success, -1 on failure
Examples:
cursesplay.c, delfile.c, deltr.c, dumpeax.c, dumptime.c, files.c,
fwupgrade.c, getfile.c, gettr.c, pl.c, play.c, playlists.c,
sendfile.c, sendtr.c, setpbm.c, settime.c, tagtr.c, and tracks.c.
References njb_struct::device_type, njb_capture(), and NJB_DEVICE_NJB1.
int NJB_Send_Firmware (njb_t * njb, const char * path, NJB_Xfer_Callback *
callback, void * data) EXPERIMENTAL: This function sends a new firmware
to the device.
DO NOT TRY OR USE THIS FUNCTION UNLESS YOU ARE 100 PERCENT SURE OF WHAT
YOU ARE DOING, IT IS VITALLY DANGEROUS TO YOUR DEVICE AND MAY RENDER IT
COMPLETELY USELESS IF USED WITH INVALID DATA.
Parameters:
njb a pointer to the njb_t object to send the file to
path a path to the firmware file that shall be downloaded. This
file must be the raw firmware chunks as sent across the USB bus to
the device.
callback a function that will be called repeatedly to report
progress during transfer, used for e.g. displaying progress bars.
This may be NULL if you don’t like callbacks.
data a voluntary parameter that can associate some user-supplied
data with each callback call. It is OK to set this to NULL of
course.
Returns:
0 on success, -1 on failure.
Examples:
fwupgrade.c.
References _file_size(), EO_INVALID, EO_SRCFILE,
njb3_announce_firmware(), and njb3_get_firmware_confirmation().
int NJB_Set_Bitmap (njb_t * njb, const unsigned char * bitmap)
EXPERIMENTAL: This sets the bitmap (boot-up logo) on the device. It is
currently experimental and not all devices support changing the bitmap.
Parameters:
njb a pointer to the jukebox object to use
bitmap A raw bitmap image to send to the device. Note that this
image shall have the dimensions indicated by a previous
NJB_Get_Bitmap_Dimensions() call.
Returns:
0 on success, -1 on failure
See also:
NJB_Get_Bitmap_Dimensions()
Examples:
setpbm.c.
References njb3_set_bitmap(), and NJB_Get_Bitmap_Dimensions().
int NJB_Set_Owner_String (njb_t * njb, const char * name) This sets the
owner string for the device, a string representing the owner.
Parameters:
njb a pointer to the njb_t object to set the owner string for
name the new owner string
Returns:
0 on success, -1 on failure
Examples:
setowner.c.
References njb_struct::device_type, NJB_DEVICE_NJB1, NJB_UC_UTF8,
njb_verify_last_command(), OWNER_STRING_LENGTH, and utf8tostr().
int NJB_Set_Turbo_Mode (njb_t * njb, u_int8_t mode) This function sets the
turbo mode to on or off. The default value if the function is not
called is that turbo is ON. We have found that a few (very few) devices
will react badly on turbo mode, resulting in bad transfers. This
setting is only applicable on the series 3 devices, it will have no
effect on the NJB1. (Command available as of libnjb 2.2.4.)
Example usage:
NJB_Set_Turbo_Mode(njb, NJB_TURBO_OFF);
Parameters:
njb a pointer to the njb_t object to set the turbo mode for.
mode the turbo mode. NJB_TURBO_ON or NJB_TURBO_OFF.
Returns:
0 if the call was successful, -1 on failure.
References njb_struct::protocol_state, and njb3_state_t::turbo_mode.
Author
Generated automatically by Doxygen for libnjb from the source code.
Version 2.2.5 The basicadevice management and information API(3)