Nokia N97 SDK Example Applications Guide |
IsvTelCallApp Example
1. About this Example
2. Prerequisites
3. Design and Implementation
This tutorial explains the IsvTelCallApp application example, which is a simple application demonstrating the use of the ISV
ETel APIs.
The tutorial starts by listing the pre-requisites the user should know before starting this example, and describes how to
build and run the example. The documentation goes on to discuss how to test an ISV ETel API, which is split into the following
sections:
- The application GUI.
- Engine.
- ISV ETel APIs.
This example exists as a complete application, and has the standard Symbian OS application architecture employing the Application,
Document, UI, and View classes. The example makes use of several other Symbian OS concepts that the reader should be aware
of before attempting to understand this example. These are:
- Active Object.
- ETel ISV APIs.
This application requires following capabilities defined in IsvTelCallApp.mmp:
NetworkServices ReadDeviceData WriteDeviceData ReadUserData WriteUserData
- Note:
- ACS Publisher ID is required to sign applications with ReadDeviceData and WriteDeviceData. However, a signed sis is provided
in sis-folder so that this example application can easily be tried on a device.
CIsvTelCallAppTelephony class is an active object, derived from CActive class and provides the functionality of the engine. Each option selected
by User through GUI invokes wrapper function of CIsvTelCallAppTelephony class, which in turn calls corresponding ISV ETel API. CTelephony class provides ISV ETel APIs. Since, CIsvTelCallAppTelephony is an active object; it waits asynchronously for the operations to complete from ISV ETel API. When engine is notified of
completion of requested ISV ETel API, it sends back the response to GUI for User.
This application uses the ISV ETel APIs related to Call functionality, e.g. CTelephony::DialNewCall(), CTelephony::GetCallStatus(),
etc.
When User wants to dial the number, edits Phone1/2 field of the application. On calling the number (either using Options menu
or Green dial button), the Call1/2 Status field gets updated. For example, before call establishment Call1/2 Status field
will display the intermediate state namely connecting. When the called party answers the call i.e. the Call is established,
the status updates to connected state. Similarly, other states of Call State Machine will be updated.
This sections gives the details about GUI implementation.
- The Framework creates the GUI, resulting in a call to Class Construct, which in turn constructs CIsvTelCallAppView object.
- CIsvTelCallAppView creates the CIsvTelCallAppContainer object from its second phase constructor.
- When User launchs the application, HandleCommandL() gets executed, which in turn invokes DisplayFormL() of CIsvTelCallAppContainer object. DisplayFormL () then creates CIsvTelCallAppDlg object and executes it.
- CIsvTelCallAppDlg creates multiple CIsvTelCallAppTelephony objects and assigns same CTelephony pointer to each object. Refer Class Constructor.
When User closes the application, CTelephony object and all engine objects are closed and destroyed.
The previous section shows how the GUI creates multiple CIsvTelCallAppTelephony objects and invokes corresponding ISV ETel API wrapper function. This section describes how these objects function as an
engine.
First, CIsvTelCallAppTelephony object creates an object of CTelephony class, and subsequently the same CTelephony pointer is assigned to other CIsvTelCallAppTelephony objects. Based on the request from GUI, associated engine function gets invoked, which in turn calls corresponding ISV ETel
API.
CIsvTelCallAppTelephony class, an active object, waits asynchronously for the reponses from ISV ETel APIs. Also, engine is registred for notification
of change in voice line state events. When command complete notification message from ISV ETel API or notification for change
in voice line status reaches the engine, it then sends back response to GUI for display.
The steps involved in MakeNewCall command is described as follows, the other commands also follow similar steps.
- When User dials a call, CIsvTelCallAppDlg decodes the command and calls corresponding engine function, in this case TelApiWrapperMakeNewCall.
- CIsvTelCallAppTelephony engine class then invokes corresponding ISV ETel API, DialNewCall().
- DialNewCall() is an asynchronous request, hence when API’s execution completes, RunL() of the IsvTelCallAppTelephony class
is called, which in turn calls MakeNewCallCompleteL() function of IsvTelCallAppDlg class.
- CIsvTelCallAppDlg class then converts the information in user friendly manner and displays on UI.
The previous two sections have shown how User selects the commands and how those commands are processed by Engine in accordance
with ISV ETel APIs. This section gives the details of CTelephony class and ISV ETel APIs provided by it.
The CTelephony class is meant for 3rd party developers. This class provides a simple interface to the phone's telephony system.
It provides two services:
- Information Service : This service provides support for retrieving Phone Settings, Line Information, Network Information and
(basic) Supplementary Service Settings.
- Call Service: This service provides dialling, answering and controlling of voice calls. This example has used APIs related
to Line information and Call funtionality. Answer incoming call option is set by default in application. APIs used in this
example are:
- DialNewCall
- GetCallStatus
- Hangup
- Hold
- Resume
- Swap
- GetLineStatus
- SendDTMFTones
- AnswerIncomingCall
- Note:
- Although mentioned APIs are public for 3rd party developers, there have been cases that in certain situations application
gets non-public error codes from Telephony. For example if a call is ended, before B-subscriber answers, the Hangup-operation
completes with non-public error code. If this happens, the example application just shows "Error"-note.
Each Symbian OS application has an associated MMP file. The MMP file defines such things as which source files are to be compiled,
which libraries to be linked, and so on. To create an IsvTelCallApp DLL, it is necessary to specify the target type and UID
in the MMP. These should be set to the values shown below.
- TARGETTYPE exe
- UID 0xA00001EF
IsvTelCallApp Example application has demonstrated the use of ISV ETel APIs. The application is split in two parts GUI and
Engine. User interacts with GUI and the GUI logic coverts those key presses to commands. Engine handles the commands and invokes
corresponding ISV ETel APIs. Upon completion of the API, the engine sends back the responses to GUI for display.
|
© Nokia 2009
|

|