Generic Binary Keyed Format (*.gbkf)

This format is a generic solution for reading and writing data in a binary mode. It is designed to reduce the data size between server and clients, and also to be simple to use and flexible for layering additional specifications.

Work in progress, the first version is not yet released.

Core Structure

Main Header 16 Bytes
...Keyed-Values...
SHA 256 32 Bytes

The data must start with a header, be followed by zero or more Keyed-Values, and end with a SHA256 sum.

Main Header

gbkf 4 Bytes
gbkf Version 1 Byte = uint8
Specification ID 4 Bytes = uint32
Specification Version 2 Bytes = uint16
Keys Length 1 Byte = uint8
Number of Keyed-Values 4 Bytes = uint32
  1. gbkf:
    • Type: ASCII character sequence
    • Encoding: 1 byte per character using 7-bit ASCII (ISO 646)
    • Length: 4 bytes, 1 byte per letter.
  2. gbkf Version:
    • Type: Unsigned Integer
    • Encoding: Big-endian
    • Length: 1 byte
    • Values:
      • Min: 0
      • Max: 255
      • Default: 0, and once the first gbkf format be finished, will be set to 1.
      • 0: means Undefined
  3. Specification ID:
    • Type: Unsigned Integer
    • Encoding: Big-endian
    • Length: 4 bytes
    • Values:
      • Min: 0
      • Max: 4,294,967,295
      • Default: 0
      • 0: means Undefined
  4. Specification Version:
    • Type: Unsigned Integer
    • Encoding: Big-endian
    • Length: 2 bytes
    • Values:
      • Min: 0
      • Max: 65,535
      • Default: 0
      • 0: means Undefined
  5. Keys Length:
    • Type: Unsigned Integer
    • Encoding: Big-endian
    • Length: 1 byte
    • Values:
      • Min: 1
      • Max: 255
      • Default: 1
  6. Number of Keyed-Values:
    • Type: Unsigned Integer
    • Encoding: Big-endian
    • Length: 4 bytes
    • Values:
      • Min: 0
      • Max: 4,294,967,295
      • Default: 0

Keyed-Values

Header
...Type Data...

Each Keyed-Value starts with a common header, followed by type-specific data, and then, depending on each type, additional fields may be added before adding the list of values.

Header

Key 1 to 255 Bytes
Instance ID 4 Bytes = uint32
Number of Values 4 Bytes = uint32
Values Type 1 Byte = uint8
...Type Data...
  1. Key:
    • Type: ASCII character sequence
    • Encoding: 1 byte per character using 7-bit ASCII (ISO 646)
    • Length: <Keys Length> This value is defined in the Main Header.
  2. Instance ID:
    • Type: Unsigned Integer
    • Encoding: Big-endian
    • Length: 4 Bytes
    • Values:
      • Min: 0
      • Max: 4,294,967,295
      • Default: 0
  3. Number of Values:
    • Type: Unsigned Integer
    • Encoding: Big-endian
    • Length: 4 Bytes
    • Values:
      • Min: 0
      • Max: 4,294,967,295
      • Default: 0
  4. Values Type:

Type Undefined

In progress...

Type Integer

Keyed-Value Header
Integers Length 1 Byte = uint8
...Values... 1 to 8 Bytes
  1. Integers Length:
    • Type: Unsigned Integer
    • Encoding: Big-endian
    • Length: 1 byte
    • Values:
      • 1: for uint8
      • 2: for uint16
      • 4: for uint32
      • 8: for uint64
      • Default: 1
  2. Values:
    • Type: Unsigned Integer
    • Encoding: Big-endian
    • Length: <Integers Length>
    • Values:
      • Min: 0
      • Max: 18,446,744,073,709,551,615

Type Single

Keyed-Value Header
...Values... 4 Bytes

The single values are read and written using IEEE 754 single-precision, and only finite normalized values are supported.

  1. Values:
    • Type: Single
    • Encoding: Big-endian
    • Length: 4 Bytes
    • Values:
      • Min: -3.4028235e+38
      • Max: 3.4028235e+38

Type Double

Keyed-Value Header
...Values... 8 Bytes

The double values are read and written using IEEE 754 double-precision, and only finite normalized values are supported.

  1. Values:
    • Type: double
    • Encoding: Big-endian
    • Length: 8 Bytes
    • Values:
      • Min: -1.7976931348623157e+308
      • Max: 1.7976931348623157e+308

SHA 256

In order to verify the file integrity, it must end with an SHA-256 (32 bytes) that hashes the header and the keyed-values.