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 %<upcode> where <upcode> is the character with a
numeric value equal with 64 + original ASCII code. The % character itself MUST
be converted to a special %% representation. Characters with codes higher than 32
(except %) SHOULD not be escaped but may be so. A %-escaped code may be received
instead of an unescaped character anywhere except in the initial keyword or the
delimiting colon (:) characters. Anywhere in the line except the initial keyword
a % character not followed by a character with a numeric value higher than 64
(40H, 0x40, '@') or another % is an error.
Special Keyword: Error in
Error in:<original>
Direction: Engine to application
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)
The external module SHOULD NOT send anything back to Yate in response to such a
notification as it can result in an infinite loop.
Keyword: %%>message
%%>message:<id>:<time>:<name>:<retvalue>[:<key>=<value>...]
Direction: Engine to application
This line is sent by the engine to the application) to ask it to process a message.
The Yate thread that dispatches the message will block until an answer is
received (see below).
<id> - obscure unique message ID string generated by Yate
<time> - time (in seconds) the message was initially created
<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>...]
Direction: Application to engine
One such answer is required for every received message (%%>message). When
the engine gets a line in this format it modifies the provided values back into
the message and let it continue or stop dispatching.
<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; to delete
the key-value pair provide just a key name with no equal sign or value
Keyword: %%>message
%%>message:<id>:<time>:<name>:<retvalue>[:<key>=<value>...]
Direction: Application to engine
This line is sent by the application to the engine to ask it to process a message.
The answer to such a message is delivered asynchronously (see below).
<id> - obscure unique message ID string generated by the application
<time> - time (in seconds) the message was initially created
<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>...]
Direction: Engine to application
One such answer is required for every message (%%>message) the application
sent to the engine. It contains the message's return values and parameters.
<id> - same message ID string received trough %%>message
<processed> - boolean ("true" or "false") indication
if the message has been declared processed by one of the handlers
<name> - name of the message, possibly changed
<retvalue> - textual return value of the message
<key>=<value> - key-value pairs of parameters to the message.
Keyword: %%>install
%%>install:[<priority>]:<name>
Direction: Application to engine
Always from the application to the engine, requests the installing of a message
handler for the application that requested it
The answer to the install request is delivered asynchronously (see below).
<priority> - priority in chain, use default (100) if missing
<name> - name of the messages for that a handler should be installed
Keyword: %%<install
%%<install:<priority>:<name>:<success>
Direction: Engine to application
Confirmation from engine to the application that the handler has been installed
properly or not.
<priority> - priority of the installed handler
<name> - name of the messages asked to handle
<success> - boolean ("true" or "false") success of operation
Keyword: %%>uninstall
%%>install:<name>
Direction: Application to engine
Always from the application to the engine, requests uninstalling a previously
installed message handler
The answer to the uninstall request is delivered asynchronously (see below).
<name> - name of the message handler thst should be uninstalled
Keyword: %%<uninstall
%%<install:<priority>:<name>:<success>
Direction: Engine to application
Confirmation from engine to the application that the handler has been uninstalled
properly or not.
<priority> - priority of the previously installed handler
<name> - name of the message handler asked to uninstall
<success> - boolean ("true" or "false") success of operation
In the example below the lines sent from application to engine are prefixed with
A: while lines sent from engine to application are prefixed with E:
Comments are indented
Application installs a handler for a "test" handler with priority 50 A: %%>install:50:test Engine installs the handler and acknowledges it E: %%<install:50:test:true Application installs a handler for the "engine.timer" handler with default priority A: %%>install::engine.timer Engine installs the handler and acknowledges it E: %%<install:100:engine.timer:true Application emits a private "app.job" message; notice how the '%' and ':' characters were escaped A: %%>message:myapp55251:1095112794:app.job::job=cleanup:done=75%%:path=/bin%Z/usr/bin Engine just dispatched an "engine.timer" message E: %%>message:234479208:1095112795:engine.timer::time=1095112795 Engine gets back the answer to the "app.job" message with a "Restart required" returned text value E: %%<message:myapp55251:true:app.job:Restart required:path=/bin%Z/usr/bin%Z/usr/local/bin Application ignores the timer message A: %%<message:234479208:false:engine.timer::time=1095112795 Application uninstalls the "test" handler A: %%>uninstall:test Engine removes the handler and acknowledges it E: %%<uninstall:50:test:true Engine just dispatched another "engine.timer" message E: %%>message:234479288:1095112796:engine.timer::time=1095112796 Application modifies the timer message but lets it flow further A: %%<message:234479288:false:engine.timer::time=1095112796:extra=yes Engine just dispatched another "engine.timer" message E: %%>message:234479244:1095112797:engine.timer::time=1095112797 Application suddenly exits without acknowledging previous message. The engine releases the message 234479244 (as if "false" was returned) and uninstalls the remaining "engine.timer" handler