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

Qtopia Phone Library

Introduction

This document describes the architecture of the qtopiaphone library which is used for example, to access phone hardware to send and receive calls, send SMS messages and access the SIM card.

Basic Architecture

The basic architecture is shown in the following diagram:

An application, such as the dialer, uses C++ APIs to access information about a phone line, the phone book in the SIM card, or the SMS message system.

Requests are transmitted to the phone server, which co-ordinates access to the phone functionality from multiple applications. This allows the dialer and the SMS messaging client to access the phone hardware at the same time.

The phone server then passes the requests to the device handler, which communicates with the hardware device to effect the requests. Responses and status messages are passed back in the reverse direction.

Currently, a device handler accessed via a serial port, is implemented based on AT commands. This is the recommended way to interface phone functionality with Qtopia Phone. If AT commands are not available, the back-end handler can be replaced with code that effects the requests in some other manner.

The remainder of this document demonstrates the flow of requests and responses through the system using the following examples:

Dialing a Number

To dial a number, the application:

Usually there is only one instance of the PhoneLine class per application. However, there may be multiple instances of PhoneCall if calls are on hold or a multi-party conference call is in progress.

The phone library transmits the dial request to the phone server using QCop and the phone server:

The sequence of operations mirrors the sequence in the application with the only difference being in the final step where:

If the device does not support AT commands, new handler classes need to be written, modelled on the structure of PhoneLineAt and PhoneCallAt. The exact details of how the device effects the dial command is beyond the scope of this document.

Receiving an Incoming SMS Message

When the AT command handler starts it registers for new message indications using the AT+CNMI command. This causes the phone device to send +CMTI indications whenever a new message arrives at the device.

When +CMTI is detected by SMSRequestAt::notification, it causes the AT command handler to initiate the message count check - SMSRequestAt::check. Once the check completes, the number of messages is transmitted to the application via the SMSRequestPrivate::messageCount signal. An alternative device handler would similarly need to arrange for the SMSRequestPrivate::messageCount signal to be emitted when new messages arrive.

The SMSRequestPrivate::messageCount signal is broadcast on the QPE/Phone QCop channel. Applications listen on this channel to receive notification of new messages. More than one application can listen for new message notifications, but only one (usually the mail client) should subsequently retrieve the message contents.

When the mail client receives the signal, it calls the SMSRequest::firstMessage and SMSRequest::nextMessage methods to retrieve the SMS message contents from the incoming queue. Each message is returned to the application via the SMSRequestPrivate::fetched signal.

Finally, once the message is received by the application it is deleted from the incoming queue using SMSRequest::deleteMessage. The application saves the message in another location so that the message is never permanently lost and the message store in the device is treated as a temporary buffer.

Note: Signals rather than function returns are used to pass messages and status reports back to the application. This is because the entire phone system is asynchronous and the information may not be available when the request is made and so must be transmitted later.

Detailed Example of the Role of the Phone Server

This section provides an example of the methods to route applications requests through the phone server to the AT command handlers, and describes how the responses are returned to the application. Using the SIMIdentity query type, which returns the IMSI number of the SIM the methods used are as follows:

This completes the example. Other commands and notifications within the phone library follow a similar pattern.

Supported Standards

The following standards are currently supported:

Standard Description
GSM 03.40 Format information for SMS messages.
GSM 11.11 GSM 11.14 SIM application toolkit.
WAP-183-PROVCONT, OMA-WAP-PROVCONT Format for over-the-air (OTA) provisioning messages.
WAP-192-WBXML Format for WBXML messages.
WAP-203-WSP Wireless session protocol specification.
WAP-205-MMSARCHOVERVIEW, WAP-206-MMSCTR, WAP-209-MMSENCAPSULATION, OMA-MMS-ARCH, OMA-MMS-CONF, OMA-MMS-CTR, OMA-MMS-ENC Format and handling for the MMS messaging service.
WAP-235 Push over-the-air protocol.
Nokia Over The-Air Settings Specification 7.0 Format for over-the-air (OTA) provisioning messages (Nokia compatible).
Nokia Smart Messaging Specification 3.0.0 Port numbers for Nokia-style push messages for applications such as for vcard and vcalendar.

