libnjb  2.2.7
Data Structures | Macros | Functions
protocol3.h File Reference
#include "libnjb.h"

Go to the source code of this file.

Data Structures

struct  njb3_state_t
 

Macros

#define NJB3_SHORTREAD_BUFSIZE   1024
 
#define NJB3_CHUNK_SIZE   0x100000U
 
#define NJB3_FIRMWARE_CHUNK_SIZE   0x40000U
 
#define NJB3_DEFAULT_GET_FILE_BLOCK_SIZE   0x2000U
 
#define NJB3_DEFAULT_SEND_FILE_BLOCK_SIZE   0x2000U
 
#define NJB3_CODECS_FRAME_ID   0x0001U /* 16 bit array R: List of supported audio file types/codecs */
 
#define NJB3_DISKUTIL_FRAME_ID   0x0002U /* 14 bytes R: disk utilization information */
 
#define NJB3_PRODID_FRAME_ID   0x0003U /* 3 bytes FW rev 3 bytes HW rev, string product ID */
 
#define NJB3_LOCKED_FRAME_ID   0x0006U /* 16 bit word */
 
#define NJB3_FNAME_FRAME_ID   0x0007U /* String: Original filename on host */
 
#define NJB3_UNKNOWN1_FRAME_ID   0x0008U /* 16 bit word, value 0x0004 on NJB Zen USB 2.0, not read by Win SW */
 
#define NJB3_KEY_FRAME_ID   0x000aU /* 4 bytes string "AR00", "PL00", "SG00", "LG00" known */
 
#define NJB3_CODEC_FRAME_ID   0x000bU /* 16 bit word */
 
#define NJB3_POSTID_FRAME_ID   0x000cU /* 16 bit word TrackID on tracks, PlaylistID on playlists */
 
#define NJB3_DIR_FRAME_ID   0x000dU /* String: Original directory on host */
 
#define NJB3_FILESIZE_FRAME_ID   0x000eU /* 32 bit word */
 
#define NJB3_FILECOUNT_FRAME_ID   0x0013U /* 32 bit word R: file & directory count */
 
#define NJB3_VALUE_FRAME_ID   0x0014U /* 8 bytes, 2*32 bit words */
 
#define NJB3_JUKEBOXID_FRAME_ID   0x0015U /* 16 bytes R: unique device ID */
 
#define NJB3_FILETIME_FRAME_ID   0x0016U /* 32 bit word - timestamp (UNIX format) */
 
#define NJB3_UNKNOWN6_FRAME_ID   0x0017U /* 32 bit word - could be FAT32 attributes */
 
#define NJB3_FILEFLAGS_FRAME_ID   0x0018U /* 32 bit word set on files and folders - NTFS file attributes */
 
#define NJB3_ALBUM_FRAME_ID   0x0101U /* String */
 
#define NJB3_ARTIST_FRAME_ID   0x0102U /* String */
 
#define NJB3_GENRE_FRAME_ID   0x0103U /* String */
 
#define NJB3_TITLE_FRAME_ID   0x0104U /* String */
 
#define NJB3_LENGTH_FRAME_ID   0x0105U /* String */
 
#define NJB3_TRACKNO_FRAME_ID   0x0106U /* 16 bit word */
 
#define NJB3_YEAR_FRAME_ID   0x0107U /* 16 bit word */
 
#define NJB3_SMARTPAR_FRAME_ID   0x010aU
 
#define NJB3_PLAYINFO_FRAME_ID   0x010bU
 
#define NJB3_SEEKTRACK_FRAME_ID   0x010cU /* 32 bit word W: seek to position (in ms) in current track */
 
#define NJB3_EAX_TYPENAME   0x010eU /* String with the name of an EAX type */
 
#define NJB3_PLNAME_FRAME_ID   0x010fU /* String: playlist name */
 
#define NJB3_TIME_FRAME_ID   0x0110U
 
