Hydranode Core/GUI Communication Protocol
Alo Sarv
September 2004
Version 1.0
Abstract
This document defines the Hydranode Core/GUI Communication Protocol, HCGCP. HCGCP is intended as a communication medium between Hydranode Core and HCGCP compliant user interfaces.
Table Of Contents
1. Introduction2. Usage Scenario
3. Definitions
4. Header Specification
5. Protocol Description
5.1. Basics
5.2. Operation Codes and RO/WO/XO Packet Structure
5.3. Object Representations
1. Introduction
HCGCP is intended to serve as a standard communication medium between Hydranode Core and compliant User Interfaces (UI's). It is designed to be suitable for fast real-time updates, as well as for slow remote connections. The protocol is binary in order to save bandwidth during remote connections and parsing time during loopback connections.
2. Usage Scenario
The basic usage of HCGCP evolves around UI's sending commands and the Core responding to them. There are three types of operations involved in the communication:
- Read Operations (RO's) perform reading of data. These include listing the contents of various data structures.
- Write Operations (WO's) perform writing data. These include setting configuration options and adding new items to lists.
- Execute Operations (XO's) execute specific commands. Examples of XO's include pausing/cancelling files, shutting down the Core and loading/unloading plugins.
Whenever UI sends a command to the Core, the core responds with a Response Code (RC). RC's indicate whether handling the command succeeded or failed, along with the reason why it failed. Fail reasons range from logic errors ("Unable to comply: No such file or directory.") to security errors ("Permission denied.").
By default, the communication between Core and UI's is one-way: the GUI sends commands and the Core handles them. However, optionally, the UI's may enable automatic updates on different data structures, e.g. monitor those. Whenever there are changes to monitored data structures, the Core will send the snapshot of the monitored object to the UI.
Thus, the UI's send out three different commands: RO's, WO's and XO's. The Core sends out two different packets: Response Packets (RP's), which contain RC's and (optionally) Data payload, and Automated Packets (AP's), which contain snapshots of monitored data structures.
3. Definitions
Read Operation (RO)
A packet sent by UI to the Core which does modify any states/variables within the Core.
Write Operation (WO)
A packet sent by UI to the Core which modifies a state/ variable/data structure, however does not perform any specific operation.
Execute Operation (XO)
A packet sent by UI to the Core which orders the Core to perform a specific operation.
Response Packet (RP)
A packet sent by Core in response to RO, WO or XO. RP begins with ResponseCode indicating success or failure of the operation, followed by optional Data payload.
Automated Packet (AP)
A packet sent by Core automatically when specified conditions are met. Conditions may include changes to data structures, variable states or similar.
Data Payload (DP)
Packet data which follows the packet header. All packets send by the UI or by Core may include optional DP specifying the concrete commands/data being handled.
ResponseCode (RC)
8-bite value indicating the success or failure of the operation being performed.
OpCode (OC)
8-bit value specifying the operation being performed, or data structure type being transmitted.
DataType (DT)
8-bit value specifying the data type. The length of the following data is dependant on the data type.
4. Header Specification
RO, WO and XO packet format:
+--------+--------+--------+------
| OC | DP Length | DP
+--------+--------+--------+------
RP and AP format:
+--------+--------+--------+------
| RC | DP Length | DP
+--------+--------+--------+------
Note: AP is a special case of RP and does not contain specific RC data. Instead, RC is set to a static value 0xff indicating the packet type.
5. Protocol Description
Each object has it's own representation in the HCGCP. Object's representation begins with its DT, which identifies the object, followed by the object's data. The length of the object's data is specified by the specific DT.
Endianess setting is negotiated during initial handshaking of peers. By default, Little Endian notation shall be used.
5.1. Basics
String
<uint16>length<length>data
Note: No terminating \0.
Tag
<uint8>TC<uint16>length<tagdata>
StringTag
0x0f<String>tagname<uint16>length<tagdata>
Whenever an object may contain Tag's, it may also contain StringTags - they are equal. StringTag is merely a special Tag, or a 'named' Tag. The rationale behind adding StringTags to the protocol is to save the opcodes and provide means of extending the protocol as much as needed.
5.2. Operation Codes and RO/WO/XO Packet Structure
OC Desc Data Payload Format ---------------------------------------------------------------- 0x01 HELLO <BIG_ENDIAN|LITTLE_ENDIAN> 0x02 HELLO_ANSWER <BIG_ENDIAN|LITTLE_ENDIAN> 0x03 AUTH <String>username<Hash>password 0x04 BIG_ENDIAN 0x05 LITTLE_ENDIAN 0x06 VERSION Hash Data at AUTH operation is SHA-1 checksum of the password. 0x10 FILES LIST 0x11 FILES MONITOR <uint16>FileId 0x12 FILES RELOAD 0x13 FILES ADD <uint8>tagcount[<Tag>*tagcount] 0x14 FILES DEL <uint16>FileId 0x15 FILES PAUSE <uint16>FileId 0x16 FILES STOP <uint16>FileId 0x17 FILES RESUME <uint16>FileId
Tag list at operation ADD specifies network-dependant data of the file being handled, and is passed to the plugin handling the request. FileId at operations DEL, PAUSE, STOP and RESUME specifies which list objects the operation shall be applied to. FileId is retrieved from FILES LIST command response. FileId 0x00 indicates the operation shall be applied to all files.
0x20 SEARCH <String>keyword<uint8>tagcount[<Tag>*tagcount] 0x21 SEARCH LIST 0x22 SEARCH RESULTS <uint8>SearchId 0x22 SEARCH MONITOR <uint8>SearchId 0x23 SEARCH CANCEL <uint8>SearchId
SEARCH operation schedules a global search with parameters described in the taglist, and responds with 8-bit SearchId. SearchId can later be used to MONITOR or CANCEL the search in progress. SEARCH LIST retrieves list of pending SEARCH jobs along with their respective SearchId?'s. SearchId 0x00 passed to SEARCH MONITOR operation indicates the entire list shall be monitored for updates.
0x24 SEARCH NET 0x25 SEARCH MINSIZE 0x26 SEARCH MAXSIZE 0x27 SEARCH FILETYPE 0x28 SEARCH METADATA
NET, MINSIZE, MAXSIZE, FILETYPE and METADATA are used within SEARCH command taglist to specify the search operation more precicely.
0x30 PLUGINS LIST 0x31 PLUGINS LOAD <String>path 0x32 PLUGINS UNLOAD <uint8>PluginId 0x33 PLUGINS MONITOR <uint8>PluginId
PluginId may be retrieved from PLUGINS LIST operation response. PluginId 0x00 passed to PLUGINS MONITOR operation indicates the entire list shall be monitored for changes.
0x40 STATISTICS LIST 0x41 STATISTICS MONITOR <uint32>FieldId 0x42 STATISTICS RESET
FieldId may be retrieved from STATISTICS LIST operation response. FieldId 0x00 passed to STATISTICS MONITOR indicates the entire list shall be monitored for updates.
0x50 CONFIG LIST 0x51 CONFIG SET <String>key<String>value 0x52 CONFIG GET <String>key 0x53 CONFIG SAVE 0x54 CONFIG MONITOR <String>key
Empty string passed to CONFIG MONITOR indicates the entire list shall be monitored for updates.
0x60 LOG LIST 0x61 LOG MONITOR 0x62 LOG SAVE <String>filename 0x63 LOG SETFILE <String>filename
LOG SAVE prints the current Log buffer into specified file. LOG SETFILE indicates all new entries shall be appended to specified file
0x70 HASHER LIST 0x71 HASHER MONITOR <uint8>HashJobId 0x72 HASHER PAUSE 0x73 HASHER RESUME
HashJobId may be retrieved from HASHER LIST operation response. HashJobId 0x00 passed to HASHER MONITOR indicates the entire list shall be monitored for updates. HASHER PAUSE and HASHER RESUME pause and resume, respectivly, the current job in progress.
0x80 METADB LIST 0x81 METADB SAVE 0x82 METADB LOAD <String>filename 0x83 METADB ADD <MetaData>data 0x84 METADB DEL <MetaData>data
5.3. Object Representations
Object's occouring in the protocol stream are identified using their opcodes. Following that is the object's actual data, which is object-specific.
0x10 RANGE <uint64>begin<uint64>end 0x11 DATARANGE <Range><uint64>dataLength<dataLength>data 0x12 RANGELIST 0x12<uint16>count[<count>Range] 0x13 FULLRL <uint64>begin<uint64>end<uint16>count[<count>Range]
FULLRL means FullRangeList, and differs from RangeList by also specifying the lower and upper bounds of the allowed contained ranges.
0x20 AUDIOMETADATA <uint16>tagcount[<Tag>*tagcount] 0x21 AUDIOMETADATA TITLE <string>title 0x22 AUDIOMETADATA ARTIST <string>artist 0x23 AUDIOMETADATA ALBUM <string>album 0x24 AUDIOMETADATA GENRE <string>genre 0x25 AUDIOMETADATA COMMENT <string>comment 0x26 AUDIOMETADATA COMPOSER <string>composer 0x27 AUDIOMETADATA ORIGARTIST <string>origartist 0x28 AUDIOMETADATA COPYRIGHT <string>copyright 0x29 AUDIOMETADATA URL <string>url 0x2a AUDIOMETADATA ENCODED <string>encoded 0x2b AUDIOMETADATA YEAR <uint16>year
Opcodes 0x2c .. 0x2f are reserved for future.
0x40 VIDEOMETADATA <uint16>tagcount[<Tag>*tagcount] 0x41 VIDEOMETADATA RUNTIME <uint32>runtime 0x42 VIDEOMETADATA FRAMES <uint32>frames 0x43 VIDEOMETADATA FRAMERATE <float>framerate 0x44 VIDEOMETADATA FRAMEWIDTH <uint32>width 0x45 VIDEOMETADATA FRAMEHEIGHT <uint32>height 0x46 VIDEOMETADATA SUBTITLES <uint16>subtitles 0x47 VIDEOMETADATA VIDEOSTREAM <Stream>vidstream 0x48 VIDEOMETADATA AUDIOSTREAM <Stream>audstream STREAM <uint32>bitrate<string>codec
Opcodes 0x49 .. 0x5f are reserved for future.
0x60 ARCHIVEMETADATA <uint16>tagcount[<Tag>*tagcount] 0x61 ARCHIVEMETADATA FORMAT <uint32>format 0x62 ARCHIVEMETADATA FILECOUNT <uint32>count 0x63 ARCHIVEMETADATA UNCOMPRSIZE <uint64>uncompr 0x64 ARCHIVEMETADATA RATIO <float>ratio 0x65 ARCHIVEMETADATA COMMENT <string>comment 0x66 ARCHIVEMETADATA PASSWORD <bool>password
Opcodes 0x67 .. 0x7f are reserved for future.
0x80 IMAGEMETADATA <uint16>tagcount[<Tag>*tagcount] 0x81 IMAGEMETADATA FORMAT <uint32>format 0x82 IMAGEMETADATA WIDTH <uint32>width 0x83 IMAGEMETADATA HEIGHT <uint32>height 0x84 IMAGEMETADATA DATE <uint32>date 0x85 IMAGEMETADATA COMMENT <string>comment
Opcodes 0x86 ... 0x8f are reserved for future.
0x90 METADATA <uint16>tagcount[<tagcount>*Tag] 0x91 METADATA FILENAME <string>name 0x92 METADATA FILESIZE <uint64>size 0x93 METADATA MODDATE <uint32>date 0x94 METADATA FILETYPE <uint32>type 0x95 METADATA TYPEGUESSED <bool>typeguessed
In addition to those tags, METADATA object may also contain the following objects in the tag list: AUDIOMETADATA, VIDEOMETADATA, ARCHIVEMETADATA, IMAGEMETADATA, HASHSET.
Opcodes 0x96 .. 0x9f are reserved for future.
0xa0 HASH <uint8>hashtype<length>hashdata 0xa1 HASH ADLER <4>hashdata 0xa2 HASH CRC32 <4>hashdata 0xa3 HASH ED2K <16>hashdata 0xa4 HASH MD4 <16>hashdata 0xa5 HASH MD5 <16>hashdata 0xa6 HASH PANAMA <32>hashdata 0xa7 HASH RIPEMD160 <20>hashdata 0xa8 HASH SHA1 <20>hashdata 0xa9 HASH SHA256 <32>hashdata 0xaa HASH SHA384 <48>hashdata 0xab HASH SHA512 <64>hashdata 0xac HASH TIGER <24>hashdata 0xad HASH UUHASH ???
Opcodes 0xae ... 0xbf are reserved for future.
0xc0 HASHSET <uint16>tagcount[<tagcount>*Tag] 0xc1 HASHSET FILEHASH <Hash>filehash 0xc2 HASHSET PARTHASH <Hash>parthash 0xc3 HASHSET PARTSIZE <uint32>partsize
Opcodes 0xc5 ... 0xcf are reserved for future.
