libnjb: /tmp/libnjb-2.2.5/src/protocol3.h File Reference

Go to the source code of this file.


Data Structures
struct	njb3_state_t
Defines
#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
#define	NJB3_DISKUTIL_FRAME_ID 0x0002U
#define	NJB3_PRODID_FRAME_ID 0x0003U
#define	NJB3_LOCKED_FRAME_ID 0x0006U
#define	NJB3_FNAME_FRAME_ID 0x0007U
#define	NJB3_UNKNOWN1_FRAME_ID 0x0008U
#define	NJB3_KEY_FRAME_ID 0x000aU
#define	NJB3_CODEC_FRAME_ID 0x000bU
#define	NJB3_POSTID_FRAME_ID 0x000cU
#define	NJB3_DIR_FRAME_ID 0x000dU
#define	NJB3_FILESIZE_FRAME_ID 0x000eU
#define	NJB3_FILECOUNT_FRAME_ID 0x0013U
#define	NJB3_VALUE_FRAME_ID 0x0014U
#define	NJB3_JUKEBOXID_FRAME_ID 0x0015U
#define	NJB3_FILETIME_FRAME_ID 0x0016U
#define	NJB3_UNKNOWN6_FRAME_ID 0x0017U
#define	NJB3_FILEFLAGS_FRAME_ID 0x0018U
#define	NJB3_ALBUM_FRAME_ID 0x0101U
#define	NJB3_ARTIST_FRAME_ID 0x0102U
#define	NJB3_GENRE_FRAME_ID 0x0103U
#define	NJB3_TITLE_FRAME_ID 0x0104U
#define	NJB3_LENGTH_FRAME_ID 0x0105U
#define	NJB3_TRACKNO_FRAME_ID 0x0106U
#define	NJB3_YEAR_FRAME_ID 0x0107U
#define	NJB3_SMARTPAR_FRAME_ID 0x010aU
#define	NJB3_PLAYINFO_FRAME_ID 0x010bU
#define	NJB3_SEEKTRACK_FRAME_ID 0x010cU
#define	NJB3_EAX_TYPENAME 0x010eU
#define	NJB3_PLNAME_FRAME_ID 0x010fU
#define	NJB3_TIME_FRAME_ID 0x0110U
#define	NJB3_ALBUMCNT_FRAME_ID 0x0111U
#define	NJB3_TRACKCNT_FRAME_ID 0x0112U
#define	NJB3_OWNER_FRAME_ID 0x0113U
#define	NJB3_BATTERY_FRAME_ID 0x0114U
#define	NJB3_PLCNT_FRAME_ID 0x0115U
#define	NJB3_PLAYTRACK_FRAME_ID 0x0119U
#define	NJB3_UNKNOWN4_FRAME_ID 0x011aU
#define	NJB3_PLTRACKS_FRAME_ID 0x011cU
#define	NJB3_MINMAX_ID 0x0201U
#define	NJB3_EAX_ACTIVE_ID 0x0202U
#define	NJB3_VOLUME_FRAME_ID 0x0203U
#define	NJB3_ENV_FRAME_ID 0x0204U
#define	NJB3_EQ_FRAME_ID 0x0205U
#define	NJB3_SPAT_FRAME_ID 0x0206U
#define	NJB3_TSCALE_FRAME_ID 0x0207U
#define	NJB3_SMARTVOL_FRAME_ID 0x0208U
#define	NJB3_EAXACTIVE_FRAME_ID 0x020aU
#define	NJB3_EAXID_FRAME_ID 0x020bU
#define	NJB3_EAX_INDEX_ID 0x020cU
#define	NJB3_KEYVALUE_FRAME_ID 0x1400U
#define	NJB3_FILE_DATABASE 0x0000U
#define	NJB3__PLAYLIST_DATABASE 0x0001U
#define	NJB3_TRACK_DATABASE 0x0002U
#define	NJB3_CODEC_MP3_ID_OLD 0x0000U
#define	NJB3_CODEC_WAV_ID 0x0001U
#define	NJB3_CODEC_MP3_ID 0x0002U
#define	NJB3_CODEC_WMA_ID 0x0003U
#define	NJB3_CODEC_AA_ID 0x0007U
#define	NJB3_CODEC_PROTECTED_WMA_ID 0x0203U
#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
#define	NJB3_STATUS_TRANSFER_ERROR 0x0002U
#define	NJB3_STATUS_BAD_FILESIZE 0x0003U
#define	NJB3_STATUS_NOTIMPLEMENTED 0x0004U
#define	NJB3_STATUS_NOTEXIST 0x0005U
#define	NJB3_STATUS_PROTECTED 0x000cU
#define	NJB3_STATUS_EMPTY_CHUNK 0x000eU
#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_t *	njb3_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_t *	njb3_get_next_track_tag (njb_t *njb)
int	njb3_reset_get_playlist_tag (njb_t *njb)
njb_playlist_t *	njb3_get_next_playlist_tag (njb_t *njb)
int	njb3_reset_get_datafile_tag (njb_t *njb)
njb_datafile_t *	njb3_get_next_datafile_tag (njb_t *njb)
int	njb3_read_keys (njb_t *njb)
njb_keyval_t *	njb3_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_t *	njb3_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

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.

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

Function Documentation

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:

	plid	a 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.
	trids	an array of tracks to add
	ntracks	absolute number of tracks in the array.

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:

	njb	a pointer to the njb device object to use
	size	the total size of the firmware image

Returns:: 0 on success, -1 on failure

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.

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

This function creates a new playlist on the device.

Parameters:

	name	the name of the playlist to create, as a string.
	plid	a 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.

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.

int njb3_get_codecs ( njb_t * njb )

Reads the supported audio file types.

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:

	data	an allocated byte array to store the retrieved chunk in.
	maxsize	the maximum number of bytes to retrieve from this chunk at a time.

int njb3_get_firmware_confirmation ( njb_t * njb )

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

int njb3_init_state ( njb_t * njb )

Initializes the basic state of the njb->protocol_state for the PROTOCOL3-devices.

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_level	a variable that will hold the current level after the call.
	charging	if the battery is charging, this variable will hold 1 after the call, else 0.
	ac_power	if 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.

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.

int njb3_reset_get_datafile_tag ( njb_t * njb )

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

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.

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:

	njb	a pointer to the njb device object to use
	chunksize	the size of this chunk
	chunk	a pointer to the raw bytes representing this firmware chunk

Returns:: 0 on success, -1 on failure

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.

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:

	itemid	the item ID (track, playlist or datafile) to modify.
	frameid	the frame ID of the frame to modyfy. Must be a 16-bit frame.
	valud	the new 16-bit value.

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:

	itemid	the item ID (track, playlist or datafile) to be modified.
	frameid	the frame ID of the frame to be updated.
	str	the new string value.

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:

	itemid	the track (or similar) whose metadata is to be updated.
	ptag	a packed metadata structure for series 3 devices.

Returns:: 0 on success, -1 on failure.

protocol3.h File Reference

Data Structures

Defines

Functions

Detailed Description

Function Documentation