#define NJB3_ALBUMCNT_FRAME_ID   0x0111U /* 32 bit word R: number of albums on device */
 
#define NJB3_TRACKCNT_FRAME_ID   0x0112U /* 32 bit word R: number of tracks on device */
 
#define NJB3_OWNER_FRAME_ID   0x0113U /* String: owner name */
 
#define NJB3_BATTERY_FRAME_ID   0x0114U
 
#define NJB3_PLCNT_FRAME_ID   0x0115U /* 32 bit word: number of playlists on device */
 
#define NJB3_PLAYTRACK_FRAME_ID   0x0119U /* 32 bit word track ID to play */
 
#define NJB3_UNKNOWN4_FRAME_ID   0x011aU
 
#define NJB3_PLTRACKS_FRAME_ID   0x011cU /* Array of 16bit words */
 
#define NJB3_MINMAX_ID   0x0201U /* 2x16 bit values, max and min */
 
#define NJB3_EAX_ACTIVE_ID
 
#define NJB3_VOLUME_FRAME_ID   0x0203U /* 16 bit word */
 
#define NJB3_ENV_FRAME_ID   0x0204U /* 16 bit word - environment setting */
 
#define NJB3_EQ_FRAME_ID   0x0205U /* 16 bit word - equalizer setting */
 
#define NJB3_SPAT_FRAME_ID   0x0206U /* 16 bit word - spatialization 2 = full */
 
#define NJB3_TSCALE_FRAME_ID   0x0207U /* 16 bit word - time scaling factor */
 
#define NJB3_SMARTVOL_FRAME_ID   0x0208U /* 16 bit word - smart volume setting */
 
#define NJB3_EAXACTIVE_FRAME_ID   0x020aU /* 16 bit word - 0x0000/0x0001 = activate/deactivate EAX processor */
 
#define NJB3_EAXID_FRAME_ID   0x020bU /* 16 bit word with the numerical ID of a certain EAX type */
 
#define NJB3_EAX_INDEX_ID   0x020cU /* 16 bit word - currently selected effect in a set of effects */
 
#define NJB3_KEYVALUE_FRAME_ID
 
#define NJB3_FILE_DATABASE   0x0000U
 
#define NJB3__PLAYLIST_DATABASE   0x0001U
 
#define NJB3_TRACK_DATABASE   0x0002U
 
#define NJB3_CODEC_MP3_ID_OLD   0x0000U /* Used on NJB3/Zen FW? */
 
#define NJB3_CODEC_WAV_ID   0x0001U
 
#define NJB3_CODEC_MP3_ID   0x0002U
 
#define NJB3_CODEC_WMA_ID   0x0003U
 
#define NJB3_CODEC_AA_ID   0x0007U /* Audible.com codec */
 
#define NJB3_CODEC_PROTECTED_WMA_ID   0x0203U /* Is it two bytes actually? */
 
#define NJB3_START_PLAY   0x00
 
#define NJB3_STOP_PLAY   0x01
 
#define NJB3_PAUSE_PLAY   0x02
 
#define NJB3_RESUME_PLAY   0x03
 
#define NJB3_STATUS_OK   0x0000U
 
#define NJB3_STATUS_EMPTY   0x0001U /* You tried to retrieve an empty item */
 
#define NJB3_STATUS_TRANSFER_ERROR   0x0002U /* Error during read or write */
 
#define NJB3_STATUS_BAD_FILESIZE   0x0003U /* Illegal file size (e.g. negative, too large) */
 
#define NJB3_STATUS_NOTIMPLEMENTED   0x0004U /* For example if EAX is not supported on a device */
 
#define NJB3_STATUS_NOTEXIST   0x0005U /* Tried to access nonexistant track */
 
#define NJB3_STATUS_PROTECTED   0x000cU /* Tried to access protected object */
 
#define NJB3_STATUS_EMPTY_CHUNK
 
