-
Notifications
You must be signed in to change notification settings - Fork 46
FastRPC binary protocol specification
FastRPC 3.0 introduces two changes to the protocol - integer unification and timestamp field enlargement in DateTime type.
The integer value is unified again under the originally used type 00001b, but uses zig-zag encoding for the value to avoid long octet streams for negative values.
ZigZag encoding uses LSB for sign storage, the value of the signed integer is shifted left by one bit, and negated in case of negative integers.
| Value | Encoded Value |
|---|---|
| 0 | 0 |
| 1 | 2 |
| -1 | 1 |
| 2 | 4 |
| -2 | 3 |
| 3 | 6 |
| -3 | 5 |
| ... | ... |
| 00001 | NLEN | data (zigzag encoded signed integer, NLEN + 1 octets) |
|---|
DateTime field now contains full 64bit timestamp in place of the original 32bit timestamp. The overall length of the data part is not 14 octets, plus one octet containing the type info.
| 00101 | 000 | zone (8b) | unix timestamp (64b) | week day (3b) | sec (6b) | min (6b) | hour (5b) | day (5b) | month (4b) | year (11b) |
|---|
FastRPC 2.0 uses two new integer types (Integer8 positive and Integer8 negative) instead old integer.
The main change, compared to protocol 1.0, is the use of Add field to encode integer size - Integer values (integer data type and size of multioctet types) are encoded in 1 - 8 octets and the additional type info (000 - 111 [0-7]) says the number of octets used (1 - 8), as depicted here:
| Type: 5 bits | NLEN (3 bits) | LEN (NLEN+1 octets) |
|---|
LEN is stored as an integer with all the zero bytes starting from MSB being cut off.
Example: number 256 is stored as 0x39 0x00 0x01 in stream.
| 00111 | NLEN (3 bits) | data (NLEN+1 octets) |
|---|
Absolute integer value stored in little endian convention. Additional type info says how much octets follows (1 - 8).
| 01000 | NLEN (3 bits) | data (NLEN+1 octets) |
|---|
Absolute integer value stored in little endian convention. Additional type info says how much octets follows (1 - 8).
| 00100 | NLEN (3 bits) | data-size (NLEN+1 octets) | data (data-size octets) |
|---|
UTF-8 encoded not null terminated strings without any escaping. Additonal info specifies length of data-size field.
| 00110 | NLEN (3 bits) | data-size (NLEN+1 octets) | data (data-size octets) |
|---|
Binary data are sent as they are. Exact number of octets is stored data-size field. No encoding is used. This type maps to Base64 data type of XML-RPC.
| 01100 | 000 |
|---|
Null data type, carrying no value.
| 01010 | NLEN (3 bits) | num-members (NLEN+1 octets) |
|---|
Followed by num-members times:
| name-size (1 octet) | name (1-255 octets) | VALUE |
|---|---|---|
| Member name is encoded in the UTF-8 encoding. |
| 01011 | NLEN (3 bits) | num-items (NLEN+1 octets) |
|---|
Followed by num-items times VALUE
FastRPC uses 8 data types: 6 scalar (integer, boolean, double, string, date and binary) and 2 structured (struct and array). It also has 3 non-data types (method call, method response and fault response). These types precisely mirrors XML-RPC'2 data types.
Every (non-)data type begins with just one octet. This octet identifies the type and also can hold some additional type info and it can even hold the value itself. Integer values (integer data type and size of multioctet types) are encoded in 1, 2 3 or 4 octets and the additional type info says the number of octets used.
| Type: 5b | Add: 3b |
|---|
| 00001 | XXX | data (1-4 means 1-4 octets) |
|---|
Signed integer value stored in little endian convention. Additional type info says how much octets follows (1, 2, 3 or 4).
| 00010 | 00V |
|---|
Value is stored in the least significant bit of type definition octet (bit marked as V).
| 00011 | 000 | data (8 octets) |
|---|
Floating-point number in double precision as specified by the IEEE 754 standard. The additional type info should by always zero.
| 00100 | XXX | data-size (1-4 means 1-4 octets) | data (data-size octets) |
|---|
UTF-8 encoded not null terminated strings without any escaping. Additonal info specifies length of data-size field.
| 00101 | 000 | zone (8b) | unix timestamp (32b) | week day (3b) | sec (6b) | min (6b) | hour (5b) | day (5b) | month (4b) | year (11b) |
|---|
year is offset (0-2047) from AD 1600 month is 1-12 hour is 0-23 min is 0-59 sec is 0-59 (leap seconds not implemented) week dat is 0 (sunday) - 6 (saturday) unix timestamp is number of seconds from the Epox (1970-Jan-01 00:00:00 UTC) zone is specified as relative number of localtime hour quarters ((-128..+12) * 15 min) added to UTC
Unix timestamp is stored in little endian order like integer. Other values are in the network order. Whole object always holds local time of specified timezone except the unix timestamp which is always in UTC. Unix timestamp is set to -1 (invalid) for dates outside Epoch.
| 00110 | XXX | data-size (1-4 means 1-4 octets) | data (data-size octets) |
|---|
Binary data are sent as they are. Exact number of octets is stored data-size field. No encoding is used. This type maps to Base64 data type of XML-RPC.
| 01010 | XXX | num-members (1-4 means 1-4 octets) |
|---|
Followed by num-members times:
| name-size (1 octet) | name (1-255 octets) | VALUE |
|---|
Member name is encoded in the UTF-8 encoding.
| 01011 | XXX | num-items (1-4 means 1-4 octets) |
|---|
Followed by num-items times VALUE
Every non-data type represents complex data structure returned by the server or sent by the client. Data always start with magic ("CALL" in hex) and protocol version (major/minor octet pair)
| 0xCA | 0x11 | version major | version minor |
|---|
| 01101 | 000 | name-size (1 octet) | name (1-255 octets) | PARAMETERS |
|---|
Method parameters are encoded as a series of values although XML-RPC has a distinct data type for them. Method name should be in the UTF-8 encoding. Additional type info should be zero.
| 01110 | 000 | VALUE |
|---|
Method is allowed to return just one value. Additional type info should be zero.
| 01111 | 000 | INT (fault number) | STRING (fault message) |
|---|
Additional type info should be zero.