Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions

Qt Extended Phone Library

• Services and Interfaces
• Using Telephony Interfaces
• Implementing Telephony Interfaces
• Automatic Starting of Telephony Services
• Modem Services

This document describes the design of the Qt Extended Phone Library. The complete list of library classes can be found on the Telephony Classes page.

Services and Interfaces

Handlers in the telephony system are referred to as services. Each service has a unique name, such as modem, voip, etc. By convention, service names are lower case. Within each service is a list of interfaces for functionality areas such as network registration, phone calls, SMS, SIM Application Toolkit, etc.

Interface names correspond to class names in the Qt Extended Telephony API. For example, the QNetworkRegistration interface provides access to network registration features, and the QSMSSender interface provides methods to send SMS messages. The following table summarises the interfaces in the Qt Extended Phone Library:

Not all services have all of these interfaces. For example, VoIP services may only have QNetworkRegistration, QPresence, QPhoneCallManager, and QTelephonyConfiguration. GSM services will not typically have QPresence, and may not have QSimToolkit if the modem does not support it.

Client applications can use the QCommServiceManager class to determine if an interface is supported by a service:

    QCommServiceManager mgr;
    if ( mgr.supports<QSimToolkit>( "modem" ) ) {
       ...
    }

Using Telephony Interfaces

Client applications access the features of an interface by creating an instance of the corresponding class. For example, the following can be used to send an SMS message using the default service that supports the QSMSSender interface:

    QSMSSender sender;
    QSMSMessage msg;
    msg.setRecipient( "1234567" );
    msg.setText( "Hello!" );
    sender.send( msg );

When creating an interface instance, the client application can specify an explicit service name, if more than one service implements the same interface, or leave the service name empty to use the default service for that interface. For example, if the VoIP implementation supported SMS over SIP, then the following could be used to send the same message via the voip service:

    QSMSSender sender( "voip" );
    if ( sender.available() ) {
        QSMSMessage msg;
        msg.setRecipient( "1234567" );
        msg.setText( "Hello!" );
        sender.send( msg );
    } else {
        QMessageBox::warning( 0, tr("SMS"), tr("SMS over SIP is not available") );
    }

This time, we have checked that the service is available before trying to send the message. The QCommServiceManager class can be used to locate all services that implement a particular interface, to allow the user to select which one they want to use:

    QCommServiceManager mgr;
    QStringList services = mgr.supports<QSMSSender>();

Implementing Telephony Interfaces

Telephony services implement interfaces by inheriting from the client-side class and overriding its public slots with a new implementation. To demonstrate how this works, we will implement the hypothetical "SMS over SIP" referred to in the previous section.

    class VoIPSMSSender : public QSMSSender
    {
        Q_OBJECT
    public:
        VoIPSMSSender( QObject *parent = 0 )
            : QSMSSender( "voip", parent, QCommInterface::Server ) {}
        ~VoIPSMSSender() {}

    public slots:
        void send( const QString& id, const QSMSMessage& msg );
    };

    void VoIPSMSSender::send( const QString& id, const QSMSMessage& msg )
    {
        ...
    }

The VoIP service creates an instance of VoIPSMSSender, passing the QCommInterface::Server flag to the base class constructor. This tells the Qt Extended Phone Library to advertise VoIPSMSSender as the implementation of the interface QSMSSender for the service voip. The Qt Extended Phone Library uses Qt Extended IPC and the Value Space to effect communication between the client application and the service. There is more information on how this process works in the documentation for QAbstractIpcInterface, which is the base class for all telephony interfaces.

The VoIPSMSSender instance can be created anywhere in the system, usually in the daemon that implements the VoIP telephony service. The example VoIP implementation that comes with Qt Extended is implemented by the sipagent daemon.

Telephony services do not need to be part of the qpe process, or any other special Qt Extended application, although they can be. The default implementation of the GSM modem service is created by qpe, but other modem implementations could be in separate daemons.

Most telephony services will have more than one interface. The QTelephonyService class makes it easy to create large numbers of related interfaces within a service. Our VoIP implementation would look something like this:

    class VoIPService : public QTelephonyService
    {
        Q_OBJECT
    public:
        VoIPService( QObject *parent = 0 )
            : QTelephonyService( "voip", parent ) {}
        ~VoIPService() {}

        void initialize();
    };

    void VoIPService::initialize()
    {
        if ( !supports<QSMSSender>() )
            addInterface( new VoIPSMSSender( this ) );

        ...

        QTelephonyService::initialize();
    }

The VoIP daemon creates an instance of VoIPService, and then calls the initialize() method to complete the initialization process.

In the example above, we call supports() to first check if there is an existing implementation of QSMSSender before creating the new one. This style of interface creation supports inheritance of services. A better version of the VoIP service could inherit from VoIPService, override initialize(), and create a new implementation of the QSMSSender interface that replaces the original.

The VoIP Integration Guide provides more detailed information on integrating VoIP telephony services into Qt Extended, and the particular interfaces that are required.

Automatic Starting of Telephony Services

Third-party telephony services can be easily added to Qt Extended by adding a file to the directory $QPEDIR/services/Telephony whose name is the same as the daemon binary. Its contents should be as follows:

    [Extensions]
    [Standard]
    Version = 100

When Qt Extended starts up, any daemons that are registered under $QPEDIR/services/Telephony will be automatically started by sending the service a start() message. The services then create instances of every interface that they support and wait for requests to arrive from client applications.

The example VoIP implementation that comes with Qt Extended, sipagent, demonstrates how to write such a service and integrate it with the rest of Qt Extended.

Because telephony services do not normally have a user interface associated with them, it is necessary to register the daemon as a running task to prevent Qt Extended from telling it to exit soon after startup. You should place a line of code in your startup logic such as the following:

    QtopiaApplication::instance()->registerRunningTask( "Telephony", obj );

where obj is a QObject in your application that will stay in existence while the telephony service is running (the QTelephonyService instance may be a good candidate).

Modem Services

AT-based GSM modem telephony services have special support in Qt Extended. Most of the time, the Qt Extended implementation will be sufficient, but there are slight variations in GSM modems that may need additional support.

The systems integrator can elect to write their own modem telephony service from scratch, but this is usually very time-consuming. A better way is to use the existing Qt Extended implementation in src/libraries/qtopiaphonemodem and just override the pieces that are different in a modem vendor plugin.

The GSM Modem Integration page describes how to write a modem vendor plugin.