#define njb3_start_play(njb)   njb3_ctrl_playing(njb, NJB3_START_PLAY)
 
#define njb3_stop_play(njb)   njb3_ctrl_playing(njb, NJB3_STOP_PLAY)
 
#define njb3_pause_play(njb)   njb3_ctrl_playing(njb, NJB3_PAUSE_PLAY)
 
#define njb3_resume_play(njb)   njb3_ctrl_playing(njb, NJB3_RESUME_PLAY)
 

Functions

int njb3_init_state (njb_t *njb)
 
int njb3_set_bitmap (njb_t *njb, u_int16_t x_size, u_int16_t y_size, const unsigned char *bitmap)
 
int njb3_current_track (njb_t *njb, u_int16_t *track)
 
int njb3_elapsed_time (njb_t *njb, u_int16_t *elapsed, int *change)
 
int njb3_play_track (njb_t *njb, u_int32_t trackid)
 
int njb3_queue_track (njb_t *njb, u_int32_t trackid)
 
int njb3_clear_play_queue (njb_t *njb)
 
int njb3_ctrl_playing (njb_t *njb, int cmd)
 
int njb3_seek_track (njb_t *njb, u_int32_t position)
 
int njb3_get_codecs (njb_t *njb)
 
int njb3_ping (njb_t *njb, int type)
 
int njb3_power_status (njb_t *njb, int *battery_level, int *charging, int *ac_power)
 
int njb3_readid (njb_t *njb, u_int8_t *sdmiid)
 
int njb3_capture (njb_t *njb)
 
int njb3_release (njb_t *njb)
 
int njb3_get_disk_usage (njb_t *njb, u_int64_t *totalbytes, u_int64_t *freebytes)
 
int njb3_turnoff_flashing (njb_t *njb)
 
int njb3_get_owner_string (njb_t *njb, char *name)
 
int njb3_set_owner_string (njb_t *njb, const char *name)
 
njb_time_tnjb3_get_time (njb_t *njb)
 
int njb3_set_time (njb_t *njb, njb_time_t *time)
 
int njb3_reset_get_track_tag (njb_t *njb)
 
njb_songid_tnjb3_get_next_track_tag (njb_t *njb)
 
int njb3_reset_get_playlist_tag (njb_t *njb)
 
njb_playlist_tnjb3_get_next_playlist_tag (njb_t *njb)
 
int njb3_reset_get_datafile_tag (njb_t *njb)
 
njb_datafile_tnjb3_get_next_datafile_tag (njb_t *njb)
 
int njb3_read_keys (njb_t *njb)
 
njb_keyval_tnjb3_get_keys (njb_t *njb)
 
int njb3_request_file_chunk (njb_t *njb, u_int32_t fileid, u_int32_t offset)
 
int njb3_get_file_block (njb_t *njb, unsigned char *data, u_int32_t maxsize)
 
u_int32_t njb3_create_file (njb_t *njb, unsigned char *ptag, u_int32_t tagsize, u_int16_t database)
 
u_int32_t njb3_send_file_chunk (njb_t *njb, unsigned char *chunk, u_int32_t chunksize, u_int32_t fileid)
 
int njb3_send_file_complete (njb_t *njb, u_int32_t fileid)
 
int njb3_create_folder (njb_t *njb, const char *name, u_int32_t *folderid)
 
int njb3_delete_item (njb_t *njb, u_int32_t itemid)
 
int njb3_update_16bit_frame (njb_t *njb, u_int32_t itemid, u_int16_t frameid, u_int16_t value)
 
int njb3_update_string_frame (njb_t *njb, u_int32_t itemid, u_int16_t frameid, unsigned char *str)
 
int njb3_update_tag (njb_t *njb, u_int32_t trackid, unsigned char *ptag, u_int32_t ptagsize)
 
int njb3_create_playlist (njb_t *njb, char *name, u_int32_t *plid)
 
