Binary output format (integration)

c10t uses a binary output format when used with the switch -x (or --binary).

This can be used for third party integration.

All bytes are packed in hexadecimal encoded strings, meaning the byte sequence 0x40, 0x01, 0x40, 0x01 will be sent as: "40014001" (each command flushes the output to make eliminate most buffering).

The format is simple and looks like the following:

<command-byte> <package-byte>

Where <command-byte> is one of the following:

• RENDER_BYTE - 0x10
• COMP_BYTE - 0x20 (not used in 1.1)
• IMAGE_BYTE - 0x30
• PARSER_BYTE - 0x40
• ERROR_BYTE - 0x01

RENDER_BYTE, COMP_BYTE and IMAGE_BYTE all means that the command is in progress of either Rendering, Compositioning or Saving the image to file. Each of these is followed by one byte in the span 0x00 - 0xff meaning the percentage for which it is ready.

// converts percentage from 0x00-0xff to 0-100
int perc = (b * 100) / 0xff;

PARSER_BYTE will indicate when a thousand chunks has been parsed in the broad phase by sending 0x01, this should be incremented in the gui until another state is reached.

ERROR_BYTE signifies that something goes wrong, if this is encountered, the rest of the output is a string containing the error message (read until EOF/EOL).

This eliminates most byte order problems which can arise on different platforms.

A reference implementation for this can be found at: http://github.com/udoprog/c10t-swt/blob/master/src/main/java/eu/toolchain/c10t/C10tDetachedProcess.java

When binary output is enabled, nothing but the above information will be printed from the command.

As a final check to see that the command is successful, check that the status code is 0.

A good way to get a feel of how the program operates is simply to run it with the switch '-x' or '--binary' and output it into a file, the hex-encoded binary package will be clearly visible (this is yet another reason for choosing encoded instead of raw bytes).