S60 3rd Edition SDK for Symbian OS
Example Applications Guide

IsvTelCallApp Example

1. About this Example
2. Prerequisites
3. Design and Implementation

1. About this Example

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:

2. Prerequisites

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:

3. Design and Implementation

3.1 Capabilities

This application requires following capabilities defined in IsvTelCallApp.mmp:

NetworkServices ReadDeviceData WriteDeviceData ReadUserData WriteUserData

Note that ACS Publisher ID is required to sign applications with ReadDeviceData and WriteDeviceData.

3.2 Application Overview

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.

3.3 GUI Implementation

This sections gives the details about GUI implementation.
  1. The Framework creates the GUI, resulting in a call to Class Construct, which in turn constructs CIsvTelCallAppView object.
  2. CIsvTelCallAppView creates the CIsvTelCallAppContainer object from its second phase constructor.
  3. When User launchs the application, HandleCommandL() gets executed, which in turn invokes DisplayFormL() of CIsvTelCallAppContainer object. DisplayFormL () then creates CIsvTelCallAppDlg object and executes it.
  4. 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.

3.4 ISV ETel API Engine

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.

  1. When User dials a call, CIsvTelCallAppDlg decodes the command and calls corresponding engine function, in this case TelApiWrapperMakeNewCall.
  2. CIsvTelCallAppTelephony engine class then invokes corresponding ISV ETel API, DialNewCall().
  3. 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.
  4. CIsvTelCallAppDlg class then converts the information in user friendly manner and displays on UI.

3.5 ISV ETel APIs

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

  1. Information Service : This service provides support for retrieving Phone Settings, Line Information, Network Information and (basic) Supplementary Service Settings.
  2. 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:
  3. DialNewCall
  4. GetCallStatus
  5. Hangup
  6. Hold
  7. Resume
  8. Swap
  9. GetLineStatus
  10. SendDTMFTones
  11. AnswerIncomingCall

3.6 MMP File

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.

4. SUMMARY

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.

This inheritance list is sorted roughly, but not completely, alphabetically:

© Nokia 2006

Back to top