A description of the Woomera protocol Craig Southeren Last updated 14 February 2005

Contents

Introduction

This document provides a description of the Woomera protocol for developers and users. 

Note that this document is a work-in-progress and is not yet complete.

Overview

The Woomera project provides a method for initiating or receiving VoIP calls using the OpenH323  protocol stack via a text-based protocol. This protocol may be carried over a TCP socket or a named pipe, and removes the requirement to use C++ in order to make or receive OPAL calls. 

Woomera consists of a process or daemon that encapsulates a running OpenH323 endpoint and provides an externally accessible socket or named pipe interface for commands called the “control channel”. The control channel implements the Woomera protocol used by other client applications.

The Woomera protocol is a synchronous client/server protocol in the same vein as other Internet protocols such as HTTP or SMTP. The client initiates a TCP connection to the server and uses this channel to send requests to which the server responds. A single connection may be used to control multiple calls, or a client may create multiple connections that each exists for the duration of a single call. Woomera does not support overlapped requests, i.e. the client must receive a response from the server for a request before another request can be sent.

Due to the interactive nature of the H.323 protocol, it is sometimes necessary for the server send a message to the client without a preceding request. This type of message is called an “event” and is required for two reasons: it avoids protocol deadlocks between the server and client; and it removes the need for Woomera endpoints to implement full asynchronous “transaction” handling. If the semantics of an event require an acknowledgement from the receiver, this is performed by sending an appropriate request any time after the event has been received. Note that a Woomera server is not allowed to send requests that require a synchronous response. This is intended to simplify the implementation of a Woomera client.

Connecting to a server

There are four ways a Woomera client and server can be connected:

1. The Woomera server runs as a stand-alone server and the clients connect to it using a TCP socket. In this mode, the server can handle multiple simultaneous connections. This approach is very flexible (it is possible to telnet directly into the server and enter commands manually), but it has the disadvantage of allowing access the Woomera server to any client that has access to the socket. In the real world this can be security problem.
   

2. The Woomera server is invoked with a parameter that causes it to load a C++ or C "plugin" module at runtime from a Windows DLL or Unix .so file. The plugin is connected to the Woomera server via an internal connection (pipe) which avoids the security problems of (1). However, this requires the abilty to invoke the Woomera process with the correct command line parameters. 
   

3. The Woomera server is invoked with a parameter that causes it run an arbitrary shell command, which is then executed with a Woomera connection as stdin/stdout. This is allows any program written in a language such as Perl or Python to be used with Woomera without the security problems of making a TCP socket available
   

4. The Woomera engine is implemented as a C++ library that can be linked directly into a client program.

Multiple calls and overlapped requests

A single Woomera connection can be used to control multiple simultaneous incoming or outgoing calls. Each call is associated with an integer call-id that is assigned by the Woomera server when a call is created. Every command, response and event contains the call-id for the associated call.

Although each Woomera control channel can be used to control multiple calls, the control channel itself will only process one command at a time. This means that there is no need to introduce complicated "transaction" handing into the application - when the application sends a command to Woomera, it can wait until it gets a response to that command.

If the application needs to handle multiple calls in parallel, it can simply open multiple channels to the Woomera server and handle each call separately. While there is no explicit support for "overlapped" requests (where the application can send multiple requests and receive responses to each request, possibly in a different order), the fact that Woomera uses TCP means that multiple requests can be sent and will be responded to by the server in the order received.

Call context

Each call has a context that holds state and status information. Some context information is set automatically by the Woomera server, while other settings can be set by the application. There are Woomera commands for retrieving and setting context information

Media format modes

Woomera can handle audio and video, which is jointly referred to as "media", in three different modes:

1. Internal mode: the media is completely handled by Woomera. This allows Woomera complete access to the media stream, allowing it to play and record audio, transfer calls etc
   
2. Raw mode: the media is converted into a raw audio/video data stream that is sent an external UDP port. This allows Woomera to act as a signalling/media gateway in environments that wish to remain protocol agnostic
   
3. External RTP mode: in this mode, the media is not handled by Woomera. The call signalling channel is configured to send the RTP stream to an external RTP device.

Message format

Woomera commands, responses and events all have the same format consisting of a command line, followed by an optional MIME table and an optional entity body. As an example, the following is a valid Woomera message:

PLAY 1 file:sample.wav
Use-Format: G.711
empty line

As can be seen, this packet format is similar to a SIP protocol packet or a MIME format email message.  Note that optional entity body is only present if there is a Content-Length entry in the MIME table, and that the MIME table is always terminated by an empty line.

The command line of a Woomera message looks slightly different for the three different types of messages:

where:

Commands

This chapter describes the commands that a Woomera client can send:

• BYE/QUIT

• CALL

• HANGUP

• PLAY

• RECORD

• STATUS

• LISTEN

• ANSWER

• SPEAK

• DEBUG

• EXTERNAL

• SET

• GET

By default, all command responses contain the following MIME fields: