The Broker Protocol
The Broker communicates using text lines sent over a TCP-connections. The
broker interferes as little as possible in the format of what is sent between
modules - that is up to the designers of the modules to specify.
This document describes version 1.0 (the first public release) of the
The terms client and server can get confusing because, in
a sense, there is only one server (the Broker) and all other processes
are clients of the Broker. However, in this documentation, another distinction
will be made.
A module (client of the broker) will be referred to as a server
if there can only be one (named) instance of the module connected at any
one time, and client if there can be several clients active at once.
For example, there can currently only be one speech recognition server
connected to the broker at any time, and it is called 'Recognizer'. However,
there can be several demonstration programs using the recognizer at once,
and they are assigned unique names when they connect to the broker, such
as RecognizerClient@kanin.speech.kth.se:3213 (The host and TCP port
number are appended to the client's base name, yielding a unique name).
This is version 1.0 of the Broker protocol. A goal has been to keep it
as small as possible. The intent is that both brokers and modules can be
implemented by third parties on any platform and interoperate by following
As the first thing after connecting to the broker, a server must
send a line of the form:
where <name> is the name of the server. Values such as <name> must
be enclosed in quotes (") if they contain spaces, and quote characters
must be preceded by a backslash (\) if they are part of the name.
Keywords such as SERVER are not case sensitive.
A client must start a session by sending a line like:
Where <name> is the base name of the client. The client must then wait
for a message from the server like:
Where <uniqueName> is the name the client must use in future calls to
Thus, after this point any module, whether client or server, has a name
to use in future calls.
During a session, a module may call functions of other modules, and receive
calls from other modules.
There are two types of calls: procedure calls (CALL PROC) which do
not return any result or error codes to the caller, and function calls
(CALL FUNC) which will return with either a result or an error to the caller.
Parameters can be specified in two ways: either in one line or on several
lines. This is specified with the INLINE or MULTILINE keywords.
There are thus four varieties of function calls:
CALL PROC <calledName> INLINE parameters
CALL PROC <calledName> MULTILINE
CALL FUNC <callerName> <callerCallId> <calledName> INLINE parameters
CALL FUNC <callerName> <callerCallId> <calledName> MULTILINE
<calledName> is the name of the module to be called.
parameters can be any data terminated by a newline. In the MULTILINE
case it may be any number of lines not equal to "END_MULTILINE". It is
recommended but not required that they only contain characters from the
ISO 8859-1 character set.
<callerName> is the name of the module making the call.
<callerCallId> is specified by the caller so that it can identify
which function call a return value or result belongs to (a module may make
many concurrent function calls.)
After receiving a function call (CALL FUNC), a module must
respond by sending either a result or an error (failure to do so may cause
a client program to wait forever for the reply). A module will also receive
these messages from the Broker in response to calls it has made.
RETURN <callerName> <callerCallId> INLINE parameters
RETURN <callerName> <callerCallId> MULTILINE
ERROR <callerName> <callerCallId> message
message is an error message.
Closing a session
When a module's connection to the broker is to be closed, either by initiative
from the Broker (because it is shutting down), or by the module itself,
a CLOSE message must be sent:
After sending the CLOSE, the sending party may close the socket connection.
A robust module implementation should support a socket being closed
without a preceding CLOSE message, perhaps due to a crashed module at the
other end, or a network failure.
Lacking Features and Possible Future Extensions
It may be desirable to have a PING message to which the other component
must immediatly reply to make sure the component at the other end is functioning
properly, and to estimate round-trip time of a network connection.
There is no security functionality at all - if authentication, digital
signatures etc are neccessary, then that must be implemented on a server
level, to achieve the goal of keeping the Broker itself as simple as possible.
Other suggestions are welcome!
Prev: Chosen Architecture, Up: The
Broker, Next: Implementing Modules
© Copyright 1997 Erland
Lewin and the members of the Center
for Speech Technology