Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference

Qtopia VoIP Integration

Introduction

This document describes how to integrate a third-party Voice over IP (VoIP) handler into Qtopia.

Third parties need to supply at least two programs as follows:

  1. phone call handler that provides the call management facilities
  2. settings program that allows the user to configure the VoIP options for the phone call handler.

The phone call handler must be registered as a VoIP service in the $QPEDIR/services/VoIP directory. For example, if the phone call handler binary is called "foovoip", you would create a file called $QPEDIR/services/VoIP/foovoip that contains the following:

[Extensions]
[Standard]
Version = 100

Qtopia will then launch the handler at the correct time.

Connection Establishment

When the Qtopia Phone Server is started, it binds to a Unix domain socket and listens for incoming connections. Phone call handlers connect to this socket and announce themselves with an INIT message. After that, all call requests of that type are redirected to the handler process.

The connection is made to /tmp/qtopia-N/call-manager, where N is the QWS display identifier (usually 0). When using Qt/Embedded, the display identifier can be obtained from the qws_display_id variable at runtime. The following code demonstrates how to construct the name of the Unix domain socket to use:

extern int qws_display_id;
struct sockaddr_un addr;
::memset( &addr, 0, sizeof(addr) );
addr.sun_family = AF_UNIX;
snprintf( addr.sun_path, sizeof( addr.sun_path ),
          "/tmp/qtopia-%d/call-manager", qws_display_id );

If the phone call handler is not using Qt/Embedded, you can obtain the display identifier from the QWS_DISPLAY environment variable, which has the form name:N.

Conventions and Command Encoding

In the commnand descriptions below [X] indicates that X is optional. (A|B) indicates that either A or B should be sent (without parentheses). The following conventions apply:

Qtopia to Handler Requests

This section describes the requests that are sent from Qtopia to the phone call handler.

Request Description
DIAL identifier number type [restrict]: Dial a number on a new call called identifier. The number argument may be a URI for VoIP (e.g. sip:name@hostname).

If the restrict flag is present, then the handler should prevent caller id information from being sent. If there is no way to prevent caller id information from being sent, the flag should be ignored.

The type will usually be voip. This may change in future versions of Qtopia to support multiple phone call handlers.

Call identifiers should be globally-unique identifiers which are never reused. In Qtopia, Global::generateUuid().toString() can be used to generate such an identifier.

HANGUP identifier (callonly|group): Hang up the call associated with identifier. If the callonly flag is supplied and the call is part of a multi-party conference group, then only this call will be hung up - all other parties remain connected. If the group flag is supplied, then all calls in the group are hung up. If the phone call handler does not support multi-party conference groups, the flag should be ignored.
ACCEPT identifier: Accept the incoming call associated with identifier. The phone call handler sends a STATUS message to Qtopia to inform it about the incoming call. See below for more details.
HOLD identifier: Place the call associated with identifier on hold. If the phone call handler does not support call hold, the handler should respond with a FAIL message.
ACTIVATE identifier (callonly|group): Re-activate the call associated with identifier that was on hold. If the callonly flag is supplied and the call is part of a multi-party conference group, then only this call is taken off hold, removing it from the multi-party conversation. If the group flag is supplied, then all calls in the multi-party conference group are re-activated.
JOIN identifier [detach]: Join the call associated with identifier (which is on hold) to the currently active conversation for three-way communication. If the detach flag is present, then the two calls are connected and then the local user is detached. To "unjoin" a call, ACTIVATE id callonly is used on the call.
DTMF identifier tones: Send DTMF tones on the call associated with identifier.
TRANSFER identifier number Transfer the call associated with identifier to number.
REGISTER Register with the network. If the phone call handler requires authentication credentials (e.g. user name and password), it must obtain this information from the user or a configuration file.
DEREGISTER De-register from the network.
STARTMONITOR who Start monitoring the presence status on who. Whenever the status changes, the handler sends a MONITOR message.
STOPMONITOR who Stop monitoring the presence status on who.
GETPRESENCE Get the presence state of the local user. The handler should respond with a PRESENCE message.
SETPRESENCE (available|unavailable) Set the presence state of the local user to available or unavailable.
GET name Get the auxillary setting name. Not used at present.
SET name value Set the auxillary setting name to value. Not used at present.

Note: DIAL, HANGUP, ACCEPT, HOLD, ACTIVATE, and JOIN should respond with STATUS messages to indicate how the status of the call has changed. e.g. DIAL will respond with a dialing status, followed by a connected status once the call connects.

Sometimes a phone operation may have unwanted effects on other calls. For example, taking a background call off hold will put the foreground call on hold. The handler should send extra STATUS messages to indicate the changes in the other calls affected.

Note: If a DIAL command fails, the correct response is to send a STATUS message, not a FAIL message. FAIL is intended for gross protocol failures such as command not supported.

Handler to Qtopia Requests

This section describes the messages that are sent from phone call handler to Qtopia.

Request Description
INIT type1 [type2 ...] Sent just after connection to indicate the types of calls that are handled by this phone call handler. The only type that is supported at present is voip.

After sending INIT, if there are pre-existing calls in progress, the handler must send STATUS messages for all existing calls to inform Qtopia about them.

STATUS identifier status type [number] Indicates a change in status on the call associated with identifier. The status must be one of incoming, dialing, connected, hold, hanguplocal, hangupremote, missed, networkfailure, otherfailure, servicehangup.

The number will usually be present on incoming calls to indicate the caller's identity.

NAME identifier name Indicate that the real name of the user on the call associated with identifier is name.
GROUP identifier groupid The call associated with identifier has changed its hold group. This is affected by HOLD, JOIN, and other multi-party conference call commands. If a call does not have an explicit group identifier yet, then its call identifier is its group.
REGISTRATION type Indicate a change in network registration. The type must be one of unregistered, home, searching, denied, unknown, or roaming.
OPERATOR name Name of the network operator that was registered.
PRESENCE status Report presence information on the local user, in response to a GETPRESENCE command. The status is available or unavailable.
MONITOR who status Change in presence information on who. The status is available or unavailable.
VALUE name value This is a response to the GET command. Not used at present.
NOTIFY name value This message notifies Qtopia of a change in the auxillary setting name to value. Not used at present.

Commands in Either Direction

The following commands may be sent in either direction.

Request Description
FAIL reason cmd [arg1 ...] Report that the command indicated by cmd arg1 ... failed for the specified reason. The only reason that is currentlysupported is unknown-command.
TEST cmd1 [cmd2 ...] Test to see if cmd1, cmd2, etc are supported. The other side responds with a SUPPORTS message. This can also test if commands in the reverse direction are supported. For example, sending TEST DIAL STATUS to the handler will test if it can receive the DIAL command and will report STATUS messages.
SUPPORTS cmd1 [cmd2 ...] Response to TEST to see if a command is supported. Command names that are not supported start with !. For example, TEST ACCEPT HOLD may respond with SUPPORTS ACCEPT !HOLD.

Relevant Code

The Qtopia side of the protocol communication can be found in the source file $QPEDIR/src/libraries/qtopiaphone/voipline.cpp. This can be used as a guide for implementing the protocol. You can also make use of the PhoneSocket class, declared in phonesocket.h, to simplify the communication if your handler is based on Qt.


Copyright © 2005 Trolltech Trademarks
Qtopia version 2.2.0