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

# Qtopia Phone Library

- Introduction
- Basic architecture
- Dialing a number
- Receiving an incoming SMS message
- Adding a new handler
- AT control commands used by Qtopia Phone Edition
  - General commands (GSM 07.07, section 5)
  - Call control commands (GSM 07.07, section 6)
  - Network service related commands (GSM 07.07, section 7)
  - Mobile equipment control and status commands (GSM 07.07, section 8)
  - SMS commands (GSM 07.05)
  - Other commands
  - Phone-specific commands

## 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:

- Create an instance of the "`PhoneLine`" class.
- Call the "`PhoneLine::createCall`" method to get an instance of the "`PhoneCall`" class that represents the call.
- Call the "`PhoneCall::dial`" method to dial the number.
- "`PhoneCall::dial`" then transmits the request to the phone server.

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:

- Obtain an instance of "`PhoneLineAt`", which represents the AT command handler for the phone line.
- Call the "`PhoneLineAt::createCall`" method to create an instance of the "`PhoneCallAt`" class.
- Call the "`PhoneCallAt::dial`" method to dial the number.
- "`PhoneCallAt::dial`" will then send the "`ATD`" command to the phone device to effect the dial request.

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`