Adding a New Handler

The process to add a new device handler is as follows:

AT Control Commands used by Qtopia Phone Edition

The following sections list the AT control commands that a device is expected to support, however, a device may support more commands than listed. For example, some phones support both AT+CGMI and AT+GMI to retrieve the manufacturer name, while only AT+CGMI is required.

In the future, additional commands from the GSM specifications 07.05 and 07.07 may be required, so it is recommended that all device manufacturers fully comply with GSM specifications.

The categories of control commands are:

General Commands (GSM 07.07, section 5)

Command Description
AT+CGMI Identify manufacturer
AT+CGMM Identify model
AT+CGMR Identify revision
AT+CGSN Identify serial number (of device, not SIM card)
AT+CSCS Select character set

Call Control Commands (GSM 07.07, section 6)

Command Description
ATDnnn; Dial "nnn" in voice mode.
ATH Hangup the current call.
ATA Answer an incoming call.

Note: When the ATD command is used with a trailing ';', it must return immediately to command mode after command processing. Some phones have been known to wait until the receiving party answers the call, or busy is detected, before returning to command mode. Such phones are not compliant with the GSM specification and will not be supported.

The GSM specification permits ATD to be used in a special mode for dialing directly from phone books. This mode is not required as Qtopia implements its own algorithm for converting phone book entries to numbers.

It is important that ATD recognise numbers starting with + as international, and all other numbers as being local.

Network Services Related Commands (GSM 07.07, section 7)

Command Description
AT+CNUM Subscriber number
AT+CREG Network registration
AT+COPS Operator selection
AT+CLCK Facility lock
AT+CPWD Change password
AT+CLIP Enable caller line identification
AT+CLIR Caller ID restriction
AT+CCUG Closed user group
AT+CCFC Call forwarding number and conditions
AT+CCWA Call waiting
AT+CHLD Call hold and multiparty
AT+CTFR Call transfer
AT+CAOC Advice of charge

Mobile Equipment Control and Status Commands (GSM 07.07, section 8)

Command Description
AT+CPAS Phone activity status
AT+CFUN Set phone functionality
AT+CPIN Enter PIN
AT+CBC Battery charge
AT+CSQ Signal quality
AT+CPBS Select phonebook memory storage
AT+CPBR Read phonebook entries
AT+CPBW Write phonebook entries

The phonebook commands are intended for accessing phone books stored on SIM cards, typically the SM phone book. However, Qtopia Phone software provides its own mechanisms for managing phone books stored within the phone memory.

SMS Commands (GSM 07.05)

Command Description
AT+CPMS Preferred message storage
AT+CMGF Message format (we use format 0: PDU)
AT+CSCA Service centre address
AT+CNMI Enable new message indications
AT+CSCB Select cell broadcast message types
AT+CMGL List messages
AT+CMGR Read message
AT+CMGS Send message
AT+CMGD Delete message
AT+CMMS More messages to send
+CMTI Notification of SMS message delivery.
+CBMI Notification of a cell broadcast message.
+CDSI Notification of an SMS status report message.
+CBM Notification of a directly delivered cell broadcast message.

It is assumed that incoming SMS messages are stored in a temporary storage area on the device and that Qtopia will retrieve the messages using the AT+CMGL and AT+CMGR commands.

Multiplexing Commands (GSM 07.10)

Qtopia Phone expects to use GSM 07.10 multiplexing to establish multiple communications paths with the modem. The modem needs to support the AT+CMUX command plus the basic packet mode in GSM 07.10. If the modem supports some other form of multiplexing, then it is necessary to modify muxdevice.cpp in the source code. Multiplexing support is required for GPRS.

Other Commands

Command Description
AT+VTS DTMF and tone generation (GSM 07.07, Appendix C)
AT+CVIB Select vibrate mode
AT+CPUC Price per unit
AT+CIMI SIM identity
AT+CHSC Get phone status (only needed if AT+CPAS is not available)
AT+CLCC List active calls

Phone-specific Commands

