# protocol3.h

Go to the documentation of this file.

    00001
    00057 #ifndef __NJB__PROTO3__H
    00058 #define __NJB__PROTO3__H
    00059
    00060 #include "libnjb.h"
    00061
    00062 /* Buffer for short reads */
    00063 #define NJB3_SHORTREAD_BUFSIZE 1024
    00064
    00065 /* Transfer block size (adding and fetching tracks, files */
    00066 #define NJB3_CHUNK_SIZE 0x100000U
    00067 #define NJB3_FIRMWARE_CHUNK_SIZE 0x40000U
    00068 #define NJB3_DEFAULT_GET_FILE_BLOCK_SIZE    0x2000U
    00069 #define NJB3_DEFAULT_SEND_FILE_BLOCK_SIZE   0x2000U
    00070
    00071 /*
    00072  * These are the frame IDs used by the series 3 devices.
    00073  * The frames are used for all the commands listed above, so
    00074  * the same number series will contain very different things
    00075  * like different kind of device properties and parameters
    00076  * (e.g. disk utilization) and metadata tag elements (e.g.
    00077  * "artist field"). The only way to see what a frame actually
    00078  * represents is to see how it is used.
    00079  */
    00080 #define NJB3_CODECS_FRAME_ID    0x0001U /* 16 bit array R: List of supported audio file types/codecs */
    00081 #define NJB3_DISKUTIL_FRAME_ID  0x0002U /* 14 bytes R: disk utilization information */
    00082 #define NJB3_PRODID_FRAME_ID    0x0003U /* 3 bytes FW rev 3 bytes HW rev, string product ID */
    00083 /*
    00084  * 0x0004 and 0x0005 return NULL when read as device
    00085  * parameters, are probably used as some kind of
    00086  * metadata frames.
    00087  */
    00088 #define NJB3_LOCKED_FRAME_ID    0x0006U /* 16 bit word */
    00089 #define NJB3_FNAME_FRAME_ID     0x0007U /* String: Original filename on host */
    00090 #define NJB3_UNKNOWN1_FRAME_ID  0x0008U /* 16 bit word, value 0x0004 on NJB Zen USB 2.0, not read by Win SW */
    00091 #define NJB3_KEY_FRAME_ID       0x000aU /* 4 bytes string "AR00", "PL00", "SG00", "LG00" known */
    00092 #define NJB3_CODEC_FRAME_ID     0x000bU /* 16 bit word */
    00093 #define NJB3_POSTID_FRAME_ID    0x000cU /* 16 bit word TrackID on tracks, PlaylistID on playlists */
    00094 #define NJB3_DIR_FRAME_ID       0x000dU /* String: Original directory on host */
    00095 #define NJB3_FILESIZE_FRAME_ID  0x000eU /* 32 bit word */
    00096 /*
    00097  * 0x0010 and 0x0011 return a 16-bit value of 0x0002
    00098  * respective 0x0200 when read as device parameters.
    00099  * e.g. 0000 0004 0011 0200 0000
    00100  * 0x0011 may be sector size or USB xfer block size...
    00101  */
    00102 #define NJB3_FILECOUNT_FRAME_ID 0x0013U /* 32 bit word R: file & directory count */
    00103 #define NJB3_VALUE_FRAME_ID     0x0014U /* 8 bytes, 2*32 bit words */
    00104 #define NJB3_JUKEBOXID_FRAME_ID 0x0015U /* 16 bytes R: unique device ID */
    00105 #define NJB3_FILETIME_FRAME_ID  0x0016U /* 32 bit word - timestamp (UNIX format) */
    00106 #define NJB3_UNKNOWN6_FRAME_ID  0x0017U /* 32 bit word - could be FAT32 attributes */
    00107 #define NJB3_FILEFLAGS_FRAME_ID 0x0018U /* 32 bit word set on files and folders - NTFS file attributes */
    00108 /*
    00109  * 0x0100 is some kind of 6-byte device parameter, value
    00110  * from NJB Zen USB 2.0: 0001 0000 03ff
    00111  */
    00112 #define NJB3_ALBUM_FRAME_ID     0x0101U /* String */
    00113 #define NJB3_ARTIST_FRAME_ID    0x0102U /* String */
    00114 #define NJB3_GENRE_FRAME_ID     0x0103U /* String */
    00115 #define NJB3_TITLE_FRAME_ID     0x0104U /* String */
    00116 #define NJB3_LENGTH_FRAME_ID    0x0105U /* String */
    00117 #define NJB3_TRACKNO_FRAME_ID   0x0106U /* 16 bit word */
    00118 #define NJB3_YEAR_FRAME_ID      0x0107U /* 16 bit word */
    00119 /*
    00120  * Smartvolume parameters for a track is sent after a track with the command:
    00121  * 0x0001 0x0001 update file with info
    00122  * 0x0000 0x0000 4 bytes trackid
    00123  * 0x01b6 (length)
    00124  * 0x010a (smartvol)
    00125  * 0x01b6 unknown bytes, appears to be an array of 109 32-bit words.
    00126  * 0x0000 terminator
    00127  */
    00128 #define NJB3_SMARTPAR_FRAME_ID  0x010aU
    00129 /*
    00130  * 16 bit word R/W: Info about current track playing on the device
    00131  * First byte appear to always be 0x0b, second means the following:
    00132  * 0x00 = play/playing
    00133  * 0x01 = stop/stopped
    00134  * 0x02 = pause/paused
    00135  * 0x03 = resume (write only)
    00136  */
    00137 #define NJB3_PLAYINFO_FRAME_ID  0x010bU
    00138 #define NJB3_SEEKTRACK_FRAME_ID 0x010cU /* 32 bit word W: seek to position (in ms) in current track */
    00139 #define NJB3_EAX_TYPENAME       0x010eU /* String with the name of an EAX type */
    00140 #define NJB3_PLNAME_FRAME_ID    0x010fU /* String: playlist name */
    00141 /*
    00142  * 8 bytes R/W, BCD-encoded time and date:
    00143  * byte: meaning:
    00144  * 00: day of the week (0 = sunday)
    00145  * 01: day of the month (1-31)
    00146  * 02: month of the year (1-12)
    00147  * 03: year century digit (20 mostly...)
    00148  * 04: year lower part
    00149  * 05: hours
    00150  * 06: minutes
    00151  * 07: seconds
    00152  * e.g.: 0619 1120 0518 4351,
    00153  * means saturday, 2005-11-19, 18:43:51
    00154  */
    00155 #define NJB3_TIME_FRAME_ID      0x0110U
    00156 #define NJB3_ALBUMCNT_FRAME_ID  0x0111U /* 32 bit word R: number of albums on device */
    00157 #define NJB3_TRACKCNT_FRAME_ID  0x0112U /* 32 bit word R: number of tracks on device */
    00158 #define NJB3_OWNER_FRAME_ID     0x0113U /* String: owner name */
    00159 /*
    00160  * 4 bytes: 0x14, one byte charging status then 16 bits of battery level
    00161  * The first byte appear to always contain 0x14.
    00162  * The second value is interpreted as follows:
    00163  * 0x00 = power connected and charging
    00164  * 0x01 = power connected, battery fully charged
    00165  * 0x02 = power disconnected
    00166  * Then follows the battery level as a 16bit value.
    00167  */
    00168 #define NJB3_BATTERY_FRAME_ID   0x0114U
    00169 #define NJB3_PLCNT_FRAME_ID     0x0115U /* 32 bit word: number of playlists on device */
    00170 /*
    00171  * 0x0116-0x0118 can be read as device registers.
    00172  * they will return one 32 bit word each, this is
    00173  * what it looks like on NJB Zen USB 2.0 in rest
    00174  * mode:
    00175  *
    00176  * 0x0116: 00000000
    00177  * 0x0117: 00000000
    00178  * 0x0118: ffffffff
    00179  *
    00180  */
    00181 #define NJB3_PLAYTRACK_FRAME_ID 0x0119U /* 32 bit word track ID to play */
    00182 /*
    00183  * Seen after clearing the playback queue in this sequence:
    00184  * 0007 0001 0004 011a 1a00 0000 reading it out gives the
    00185  * same value so probably the writing of it is useless.
    00186  */
    00187 #define NJB3_UNKNOWN4_FRAME_ID  0x011aU
    00188 #define NJB3_PLTRACKS_FRAME_ID  0x011cU /* Array of 16bit words */
    00189 /*
    00190  * 0x011d - 0x0120 return sensible, static but undeciphered values
    00191  * when read out as device registers. Sample values from NJB Zen USB 2.0:
    00192  * 0x011d: 00000407
    00193  * 0x011e: 00000070
    00194  * 0x011f: 1f00 1f01 1f02 1f03
    00195  * 0x0120: 0001 fffe 0011
    00196  */
    00197 #define NJB3_MINMAX_ID          0x0201U /* 2x16 bit values, max and min */
    00198 #define NJB3_EAX_ACTIVE_ID      0x0202U /* 16 bit word - this EAX type is active/to
    00199                                          * be activated (0x0000 = off, 0x0001 = on) */
    00200 #define NJB3_VOLUME_FRAME_ID    0x0203U /* 16 bit word */
    00201 #define NJB3_ENV_FRAME_ID       0x0204U /* 16 bit word - environment setting */
    00202 #define NJB3_EQ_FRAME_ID        0x0205U /* 16 bit word - equalizer setting */
    00203 #define NJB3_SPAT_FRAME_ID      0x0206U /* 16 bit word - spatialization 2 = full */
    00204 #define NJB3_TSCALE_FRAME_ID    0x0207U /* 16 bit word - time scaling factor */
    00205 #define NJB3_SMARTVOL_FRAME_ID  0x0208U /* 16 bit word - smart volume setting */
    00206 #define NJB3_EAXACTIVE_FRAME_ID 0x020aU /* 16 bit word - 0x0000/0x0001 = activate/deactivate EAX processor */
    00207 #define NJB3_EAXID_FRAME_ID     0x020bU /* 16 bit word with the numerical ID of a certain EAX type */
    00208 #define NJB3_EAX_INDEX_ID       0x020cU /* 16 bit word - currently selected effect in a set of effects */
    00209 #define NJB3_KEYVALUE_FRAME_ID  0x1400U /* Array of value-key-pairs, requested in a
    00210                                           subrequest parameter to this request */
    00211
    00212 /* Database IDs, used for eg create_file */
    00213 #define NJB3_FILE_DATABASE       0x0000U
    00214 #define NJB3__PLAYLIST_DATABASE  0x0001U
    00215 #define NJB3_TRACK_DATABASE      0x0002U
    00216
    00217 /* Codec IDs */
    00218 #define NJB3_CODEC_MP3_ID_OLD        0x0000U /* Used on NJB3/Zen FW? */
    00219 #define NJB3_CODEC_WAV_ID            0x0001U
    00220 #define NJB3_CODEC_MP3_ID            0x0002U
    00221 #define NJB3_CODEC_WMA_ID            0x0003U
    00222 /*
    00223  * 0x0004, 0x0005 and 0x0006 unknown, one of them is
    00224  * undoubtedly the Real Networks AAC + Helix DRM
    00225  * decoder. Only very certain firmwares will support
    00226  * these I believe...
    00227  */
    00228 #define NJB3_CODEC_AA_ID             0x0007U /* Audible.com codec */
    00229 #define NJB3_CODEC_PROTECTED_WMA_ID  0x0203U /* Is it two bytes actually? */
    00230
    00231 /* Stop, pause and resume are very much alike. */
    00232 #define NJB3_START_PLAY     0x00
    00233 #define NJB3_STOP_PLAY      0x01
    00234 #define NJB3_PAUSE_PLAY     0x02
    00235 #define NJB3_RESUME_PLAY    0x03
    00236
    00237 /* Status codes */
    00238 #define NJB3_STATUS_OK                0x0000U
    00239 #define NJB3_STATUS_EMPTY             0x0001U /* You tried to retrieve an empty item */
    00240 #define NJB3_STATUS_TRANSFER_ERROR    0x0002U /* Error during read or write */
    00241 #define NJB3_STATUS_BAD_FILESIZE      0x0003U /* Illegal file size (e.g. negative, too large) */
    00242 #define NJB3_STATUS_NOTIMPLEMENTED    0x0004U /* For example if EAX is not supported on a device */
    00243 #define NJB3_STATUS_NOTEXIST          0x0005U /* Tried to access nonexistant track */
    00244 #define NJB3_STATUS_PROTECTED         0x000cU /* Tried to access protected object */
    00245 #define NJB3_STATUS_EMPTY_CHUNK       0x000eU /* Appear when requesting empty metadata lists
    00246                                                * or beyond the end of files. */
    00247
    00248 /*
    00249  * Status codes that must exist, find by trial-and-error:
    00250  * - postid invalid (does not exist)
    00251  * - disk full
    00252  * - file path / track name etc too long
    00253  * - playing (cannot transfer when playing)
    00254  * - tried to skip to position outside file in playback mode
    00255  * - too many files/tracks etc - limit reached.
    00256  * - filename or track+artist+(all metadata) is the same as
    00257  *   one already present on the player
    00258  * - transfer in progress (a track/file is transferring in
    00259  *   either direction
    00260  */
    00261
    00262 #define njb3_start_play(njb) njb3_ctrl_playing(njb, NJB3_START_PLAY)
    00263 #define njb3_stop_play(njb) njb3_ctrl_playing(njb, NJB3_STOP_PLAY)
    00264 #define njb3_pause_play(njb) njb3_ctrl_playing(njb, NJB3_PAUSE_PLAY)
    00265 #define njb3_resume_play(njb) njb3_ctrl_playing(njb, NJB3_RESUME_PLAY)
    00266
    00267 /* Structure to hold protocol3 states */
    00268 typedef struct {
    00269   /* Get extended tags */
    00270   int get_extended_tag_info;
    00271   njb_songid_t *first_songid;
    00272   njb_songid_t *next_songid;
    00273   njb_playlist_t *first_plid;
    00274   njb_playlist_t *next_plid;
    00275   njb_datafile_t *first_dfid;
    00276   njb_datafile_t *next_dfid;
    00277   int current_playing_track;
    00278   njb_keyval_t *first_key;
    00279   njb_keyval_t *next_key;
    00280   njb_eax_t *first_eax;
    00281   njb_eax_t *next_eax;
    00283   u_int8_t eax_processor_active;
    00285   char *product_name;
    00287   u_int8_t fwMajor;
    00289   u_int8_t fwMinor;
    00291   u_int8_t fwRel;
    00293   u_int8_t hwMajor;
    00295   u_int8_t hwMinor;
    00297   u_int8_t hwRel;
    00299   u_int16_t last_elapsed;
    00301   u_int8_t turbo_mode;
    00302 } njb3_state_t;
    00303
    00304
    00305 /*
    00306  * NJB3 functions: the commands listed at the top of this
    00307  * file are wrapped in binary form more or less using the defined
    00308  * values in this file to conjure and decipher byte-sequences
    00309  * sent by the devices.
    00310  */
    00311 int njb3_init_state (njb_t *njb);
    00312 int njb3_set_bitmap(njb_t *njb, u_int16_t x_size, u_int16_t y_size, const unsigned char *bitmap);
    00313 int njb3_current_track (njb_t *njb, u_int16_t * track);
    00314 int njb3_elapsed_time (njb_t *njb, u_int16_t * elapsed, int * change);
    00315 int njb3_play_track (njb_t *njb, u_int32_t trackid);
    00316 int njb3_queue_track (njb_t *njb, u_int32_t trackid);
    00317 int njb3_clear_play_queue(njb_t *njb);
    00318 int njb3_ctrl_playing (njb_t *njb, int cmd);
    00319 int njb3_seek_track (njb_t *njb, u_int32_t position);
    00320 int njb3_get_codecs(njb_t *njb);
    00321 int njb3_ping (njb_t *njb, int type);
    00322 int njb3_power_status (njb_t *njb, int *battery_level, int *charging, int *ac_power);
    00323 int njb3_readid (njb_t *njb, u_int8_t *sdmiid);
    00324 int njb3_capture (njb_t *njb);
    00325 int njb3_release (njb_t *njb);
    00326 int njb3_get_disk_usage (njb_t *njb, u_int64_t *totalbytes, u_int64_t *freebytes);
    00327 int njb3_turnoff_flashing(njb_t *njb);
    00328 int njb3_get_owner_string (njb_t *njb, char *name);
    00329 int njb3_set_owner_string (njb_t *njb, const char *name);
    00330 njb_time_t *njb3_get_time(njb_t *njb);
    00331 int njb3_set_time(njb_t *njb, njb_time_t *time);
    00332 int njb3_reset_get_track_tag (njb_t *njb);
    00333 njb_songid_t *njb3_get_next_track_tag (njb_t *njb);
    00334 int njb3_reset_get_playlist_tag (njb_t *njb);
    00335 njb_playlist_t *njb3_get_next_playlist_tag (njb_t *njb);
    00336 int njb3_reset_get_datafile_tag (njb_t *njb);
    00337 njb_datafile_t *njb3_get_next_datafile_tag (njb_t *njb);
    00338 int njb3_read_keys(njb_t *njb);
    00339 njb_keyval_t *njb3_get_keys(njb_t *njb);
    00340 int njb3_request_file_chunk(njb_t *njb, u_int32_t fileid, u_int32_t offset);
    00341 int njb3_get_file_block(njb_t *njb, unsigned char *data, u_int32_t maxsize);
    00342 u_int32_t njb3_create_file(njb_t *njb, unsigned char *ptag, u_int32_t tagsize, u_int16_t database);
    00343 u_int32_t njb3_send_file_chunk(njb_t *njb, unsigned char *chunk, u_int32_t chunksize, u_int32_t fileid);
    00344 int njb3_send_file_complete(njb_t *njb, u_int32_t fileid);
    00345 int njb3_create_folder(njb_t *njb, const char *name, u_int32_t *folderid);
    00346 int njb3_delete_item(njb_t *njb, u_int32_t itemid);
    00347 int njb3_update_16bit_frame(njb_t *njb, u_int32_t itemid, u_int16_t frameid, u_int16_t value);
    00348 int njb3_update_string_frame(njb_t *njb, u_int32_t itemid, u_int16_t frameid, unsigned char *str);
    00349 int njb3_update_tag(njb_t *njb, u_int32_t trackid, unsigned char *ptag, u_int32_t ptagsize);
    00350 int njb3_create_playlist(njb_t *njb, char *name, u_int32_t *plid);
    00351 int njb3_add_multiple_tracks_to_playlist (njb_t *njb, u_int32_t *plid, u_int32_t *trids, u_int16_t ntracks);
    00352 int njb3_adjust_volume(njb_t *njb, u_int16_t value);
    00353 int njb3_control_eax_processor (njb_t * njb, u_int16_t state);
    00354 int njb3_adjust_eax(njb_t *njb, u_int16_t eaxid, u_int16_t patchindex, u_int16_t active, u_int16_t scalevalue);
    00355 void njb3_read_eaxtypes(njb_t *njb);
    00356 njb_eax_t *njb3_get_nexteax(njb_t *njb);
    00357 int njb3_announce_firmware(njb_t *njb, u_int32_t size);
    00358 u_int32_t njb3_send_firmware_chunk(njb_t *njb, u_int32_t chunksize, unsigned char *chunk);
    00359 int njb3_get_firmware_confirmation(njb_t *njb);
    00360 void njb3_destroy_state(njb_t *njb);
    00361
    00362 #endif