![]() Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference |
![]() |
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.
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:
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.
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.
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:
PhoneLine *line = new PhoneLine();
connect( line, SIGNAL(queryResult(PhoneLine::QueryType, const QString&)), this, SLOT(simIdResult(PhoneLine::QueryType, const QString&)) ); ... void AppClass::simIdResult( PhoneLine::QueryType type, const QString& value ) { // Process the result "value". ... }
line->query( PhoneLine::SIMIdentity );
Note: The PhoneLine for the phone server contains a private PhoneLineAt object rather than the PhoneLineQCop object used by applications.
The following standards are currently supported:
Standard | Description |
---|---|
GSM 03.40 | Format information for SMS messages. |
GSM 11.11 | 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. |
The process to add a new device handler is as follows:
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
The categories of control commands are:
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 |
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
The
It is important that ATD recognise numbers starting with + as international, and all other numbers as being local.
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 |
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.
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.
Qtopia Phone expects to use
Command | Description |
---|---|
AT+VTS | DTMF and tone generation ( |
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 |
The
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 |
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:
Qtopia Phone provides built-in support for:
This is described in the WAP/OMA standards wap-183-provcont-20010724-a.pdf and OMA-WAP-ProvCont-V1_1-20021112-C.pdf.
Both of these can be found at Open Mobile Alliance.
This is described in the Nokia Over The Air Settings Specification 7.0.
This is described in the WAP/OMA standard oma-wap-mms-enc-v1_1-20021030-c.pdf.
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.
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.
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.
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.
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
|