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

# Qtopia Phone library

- Introduction
  - Dialing a number
  - Receiving an incoming SMS message
  - Adding a new handler

## 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, etc. The basic architecture is demonstrated in the following diagram:

An application, such as the dialer, uses C++ API's 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 onto 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 hone 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`".