int njb3_add_multiple_tracks_to_playlist (njb_t *njb, u_int32_t *plid, u_int32_t *trids, u_int16_t ntracks)
 
int njb3_adjust_volume (njb_t *njb, u_int16_t value)
 
int njb3_control_eax_processor (njb_t *njb, u_int16_t state)
 
int njb3_adjust_eax (njb_t *njb, u_int16_t eaxid, u_int16_t patchindex, u_int16_t active, u_int16_t scalevalue)
 
void njb3_read_eaxtypes (njb_t *njb)
 
njb_eax_tnjb3_get_nexteax (njb_t *njb)
 
int njb3_announce_firmware (njb_t *njb, u_int32_t size)
 
u_int32_t njb3_send_firmware_chunk (njb_t *njb, u_int32_t chunksize, unsigned char *chunk)
 
int njb3_get_firmware_confirmation (njb_t *njb)
 
void njb3_destroy_state (njb_t *njb)
 

Detailed Description

This is the main header file for the "series 3" protocol that is believed to have the internal name "PDE" at Creative, an acronym that probably reads out "Personal Digital Entertainment".

The protocol has three distinct namespaced ("enum series") that are used for communications. These are:

  1. Command namespace, all commands that can be sent are uniquely enumerated.
  2. Device register and frame namespace: all kind of metadata, database data and device registers (!) are enumerated in the same namespace, making very different things share the same number series.
  3. Return types (error codes).
  4. Codecs.
  5. File types (or databases), it's just track, file or playlist really.

Known commands (first 16 bits)

0x0001 Update database item metadata on files, tracks, playlists also used for adding smartvolume information to tracks 0x0002 Get file/track chunk 0x0003 Send file/track chunk 0x0004 Create database file item (files and tracks) 0x0005 Delete database file item (files and tracks) 0x0006 Read database tracks, datafiles, playlists, all the commands seen for this code has produced a dump of the entire database so these are all-or-nothing operations. 0x0007 Set device register - owner string, current track position, play status (pause/stop), set time, EAX processor mode (on/off) 0x0008 Request device register - codecs, device info, ID, fw version, hw version, disk usage, owner string, time, current track position, play status (pause/stop), number of tracks, albums or playlists, battery status. 0x0009 Send file/track complete 0x000a Create folder or playlist (empty, non-file item entry in database) 0x000b Load device firmware (bitmaps and firmware upgrade) 0x000c Get device keys, returns a number of device-unique keys. 0x0010 Verify file?? 0x0100 Playback track (on the device) 0x0101 Get elapsed time for current track, just 4 bytes 0101 0001 0x0103 Clear playback queue 0x0104 Enqueue track for playing 0x0107 Add tracks to playlist 0x0108 Get tracks for playlist 0x0200 Get EAX effect settings 0x0201 Adjust EAX setting

Macro Definition Documentation

◆ NJB3_EAX_ACTIVE_ID

#define NJB3_EAX_ACTIVE_ID
Value:
0x0202U /* 16 bit word - this EAX type is active/to
* be activated (0x0000 = off, 0x0001 = on) */

◆ NJB3_KEYVALUE_FRAME_ID

#define NJB3_KEYVALUE_FRAME_ID
Value:
0x1400U /* Array of value-key-pairs, requested in a
subrequest parameter to this request */

◆ NJB3_STATUS_EMPTY_CHUNK

#define NJB3_STATUS_EMPTY_CHUNK
Value:
0x000eU /* Appear when requesting empty metadata lists
* or beyond the end of files. */

Function Documentation

◆ njb3_add_multiple_tracks_to_playlist()

int njb3_add_multiple_tracks_to_playlist ( njb_t njb,
u_int32_t *  plid,
u_int32_t *  trids,
u_int16_t  ntracks 
)

This takes an array of 32-bit track ID:s and adds it to a certain playlist.

