Home · All Classes · Grouped Classes · Annotated · Functions

Qtopia Phone Library

This document describes the design of the Qtopia 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 Qtopia 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 Qtopia Phone Library:

InterfaceDescription
QAdviceOfChargeAdvice of charge information during a call.
QBandSelectionSelection of GSM bands - 850 MHz, 900 MHz, 1800 MHz, 1900 MHz, dual, and tri-band.
QCallBarringSettings related to call barring.
QCallForwardingSettings related to call forwarding.
QCallSettingsOther call settings: call waiting and caller ID restrictriction.
QCallVolumeControl the volume while on a call.
QCellBroadcastAccess to cell broadcast messages.
QGprsNetworkRegistrationNotification of GPRS registration state.
QNetworkRegistrationNotification of general network registration state, plus operator selection.
QPhoneBookAccess to phone books that are stored on a SIM.
QPhoneCallManagerMaking and receiving calls: voice, data, fax, etc.
QPhoneRfFunctionalityManipulation of the RF functionality level for selecting airplane and non-airplane modes.
QPinManagerNotification of PIN requests, and PIN management (change, lock, unlock, etc).
QPreferredNetworkOperatorsAccess to the preferred network operator list in a SIM.
QPresenceVoIP presence information.
QServiceCheckerCheck that a service was started and has sufficient resources to perform operations.
QServiceNumbersAccess to service numbers such as SMS service center and the voice mail number.
QSimFilesRaw access to files on the SIM.
QSimGenericAccessRaw access for sending commands to the SIM.
QSimInfoInformation about the SIM's identity and whether or not it is currently inserted.
QSimToolkitAccess to SIM Application Toolkit features of the SIM.
QSMSReaderAccess to the incoming SMS message queue.
QSMSSenderAccess to the outgoing SMS message queue.
QSupplementaryServicesSS and USSD support for GSM networks.
QTelephonyConfigurationService configuration interface and miscellaneous settings.

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 Qtopia Phone Library to advertise VoIPSMSSender as the implementation of the interface QSMSSender for the service voip. The Qtopia Phone Library uses Qtopia IPC and the Qtopia 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 Qtopia is implemented by the sipagent daemon.

Telephony services do not need to be part of the qpe process, or any other special Qtopia 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 Qtopia, and the particular interfaces that are required.

Automatic Starting of Telephony Services

Third-party telephony services can be easily added to Qtopia 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 Qtopia 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 Qtopia, sipagent, demonstrates how to write such a service and integrate it with the rest of Qtopia.

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 Qtopia 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 Qtopia. Most of the time, Qtopia's 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 Qtopia 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.


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3