Home · All Classes · Grouped Classes · Annotated · Functions

Qtopia VoIP Integration

• Introduction
• Connection Establishment
• Conventions and Command Encoding
• Qtopia to Handler Requests
• Handler to Qtopia Requests
• Commands in Either Direction
• Relevant Code

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. The file should be installed by the build system. See Register a service provider for details.

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 Qtopia Core, 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;
    strncpy( addr.sun_path,
             (Qtopia::tempDir()+"call-manager").toLatin1(),
             sizeof( addr.sun_path ));

If the phone call handler is not using Qtopia Core, 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:

• arguments to a command are separated by one or more space characters (0x20).
• arguments may be sent quoted or unquoted and have the following rules:
  • unquoted arguments must not contain spaces, characters with codes less than 0x20, a double quote (") or a backslash (\).
  • quoted arguments are surrounded by double quotes and may contain \" to escape an embedded double quote, \\ to escape a backslash, or \NNN for the octal encoding of non-printable characters below 0x20. The character set is UTF-8. An 8-bit clean transport is assumed.
• any argument that may be sent unquoted can also be sent quoted, but not all quoted arguments can be sent unquoted.
• Ordinary characters can be escaped with \\, and stand for the character themselves. For example, \\n is the letter n, although it would be more efficient to simply send the n as-is. An embedded line feed would be sent as \\012.
• lines can be of arbitrary length, and are terminated with CRLF.
• command names and arguments are case-sensitive.

Qtopia to Handler Requests

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

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.

Commands in Either Direction

The following commands may be sent in either direction.

Relevant Code

A sample SIP stack and VoIP user agent can be found in $QPEDIR/src/tools/sipagent. It is based around the LGPL'ed libdissipate2 library, which provides the SIP functionality. The sipagent program also implements audio transport via the Real Time Protocol (RTP), using the freely available G711u, G711a, GSM, and iLBC codecs.

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