Parameters
plida pointer to the ID of the playlist to add tracks to. The ID will change during this operation, so it is important to pass in a pointer.
tridsan array of tracks to add
ntracksabsolute number of tracks in the array.

References EO_NOMEM, from_16bit_to_njb3_bytes(), and from_32bit_to_njb3_bytes().

◆ njb3_announce_firmware()

int njb3_announce_firmware ( njb_t njb,
u_int32_t  size 
)

This announces a firmware image which will then be sent in several chunks.

Parameters
njba pointer to the njb device object to use
sizethe total size of the firmware image
Returns
0 on success, -1 on failure

References from_32bit_to_njb3_bytes().

Referenced by NJB_Send_Firmware().

◆ njb3_control_eax_processor()

int njb3_control_eax_processor ( njb_t njb,
u_int16_t  state 
)

This command turns the EAX DSP processor on or off. You will also have to adjust the currently used EAX effect with njb3_adjust_eax() below.

References from_16bit_to_njb3_bytes().

◆ njb3_create_playlist()

int njb3_create_playlist ( njb_t njb,
char *  name,
u_int32_t *  plid 
)

This function creates a new playlist on the device.

Parameters
namethe name of the playlist to create, as a string.
plida pointer to a 32-bit numer that will contain the new playlist ID after this routine has been called.
Returns
0 on success, -1 on failure.

References EO_NOMEM, from_16bit_to_njb3_bytes(), and ucs2strlen().

◆ njb3_destroy_state()

void njb3_destroy_state ( njb_t njb)

Cleans up any dangling lists in the njb_t state holder struct, and other stuff related to the state.

References njb_keyval_struct::next, and njb_struct::protocol_state.

◆ njb3_get_codecs()

int njb3_get_codecs ( njb_t njb)

Reads the supported audio file types.

◆ njb3_get_file_block()

int njb3_get_file_block ( njb_t njb,
unsigned char *  data,
u_int32_t  maxsize 
)

This function retrieves a part of the requested chunk. Short reads are allowed, so the caller must make sure that it is called as many times as is needed to retrieve the entire file chunk.

Parameters
dataan allocated byte array to store the retrieved chunk in.
maxsizethe maximum number of bytes to retrieve from this chunk at a time.

References EO_USBBLK, and usb_pipe_read().

◆ njb3_get_firmware_confirmation()

int njb3_get_firmware_confirmation ( njb_t njb)

This simply reads back the device status after a firmware upgrade.

◆ njb3_init_state()

int njb3_init_state ( njb_t njb)

◆ njb3_power_status()

int njb3_power_status ( njb_t njb,
int *  battery_level,
int *  charging,
int *  ac_power 
)

This function reads out the current battery level and charging status from a series 3 device.

Parameters
battery_levela variable that will hold the current level after the call.
chargingif the battery is charging, this variable will hold 1 after the call, else 0.
ac_powerif the charger is connected, this variable will hold 1 after the call, else 0.
Returns
0 on success, -1 on failure. If the call fails, all other return values are invalid.

Referenced by NJB_Get_Auxpower(), NJB_Get_Battery_Charging(), and NJB_Get_Battery_Level().

◆ njb3_request_file_chunk()

int njb3_request_file_chunk ( njb_t njb,
u_int32_t  fileid,
u_int32_t  offset 
)

This function requests a chunk from a certain file. The offset may index into the file. The chunk transfer size is 1MB by default (as used by creative) but may actually exceed that.

Returns actual chunk size or -1 if failed.

References from_32bit_to_njb3_bytes().

◆ njb3_reset_get_datafile_tag()

int njb3_reset_get_datafile_tag ( njb_t njb)

This routine retrieves the list of datafiles, and returns the first item.

References njb_struct::protocol_state.

Referenced by NJB_Reset_Get_Datafile_Tag().

◆ njb3_reset_get_playlist_tag()

int njb3_reset_get_playlist_tag ( njb_t njb)

