Telephony ISV API overview

Symbian OS's CTelephony class provides a simple interface to the phone's telephony system.

CTelephony provides two services: Firstly, you can find out information about the phone. Secondly, you can dial and answer voice calls.

Note: In the past, CTelephony could be used for data calls. This functionality has been deprecated and may be removed in future versions of Symbian OS.

CTelephony provides lots of information about the phone. For clarity, we've grouped the informaton as follows:

Phone, battery and subscriber information

Find out about the phone - its make, model and serial number. Also find out about the battery, locks and the flight mode status.

Line and call information

Find out about calls in progress. Limited information is available for fax and data calls, but detailed information can be read about voice calls.

Network information

Find out about the currently connected network, including its name, status and signal strength.

Supplentary services setting information

Find out about the call forwarding, call barring, call waiting and caller indentification status of the phone.

You can access this information in two ways:

1. You can get the current value, such as the current battery level, current signal strength and whether a call is currently being made. See the description of each item of information for an example.

2. You can request notification when information changes. For instance, you can be notified when the battery level changes, when the signal strength changes and when the there is an incoming call to be answered.

Controlling a single voice call

You can use CTelephony to dial and answer voice calls. You cannot make or receive data or fax calls.

You own calls that you dial or answer: you can terminate them and put them on hold. You cannot terminate or hold calls that were dialled or answered by others. Handling One Call at a Time describes how to dial and answer a voice call.

Controlling two voice calls at once

You can dial or answer a second call while another is in progress. Only one can be active at once; this is the call that the phone's user is speaking on. The other call must be on hold. Use CTelephony to change calls between active and on hold, and to dial and answer a second call. This is described in Handling Two Calls at Once.

Find out about your calls

CTelephony can tell you information about your calls, including the current duration, the date and time it was started. You can find out the call's status (is it dialling, ringing, on-hold etc?) and capabilities (can it be put on hold?) You can find out about the remote party (who dialled your phone and what is their number?) providing your phone settings, the network and the remote party allow it. All this is described in Line and Call Information.

Voice call operations

• How to dial a call with CTelephony::DialNewCall().

• How to detect and answer a call with CTelephony::NotifyChange() and with CTelephony::AnswerIncomingCall().

• How to hold, resume and swap calls with CTelephony::Hold(), CTelephony::Resume() and CTelephony::Swap().

• How to send DTMF tones with CTelephony::SendDTMFTones().

• How to terminate calls with CTelephony::Hangup()

Many calls to CTelephony methods are asynchronous. For this, you will need to know about Active Objects. In particular, ensure that the Active Scheduler has started before using CTelephony. An active scheduler is provided for you if you are writing a GUI application. Otherwise you must start it yourself.

CTelephony is an API that everyone can use.

CTelephony is the simplest way to access Symbian OS's telephony system but it provides limited services. Some users such as phone manufacturers require Symbian OS's advanced telephony services. To prevent malicious use of the telephony system, advanced telephony services are not available to everyone.

Typically, only Symbian's licensees have access to the advanced telephony services. Everybody else, including third-party developers and Independant Software Vendors (ISVs) have to use CTelephony.