The work on this document is still in progress. Please do not use it as reference, the specifications are likely to change.

External module command flow

File handles used

The external user application or script comunicates with the module trough several file descriptors:
0 (stdin) - Carries commands and notifications from engine to application
1 (stdout) - Carries commands and answers from application to the engine
2 (stderr) - Has the usual meaning of reporting errors and is directed to the engine's stderr or logfile
3 (optional) - Transports audio data from the engine to the application
4 (optional) - Transports audio data from the application to the engine
File descriptors 3 and 4 are open only for audio capable applications.

Format of commands and notifications

In the following description the _ (underscore) character is used to denote the TAB character (\t, ^I, decimal 9) used as element separator.
Words enclosed in <angle brackets> must be replaced with the proper value.
Elements in [square brackets] are optional. An ellipsis ... denotes optional repetition of the last element.
Every command is sent on its own newline (\n, ^J, decimal 10) delimited line.
Any value that contains special characters (ASCII code lower than 32) MUST have them converted to %<hexcode> where <hexcode> is the 2 character hexadecimal representation of that ASCII code. The % character itself MUST be converted to its %25 representation. Characters with codes higher than 32 (except %) SHOULD not be escaped but may be so. An %-escaped code may be received instead of an unescaped character anywhere except in the initial keyword or the delimiting TAB characters. Anywhere in the line except the initial keyword a % character not followed by 2 hexadecimal digits is an error.

Keyword: %%=error
%%=error_<original>
The engine sends this notification as answer to a syntactically incorrect line it received from the application.
<original> - the original line exactly as received (not escaped or something)

Keyword: %%=init
%%=init
This command is sent to the other party requesting it to (re)initialize.

Keyword: %%=halt
%%=halt[_<exitcode>]
Command from application to the engine asking it to terminate. An optional exit code may be provided.
<exitcode> - positive numeric engine exit code

Keyword: %%=output
%%=output_<message>
Asks the engine to display a message in its console output.
<message> - message line to display as-is

Keyword: %%=debug
%%=debug_[<facility>]_<level>_<message>
Asks the engine to emit a debugging message to the console output.
<facility> - optional facility text to display
<level> - numeric debug level (0-9) at which to output
<message> - debug message to display

Keyword: %%>message
%%>message_<id>_<name>_<retvalue>[_<key>=<value>...]
This is sent by a party (engine or application) to ask the other to run a message trough its handlers. The local message must be held until an answer is received.
<id> - obscure unique message ID string generated by the sender
<name> - name of the message
<retvalue> - default textual return value of the message
<key>=<value> - enumeration of the key-value pairs of the message

Keyword: %%<message
%%<message_<id>_<processed>_[<name>]_<retvalue>[_<key>=<value>...]
One of this answer is required for every received message (%%>message). When a party gets a line in this format it should paste the provided values back into the message and let it continue.
<id> - same message ID string received trough %%>message
<processed> - boolean ("true" or "false") indication if the message has been processed or it should be passed to the next handler
<name> - new name of the message, if empty keep unchanged
<retvalue> - new textual return value of the message
<key>=<value> - new key-value pairs to set in the message; delete the key if the value is an empty string

Keyword: %%>install
%%>install_<name>[_<priority>]
Always from the application to the engine, requests the installing of a message handler
<name> - name of the messages for that a handler should be installed
<priority> - priority, use default if missing

Keyword: %%<install
%%<install_<name>_<priority>
Confirmation from engine to the application that the handler has been installed properly or not.
<name> - name of the messages asked to handle
<priority> - priority of the installed handler, -1 if it failed