Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded

Qtopia Phone Library

Introduction

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

Basic architecture

The basic architecture is demonstrated 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 both access the phone hardware at the same time.

The phone server then passes the requests on 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, we have implemented a device handler based on "AT" commands. The actual device itself is accessed via a serial port. This is the recommended way to interface phone functionality with Qtopia Phone.

If "AT" commands are not available, the backend handler can be replaced with code that effects the requests in some other manner.

In the remainder of this document, we will demonstrate how requests and responses flow through the system with two examples: dialing a number, and receiving an incoming SMS message.

Dialing a number

When the application wishes to dial a phone number, it performs the following actions:

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

The phone library will transmit the dial request to the phone server using QCop. The phone server will then take the following actions:

As can be seen, the sequence of operations directly mirrors the sequence in the application. The only difference is the final step: the application side sends the request to the phone server, and the handler side performs the low-level device operations directly.

If your device does not support AT commands, you would write new handler classes, modelled on the structure of "PhoneLineAt" and "PhoneCallAt". The exact details of how your device effects the dial command is beyond the scope of this document.

Receiving an incoming SMS message

When the AT command handler starts up, 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.

In the code, "+CMTI" is detected by "SMSRequestAt::notification", and causes the AT command handler to initiate a 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.

This signal is broadcast on the "QPE/Phone" QCop channel. Applications can 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 application has received the message, it will delete it from the incoming queue using "SMSRequest::deleteMessage". The application (usually the mail client) will save the message in another location so that the message is never permanently lost (the message store in the device is treated as a temporary buffer in our system).

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

Adding a new handler

If you wish to add a new phone device handler, you should inherit the class "PhoneLinePrivate" and override all of the functionality that is specified therein. The "PhoneLineAt" class can be used as a guide to the necessary structure.

You will also need to modify the "PhoneLinePrivate::create" method to return an instance of your class instead of "PhoneLineAt".

AT control commands used by Qtopia Phone Edition

This following sections list the "AT" control commands that we expect the device to support. Most of them are from the GSM specifications.

The device may support more commands than are listed here. For example, some phones support both "AT+CGMI" and "AT+GMI" to get the manufacturer name. We only require "AT+CGMI" but there is no harm in the device supporting both.

In the future, we may need to additional commands from the GSM specifications 07.05 and 07.07, so we recommend that all device manufacturers fully comply with those specifications.

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 immediately return to command mode after processing the command. Some phones have been known to wait until the other party answers the call, or busy is detected, before returning to command mode. Such phones are not compliant with the GSM specification and we will not be supporting them.

The GSM specification allows "ATD" to be used in a special mode for dialing directly from phone books. We do not need this mode as we implement our own algorithm for converting phone book entries into numbers.

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

Network service related commands (GSM 07.07, section 7)

Command Description
AT+CNUM Subscriber number
AT+CREG Network registration
AT+COPS Operator selection
AT+CLIP Enable caller line identification
AT+CLIR Caller ID restriction
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+CBC Battery charge
AT+CSQ Signal quality
AT+CPBS Select phonebook memory storage
AT+CPBR Read phonebook entries
AT+CPBF Find phonebook entries
AT+CPBW Write phonebook entries

The phonebook commands are intended for accessing phone books stored on SIM cards. The Qtopia Phone software has its own mechanisms for managing phone books that are stored in the phone's 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+CMGL List messages
AT+CMGR Read message
AT+CMGS Send message
AT+CMGD Delete message
+CMTI Notification of SMS message delivery.
+CBMI Notification of a cell broadcast message.
+CDSI Notification of an SMS status report message.

We assume that incoming SMS messages are stored into a temporary storage area on the device from which our software will retrieve the messages using the "AT+CMGL" and "AT+CMGR" commands.

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 is lacking some functionality that we require to round out the feature set. The most important of these is "call monitoring". When an outgoing dial request is made, we need some way to detect when the other party accepts the call, if it rejected due to the other party being busy, or some other failure.

Ericsson phones have a "AT*ECAM" command that is used to turn on supplementary call monitoring events: every time a call's status changes, the phone emits a "*ECAV" message with the details. We recommend that device manufacturers provide these commands, or something very similar to them.

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


Copyright © 2001-2005 Trolltech Trademarks
Qtopia version 2.1.1