This routine retrieves the list of playlists, while also filling in each playlist post with it's respective track ID:s.

References njb_struct::protocol_state.

Referenced by NJB_Reset_Get_Playlist().

◆ njb3_send_firmware_chunk()

u_int32_t njb3_send_firmware_chunk ( njb_t njb,
u_int32_t  chunksize,
unsigned char *  chunk 
)

This sends a chunk of firmware. Typically the chunks are NJB3_FIRMWARE_CHUNK_SIZE each, except for the last chunk.

Parameters
njba pointer to the njb device object to use
chunksizethe size of this chunk
chunka pointer to the raw bytes representing this firmware chunk
Returns
0 on success, -1 on failure

◆ njb3_set_bitmap()

int njb3_set_bitmap ( njb_t njb,
u_int16_t  x_size,
u_int16_t  y_size,
const unsigned char *  bitmap 
)

NJB2 only (shall be expanded for all jukeboxes). Set up the black/white bitmap shown on shutdown.

The bitmap must be exactly 1088 bytes large, coded as a serial bitmap of 136x64 pixels. The final 4 bits per line are not shown, because the the display of the NJB2 has only 132x64 pixels.

A set pixel (1) means dark, an unset means white.

To create a compatible bitmap, take a 132x64 PBM file (of course not a ASCII-coded, but a binary "P4") and cut off the header.

Explaination of the JBM1 file format:

Byte offset:     Contents:
0x00 - 0x03      "JBM1"
0x04 - 0x05      width of bitmap in pixels 16bit
                 unsigned bigendian integer
0x06 - 0x07      height of bitmap in pixels 16bit
                 unsigned bigendian integer
0x08 - 0x0b      file format version? contains 0x00000001
                 as a 32bit unsigned bigendian integer
0x0c - fileend   actual bitmap data

The bitmap data is black-and-white and each bit represents a single pixel. A set pixel is 1 and a cleared pixel is 0. The bitmap is stored in 16bit unsigned integers which are little-endian, and each of these 16bit integers form a vertical, eight-pixel high and two-pixel wide "bar".

References EO_NOMEM, from_16bit_to_njb3_bytes(), and from_32bit_to_njb3_bytes().

Referenced by NJB_Set_Bitmap().

◆ njb3_update_16bit_frame()

int njb3_update_16bit_frame ( njb_t njb,
u_int32_t  itemid,
u_int16_t  frameid,
u_int16_t  value 
)

This function will update a single 16bit metadata frame associated with a certain item (track, playlist or datafile). Only call this function to modify 16-bit values!

Parameters
itemidthe item ID (track, playlist or datafile) to modify.
frameidthe frame ID of the frame to modyfy. Must be a 16-bit frame.
valudthe new 16-bit value.

References from_16bit_to_njb3_bytes(), and from_32bit_to_njb3_bytes().

◆ njb3_update_string_frame()

int njb3_update_string_frame ( njb_t njb,
u_int32_t  itemid,
u_int16_t  frameid,
unsigned char *  str 
)

This function updates a single string of metadata associated with a certain item (track, playlist or datafile). Only call this routine to modify string frames!

Parameters
itemidthe item ID (track, playlist or datafile) to be modified.
frameidthe frame ID of the frame to be updated.
strthe new string value.

References EO_NOMEM, from_16bit_to_njb3_bytes(), from_32bit_to_njb3_bytes(), and ucs2strlen().

◆ njb3_update_tag()

int njb3_update_tag ( njb_t njb,
u_int32_t  itemid,
unsigned char *  ptag,
u_int32_t  ptagsize 
)

A function to update a block of metadata on the series 3 devices.

Parameters
itemidthe track (or similar) whose metadata is to be updated.
ptaga packed metadata structure for series 3 devices.
Returns
0 on success, -1 on failure.

References EO_NOMEM, and from_32bit_to_njb3_bytes().

Referenced by NJB_Replace_Track_Tag().