The GSM specification lacks some functionality required to provide a complete feature set. The most important of these is Call Monitoring, that is, when an outgoing dial request is made, a method of detecting call acceptance or rejection by the other party is required.

Ericsson phones have an AT*ECAM command that is used to turn on supplementary call monitoring events. That is, each time the call status changes, the phone emits an *ECAV message with the details. It is recommended that device manufacturers provide these or similar commands.

Command Description
AT*ECAM Turn on call monitoring
AT*ESIL Select silent mode
*ECAV Unsolicited response for AT*ECAM

WAP Push and Over-The-Air (OTA) Support

WAP Push

Qtopia Phone intercepts WAP push messages arriving via SMS and delivers them to an interested application.

When an SMS message is received with a destination port number, Qtopia will attempt to find a service that can handle it by:

If a matching service is found then:

If a matching service is not found:

Over-The-Air (OTA)

Qtopia Phone provides built-in support for:

Other OTA messages are handled on a type-by-type basis by vendor-supplied applications, via the Qtopia Services system. See Qtopia Application Services for more information on configuring a service.

Video Calls

The phone library provides a facility for applications supporting video calls, to interface with the underlying communications hardware in order to send and receive data over the network. A video call application is not provided as part of Qtopia.

Overview

A video call application, manages video calls similarly to voice calls with the APIs provided by the PhoneLine and PhoneCall classes. Once the application detects that a video call object in the system has been connected, it can then connect via a TCP socket to the address localhost:51423 to send and receive data over the network. This socket is called the video data socket.

Qtopia performs buffering of data:

Generally, an application can connect to the video data socket, transfer data as required and not be concerned about loss or flow of data between the modem and Qtopia.

API Example

The following is a simple example of the APIs used to:

MyClass::MyClass()
{
    myLine = new PhoneLine(); // Gain access to a PhoneLine instance
    connect( line, SIGNAL(newCall(const PhoneCall&)), this, SLOT(newCall(const PhoneCall&)) ); // Monitor new PhoneCall objects
}

void MyClass::createVideoCall( const QString &phoneNumber )
{
    // Create an outgoing video call. MyClass::newCall will detect the new PhoneCall object
    myLine->startVideo( phoneNumber );
}

void MyClass::newCall( const PhoneCall &nc )
{
    if( nc.callType() == PhoneCall::Video ) {
        if( myVideoCall != PhoneCall::null )
            return; // Only one video call at a time

        myVideoCall = nc; // New video call object in the system
        myVideoCall.connectStateChanged( this, SLOT(videoCallStateChanged(const PhoneCall&)) ); // Monitor its state
    }
}

void MyClass::videoCallStateChanged( const PhoneCall &vc ) { // video call object's state changed
    // vc == myVideoCall
    if( myVideoCall.connected() ) { 
        // Video call is connected, connect TCP socket to locahost:51423 and transfer data
    } else if( myVideoCall.dropped() ) {
        // Video call disconnected, close video data socket
        myVideoCall = PhoneCall::null;
    } else if( myVideoCall.incoming() ) {
        // ncoming video call - accept it. Next state will be PhoneCall::Connected
        myVideoCall.accept();
    }
}

void MyClass::endVideoCall()
{
    // The user wants to end the video call, hangup. Next state will be PhoneCall::HangupLocal
    myVideoCall.hangup();
}

An application handling incoming video calls must provide the VideoCall service and handle the incomingVideoCall() message by connecting to the QPEApplication::appMessage() signal. Qtopia sends the message to the service when it detects an incoming video call from the modem. As Qtopia Services use QCop, the application will be started to handle the message if it is not running at the time. See Services for more information.

Modem Requirements

The following is required for video call functionality:

Below is the expected AT command communication between Qtopia and the modem for successful outgoing and incoming video calls. All communication occurs on mux channel 5.

Outgoing:

AT+CBST=134,1,0
OK
ATD<number>
OK
CONNECT 64000
<video data follows>

Incoming:

+CRING: ASYNC
ATA
CONNECT 64000
<video data follows>


Copyright © 2005 Trolltech Trademarks
Qtopia version 2.2.0