Symbianapi

S60 5th Edition C++ Developer's Library v2.1 > Symbian Developer's Library v9.4 > Symbian OS v9.
4 > Symbian OS guide >Telephony > Using the Telephony ISV API
SYMBIAN OS V9.4
Feedback
Telephony ISV API overview

Symbian OS's CTelephony class provides a simple interface to the phone's telephony system.
Services
provides two services: Firstly, you can find out information about the phone. Secondly, you can dial and answer voice calls.
CTelephony
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.
Find out about the phone

provides lots of information about the phone. For clarity, we've grouped the informaton as follows:
CTelephony
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 aboutvoice calls. Network information Find out about the currently connected network, including its name, status and signal strength.
You created this PDF from an application that is not licensed to print to novaPDF printer (http://www.novapdf.com)
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.
Voice call control

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 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.
CTelephony
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()
Prerequisites
Many calls to CTelephony methods are asynchronous. For this, you will need to know about Active Objects. In particular, ensure that theActive 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.
Scope
CTelephony
is an API that everyone can use.
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.
CTelephony
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.
Copyright 2005-2008 Symbian Software Ltd.
S60 5th Edition C++ Developer's Library v2.1 > Symbian Developer's Library v9.4 > Symbian OS v9.4 > Symbian OS guide >Telephony > Using the Telephony ISV API
SYMBIAN OS V9.4
Feedback
Phone, battery and subscriber information

Here is a list of phone, battery and subscriber information items that are available through the Telephony ISV API, CTelephony:

Phone identification: manfacturer, model and serial number Subscriber identification Flight mode status Battery information: battery status and charge level
Battery charger information: is a charger connected? Lock information: which locks are available, and are they currently locked?
Get current value You can get the current value of all these items. Each item's description gives you an example of this. Some of the methods to get information are asynchronous; the operation can be cancelled before it completes. Request notification of changes For some of these items, CTelephony can notify you when the information changes. Each item's description tells you whether notification is available. If so, then this document tells you the notification event and information class that you need. How to request notification when information changes explains how to use them and provides some examples. Notification can also be cancelled.
Phone identification
Description The phone idenitifcation is returned in a packaged CTelephony::TPhoneIdV1. It contains the following member variables, each aTBuf descriptor of up to 50 characters:

Manufacturer Model Serial Number, the IMEI or ESN serial number. It identifies the phone, not the subscriber using the phone.
Get current value writes the flags to a packaged CTelephony::TPhoneIdV1.

CTelephony::GetPhoneId()
This is an asynchronous call; use CTelephony::EGetPhoneIdCancel to cancel it. For example:

#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TPhoneIdV1 iPhoneIdV1;
CTelephony::TPhoneIdV1Pckg iPhoneIdV1Pckg; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iPhoneIdV1Pckg(iPhoneIdV1) { //default constructor } void CClientApp::SomeFunction() { iTelephony->GetPhoneId(iStatus, iPhoneIdV1Pckg); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) { TBuf<CTelephony::KPhoneManufacturerIdSize> manufacturer = i PhoneIdV1.iManufacturer; TBuf<CTelephony::KPhoneModelIdSize> model = iPhoneIdV1.iMod el; TBuf<CTelephony::KPhoneSerialNumberSize> serialNumber = iPh oneIdV1.iSerialNumber; } } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::EGetPhoneIdCancel); }
Remember to link to the Etel3rdParty.lib and Request notification of changes
euser.lib
libraries.
This information is constant and therefore does not change.
Subscriber identification
Description A string of up to 15 characters containing that identifies the subscriber using the phone. This will normally identify the SIM card on GSM and WCDMA networks or the R-UIM card on CDMA networks. It is independent of the phone. Get current value
writes the value to a packaged CTelephony::TSubscriberIdV1.

CTelephony::GetSubscriberId()
This is an asynchronous call; use CTelephony::EGetSubscriberIdCancel to cancel it. For example:

#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TSubscriberIdV1 iSubscriberIdV1; CTelephony::TSubscriberIdV1Pckg iSubscriberIdV1Pckg; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp:: CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iSubscriberIdV1Pckg(iSubscriberIdV1) { //default constructor } void CClientApp::SomeFunction() { iTelephony->GetSubscriberId(iStatus, iSubscriberIdV1Pckg); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) { TBuf<CTelephony::KIMSISize> suscriberId = iSubscriberIdV1.i SubscriberId; } } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::EGetSubscriberIdCancel); }
euser.lib
libraries.
You cannot receive notification when this information changes.
Flight mode status

Description Some phones can be put into a state in which all network-related operations are disabled, including making and receiving calls. This is known as the flight mode. The flight mode status is either "on" or "off". You cannot make or receive calls when the flight mode is "on". In addition, the following information is unnavailable:

All information in Supplentary services setting information In Line and call information, all information except the Callin-progress indicator is unnavailable. In Network information, all information except the Network signal indicator is unnavailable.
Get current value writes the value to a packaged CTelephony::TFlightModeV1. The method returnsKErrNotSupported if the phone does not support the flight mode feature.
CTelephony::GetFlightMode()
This is an asynchronous call; use CTelephony::EGetFlightModeCancel to cancel it. For example:

#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TFlightModeV1 iFlightModeV1; CTelephony::TFlightModeV1Pckg iFlightModeV1Pckg; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp:: CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iFlightModeV1Pckg(iFlightModeV1) { //default constructor }
void CClientApp::SomeFunction() { iTelephony->GetFlightMode(iStatus, iFlightModeV1Pckg); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) { CTelephony::TFlightModeStatus flightMode = iFlightModeV1.iF lightModeStatus; if(flightMode == CTelephony::EFlightModeOff) {} // Flight mode is off, so all operations are allowed } } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::EGetFlightModeCancel); }
euser.lib
libraries.
Use the CTelephony::EFlightModeChange notification event, the CTelephony::TFlightModeV1Pckg information class and theCTelephony::EFlightModeChangeCancel cancellation code; see Get notification when information changes.
Battery information
Description Battery information is returned in a packaged CTelephony::TBatteryInfoV1. This contains two member variables: battery charge level A TUint containing the current charge as a percentage of the battery's full capacity. battery status A CTelephony::TBatteryStatus that represents states stuch as Battery Powered, No Battery, Battery Fault etc. Get current value writes the value to a packaged CTelephony::TBatteryInfoV1.
CTelephony::GetBatteryInfo()
This is an asynchronous call; use CTelephony::EGetBatteryInfoCancel to cancel it. For example:

#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TBatteryInfoV1 iBatteryInfoV1; CTelephony::TBatteryInfoV1Pckg iBatteryInfoV1Pckg; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iBatteryInfoV1Pckg(iBatteryInfoV1) { //default constructor } void CClientApp::SomeFunction() { iTelephony->GetBatteryInfo(iStatus, iBatteryInfoV1Pckg); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) { CTelephony::TBatteryStatus batteryStatus = iBatteryInfoV1.i Status; TUint chargeLevel = iBatteryInfoV1.iChargeLevel; } } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::EGetBatteryInfoCancel); }
euser.lib
libraries.
Use the CTelephony::EBatteryInfoChange notification event, the CTelephony::TBatteryInfoV1Pckg information class and theCTelephony::EBatteryInfoChangeCancel cancellation code; see Get notification when information changes.
Battery charger information

Description You can read a number of flags that indicate several conditions. Two of them answer the questions below: 1. Can the phone detect when a charger is connected? 2. If so, is a charger currently connected? Get current value writes the value to a packaged CTelephony::TIndicatorV1.
CTelephony::GetIndicator()
This is an asynchronous call; use CTelephony::EGetIndicatorCancel to cancel it. For example:

#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TIndicatorV1 iIndicatorV1; CTelephony::TIndicatorV1Pckg iIndicatorV1Pckg; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iIndicatorV1Pckg(iIndicatorV1) { //default constructor } void CClientApp::SomeFunction() { iTelephony->GetIndicator(iStatus, iIndicatorV1Pckg); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) { if(iIndicatorV1.iCapabilities & CTelephony::KIndChargerConn ected) { // We can detect when a charger is connected if(iIndicatorV1.iIndicator & CTelephony::KIndChargerConn ected) {} // Charger is connected
else {} // Charger is not connected } else {} // We do not know whether a charger is connected } } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::EGetIndicatorCancel); }
euser.lib
libraries.
The CTelephony::EIndicatorChange notification event indicates when any of the flags change. Use theCTelephony::TIndicatorV1Pckg information class and the CTelephony::EIndicatorChangeCancel cancellation code; see Get notification when information changes.
Lock information
Description Some phones allows users to lock them to prevent unautherised use. Typically, a code must be entered to unlock the phone. You can read the lock details as described below. This information does not concern the keypad locks, nor the lock that the networks use to prevent a phone from being on other networks. A phone can have up to two locks. When requesting lock information, you must specify which lock you are interested in. The lock information is returned in a packaged CTelephony::TIccLockInfoV1. It contains two items of information: Is this lock available? A CTelephony::TIccLockSetting that states whether this lock is available. Is the lock currently locked? If the lock is avilable, a CTelephony::TIccLockStatus states whether the lock is currently locked, unlocked or blocked. Get current value
writes lock 1 or lock 2 information into a packaged CTelephony::TIccLockInfoV1. Pass the method aCTelephony::TIccLock to choose the lock you are interested in.
CTelephony::GetLockInfo()
This is an asynchronous call; use CTelephony::EGetLockInfoCancel to cancel it. This example reads information about lock 2:
#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TIccLockInfoV1 iIccLockInfoV1; CTelephony::TIccLockInfoV1Pckg iIccLockInfoV1Pckg; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iIccLockInfoV1Pckg(iIccLockInfoV1) { //default constructor } void CClientApp::SomeFunction() { CTelephony::TIccLock lockSelect = CTelephony::ELockPin2; iTelephony>GetLockInfo(iStatus, lockSelect, iIccLockInfoV1Pckg); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) { if( iIccLockInfoV1.iSetting == CTelephony::ELockSetEnabled && iIccLockInfoV1.iStatus == CTelephony::EStat usUnlocked) { // Lock 2 is available for the phone to use // and its current statues is open, // The user can access functionality governed by this lo ck. } } } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::EGetLockInfoCancel); }
euser.lib
libraries.
Use the CTelephony::EPin1LockInfoChange or CTelephony::EPin2LockInfoChangenotifica tion event for lock 1 or 2 respectively. Use the CTelephony::TIccLockInfoV1Pckg information class. Use the CTelephony::EPin1LockInfoChangeCancel or CTelephony::EPin2LockInfoChangeCanc el cancellation codes; see Get notification when information changes.
SYMBIAN OS V9.4
Feedback
Line and call information

Here is a list of line and call information items that are available through the Telephony ISV API, CTelephony. Only a simple status is available for the data and fax lines. More detailed information is available for the voice line. Voice call control describes the Telephony ISV API's model of the voice line, which may help you understand the information available.

Call-in-progress indicator: are any calls in progress on the fax, data or voice line? Fax line status Data line status Voice line information: o Voice line status: overall status of the voice line. Use this to tell whether a voice call is in progress and to detect incoming calls o Status of voice calls you own: status of individual voice calls dialled or answered by you. Use this to detect when the remote party terminates your call o Detailed line and call information: use this to find out about any voice call currently in progress. It does not matter whether it is owned by you or not
Remote party information: use this to find out about a voice call's remote party. It does not matter whether it is owned by you or not. The remote party does not always allow this information to be available o Dynamic call capabilities: can a call be held, resumed or and swapped? This is only available for calls that you dialled or answered yourself
o
Note: With the exception of the Call-in-progress indicator, none of this information is available when the phone is in Flight Mode Get current value You can get the current value of all these items. Each item's description gives you an example of this. Some of the methods to get information are asynchronous; the operation can be cancelled before it completes. Request notification of changes For some of these items, CTelephony can notify you when the information changes. Each item's description tells you whether notification is available. If so, then this document tells you the notification event and information class that you need. How to request notification when information changes explains how to use them and provides some examples. Notification can also be cancelled.
Call-in-progress indicator
Description You can read a number of flags that indicate several conditions. Two of them answer the questions below: 1. Can CTelephony detect when a call is in progress? 2. If so, is a call currently in progress? This is true if any call is in progress: it can be a voice, data or fax call, it can be active or on-hold, and it does not matter whether the call is handled with CTelephony or not. Get current value writes the value to a packaged CTelephony::TIndicatorV1.
This is an asynchronous call; use CTelephony::EGetIndicatorCancel to cancel it.
For example:
#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TIndicatorV1 iIndicatorV1; CTelephony::TIndicatorV1Pckg iIndicatorV1Pckg; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iIndicatorV1Pckg(iIndicatorV1) { //default constructor } void CClientApp::SomeFunction() { iTelephony->GetIndicator(iStatus, iIndicatorV1Pckg); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) { if(iIndicatorV1.iCapabilities & CTelephony::KIndCallInProgr ess) { // We can detect when a call is in progress if(iIndicatorV1.iIndicator & CTelephony::KIndCallInProgr ess) {} // A call is in progress else {} // A call is not in progress } else {} // We do not know whether a call is in progress } } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::EGetIndicatorCancel); }
euser.lib
libraries.
The CTelephony::EIndicatorChange notification event indicates when any of the flags change. Use theCTelephony::TIndicatorV1Pckg information class and the CTelephony::EIndicatorChangeCancel cancellation code; see Get notification when information changes.
Fax line status

Description A simple status is avilable for the phone's fax line. The status returned in a packaged CTelephony::TCallStatusV1. It represents states such as Idle, Dialling, Ringing, Answering, OnHold etc. Note: In the past, CTelephony could be used for data calls. This functionality has been deprecated and may be removed in future version of Symbian OS. Get current value writes the information to a packaged CTelephony::TCallStatusV1. Pass the method aCTelephony::TPhoneLine set to CTelephony::EFaxLine.
CTelephony::GetLineStatus()
This is a synchronous call and cannot be cancelled. For example:

CTelephony* telephony = CTelephony::NewLC(); CTelephony::TCallStatusV1 callStatusV1; CTelephony::TCallStatusV1Pckg callStatusV1Pckg( callStatusV1 ); CTelephony::TPhoneLine line = CTelephony::EFaxLine; telephony->GetLineStatus( line, callStatusV1Pckg ); CTelephony::TCallStatus faxLineStatus = callStatusV1.iStatus; CleanupStack::PopAndDestroy( telephony );
Request notification of changes You cannot receive notification when the data line's status changes.
Data line status

Description A simple status is avilable for the phone's data line. The status returned in a packaged CTelephony::TCallStatusV1. It represents states such as Idle, Dialling, Ringing, Answering, OnHold etc.
Note: In the past, CTelephony could be used for data calls. This functionality has been deprecated and may be removed in future version of Symbian OS. Get current value writes the information to a packaged CTelephony::TCallStatusV1. Pass the method aCTelephony::TPhoneLine set to CTelephony::EDataLine.

CTelephony* telephony = CTelephony::NewLC(); CTelephony::TCallStatusV1 callStatusV1; CTelephony::TCallStatusV1Pckg callStatusV1Pckg( callStatusV1 ); CTelephony::TPhoneLine line = CTelephony::EDataLine; telephony->GetLineStatus( line, callStatusV1Pckg ); CTelephony::TCallStatus dataLineStatus = callStatusV1.iStatus; CleanupStack::PopAndDestroy( telephony );
Remember to link to the Etel3rdParty.lib library. Request notification of changes You cannot receive notification when the data line's status changes.
Voice line information
Voice line status

Description A simple status is avilable for the phone's voice line. Use this to tell whether a voice call is in progress and to detect incoming calls. The status returned in a packaged CTelephony::TCallStatusV1. It represents states such as Idle, Dialling, Ringing, Answering, OnHold:
CTelephony::EStatusIdle CTelephony::EStatusRinging
The line is idle; no calls are in progress There is an incoming call to be answered. There
may already be a second call (either active or onhold) CTelephony::EStatusConnected A call is active and the phone's user can talk. There may also be a call on hold. CTelephony::EStatusHold A call is on hold. There is no active call. Other status - dialing, answering, The phone is in the process of setting up a call or terminating a call. These states are not needed to disconnecting etc dial or answer voice calls. Get current value writes the information to a packaged CTelephony::TCallStatusV1. Pass the method aCTelephony::TPhoneLine set to CTelephony::EVoiceLine.

CTelephony* telephony = CTelephony::NewLC(); CTelephony::TCallStatusV1 callStatusV1; CTelephony::TCallStatusV1Pckg callStatusV1Pckg( callStatusV1 ); CTelephony::TPhoneLine line = CTelephony::EVoiceLine; telephony->GetLineStatus( line, callStatusV1Pckg ); CTelephony::TCallStatus voiceLineStatus = callStatusV1.iStatus; CleanupStack::PopAndDestroy( telephony );
Remember to link to the Etel3rdParty.lib library. Request notification of changes Use the CTelephony::EVoiceLineStatusChange notification event, the CTelephony::TCallStatusV1Pckg information class and the CTelephony::EVoiceLineStatusChangeCancel cancellation code; see Get notification when information changes.
Status of voice calls you own

Description A simple status is available for each call that you own. It is only available for calls the were dialled or answered by you usingCTelephony; see Voice call control. This is useful to detect when the remote paarty terminates on of your calls. Request notification when a call's status changes. If the new status is CTelephony::EStatusIdle then the remote party has terminated the call.
The status is returned in a packaged CTelephony::TCallStatusV1. Inside this, the status is a CTelephony::TCallStatus set to one of: The call is not in progress There is an incoming call to be answered CTelephony::EStatusConnected The call is connected and the phone's user can talk CTelephony::EStatusHold The call is on hold Other status - dialing, answering, The phone is in the process of setting up a call or terminating the call. These states are not needed disconnecting etc to dial or answer voice calls. Get current value
CTelephony::EStatusRinging CTelephony::EStatusIdle
writes the information to a packaged CTelephony::TCallStatusV1. Pass the method aCTelephony::TCallId.

CTelephony::GetCallStatus()
This is a synchronous call and cannot be cancelled. This example reads the status of a call. When you dialled or answered the call, you will have been given a CTelephony::TCallIdthat identifies it. Later, this can be passed to CTelephony::GetCallStatus() to read the call's status:
CTelephony::TCallStatusV1 callStatusV1; CTelephony::TCallStatusV1Pckg callStatusV1Pckg( callStatusV1 ); telephony->GetCallStatus( callId, callStatusV1Pckg ); CTelephony::TCallStatus callStatus = callStatusV1.iStatus;
Remember to link to the Etel3rdParty.lib library. This is an asynchronous call; use CTelephony::EGetNetworkRegistrationStatusCancel to cancel it. Request notification of changes Use the CTelephony::EOwnedCall1StatusChange or CTelephony::EOwnedCall2StatusChange notification event for lock 1 or 2 respectively. Use the CTelephony::TCallStatusV1Pckg information class. Use the CTelephony::EOwnedCall1StatusChangeCancel or CTelephony::EOwnedCall2StatusCh angeCancel cancellation codes. There is an example of this in Detect remote party terminating a call. See also Get notification when information changes.
Detailed call information

Description The following detailed information is available for voice calls. It is not available for the fax or data calls. You do not need to have dialled or the answered the calls yourself in order to read this information. The information is returned in a packaged CTelephony::TCallInfoV1. This contains several member variables: call status A CTelephony::TCallStatus that represents statuses such as Idle, Dialling, Ringing, Answering, On-Hold etc date and time that the call started A TDateTime current duration of the call A TTimeIntervalSeconds, measured in seconds dialled phone number A CTelephony::TTelAddress. It is only valid for outgoing calls. It includes any DTMF tones that have been sent. ciphering status A CTelephony::TPhoneNetworkSecurity that is either disabled, GSM ciphering enabled or WCDMA ciphering enabled. It is only valid on GSM & WCDMA networks. Call ID A TInt. If the call is one that you own then this is the call ID as returned by the CTelephony::DialNewCall() andCTelephony::AnswerIncomingCall() methods. Otherwise this field has a value of '-1'. Note: TCallInfoV1 contains a field called iExitCode. This field is unused at present; it is reserved for future expansion. Get current value
writes the information to a packaged CTelephony::TCallInfoV1.

CTelephony::GetCallInfo()
When you read information, you must select a call to read. You can select the currently active call, the call that's currently on hold, or a call that is in-progress - i.e. in the process of dialling/terminating/ringing etc. An active call has the CTelephony::EStatusConnected status, a call on hold has the CTelephony::EStatusHold status. An in-progress call refers to states such as ringing, dialling, disconnecting etc. The line and call status can be read as described in Voice line status and Status of voice calls you own. Pass the method a packaged CTelephony::TCallSelectionV1 to select the information for the desired call:

The iLine member must be set to CTelephony::EVoiceLine The iSelect member is a CTelephony::TCallSelect that selects the CTelephony::EActiveCall, CTelephony::EHeldCall orCTelephony::EInProg ressCall call.
is returned if your selection is not avilable. For instance, you could request information when no calls are being made, or you could request information for an on-hold call when there is no call on hold.
KErrNotFound
This is a synchronous call and cannot be cancelled. This example reads both the detailed call infornation and the remote party information for the currently active call:
CTelephony* telephony = CTelephony::NewLC(); CTelephony::TCallInfoV1 callInfoV1; CTelephony::TCallInfoV1Pckg callInfoV1Pckg( callInfoV1 ); CTelephony::TCallSelectionV1 callSelectionV1; CTelephony::TCallSelectionV1Pckg callSelectionV1Pckg( callSelectio nV1 ); CTelephony::TRemotePartyInfoV1 remotePartyInfoV1; CTelephony::TRemotePartyInfoV1Pckg remotePartyInfoV1Pckg( remotePa rtyInfoV1 ); callSelectionV1.iLine = CTelephony::EVoiceLine; callSelectionV1.iSelect = CTelephony::EActiveCall; telephony>GetCallInfo( callSelectionV1Pckg, callInfoV1Pckg, remotePartyInfo V1Pckg ); CleanupStack::PopAndDestroy( telephony );
Remember to link to the Etel3rdParty.lib library. Request notification of changes
You cannot receive notification when this item changes. You can only be notified when the voice line's status changes; see Voice line status and Status of voice calls you own above.
Remote party information

Description The remote party may make their details available to you. If so, then the following information is available for the phone's voiceline. It is not available for the fax or data lines. When the voice line is making more than one call (such as when one call is active and another is on hold) then you can read this information for individual calls. You do not need to have dialled or the answered the call yourself in order to read this information. However, the remote party may not allow you to know this information. The information is returned in a packaged CTelephony::TRemotePartyInfoV1. This contains several member variables. It is important to check the remote identity status before reading any other remote party information : remote identity status A CTelephony::TCallRemoteIdentityStatus that is either available, supressed or unknown. Available indicates that the rest of the remote party information is valid. Otherwise calling the party name, remote party's number and call direction are not valid. calling party name A descriptor of up to 80 characters describing the calling party. This field is only valid if the remote identity status field is set to available. remote party's phone number A CTelephony::TTelAddress. This field is only valid if the remote identity status field is set to available. call direction
A CTelephony::TCallDirection. The call is either mobile-originated (your phone dialled) or mobile-terminated (your phone received the call). It is only valid if the remote identity status field is set to available. Get current value writes the information to a packaged CTelephony::TRemotePartyInfoV1. Pass the method aCTelephony::TCallSelectionV1 to select the information for the desired call; see the description of TCallSelectionV1 in Detailed line and call information.
CTelephony::GetCallInfo()
This is a synchronous call and cannot be cancelled. See Detailed line and call information for an example of reading remote party information. Request notification of changes Use the CTelephony::EOwnedCall1RemotePartyInfoChange or CTelephony::EOwnedCall2Remot ePartyInfoChange notification event for call 1 or 2 respectively. Use the CTelephony::TRemotePartyInfoV1Pckg information class. Use the CTelephony::EOwnedCall1RemotePartyInfoChangeCancel or CTelephony::EOwnedCall 2RemotePartyInfoChangeCancelcancellation codes; see Get notification when information changes.
Dynamic call capabilities

Description You can read flags that tell you the following for each call that you own:

Can the call be put on hold? This implies that the call is currently active and that there is no other call on-hold. Can the call be resumed? This implies that the call is currently on hold and that there is no other active call. Can the call be swapped? You can swap a call when you have two calls in progress, one active and one on hold. Swapping will put the active call on hold and activate the on-hold call.
You should check this information before putting a call on hold, and before resuming or swapping a held call. Get current value writes the information to a packaged CTelephony::TCallCapsV1.
CTelephony::GetCallDynamicCaps()
This is a synchronous call and cannot be cancelled. This example reads the capabilities of a call. When you dialled or answered the call, you will have been given aCTelephony::TCallId that identifies it. Later, this can be passed to CTelephony::GetCallDynamicCaps() to read the call's capabilities:
CTelephony::TCallCapsV1 callCapsV1; CTelephony::TCallCapsV1Pckg callCapsV1Pckg( callCapsV1 ); telephony->GetCallDynamicCaps( callId, callCapsV1Pckg ); TUint32 caps = callCapsV1.iControlCaps; if( caps & CTelephony::KCapsHold ) {} // The call represented by 'callId' can be put on hold
Remember to link to the Etel3rdParty.lib library. Request notification of changes You cannot receive notification when this item changes.
SYMBIAN OS V9.4
Feedback
Network information
Here is a list of network information items that are available through the Telephony ISV API, CTelephony:

Network signal indicator: can a network be detected? Signal strength: as a percentage and as a number of bars to display Registration status: status of the network connection Current network information: o Information for all networks
o o
GSM/WCDMA networks CDMA networks
Note: With the exception of the Network signal indicator, none of this information is available when the phone is in Flight Mode Get current value You can get the current value of all these items. Each item's description gives you an example of this. Some of the methods to get information are asynchronous; the operation can be cancelled before it completes. Request notification of changes You can also request notification when any of these items change. Each item's description tells you the notification event and information class that you need. How to request notification when information changes explains how to use them and provides some examples. Notification can also be cancelled.
Network signal indicator

Description You can read a number of flags that indicate several conditions. Two of them answer the questions below: 1. Can the phone detect when a signal from the network is present? 2. If so, is a network signal currently present? Get current value writes the flags into a packaged CTelephony::TIndicatorV1.
This is an asynchronous call; use CTelephony::EGetIndicatorCancel to cancel it. For example:

#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TIndicatorV1 iIndicatorV1; CTelephony::TIndicatorV1Pckg iIndicatorV1Pckg;
public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iIndicatorV1Pckg(iIndicatorV1) { //default constructor } void CClientApp::SomeFunction() { iTelephony->GetIndicator(iStatus, iIndicatorV1Pckg); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) { if(iIndicatorV1.iCapabilities & CTelephony::KIndNetworkAvai lable) { // We can detect when a network is present if(iIndicatorV1.iIndicator & CTelephony::KIndNetworkAvai lable) {} // Network is present else {} // Network is no present } else {} // We do not know whether a network is present } } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::EGetIndicatorCancel); }
euser.lib
libraries.
The CTelephony::EIndicatorChange notification event indicates when any of the flags change. Use theCTelephony::TIndicatorV1Pckg information class and the CTelephony::EIndicatorChangeCancel cancellation code; see Get notification when information changes. Unfortunately, you do not know which flags have changed. The code that detects the EIndicatorChange event must store the old flags for comparison.
Signal strength
Description The signal strength information is returned in a packaged CTelephony::TSignalStrengthV1. This contains two member variables: signal strength Signal strength is measured in dBm. For example, "-51" is a signal strength of -51dBm. A value of zero indicates that the signal strength cannot be measured number of signal bars Tells the phone how many signal strength bars to display to the user. A value of '-1' indicates that the number of bars is not available Get current value writes the value into a packaged CTelephony::TSignalStrengthV1.
CTelephony::GetSignalStrength()
This is an asynchronous call; use CTelephony::EGetSignalStrengthCancel to cancel it. For example:

#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TSignalStrengthV1 iSigStrengthV1; CTelephony::TSignalStrengthV1Pckg iSigStrengthV1Pckg; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iSigStrengthV1Pckg(iSigStrengthV1) { //default constructor } void CClientApp::SomeFunction() { iTelephony->GetSignalStrength(iStatus, iSigStrengthV1Pckg); SetActive();
} void CClientApp::RunL() { if(iStatus==KErrNone) { TInt32 sigStrength = iSigStrengthV1.iSignalStrength; TInt8 bar = iSigStrengthV1.iBar; } } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::EGetSignalStrengthCancel); }
euser.lib
libraries.
Use the CTelephony::ESignalStrengthChange notification event, the CTelephony::TSignalStrengthV1Pckg information class and the CTelephony::ESignalStrengthChangeCancel cancellation code; see Get notification when information changes.
Registration status
Description The registration status indicates the service that the current network provides to the phone. It indicates statuses such as No Service, Emergency Only, Busy, Roaming etc. Get current value writes the value to a packaged CTelephony::TNetworkRegistrationV1.
CTelephony::GetNetworkRegistrationStatus()
This is an asynchronous call; use CTelephony::EGetNetworkRegistrationStatusCancel to cancel it. For example:

#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TNetworkRegistrationV1 iNetworkRegistrationV1; CTelephony::TNetworkRegistrationV1Pckg iNetworkRegistrationV1P ckg; public: CClientApp(CTelephony* aTelephony); void SomeFunction();
private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iNetworkRegistrationV1Pckg(iNetworkRegistrationV1) { //default constructor } void CClientApp::SomeFunction() { iTelephony>GetNetworkRegistrationStatus(iStatus, iNetworkRegistrationV1Pckg) ; SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) { CTelephony::TRegistrationStatus regStatus = iNetworkRegistr ationV1.iRegStatus; } } void CClientApp::DoCancel() { iTelephony>CancelAsync(CTelephony::EGetNetworkRegistrationStatusCancel); }
euser.lib
libraries.
Use the CTelephony::ENetworkRegistrationStatusChange notification event, the CTelephony::TNetworkRegistrationV1Pckginformation class and the CTelephony::ENetworkRegistrationStatusChangeCancel cancellation code; see Get notification when information changes.
Current network information

Description The following information is available for the the currently connected network:

Information for all networks GSM/WCDMA networks CDMA networks
It is returned in a packaged CTelephony::TNetworkInfoV1. Inside this there are a number of member variables. Some contain
information that is valid for all networks; some are only valid on certain networks. Use the Network signal indicator above to determine whether a network's signal is present. Get current value writes the value to a packaged CTelephony::TNetworkInfoV1.
CTelephony::GetCurrentNetworkInfo()
This is an asynchronous call; use CTelephony::EGetCurrentNetworkInfoCancel to cancel it. For example:

#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TNetworkInfoV1 iNetworkInfoV1; CTelephony::TNetworkInfoV1Pckg iNetworkInfoV1Pckg; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iNetworkInfoV1Pckg(iNetworkInfoV1) { //default constructor } void CClientApp::SomeFunction() { iTelephony>GetCurrentNetworkInfo(iStatus, iNetworkInfoV1Pckg); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) { CTelephony::TNetworkMode mode = iNetworkInfoV1.iMode; if((mode == CTelephony::ENetworkModeCdma2000) || (mode == C Telephony::ENetworkModeCdma95)) {} // CDMA network; process CDMA-specific information } } void CClientApp::DoCancel() { iTelephony>CancelAsync(CTelephony::EGetCurrentNetworkInfoCancel); }
euser.lib
libraries.
Use the CTelephony::ECurrentNetworkInfoChange notification event, the CTelephony::TNetworkInfoV1Pckg information class and the CTelephony::ECurrentNetworkInfoChangeCancel cancellation code; see Get notification when information changes.
All networks
This information concerns the currently connected network, if there is one. network mode A CTelephony::TNetworkMode describing the technology that the network uses. Values includes GSM, CDMA2000, WCDMA, Unregistered etc. mobile country code (MCC) A 3-digit code that indicates the country that the network is in. It is returned in a descriptor network identity A2 to 5 digit code that identifies the network. This is called the mobile network code (MNC) in GSM networks, and the network identity (NID) in CDMA networks. It is returned in a descriptor. For CDMA networks, you can also read the system identity (SID); see CDMA networks network display tag When the phone wishes to display the name of the network to the user, it should display the network display tag. It is a descriptor of up to 32 characters. Note: TNetworkInfoV1 contains a field called iStatus. This field does not contain useful information at present; it is reserved for future expansion.
GSM/WCDMA networks
This information is available from GSM/WCDMA networks only. It concerns the currently connected network, if there is one. Use thenetwork
mode (see Information for all networks above) to determine whether the phone is connected to a GSM or WCDMA network: network short name The network operator's name shortened to 8 characters or less. It is returned in a descriptor network long name The network operator's name that can be up to 16 characters in length. It is returned in a descriptor access technology A CTelephony::TNetworkAccess that indicates the technology type if the GSM/WCDMA network. Values include GSM, GSM Compactand UTRAN area known? A TBool flag that indicates whether the network can supply the phone with information about the area the phone is in. It is a binary value. If it is ETrue then the location area code and cell ID below are valid: location area code A TUint containing the area code that the phone is currently in. It is only valid if the area known? flag is ETrue cell ID A TUnit containing the ID of the cell that the phone is currently in. It is only valid if the area known? flag is ETrue More names for GSM/WCDMS networks In addition to the above, two other names can be read for GSM/WCDMS networks:
The network operator name stored on the SIM is returned in a descriptor of up to 16 characters by callingCTelephony::GetCurrentNetworkName(). This is an asynchronous call; use CTelephony::EGetCurrentNetworkNameCancel to cancel it.
The service provider name is returned in a descriptor of up to 16 characters by calling CTelephony::GetOperatorName().
This is an asynchronous call; use CTelephony::EGetOperatorNameCancel to cancel it.
CDMA networks
This information is available from CDMA networks only. It concerns the currently connected network, if there is one. Use the network mode (see Information for all networks above) to determine whether the phone is connected to a CDMA network: band information A CTelephony::TNetworkBandInfo containing the frequency band that the current network uses system identity The system identity (SID), a 2-5 digit code returned in a descriptor. You can also read the network identity (NID); see Information for all networks
SYMBIAN OS V9.4
Feedback
Supplementary services setting information

All of the following information is available through the Telephony ISV API, CTelephony: All networks:

Call barring status Call waiting status
GSM/WCDMA networks only:
Call forwarding status Caller Identification status: o see who is calling you (CLIP) o withhold your number (CLIR)
Note: None of this information is available when the phone is in Flight Mode Get current value You can get the current value of all these items. Each item's description gives you an example of this. Some of the methods to get information are asynchronous; the operation can be cancelled before it completes. Request notification of changes You cannot receive notification when any of these items change.
Call barring status

Description The call carring status indicates whether call barring is active, inactive or not avilable. The status can also be not provisioned on GSM/WCDMA networks. Phones have different call barring settings for different conditions. For instance, a phone might bar outgoing calls but accept incoming calls. You can get the call barring status for each of the conditions in CTelephony::TCallBarringCondition. Get current value writes the information to a packaged CTelephony::TCallBarringSupplServicesV1. Pass the method a CTelephony::TCallBarringCondition to select the conditon.
CTelephony::GetCallBarringStatus()
This is an asynchronus call; use CTelephony::EGetCallBarringStatusCancel to cancel it. This example finds out whether outgoing calls are barred:
#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony;
CTelephony::TCallBarringSupplServicesV1 iCallBarringSupplServi cesV1; CTelephony::TCallBarringSupplServicesV1Pckg iCallBarringSupplS ervicesV1Pckg; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iCallBarringSupplServicesV1Pckg(iCallBarringSupplServicesV1) { //default constructor } void CClientApp::SomeFunction() { CTelephony::TCallBarringCondition condition = CTelephony::EBar AllOutgoing; iTelephony>GetCallBarringStatus(iStatus, condition, iCallBarringSupplService sV1Pckg); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) { if( iCallBarringSupplServicesV1.iCallBarring == CTelephony: :EStatusActive ) {} // The call barring condition is active; // all outgoing calls are barred. } } void CClientApp::DoCancel() { iTelephony>CancelAsync(CTelephony::EGetCallBarringStatusCancel); }
euser.lib
libraries.
You cannot receive notification when this item changes.
Call waiting status

Description The call waiting status indicates whether call waiting is active, inactive or not avilable. The status can also be not provisioned on GSM/WCDMA networks.
Get current value writes the information to a packaged CTelephony::TCallWaitingSupplServicesV1.

CTelephony::GetCallWaitingStatus()
This is an asynchronus call; use CTelephony::EGetCallWaitingStatusCancel to cancel it. For example:

#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TCallWaitingSupplServicesV1 iCallWaitingSupplServi cesV1; CTelephony::TCallWaitingSupplServicesV1Pckg iCallWaitingSupplS ervicesV1Pckg; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iCallWaitingSupplServicesV1Pckg(iCallWaitingSupplServicesV1) { //default constructor } void CClientApp::SomeFunction() { iTelephony>GetCallWaitingStatus(iStatus, iCallWaitingSupplServicesV1Pckg); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) { CTelephony::TSupplServiceStatus callWaitingStatus = iCallWa itingSupplServicesV1.iCallWaiting; } } void CClientApp::DoCancel() { iTelephony>CancelAsync(CTelephony::EGetCallWaitingStatusCancel); }
euser.lib
libraries.
Call forwarding status

Description The call forwarding status indicates whether call forwarding is active, inactive, not provisioned or not avilable. Phones can have different call forwarding settings for different conditions. For instance, a phone might forward calls when the subscriber is busy, but not when the subscriber doesn't respond. You can get the status for each of the conditions inCTelephony::TCallForwardingCondition. Note: Call forwarding information is only available on GSM/WCDMA networks. Symbian OS does not provide this information for phones on CDMA networks. Get current value writes the information to a packagedCTelephony::TCallForwardingSupplServicesV1. Pass the method a CTelephony::TCallForwardingCondition to select the conditon.
CTelephony::GetCallForwardingStatus()
This is an asynchronus call; use CTelephony::EGetCallForwardingStatusCancel to cancel it. For example:

#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TCallForwardingSupplServicesV1 iCallForwardingSupp lServicesV1; CTelephony::TCallForwardingSupplServicesV1Pckg iCallForwarding SupplServicesV1Pckg; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iCallForwardingSupplServicesV1Pckg(iCallForwardingSupplServi cesV1)
{ //default constructor } void CClientApp::SomeFunction() { CTelephony::TCallForwardingCondition condition = CTelephony::E CallForwardingNoReply; iTelephony>GetCallForwardingStatus(iStatus, condition, iCallForwardingSupplS ervicesV1Pckg); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) { if( iCallForwardingSupplServicesV1.iCallForwarding == CTele phony::ENotActive ) {} // The call forwarding condition is inactive; // If the phone user does not answer a call then the call is _not_ forwarded } } void CClientApp::DoCancel() { iTelephony>CancelAsync(CTelephony::EGetCallForwardingStatusCancel); }
euser.lib
libraries.
Caller Identification status
See who is calling you (CLIP)

Description When CLIP (Calling Line Identification Presentation) is enabled then the phone displays the number of remote party that calls your phone. The remote party can the withold their number using a complementaty service, CLIR (see below).
CTelephony
can tell you the status of the CLIP service.
Note: This information is only available on GSM/WCDMA networks. Symbian OS does not provide this information for phones on CDMA networks. Get current value
writes the information to a packaged CTelephony::TIdentityServiceV1. Pass it aCTelephony::TIdentityService set to CTelephony::EIdServiceCallerPresentation

CTelephony::GetIdentityServiceStatus()
This is an asynchronus call; use CTelephony::EGetIdentityServiceStatusCancel to cancel it. For example:

#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TIdentityServiceV1 iTIdentityServiceV1; CTelephony::TIdentityServiceV1Pckg iTIdentityServiceV1Pckg; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iTIdentityServiceV1Pckg(iTIdentityServiceV1) { //default constructor } void CClientApp::SomeFunction() { CTelephony::TIdentityService condition = CTelephony::EIdServic eCallerPresentation; iTelephony>GetIdentityServiceStatus(iStatus, condition, iTIdentityServiceV1P ckg); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) { if( iTIdentityServiceV1.iIdentityStatus == CTelephony::EIdS erviceActivePermanent ) {} // CLIP is permanently active; // Your phone will display the callers number wheneve r this is allowed by the caller } } void CClientApp::DoCancel() { iTelephony>CancelAsync(CTelephony::EGetIdentityServiceStatusCancel); }
euser.lib
libraries.
Withold your number (CLIR)

Description When CLIR (Calling Line Identification Restriction) is enabled then the remote party cannot see your number when your phone makes a call. Otherwise, they can see your phone's number if they have a complementary service, CLIP, enabled (see above).
CTelephony
can tell you the status of the CLIR service.
Note: This information is only available on GSM/WCDMA networks. Symbian OS does not provide this information for phones on CDMA networks. Get current value writes the information to a packaged CTelephony::TIdentityServiceV1. Pass it aCTelephony::TIdentityService set to CTelephony::EIdServiceCallerRestriction.
CTelephony::GetIdentityServiceStatus()
This is an asynchronus call; use CTelephony::EGetIdentityServiceStatusCancel to cancel it. For example:

#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TIdentityServiceV1 iTIdentityServiceV1; CTelephony::TIdentityServiceV1Pckg iTIdentityServiceV1Pckg; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony), iTIdentityServiceV1Pckg(iTIdentityServiceV1) { //default constructor }
void CClientApp::SomeFunction() { CTelephony::TIdentityService condition = CTelephony::EIdServic eCallerRestriction; iTelephony>GetIdentityServiceStatus(iStatus, condition, iTIdentityServiceV1P ckg); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) { if( iTIdentityServiceV1.iIdentityStatus == CTelephony::EIdS erviceNotProvisioned ) {} // CLIR is in-active; // The phone's number is freely available to any remo te party that // has the CLIP service enabled. } } void CClientApp::DoCancel() { iTelephony>CancelAsync(CTelephony::EGetIdentityServiceStatusCancel); }
euser.lib
libraries.
SYMBIAN OS V9.4
Feedback
How to request notification when information changes

can notify you when certain information in the phone changes. Typical uses are to detect incoming calls, to detect when the phone charger is unplugged or when the battery is about to run out. There are examples of these below.
CTelephony
Find out about the phone lists many items of information. Each item's description will tell you whether CTelephony can notify you when it changes. If so, the description will specify a notification event, an information class and a cancellation code:
For example, the description of the Voice Line Status says that you can receive notification when it changes. This status indicates whether the line is being used to make a call, whether the line is ringing and and could be answered, whether there is a call on hold etc. The description says to use CTelephony::EVoiceLineStatusChange notification event, the CTelephony::TCallStatus information class and the CTelephony::EVoiceLineStatusChangeCancel cancellation code You can see all the notification events in CTelephony::TNotificationEvent. This also shows which information class is associated with each event. Request notification with CTelephony::NotifyChange(), passing it the notification event and an empty instance of the information class. This method starts an asynchronous operation that completes when the requested notification event occurs. For instance, the EVoiceLineStatusChange event occurs when the voice line status changes. At this point, the asynchronous operation completes, giving your code the oppurtunity to respond to the event. The new status will have been written into the TCallStatus object that was given to NotifyChange(), allowing your code the see the new signal stength. Rememember that the TCallStatus does not contain valid information until this point. You can cancel a request for notificaton any time before the operation finished. Do this by passing CTelephony::CancelAsync() the cancellation code.
Voice Line Status Example

Here is an active object that detects a change in voice line status. It doesn't do much when the voice line status changes; it simply stores the new status values and then starts the next asynchonous operation. This is a basic Active Object. You will need to know about active objects in order to use CTelephony's notification abilities.
/* Example CTelephony Notification ------------------------------This class uses the CTelephony API to get notification when a phone's voice line status changes. This class is an active object. You will need to have knowledge of active objects in order to understand this class. All active object are derived from CActive. This program can be easily modified to get notification when other events occur. See CTelephony::TNotificationEvent for a list of events. */
#include <e32base.h> #include <Etel3rdParty.h> class CNotifyExample : public CActive { public: // Constructor/Destructor CNotifyExample( CTelephony* aTelephony ); // Request voice line status change notification void RequestNotification(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); private: /* A reference to a CTelephony, obtained with CTelephony::NewL() or NewLC() */ CTelephony* iTelephony; /* When the voice line status changes (and hence the asynchronous operation completes) the new voice line status is written into iLineStatus. Until this point, iLineStatus is not valid. If you change this class to get notification of other events, then change this class. CTelephony::TNotificationEvent lists the classes associated with each event. */ CTelephony::TCallStatusV1 iLineStatus; CTelephony::TCallStatusV1Pckg iLineStatusPckg; }; /* Default constructor. Pass it a reference to a CTelephony, created with CTelephony::NewL() or NewLC() */ CNotifyExample::CNotifyExample( CTelephony* aTelephony ) : CActive( EPriorityStandard ), iTelephony( aTelephony ), iLineStatusPckg( iLineStatus ) { //default constructor iLineStatus.iStatus = CTelephony::EStatusUnknown; } /* This method requests notification by calling CTelephony::NotifyChange() to initialise an asynchronous operation. Then it immediately calls CActive::SetActive to start the operation. The operation completes when the notification event occurs. In this case, we tell CTelephony to wait for the CTelephony::EVoiceLineStatusChange notification event, hence the event occurs when the voice line status changes. For other events, change the notification event in the call to CTelephony::NotifyChange(). The CTelephony::TNotificationEvent description all the notification events. It also list the information class to pass to CTelephony::NotifyChange(). The TCallStatus class is associated with CTelephony::EVoiceLineStatusChange. */ void CNotifyExample::RequestNotification() { /* Panic if this object is already performing an asynchronous operation */ _LIT( KNotifyExamplePanic, "CNotifyExample" );
__ASSERT_ALWAYS( !IsActive(), User::Panic( KNotifyExamplePanic, 1 )); iTelephony->NotifyChange( iStatus, CTelephony::EVoiceLineStatusChange, iLineStatusPckg ); SetActive(); } /* The active object's RunL method is called when the asynchronous event completes. In this case, RunL is called when the voice line status changes. When this occurs, the new voice line status is written to the iLineStatus. iLineStatus was passed to CTelephony::NotifyChange() when the asynchronous operation was started. This is where you put your code to respond to your chosen notification event. In all active objects, iStatus indicates whether the asynchronous operation succeeded, failed, or is still in progress. KErrNone indicates success, and hence the value in iStatus is valid. */ void CNotifyExample::RunL() { if( iStatus==KErrNone ) { /* Insert code to respond to the change of voice line status here. A typical use to answer a call if the voice line status is 'ringing' (EStatusRinging) Remember that you must implement a RunError() method if your code in RunL can leave. */ if( iLineStatus.iStatus == CTelephony::EStatusRinging ) ; // Answer call by calling 'AnswerIncomingCall()' /* Request the next notification */ iTelephony->NotifyChange( iStatus, CTelephony::ESignalStrengthChange, iLineStatusPckg ); SetActive(); } } /* Like all active objects, you must supply a DoCancel() method to cancel the asynchronous operation. This must cancel a CTelephony notification operation with CTelephony::CancelAsync. Give the method the appropriate 'cancellation event' from those in 'TCancellationReque st' In this case, we are cancelling the "voice line status Change" event, and so we need to supply the EVoiceLineStatusChange cancellation code. If you change this class to respond to a different notification event, remember to change the call to CTelephony::CancelAsync. */ void CNotifyExample::DoCancel() { iTelephony->CancelAsync( CTelephony::EVoiceLineStatusChangeCancel ); }
Remember to link to the Etel3rdParty.lib and You use the class as follows:
euser.lib
libraries.
1. Create an instance of CTelephony:

2. CTelephony* telephonyApi = CTelephony::NewL(); CleanupStack::PushL( telephonyApi );
3. Create an instance of the class, passing it the pointer to CTelephony:

CNotifyExample *exampleObject = new CNotifyExample( telephonyApi ) ; CleanupStack::PushL( exampleObject ); 4.
5. Call the object's RequestNotification method to start the request. This calls CTelephony::NotifyChange():
exampleObject->RequestNotification();
Not that you should never request notification before the previous notification request was either completed or cancelled. In the situation above, the notification request was started just after the active object was created, so there could not be a request already in progress. If you are not sure that previous requests for that object have completed, then call the object's GOT TO HERE. CActive::Cancel method before issuing the new request:
exampleObject->Cancel(); exampleObject->RequestNotification();
This will cancel any previous requests. CNotifyExample::DoCancel will be called as part of the cancelling process.
Adapting the examples for other events

The previous examples detect changes in voice line status. You can adapt this example for other events as follows:
In the RequestNotification() method, pass CTelephony::NotifyChange() the notification event you want to detect, listed inCTelephony::TNotificationEvent. Each event has an information class associated with it, which stores the new information after it has changed. Pass NotifyChange() an instance of the information class, too:

} CNotifyExample::RequestNotification() { _LIT( KNotifyExamplePanic, "CNotifyExample" ); __ASSERT_ALWAYS( !IsActive(), User::Panic( KNotifyExamplePanic , 1 ));
iTelephony->NotifyChange( iStatus, ---Insert notification event----Insert packaged information class instance--- ); SetActive();
You will need to declare the information class instance in the CNotifyExample's declaration.

Change the code in CNotifyExample::RunL that handles the event. Change the DoCancel method to cancel the correct event. Insert the correct cancellation code from those inCTelephony::TCancellationRequest:
CNotifyExample::DoCancel()

} Copyright 2005-2008 Symbian Software Ltd.
{ iTelephony->CancelAsync(---Insert cancellation code--- );
SYMBIAN OS V9.4
Feedback
Handling one call at a time

This state diagram shows how to dial or answer one call at a time. It presumes there are no other calls being made by any other code.
The boxes are states. The 'E...' value in each box is the status of the phone's voice line. Voice line status describes these states and their meaning. You can also find the status of individual calls. However, when only one call is in progress then the line state and the call state are the same. The arrows show events that trigger a change of state. In these events, a word in bold indicates a CTelephony method that you can call. To dial or answer a call: 1. Check for other calls by getting the Voice line status. o If the line is Idle (CTelephony::EStatusIdle) then no calls are in progress
If the line is on hold (CTelephony::EStatusHold) then there is another call in progress, but it is on hold and you can still dial or answer a second call; see Handling Two Calls at once o Otherwise, another call is active: you must wait until it finishes before you can dial or receive a call. To detect when this occurs, see the example in How to get notification when information changes 2. Dialling a call
o
While no calls are in progress, the line's status is CTelephony::EStatusIdle. To dial a call, use CTelephony::DialNewCall(); seeDial a call. If dialling was successful and the remotes party answers the call then the line's status will becomeCTelephony::EStatusConnected. Answering a call While no calls are in progress, the line's status is CTelephony::EStatusIdle. When a remote party calls your phone, the voice line's status will change to CTelephony::EStatusRinging. Detect an incoming call describes how to detect this change. When the status is CTelephony::EStatusRinging, use CTelephony::AnswerIncomingCall() to answer the call. The status will change to CTelephony::EStatusConnected and the phone user can talk to the remote party. 3. What next? You now have several options. They are the same for both answered calls and calls you dial yourself:
o o o o o
Terminate the call Detect remote party terminating the call Hold and resume the call Send DTMF tones down the line Find out about the call and the call; see Detailed line and call information and Remote party information
When you successfully dial or answer a call, you will be given a CTelephony::TCallId the identifies the call. You must keep this safe it is needed to perform each of the opeations above. At some point, a remote party might try to ring your phone. The voice line state will change to CTelephony::EStatusRinging. You can ignore this call; you can still terminate, hold, resume and send DTMF.
SYMBIAN OS V9.4
Feedback
Handling two calls at once

This state diagram shows how to dial or answer one or two calls at a time. It presume that no other code is making any calls; only you are making calls.
The boxes are states. The 'E...' value in each box is the status of the phone's voice line. Voice line status describes these states and their meaning. You can also find the status of individual calls; see Status of voice calls you own The arrows show events that trigger a change of state. In these events, a word in bold indicates a CTelephony method that you can call.
To dial or answer a call: 1. Check for other calls by getting the Voice line status. o If the line is Idle (CTelephony::EStatusIdle) then no calls are in progress o If the line is on hold (CTelephony::EStatusHold) then there is another call in progress, but it is on hold and you can still dial or answer a second call. Now go to point four below o Otherwise, another call is active: you must wait until it finishes before you can dial or receive a call. To detect when this occurs, see the example in How to Get Notification when Information Changes 2. Dialling a call While no calls are in progress, the line's status is CTelephony::EStatusIdle. To dial a call, use CTelephony::DialNewCall(); seeDial a call. If dialling was successful and the remotes party answers the call then the line's status will becomeCTelephony::EStatusConnected. Answering a call While no calls are in progress, the line's status is CTelephony::EStatusIdle. When a remote party calls your phone, the voice line's status will change to CTelephony::EStatusRinging. Detect an incoming call describes how to detect this change. When the status is CTelephony::EStatusRinging, use CTelephony::AnswerIncomingCall() to answer the call. The status will change to CTelephony::EStatusConnected and the phone user can talk to the remote party. 3. What next? When you successfully dial or answer a call, you will be given a CTelephony::TCallId the identifies the call. You must keep this safe. To control your call (hang-up, hold, resume etc) you call CTelephony methods. Each method must be passed the ID of a call to operate on. Once a call is connected you have a number of options. You can perform these operations on your call. They are the same as those inHandling one call at a time:
o o o o o
Terminate the call Detect remote party terminating the call Hold and resume the call Send DTMF tones down the line Find out about the call and the call; see Detailed line and call information and Remote party information
In addition, you can dial or answer a second call: Answer a second call At some point, a remote party might try to ring your phone. It is answered in the same way as the first. The voice line state will change to CTelephony::EStatusRinging. You can receive notification when this occurs; see Detect an incoming call. Before answering the second call, you must put the original call on hold. This is shown in the diagram above. Dial a second call You can also dial a second call in the same way as the first. Once again, you must put your original call on hold before dialling the second call. 4. A CTelephony::TCallId will be given to you when you successfully connect a second call. You will also have a CTelephony::TCallIdfrom the first call. Now you will be the owner of two calls: at any one time, one will always be active and one will always be on hold. Now you can: Terminate either call. If you terminate the active call then you will be left with a call on hold. If you terminate the onholdcall then you will be left with an active call. o Detect remote party terminating either call. Once again, if the active call ends then you will be left with a call on hold and vice versa. o Swap held and active calls. o Find out about the call and the call; see Detailed line and call information and Remote party information
o
SYMBIAN OS V9.4
Feedback
How to dial a call
Dial the first call

Dial a call with CTelephony::DialNewCall(), passing it the number to dial in a CTelephony::TTelNumber. The method starts the dialling process. returns a CTelephony::TCallId that identifies the call. This will be either CTelephony::EISVCall1 orCTelephony::EISVCall2. You need this ID to perform operations such as putting the call on hold and hanging up. It tells CTelephony's methods which call to operate on.
CTelephony::DialNewCall()
To control whether you want the call's recipient to know your identity, pass CTelephony::DialNewCall() a CTelephony::TCallParamsV1. You have three options: hide your identity, show your identity, or use the phone's default setting. To read your phone's default setting, seeCaller ID - Withholding your number.
CTelephony::DialNewCall()
is asynchronous; use CTelephony::EDialNewCallCancel to cancel it.
This example dials the number 123456789 and allows the remote party to see the phone's number:
#include <e32base.h> #include <Etel3rdParty.h> _LIT(KTheNumber, "123456789"); class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TCallId iCallId; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony) { //default constructor } void CClientApp::SomeFunction() { CTelephony::TTelNumber telNumber(KTheNumber); CTelephony::TCallParamsV1 callParams; callParams.iIdRestrict = CTelephony::ESendMyId; CTelephony::TCallParamsV1Pckg callParamsPckg(callParams); iTelephony->DialNewCall(iStatus, callParamsPckg, telNumber, iCallId); SetActive(); }
void CClientApp::RunL() { if(iStatus==KErrNone) {} // The call has been dialled successfully; // iCallId contains the call's ID, needed when controlling the call. } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::EDialNewCallCancel); }
Remember to link to the Etel3rdParty.lib and
euser.lib
libraries.
You can check the voice line's status by calling CTelephony::GetLineStatus(). The call has not connected until the status isCTelephony::EStatusConnected.
Dial a second call

This describes how to dial a second call while another is in progress. 1. Put the first call on hold This is described in Hold a call. If the first call was not dialled or answered by you then you cannot control it, and so you cannot put it on hold. If it is not on hold already then you will have to wait until the it is put on hold (i.e. the Voice line status changes to CTelephony::EStatusHold). 2. Dial the second call This is the same as dialling a call in Dial a call. CTelephony::AnswerIncomingCall() will return a different call ID to the first call. Remember that dialling a call is an asynchronous operation: you do not know whether you have successfully connected until the asynchronous operation has completed. If the operation fails, remember to resume the first call; see Resume a call. As a result, the first call is on hold, and the phone user is talking to the second caller.
SYMBIAN OS V9.4
Feedback
How to detect and answer a call

Detect an incoming call
represents the voice line's status with a CTelephony::TCallStatus. Possible status values include Idle, Ringing, On-Hold etc. When the voice line's status is Ringing (CTelephony::EStatusRinging) then there is an incoming voice call to be answered.
CTelephony
Use CTelephony::NotifyChange() to detect changes in the voice line's status. NotifyChange() can be used to detect a variety of changes, but in this case you are only interested in the status of the voice line. Pass the method a notification event, in this caseCTelephony::EVoiceLineStatusChange. Also pass it an empty CTelephony::TCallStatusV1Pckg. The method starts an asynchonous operation that completes when the voice line's status changes. At this point, the line's status (aTCallStatus) is written into the TCallStatusV1. If this status is Ringing (CTelephony::EStatusRinging) then there is an incoming call. Notification is described more in How to get notification when information changes. It includes an example active object that detects incoming calls. The procedure for detecting incoming calls is the same whether there is a second call in progress or not; the line's status changes toCTelephony::EStatusRinging from whatver state it used to be.
Answer an incoming call

Answer a call with CTelephony::AnswerIncomingCall(). You can only answer a call when the voice line's status is Ringing(CTelephony::EStatusRinging); see Detect an incoming call. returns a CTelephony::TCallId that identifies the call. This will be either CTelephony::EISVCall1 orCTelephony::EISVCall2. You need this ID to perform operations such as putting the call on hold and hanging up: it tells CTelephony's
AnswerIncomingCall()
methods which call to operate on. It also tells the methods that you answered the call, and hence you are allowed to control the call.
AnswerIncomingCall()
is asynchronous; Use
CTelephony::EAnswerIncomingCallCancel
to cancel the
operation. For example:

#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TCallId iCallId; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony) { //default constructor } void CClientApp::SomeFunction() { iTelephony->AnswerIncomingCall(iStatus, iCallId); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) {} // The call has been answered successfully; // iCallId contains the call's ID, needed when controlling the call. } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::EAnswerIncomingCallCancel); }
euser.lib
libraries.
Answer a second call

This describes how to answer a second call while another is in progress. 1. Put the first call on hold
This is the same as holding a call in Hold a call. If the other call was not dialled or answered by you then you cannot control it, and so you cannot put it on hold. If it is not on hold already (i.e. the Voice line status is not CTelephony::EStatusHold) then you cannot answer the call. 2. Answer the second call This is the same as answering a call in Answer an incoming call. AnswerIncomingCall() will return a different call ID from the first call. Remember that answering a call is an asynchronous operation: you do not know whether you have successfully answered the call until the asynchronous operation has completed. If the operation fails, remember to resume the original call; see Resume a call. As a result, the first call is on-hold and the second call is active; the phone user is talking to the second caller.
SYMBIAN OS V9.4
Feedback
How to hold, resume and swap calls

Hold a call
puts a call on hold. Pass it the ID of the call to hold. The ID is the CTelephony::TCallId returned when you dialled or answered the call.
CTelephony::Hold()
Before calling CTelephony::Hold(), check that your phone supports call holding; see Dynamic call capabilities.
CTelephony::Hold()
is asynchronous; use CTelephony::EHoldCancel to cancel.
For example:
#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TCallId iCallId; public: CClientApp(CTelephony* aTelephony, CTelephony::TCallId aCallId); TInt SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony, CTelephony::TCallId aCallI d) : CActive(EPriorityStandard), iTelephony(aTelephony), iCallId(aCallId) { //default constructor } TInt CClientApp::SomeFunction() { // Check that the phone supports holding calls. CTelephony::TCallCapsV1 callCapsV1; CTelephony::TCallCapsV1Pckg callCapsV1Pckg(callCapsV1); iTelephony->GetCallDynamicCaps(iCallId, callCapsV1Pckg); if( callCapsV1.iControlCaps & CTelephony::KCapsHold ) { // The call represented by 'iCallId' can be put on hold iTelephony->Hold(iStatus, iCallId); SetActive(); return KErrNone; } else { // The call cannot be put on hold; // return an error indicate this. return KErrNotSupported; } } void CClientApp::RunL() { if(iStatus==KErrNone) {} // The call has been held successfully; } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::EHoldCancel); }
euser.lib
libraries.
Resume a call
Once a call is on hold, you can resume the call by with CTelephony::Resume(). It is very similar to CTelephony::Hold(): check that the phone supports resuming (see Dynamic call capabilities), then pass CTelephony::Resume() the ID of the call to resume.
CTelephony::Resume()
is asynchronous; use CTelephony::EResumeCancel to cancel.
Note that you can terminate a call while it is on hold; you do not have to resume it first. For example:
#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TCallId iCallId; public: CClientApp(CTelephony* aTelephony, CTelephony::TCallId aCallId); TInt SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony, CTelephony::TCallId aCallI d) : CActive(EPriorityStandard), iTelephony(aTelephony), iCallId(aCallId) { //default constructor } TInt CClientApp::SomeFunction() { // Check that the phone supports Resuming calls. CTelephony::TCallCapsV1 callCapsV1; CTelephony::TCallCapsV1Pckg callCapsV1Pckg(callCapsV1); iTelephony->GetCallDynamicCaps(iCallId, callCapsV1Pckg); if( callCapsV1.iControlCaps & CTelephony::KCapsResume ) { // The call represented by 'iCallId' can be resumed iTelephony->Resume(iStatus, iCallId); SetActive(); return KErrNone; } else { // The call cannot be resumed; // return an error indicate this. return KErrNotSupported; } } void CClientApp::RunL() { if(iStatus==KErrNone) {} // The call has been resumed successfully; } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::EResumeCancel); }
euser.lib
libraries.
Swap held and active calls

Call CTelephony::Swap() when you have an active call and a call on hold. It makes the held call active and the puts the active call on hold. Pass it the IDs of the two calls. The IDs are the CTelephony::TCallIds returned when you dialled or answered the calls. Before calling CTelephony::Swap(), check that your phone supports call swapping; see Dynamic call capabilities.
CTelephony::Swap()
is asynchronous; use CTelephony::ESwapCancel to cancel.
For example:
#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TCallId iCallIdA; CTelephony::TCallId iCallIdB; public: CClientApp(CTelephony* aTelephony, CTelephony::TCallId aCallIdA, CTel ephony::TCallId aCallIdB); TInt SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony, CTelephony::TCallId aCallI d) : CActive(EPriorityStandard), iTelephony(aTelephony), iCallIdA(aCallIdA) iCallIdB(aCallIdB) { //default constructor } TInt CClientApp::SomeFunction() { // Check that the phone supports Resuming calls. CTelephony::TCallCapsV1 callCapsV1; CTelephony::TCallCapsV1Pckg callCapsV1Pckg(callCapsV1); iTelephony->GetCallDynamicCaps(iCallId, callCapsV1Pckg); if( callCapsV1.iControlCaps & CTelephony::KCapsSwap ) { // The call represented by 'iCallId' can be swapped iTelephony->Swap(iStatus, iCallIdA, iCallIdB); SetActive(); return KErrNone; } else
{ // The call cannot be swapped; // return an error indicate this. return KErrNotSupported; } } void CClientApp::RunL() { if(iStatus==KErrNone) {} // The call has been swapped successfully; } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::ESwapCancel); }
euser.lib
libraries.
SYMBIAN OS V9.4
Feedback
How to send DTMF tones

transmits a sequence of DTMF tones across the currently active call. The sequence of tones is a TDesCstring. It can contain one or more occurance of the numbers 0 to 9, * and #.
CTelephony::SendDTMFTones() SendDTMFTones()
is asynchronous; use CTelephony::ESendDTMFTonesCancel to cancel it.

123456789
This example sends the string
#include <e32base.h> #include <Etel3rdParty.h> _LIT(KTheTones, "123456789"); class CClientApp : public CActive { private: CTelephony* iTelephony; public: CClientApp(CTelephony* aTelephony); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel();
}; CClientApp::CClientApp(CTelephony* aTelephony) : CActive(EPriorityStandard), iTelephony(aTelephony) { //default constructor } void CClientApp::SomeFunction() { iTelephony->SendDTMFTones(iStatus, KTheTones); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) {} // The tones were sent successfully; } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::ESendDTMFTonesCancel); }
euser.lib
libraries.
SYMBIAN OS V9.4
Feedback
How to terminate calls

Terminate a call
terminates a call. Pass it the ID of the call to terminate. The ID is the CTelephony::TCallId returned when you dialled or answered the call.
CTelephony::Hangup() CTelephony::Hangup()
is asynchronous; use CTelephony::EHangupCancel to cancel it.
Use CTelephony::Hangup() to terminate either call when you have two call in progress. Pass it the ID of the call you wish to terminate. To terminate them both, call the method twice with the two IDs. If you terminate an active call while another is on hold, then
The procedure for terminating incoming calls is the same whether there is a second call in progress or not. When you have two calls in progress, one will always be active while the other will always be on hold. You can terminate either:

If you terminate the on-hold call then you will be left with an active call. If you terminate the active call then you will be left with a call on hold; the on-hold call does not become active. You can make it active with CTelephony::Resume().
For example:
#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TCallId iCallId; public: CClientApp(CTelephony* aTelephony, CTelephony::TCallId aCallId); void SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony, CTelephony::TCallId aCallI d) : CActive(EPriorityStandard), iTelephony(aTelephony), iCallId(aCallId) { //default constructor } void CClientApp::SomeFunction() { iTelephony->Hangup(iStatus, iCallId); SetActive(); } void CClientApp::RunL() { if(iStatus==KErrNone) {} // The call has been terminted successfully; } void CClientApp::DoCancel() { iTelephony->CancelAsync(CTelephony::EHangupCancel); }
euser.lib
libraries.
Detect remote party terminating a call
represents the status of your calls with a CTelephony::TCallStatus. Possible status values include Idle, Ringing, On-Holdetc:
CTelephony
When a call's status changes from CTelephony::EStatusConnected to CTelephony::EStatusIdle then the call has terminated. When a call's status changes from CTelephony::EStatusHold to CTelephony::EStatusIdle then the call has terminated.
Use CTelephony::NotifyChange() to detect changes in the voice line's status. CTelephony::NotifyChange() can be used to detect a variety of changes, but in this case you are only interested in the status of your voice calls. Pass the method a notification event: pass itCTelephony::EOwnedCall1StatusChange to detect a change in call 1's status, and pass it CTelephony::EOwnedCall2StatusChange for call 2. Also pass it an empty CTelephony::TCallStatusV1Pckg. The method starts an asynchonous operation that completes when the calls's status changes. At this point, the call's new status is written into the CTelephony::TCallStatusV1Pckg. Notification is described more in How to Get Notification when Information Changes. It includes an example active object. The procedure for detecting a terminated call is the same whether there is a second call in progress or not. For example:
#include <e32base.h> #include <Etel3rdParty.h> class CClientApp : public CActive { private: CTelephony* iTelephony; CTelephony::TCallId iCallId; CTelephony::TCallStatusV1 iCallStatusV1; CTelephony::TCallStatusV1Pckg iCallStatusV1Pckg; CTelephony::TNotificationEvent iEvent; public: CClientApp(CTelephony* aTelephony, CTelephony::TCallId aCallId); TInt SomeFunction(); private: /* These are the pure virtual methods from CActive that MUST be implemented by all active objects */ void RunL(); void DoCancel(); }; CClientApp::CClientApp(CTelephony* aTelephony, CTelephony::TCallId aCallI d) : CActive(EPriorityStandard), iTelephony(aTelephony), iCallId(aCallId), iCallStatusV1Pckg(iCallStatusV1) { //default constructor
} TInt CClientApp::SomeFunction() { switch(iCallId) { case CTelephony::EISVCall1: iEvent = CTelephony::EOwnedCall1StatusChange; break; case CTelephony::EISVCall2: iEvent = CTelephony::EOwnedCall2StatusChange; break; default: // We have not been given a valid call ID, so return an error return KErrArgument; } iTelephony->NotifyChange(iStatus, iEvent, iCallStatusV1Pckg); SetActive(); return KErrNone; } void CClientApp::RunL() { if(iStatus==KErrNone) { // The status of the call has changed. if(iCallStatusV1.iStatus == CTelephony::EStatusIdle) { // The call has been terminated. } else { // The call has not yet been terminated, so request notificatio n again iTelephony->NotifyChange(iStatus, iEvent, iCallStatusV1Pckg); SetActive(); } } } void CClientApp::DoCancel() { CTelephony::TCancellationRequest cancelRequest; if(iCallId == CTelephony::EISVCall1) { cancelRequest = CTelephony::EOwnedCall1StatusChangeCancel; } else // iCallId == CTelephony::EISVCall2 { cancelRequest = CTelephony::EOwnedCall2StatusChangeCancel; } iTelephony->CancelAsync(cancelRequest); }
euser.lib
libraries.
S60 5th Edition C++ Developer's Library v2.1 > Symbian Developer's Library v9.4 > Symbian OS v9.4 > Application development tutorial
SYMBIAN OS V9.4
Feedback
The basics
This section first describes the similarities and differences between S60 and UIQ platforms. It then moves on to examine what you need to develop an application on each, and what you need to know to start work. Contents

Symbian OS and the S60 and UIQ mobile phone platforms What you will need to start development SDK contents The emulator Compilers and IDEs Symbian OS development tools
Symbian OS and the S60 and UIQ mobile phone platforms

Symbian OS has a flexible architecture which allows different mobile phone platforms to run on top of the core operating system. The two most widely of used of these are S60 (formerly known as Series 60) and UIQ, which are both discussed in this tutorial. Platforms provides a graphical user interface (GUI) framework, applications which use it, such as messaging or calendar, and can supply additional application and middleware services. The platforms are said to be open because, in addition to these built-in applications, a user may additionally install others such as games, enterprise applications, like push e-mail, or utilities. This tutorial explains the process of creating such distributable applications.
Symbian OS and the UIQ and S60 platforms S60 The Nokia S60 platform is used in the majority of Symbian OS smartphones shipped to date. S60 has been designed for easy one-handed use. It does not have a touch screen but instead has various input keys, including two soft keys, a five-way navigator pad (4 ways plus a centre selection button), the number keys and several dedicated keys such as the menu key.
The Nokia N91 is based on S60 3rd Edition. When programming for S60, since there is no touch screen, pointer events are not supported. Another consequence of having no touch screen input is that developer should consider the type of user input required. For example, in some situations it may be appropriate to replace a text entry box with a pre-filled list, from which a selection can be made. Phones built on the S60 3rd Edition Platform have high quality, high-resolution colour screens. Possible layouts include:

Double Resolution Portrait (352x416) Double Resolution Landscape (416x352) QVGA Portrait (240x320) QVGA Landscape (320x240) Low Resolution Portrait (176x208) Low Resolution Landscape (208x176)
UIQ The UIQ Platform originates from a Symbian reference design and supports both keypad and touchscreen input (through virtual keyboard, handwriting recognition or interaction with typical UI controls). It can be configured with respect to
touch/non-touch screens, screen size, the use of a menu bar or the use of soft keys.
The Sony Ericsson P990 is based on UIQ 3.0. Like S60, UIQ supports a range of screen sizes defined using a combination of four UI parameters called a UI Configuration. The parameters are: Parameter Screen layout Configuration options Portrait (240x320) Landscape (320x240) Portrait Small (240x256) Landscape Small (256x240)
Touch screen Yes or No Interaction style Menu or Soft key Orientation Normal or Inverted When writing an application for either platform, you should make its style and user experience consistent with other applications so it is not confusing for a user. Both S60 and UIQ have style guide documents which you should consult before designing your application. By adhering to the "Look and Feel" guidelines, you will give your application the best chance of success amongst users of any particular platform or smartphone. The guides are also a good way to learn about the types of controls available and the UI techniques commonly used on each platform.
What you will need to start development

You will need

a PC running Windows NT or better an SDK (S60 or UIQ) a C++ development IDE supported by your SDK. the appropriate phone handsets on which to test your application The ability to deploy code onto the phone (for example, a removable media card, for example, MMC or Memory Stick, or a connection between your development PC and the handset using USB or Bluetooth).
To install code which requires particular privileges, such as access to certain areas of the filesystem or to have high priority use of the multimedia hardware, you will also need a level of trust. The first step to attain this is to acquire an ACS Publisher ID. You can find more information about this requirement from the Application signing section of this tutorial and from Symbian Signed. Finally, you will need to have some knowledge about C++ programming and the basic principles of object-oriented design. You do not necessarily need prior information about the S60 or UIQ Platforms, or extensive experience of working with Symbian OS. If this tutorial takes you out of your depth, there is a list of books and other Symbian OS resources in the Additional resourcessection at the end of this tutorial. You can also find an extensive glossary of Symbian OS terms in the Symbian OS Library. Downloading the SDKs Before you can build any of the code that accompanies this guide, you must have installed the appropriate SDK for the platform you wish to work with. These can be downloaded as follows: For the UIQ platform - a UIQ 3.0 SDK for Symbian OS v9.1. For the S60 platform - a S60 3rd Edition SDK Each SDK provides the tools, libraries and application programming interfaces required to build C++ applications for handsets based on S60 or UIQ Switching between the UIQ and S60 SDKs Theres nothing to say that you cant install both SDKs on the same PC. If you do so, you can switch between them by typing devices at the command prompt. The
command will list the SDKs installed on your PC one of them will be marked as default. For example:
> devices S60_3rd_Beta:com.nokia.series60 UIQ3:com.symbian.UIQ - default
To switch between them, and make the S60 SDK the default working SDK, you can use the devices command with the setdefaultswitch, passing in the SDK name. That is:
> devices setdefault @S60_3rd_Beta:com.nokia.series60
Changing the default SDK using either technique sets up the build environment to point to the appropriate set of tools (so the correct commands are invoked) and identifies the root directory of the SDK (so that the correct include files and libraries are located). NOTE: The names assigned to each SDK will change for different versions as they are released. If you do plan to install both SDKs to write an application which will run on both platforms, you cant use exactly the same code and expect it to run on both. The reason for this will be explained later in this tutorial which, after introducing the process for generic application development on Symbian OS, will describe the creation of an application for both S60 and UIQ, and describe the important differences between them.
SDK contents
The key elements of an SDK are:

a Windows-based emulation of a phone. Programs are initially developed and tested on the emulator. header files and binary library files both for emulator development and for running the code on real ARM processor-based phones a GCC-based compiler for building for ARM-based targets additional tools for building and application deployment documentation (the Symbian OS Library) and examples
If you look at the directory into which you installed the SDK, you'll see a number of subdirectories and files. The following list gives a brief explanation of what each contains:
Documentation\
: On UIQ SDKs, Symbian OS and UIQ documentation.
: binaries and tools to support development, including emulator files, libraries, header files, and tools. The form of this directory is explained in detail in the following table.
epoc32\
Directory Description BUILD Intermediate build files (makefiles, object code, project browsing information). This directory is created when a project is built. data Emulator configuration files. The files stored under the z subdirectory are combined with the\epoc32\release\winscw\udeb\z directory to make up the ROM drive for the emulator. See \release\ for more information. gcc GNU GCC toolchain required for various build utilities (this is not however the compiler now used for building application code). include UIQ or S60 and Symbian OS C++ system include files. localisation Localisable files. release This is where the executables will be placed when you build your project build output files such as .exe or.dll are stored here. The directory has sub-directories for each build target. The armv5 and gccedirectories contain files for ARM targets and winscw contains build output for the emulator. Each directory will have subdirectories for debug (udeb), and release (urel) builds. For emulator build targets, under udeb and urel there will be a subdirectory called z which contains the contents of the ROM drive for the emulator. For phone build targets, the release directory is used to store the executables before they are packaged into an install file for installation onto a phone. Windows-based SDK tools such as batch files, perl scripts, Windows, DOS and Java executables. The emulated drives of the emulator (C:\ etc) are stored under here.

tools
winscw
: generic Symbian OS example code. On UIQ SDKs, UIQ specific examples are contained in examples\UIQ. S60Doc: On S60 SDKs, S60 and Symbian OS documentation. S60Ex: On S60 SDKs, S60 example programs.
examples\
Once youve installed an SDK and familiarised yourself with its contents, it is worth taking some time to review the file layout of some of the example applications provided with each SDK. Besides getting accustomed to Symbian OS code, and the tools used to create, build and test it, its a good idea to use the examples to check that your SDK is correctly installed. For example, you may find it useful to take a look at the "Hello World!" example which comes with both the UIQ and S60 SDKs and experiment by

modifying it to present a different message compiling and running the modified example on the emulator compiling the code and building an installation package to deploy it to an appropriate phone.
This tutorial will describe how to perform each of these steps, before moving on to a slightly more complex example than "Hello World!" which will examine common aspects of creating an application for S60 or UIQ and describe some of the differences.
The emulator
The emulator is a Windows application which simulates the phone hardware on the PC. This enables the development of phone software to be substantially PC-based, with only the final development stages focussed on the hardware. Use of the emulator saves time in the early stages of development, since you can use the development IDE to debug the code easily and resolve most initial bugs and design problems. For example, if a panic occurs in your code, the debugger can provide comprehensive information to diagnose the error condition that caused it. Use of the emulator also reduces the number of times you need to create an installation package, transfer it to the phone and install it, which would otherwise be time consuming in the early phases of development. The emulator provides as faithful an emulation as possible of Symbian OS running on target hardware, and has processes and scheduling that are almost identical to those on a real device. However, there are necessarily some differences, for example the memory model for a real phone is different to that of the emulator and the underlying hardware is different, so it is not possible to use the same device driver and hardware abstraction layer code on both the emulator and a real phone. For this reason, the emulator cannot be used for all development and, for low-level programming such as that for device drivers, target hardware cannot be emulated. One of the differences between a phone handset and the emulator may be observed as a slight difference in the pixel sizes of each. Text may be displayed differently on the phone to the way it appears on the emulator. Another difference is that the emulator programming environment tends to be more forgiving than that of the target hardware. For example, code which uses non-constant static variables will compile for the emulator, but will not compile for the ARM platform. Sometimes code which may run successfully on the emulator will fail on the hardware. To eliminate any issues that are caused by differences between the emulator and a real phone, all application code must be run and tested thoroughly on the phone itself as well as the emulator before it is released. You can find more detail in Deploying code on hardware. The emulator is most commonly used as part of debugging a project, in which case it is usually started by using Run or Debug from within the IDE. On either platform, it can also be started from a command prompt by entering the command:
> epoc
EPOC was an earlier name for Symbian OS, and is used in various instances, such as in this executable name. The command runs a debug build of the emulator (epoc.exe, found in the SDK directory \epoc32\release\winscw\udeb), which is what you will normally work with, as it allows you to debug your programs through the IDE. A new window should then appear showing an emulation of the phones display, plus a surround that includes some navigation and phone buttons. The S60 and UIQ SDKs each customise the display to mimic the smartphone types supported by that UI platform.
The S60 emulator. You'll find the emulator fairly straightforward to use. On both S60 and UIQ, you can use the PCs mouse or the cursor keys and the enter key to navigate, and the keyboard and number pad to enter text. On UIQ, you can also click and draw on the screen with the PC's mouse, as if it were the stylus.
The UIQ emulator. Additionally, the PC function keys are set to simulate certain hardware events (such as power on/off), and other special keyboard combinations provide options that are helpful for debugging, such as viewing and manipulating the memory heap and simulating rapid random keypresses to test application robustness. More information on the use of the debugging keys can be found in the Symbian OS Library in the Debug facilities section of the emulator guide. The filesystem of the phone is mapped to the PC, with the internal writable drive (C:) usually mapped to \epoc32\winscw\c and the ROM mapped to \epoc32\release\winscw\udeb\z for the debug build. You can also add further virtual drives, and reconfigure the standard drives to map to alternative locations. There is one exception to the filesystem mapping, which is the location of the executables. On the phone, all executables are stored in the \sys\bin directory, but on the emulator, the executables are loaded from where they are built, that is, the\epoc32\release\winscw\udeb or \epoc32\release\winscw\urel directory. For example, a program called helloworld.exe, built into the phone's ROM, will be stored in z:\sys\bin or, if it is installed onto the phone's internal drive will be located at c:\sys\bin (other drives can map to the phone's removable memory card). For the same application on the emulator, helloworld.exe will always be stored
in \epoc32\release\winscw\udeb or\epoc32\release\winscw\urel for debug or release builds respectively. A more detailed description of the typical Symbian OS file locations for both the emulator and phone can be found in a section of the File Server guide within the Symbian OS Library. Some programs, such as test programs, don't require the full GUI to start up, and instead run inside a simple text console. This is useful for automated testing, for example, to check for code regressions by running a suite of console tests after each build. The code required for a console test application is described in The filesystem browser engine class and console test code. You can also experiment with the test console by running eshell, which provides a simple text shell. Emulator know-how The UIQ SDK includes a configuration tool called UiqEnv to help set up the emulator environment for various UI styles, determine which communication ports to use and to provide connectivity through the PC. For more information on UiqEnv, refer to UIQ SDK. The S60 emulator can also be configured using the Tools menu on the emulator itself. The Preferences option allows configuration of a number of global emulator settings and network connectivity. More information is available from the S60 SDK, in the S60 Tools and Utilities Emulator Guide.
The 'Tools' menu option can be used to set a range of S60 emulator preferences. Comms setup An application running on a smartphone will have access to various communication technologies. These can be emulated by attaching suitable hardware to a comms port on the PC, and making any necessary configuration changes. Infra red To use infrared, connect an IrDA COM-port serial adapter (or "pod"). Pods supported by the Symbian OS IrDA stack include: Extended Systems, Inc. Jeteye pods 7201, 7401 and 7501, iFoundry 8001A, Actisys 220L, Actisys 220L+, Actisys 220Li. By default, the emulator looks for an infra-red device on COM port 2. Bluetooth Connect a Bluetooth module to the PC. The currently supported module is the Casira. The default port is COM1. Telephony data calls If you need genuine telephony protocols, such as SMS, you can connect a dataenabled mobile phone (as specified in the Knowledgebase entry What telephony
hardware does Symbian use for testing the IP connectivity of the OS?) to the emulator via a COM port. If you want to use TCP/IP (as if over a data call), a connected phone can be used, although most developers prefer, for convenience, and to avoid call costs, to instead set up the emulator to use the PC's own network connection. Both S60 and UIQ emulators are set up to enable this. You can use the S60 and UIQ SDKs' set up utilities to configure Bluetooth, infrared, and network settings. For S60, use Tools | Preferences from the emulator; for UIQ, use the SDK Configurator program. The emulator configuration file The emulator can be configured through an initialisation file called epoc.ini located in \epoc32\data, which is where all configuration files are stored for the emulator. For normal use, you dont to need modify epoc.ini, but you can make changes to customise it if you need to, for example, to add customised virtual drives, change the size of the heap or map hot keys on the PC keyboard to the phone keypad. If you do make changes to epoc.ini, its advisable to keep a back-up copy in case you need to revert your changes. More information about the keywords supported by epoc.ini can be found in the Emulator reference in the Symbian OS Library. Platform security configuration Platform security is discussed in more detail later in this tutorial in Platform security and platform migration. The Platform security settings for the emulator can be configured by adding statements to epoc.ini. This can be useful in the early stages of development, for example, to suspend platform security checking. The default setting for the emulator (and, of course, for all phone hardware) is that platform security is fully enabled and enforced. The flags to use in epoc.ini are described in detail in the Platform security section of the epoc.ini reference in the Symbian OS Library. The configuration options include:
PlatSecEnforcement [On | Off]
for switching off platform security policy enforcement so the system behaves as if all security checks have passed
PlatSecDisabledCaps <capability> + <capability> + ...
for switching off the checking of certain capabilities
PlatSecDiagnostics [On | Off]
for logging platform security diagnostic messages to the debug log file. Platform security messages, among others, are written to the emulators debug log file which is described in more detail in the emulator debugging section later in this tutorial.
Compilers and IDEs

This section examines the compilers and IDEs that you can use when developing applications for Symbian OS. CodeWarrior for Symbian OS CodeWarrior for Symbian OS, which comes in several packages (personal, professional and OEM editions), supports C++ development on Symbian OS. The IDE integrates compilation for both emulator (using its own compiler) and hardware builds (using one of the hardware cross compilers supported for Symbian OS), emulator debugging and, additionally, hardware debugging with the OEM package. More information is available from CodeWarrior for Symbian OS. The GCC-E target compiler To build binaries to run on phone hardware, which has an ARM processor rather than the Intel (or compatible) x86 processors used on PCs, different compilation tools are required. Such a compiler, GCC-E, is supplied free with the SDK and is taken from the free software GNU GCC. GCC-E can be used as either from the command line or invoked an IDE. You can find more information in theNative build targets section in the Symbian OS Library. The RVCT target compiler GCC-E supports the same Embedded Application Binary Interface (EABI) as the ARM Real View Compilation Tool (RVCT, version 2.2 or higher). RVCT is used by Symbian to compile Symbian OS and by S60 and UIQ licensees to develop ROM-based code. It gives the best performance and smallest code compared to other alternatives, but must be purchased separately. Like GCC-E, RVCT can be used as either from the command line or invoked from within the CodeWarrior IDE. Carbide.c++ IDE Nokia are releasing a suite of new developer tools for Symbian OS application development, called Carbide.C++, in 2006. Based upon Eclipse, the rapidly evolving Java-based open-source integrated development environment (IDE), the tools family contains three products:
Carbide.c++ Express A free IDE with basic build and debug support for SDK platforms. This product will be suitable for phone and emulator target compilation and emulator debug. Carbide.c++ Developer Edition For more advanced application developers, this will include a new graphical Rapid Application Development (RAD) tool and support compilation and debugging for both emulator and phone targets. Carbide.c++ Professional Edition This product will be available to OEM developers who create phones and require early access to next-generation Symbian technical specifications and a low level hardware debugging facility. More information about the Carbide.c++ family is available at Forum Nokia. Microsoft Visual Studio .NET 2003 IDE using Carbide.vs Carbide.vs (which was formerly known as Nokia Developer's Suite for Symbian OS) 2.0 is a set of tools to allow Symbian OS C++ application development using Microsoft Visual Studio .NET 2003. It can be used with the S60 Platform 2nd Edition and 3rd Edition, or the Series 80 Platform 2nd Edition. More information can be found at Forum Nokia.
Symbian OS development tools

The kits supply tools that allow projects to be built from the command line. This is not as easy as using the IDE to control a build, but it does allow for building from batch processes, such as automatic build and test scripts. The following table summarises the command line tools, most of which will be discussed further in the Building, debugging and deploying an application section of this tutorial. Tool
abld
bldmake
bmconv
Description Build tool used to control all aspects of building a project. It is created in the current directory by the bldmake tool from a component description filebld.inf. For a command line reference, see the abld command syntax. abldinvokes the resource compiler and bitmap converter, described below. Build tool that processes the component description file (bld.inf) in the current directory and generates the batch fileabld and several build batch makefiles (.make). For command line reference, see the Bldmake command syntax. Bitmap converter that takes one or more Windows bitmap files (.bmp) and generates a single Symbian OS multi-bitmap file (.mbm). For command line syntax, see
the Bitmap converter syntax. Context sensitive help compiler that builds .hlp help files using information defined in a project file, .rtf source file or files, and an optional customisation file. For command line reference, see the CS Help Compiler. cshlpcmp_gui is a GUI for this compiler (not used in S60). epocrc Combines the actions of passing a resource file through the C++ preprocessor, and then compiling it with rcomp. For command line reference, see Resource builder tool: epocrc. createSIS The createSIS tool creates and signs software installation packages (SIS files). It provides a wrapper around lower level installation tools such as makesis and makekeys. makeSIS Installation File Generator that creates software installation packages based on source PC/target Symbian OS file locations defined in a .pkg package file. For command line reference, see the Installation File Generator syntax. makekeys Certification Generator that creates a private/public key pair and issues certificate requests. For a command line reference, see the Certification Generator syntax. makmake Build tool that takes a .mmp project file which lists the components of the project, and produces a makefile. Uses GNU cpp to evaluate dependencies. Generated headers from resource compilation and multi-bitmap compilation, etc., should be available before makmake is run. For a command line reference, see the makmake command syntax. petran For Portable Executable Translation. The petran tool converts executables from Portable Executable format (the standard format for executable and object files) to the Symbian OS executable format. It is invoked at the final stage of the build process for ARM targets. rcomp Resource compiler that compiles source (.rss) resource files into a resource data file (default extension .rsc) which can be used by applications, and a resource header file (.rsg). The operation of the resource compiler is usually wrapped in an abld batch file. For command line reference, see the Resource compiler syntax.
cshlpcmp Copyright 2005-2008 Symbian Software Ltd.
SYMBIAN OS V9.4
Feedback
Symbian OS essentials
This section lists concepts essential to working with Symbian OS, and provides links to further information about them. Contents
Introduction Basic types and naming conventions The cleanup stack and leaves Descriptors Event handling and active objects Panics and assertions Platform security and platform migration Other topics of interest
Introduction
If you are new to C++ programming on Symbian OS, there are a few fundamental aspects to grasp before starting to develop applications on the platform, mostly related to the design of the operating system, which is purpose-built to run on portable devices. These, by their very nature, have limited memory, battery life and processing power. To manage these characteristics, Symbian OS provides, for example, lightweight string classes and an efficient event handling framework which will differ slightly from those offered by other operating systems. This section will briefly summarise some of the features that youll find used most widely in Symbian OS code. For more detail on these and other Symbian OS APIs and techniques, you are recommended to consult the Essential Idioms section of the Symbian OS Library which also contains a number of example projects to illustrate the key points. The Resources section of this tutorial provides links to other comprehensive sources of information about Symbian OS, including the Symbian Developer Network site ('DevNet') and a range of books published by Symbian Press.
Basic types and naming conventions

This section explains the most common Symbian OS naming conventions that are used in the example application. These conventions help to clarify the code; for instance, they tell you if a function can leave or if a class is allocated on the heap. SeeNaming conventions in the Symbian OS Library for more information. If you browse through the class names typically used in Symbian OS applications, you will notice that they begin with either C, M, Ror T. This letter indicates the class's characteristics, and, in particular, its cleanup requirements:
classes that are allocated on the heap and need to be explicitly deleted, begin with a C. Other properties of C classes are described in the Symbian OS Library under Class types.
classes that do not own any resources and therefore don't have a destructor use a T prefix (for type). Typedefs and enumerations also use an initial T. T objects are normally used as automatics, allocated on the stack. classes that use a handle to resources that are owned elsewhere, for instance by a server, have an R prefix (for resource). Such classes normally use a Close() function instead of a destructor to cause the resources to be cleaned up and set the handle to zero. classes beginning with the letter M (for mixin) are interface definition classes that normally consist of only pure virtual functions, and never have member data.
Most Symbian OS header files contain occurrences of TInt and TBool used instead of the C++ built-in types int and bool. These, and some others, are typedefs (hence the T suffix) for the fundamental C++ types. You should use these Symbian OS types rather than the C++ equivalent to guarantee compiler independence. The basic types are documented in the Symbian OS Library: seeBasic Types. As an aside, TBool represents a Boolean, whose value may be true (ETrue in Symbian OS) or false (EFalse). Because C++ interprets any non-zero value as true, you should test the value of a TBool using code like:
if (boolVal) { ... };
or
if (!boolVal) { ... };
rather than, respectively:

if (boolVal==ETrue) { ... };
or
if (boolVal==EFalse) { ... };
Many function names end with an upper-case L or LC. such as NewL() or NewLC(). This suffix is significant; the L indicates that the function (or any function it calls) can leave. The LC suffix denotes a function that allocates an object and then places it on the cleanup stack. It is important to follow this convention and name any functions you write that may leave, or may leave and return after putting objects on the cleanup stack, so code which calls your functions can take the necessary steps to ensure that memory leaks are prevented. Parameter names begin with a lower case a (for argument) and member data names begin with lower case i (for instance). Local variables use lower case and no prefix. Constant names begin with upper case K, but enumerated constants begin with upper caseE. Finally, you will see many occurrences of IMPORT_C and EXPORT_C. These are macros that identify functions intended to be called from outside of their own
DLL. IMPORT_C (in front of a class method declared in a header file) and EXPORT_C (in the corresponding method definition within a .cpp file) means that the method will be exported, so that it can be called from code in other DLLs. In general, therefore, with the exception of virtual and inline functions, if you see a method defined in a header file for another library whose prototype is not preceded by IMPORT_C, this means that you cannot call it, even if it has a public access specifier. It will not cause a compilation error, but you will see "unresolved external" linker errors if you attempt to use it in your code.
The cleanup stack and leaves

Instead of C++ exceptions, which were not part of the C++ standard when Symbian OS was designed, the operating system uses a lightweight exception-handling mechanism, called a leave. Leaves may occur as a result of an error condition or abnormal event, such as insufficient memory or disk space to complete a request. The leave propagates the error to a point in the calling code where it can be handled, called a TRAP harness, unwinding the call stack as it does so. However, because of the jump, any local resources, such as memory allocated on the heap, will be orphaned, potentially leading to memory or resource handle leaks. Developers working on Symbian OS use the cleanup stack to keep track of resources to which the only pointer is an automatic variable. In the event of a leave, the cleanup stack will destroy each of the resources placed upon it. Most leaves are caught by a TRAP harness provided by the UI framework, which will display an appropriate error message. However, there are occasions when you will need to use a TRAP harness yourself; you can find out more about them from the How to use TRAP page of the Symbian OS Library. There are some important places in code which should never leave namely C++ constructors and destructors. Symbian OS classes typically use two-phase construction to avoid leaves occurring in construction code; see the Two Phase Construction section of the Symbian OS Library to find out more. More information can also be found in the Symbian OS Library, under Memory Management. You should also consult a Symbian Press text book, such as Symbian OS Explained, for detailed information about, and examples of the use of, these concepts.
Descriptors
Descriptors are Symbian OS strings, and are so-called because they are self describing. Each descriptor object holds the length of the string of data it
represents as well as its 'type', which identifies the underlying memory layout of the data it holds. Because they hold length information, they do not need to be NULL-terminated and can thus be used to store binary data as well as text. Descriptors can also exist in either 8-bit ASCII or 16-bit Unicode format. There are separate descriptor classes for data stored within the descriptor (the buffer descriptors) or in a separate area of memory (the pointer descriptors) and a further distinction between those which are stack-based and those created on the heap. Furthermore, there are descriptor types which may be accessed but not modified (that is, for look-up and comparison) and those which may altered by formatting, replacing or appending to the data. The following table summarises the descriptor classes: Description Base class Stack buffer Heap buffer Pointer HBufC TPtrC Non-modifiable descriptor (16-bit by default) TDesC(16) TBufC<n> TDes(16) TBuf<n> RBuf TPtr Modifiable descriptor (16-bit by default) TDesC8 TBufC8<n> HBufC8 TPtrC8 Non-modifiable 8-bit descriptor TDes8 TBuf8<n> RBuf8 TPtr8 Modifiable descriptor 8-bit descriptor TBufC16<n> HBufC16 TPtrC16 Non-modifiable descriptor (explicitly 16-bit) TDesC16 TDes16 TBuf16<n> RBuf16 TPtr16 Modifiable descriptor (explicitly 16-bit) Although there are a number of descriptor classes, which initially makes mastering the Symbian OS strings quite daunting in comparison to, for example, a scripting language, the classes all share the same base classes, as shown in the table above. The base classes provide common APIs for modifiable and non-modifiable descriptor operations, which are agnostic of the implementation type. The filesystem browser example code which accompanies this tutorial uses a number of descriptor functions such as Format(),Append(), Zero(), SetLength() and LocateReverse(). Each SDK will also include a number of examples designed specifically to demonstrate their use. For more information about descriptors, and examples of their usage, consult the Symbian OS Library, books in the Symbian Press series or any relevant technical papers in the SDK documentation for your chosen UI platform.
Event handling and active objects

As with applications on other operating systems, Symbian OS applications need to make both asynchronous function calls and receive asynchronous event notifications. For UI events, most of the work is done for by the Symbian OS UI framework, but other sources of asynchronicity (such as incoming data on a communications socket, interaction with hardware or use of a timer) are not wrapped by the application framework. To handle these, you typically create a
class which submits a request to an asynchronous service provider and waits for its completion, supplying a function which is called when the event is received. Symbian OS supplies a base class, CActive, to be used as the base for such classes; objects of such classes are known as active objects. The wait loop in which they run is known as the active scheduler. Consult the High Level Asynchronous Service Handlingsection of the Symbian OS Library for more information about Symbian OS event handling using active objects and the active scheduler. Further information and example can also be found in Symbian Press books and technical papers.
Panics and assertions

Symbian OS uses panics to halt the flow of program execution. Unlike a leave, which can be trapped, if a panic occurs in an application running on the phone, the application will be terminated. This does not make for a good user experience, and, for this reason, panics should only be used in assertion statements, to halt code when an unrecoverable error occurs. Typically, assertions are used in debug builds to verify code logic and program state, and are very useful when running code on the emulator because the panic enters the debugger and allows you to investigate the root cause using just-in-time debugging. The simplest assertion statement is ASSERT, which raises a "USER 0" panic in debug builds only. __ASSERT_DEBUG and__ASSERT_ALWAYS allow you to specify what action to take if the condition fails, for debug only and for all builds respectively. Although the macros allow you to specify the action when the assertion condition fails, the typical, and best, response is to panic and thus terminate the application. You can find out more about the use of the assertion macros from the Symbian OS Library; the Symbian OS system panic categories and numbers are documented in the System panic reference.
Platform security and platform migration

Symbian OS v9.1 is said to be a secure platform because of changes to the operating system to extend its security model and ensure more protection against malicious or badly-implemented software. The security model operates at the software level to detect and prevent unauthorised access (to hardware, software or data) which may, for example, lock up the phone, compromise user data, or affect other software or the network. The secure platform prevents programs from
acting in unacceptable ways, irrespective of whether these actions are intentional or unintentional. The impact of platform security on application development is described in this tutorial where it is most relevant to the discussion. For example, data caging, capabilities, Secure IDs and Vendor IDs are described in the mmp file syntax section. Data caging is also covered in the pkg file format section and is illustrated by the filesystem browser application. Configuring the platform security settings of the emulator is described in The emulator. Certification and Symbian Signed are discussed in theApplication signing section. Further information is also available in the Symbian OS Library, under Platform security and from a forthcoming Symbian Pressbook devoted entirely to this subject. This tutorial is based on S60 3rd Edition and UIQ 3.0. It does not cover the migration of application code written for earlier versions of either platform. You should consult the appropriate SDK for a guide to changes in the new UIQ or S60 releases and information about how to update code written for previous versions to run on the new platform.
Other topics of interest

The previous sections have briefly introduced a few of the basic idioms used when developing C++ code on Symbian OS. There are many other aspects of the operating system that are important to know about if your application needs to use them, such as the communications programming, the filesystem, client-server design, ECOM, threading and, for all applications, good coding techniques. To find out more, the first place to start is the Symbian OS Library. In addition, the Resources section of this tutorial provides links to other comprehensive sources of information about Symbian OS.
SYMBIAN OS V9.4
Feedback
This item is not part of the S60 5th Edition SDK
Building, debugging and deploying an application

This section discusses the details of creating an application, from defining the project files needed for an application, building it from within the IDE and from the command line, debugging it on the emulator and, finally, deploying it onto hardware. Contents

Getting started: Symbian OS projects Symbian OS project files Building code Debugging on the emulator Deploying code on hardware pkg file format Application signing
Getting started: Symbian OS projects

A project defines the source files and settings required to build an executable. You can create new projects using the wizards in the CodeWarrior or Carbide.c++ IDEs. If you want to build from the command line, you write project files in a text editor. Creating a new project using Carbide.c++ Carbide.c++ supplies a new project wizard to create a skeleton application. To use it, choose File > New > Symbian OS C++ Project. The New Project wizard then starts, and you are asked for the project's name. Next, you need to choose a project template, which provides an initial set of source files and project settings. The templates offered provide starting points for various different platforms and versions. For a GUI application, choose either the S60 3.0 GUI Application or UIQ 3.0 GUI Application from the Symbian Executable Project group. The next step is to choose which kit to build with: you can build with multiple kits if your program should work with multiple platforms or operating system versions. The wizard then asks for some project settings. The most important of these is the Application UID setting. This is a unique number that identifies the application. You should get UIDs from the Symbian Signed web site. Creating a new project using CodeWarrior
The Symbian Project Wizard can be used to create the skeleton of a new Symbian OS application. The Wizard can be invoked from within CodeWarrior by selecting File|New. Give the new project a name and choose a location. By default, CodeWarrior will create a subfolder with the same name as the project and put the project there. Click OK, and select the vendor and SDK to use (Symbian UIQ or Nokia S60). Then click Next to be given a choice of application templates to use. You can use the Wizard to create either a simple console application or a basic GUI application for either UIQ or S60 platforms (the differences between console and GUI applications are described later in The filesystem browser engine class and console test code). You can build, debug and run the applications created by the Wizard. Project directory layout Before you write a line of code, it will help to understand the directory structure under which your source and project files should be stored. If you look at the example code accompanying your SDK, or use project wizards from an IDE to create a UI application, youll see examples of the typical layout used to organise a project. A good directory layout is invaluable for keeping track of your code as the project grows. Its usual to separate the project files, which will be described shortly, from the source code, which is itself split further into header files, such as .h and .hrh, and implementation files, such as .cpp. Resources, such as .bmp or .wav files used by the application, usually go into yet another separate directory. Test code should also be stored apart from production code. Thus, a typical UI application would have the following directory structure and files.
data
(S60) - resource specification files (.rss)
gfx
(S60) - application resources such as bitmaps or audio files - project files (e.g. .mmp and
bld.inf
group
images
(UIQ) - application resources such as bitmaps
inc
- header files (typically .h, .hrh and .inl) (UIQ) - resource specification files (.rss, .ra)
rsrc
src
- short for 'source', contains the implementation code in .cpp files - test code
test
There are two key files involved in creating any new Symbian OS project, both are stored in the group directory:
Symbian OS project files

If you want your programs to be buildable from the command line, you must write project files in a Symbian specific format. The files are:
a project definition file (.mmp file) that describes a project to be built. This is an environment neutral file that can be used by the tools to produce make files for any of the supported target environments. It also defines resource files to be built. a component description file (bld.inf), which lists a group of related projects, and gives additional build instructions.
Both CodeWarrior and Carbide.c++ can import project definition files to create projects in the IDE. More details of these file formats are given below.
The component description file: bld.inf

is a text file. Its contents are normally trivial since its main purpose is to list the project definition mmp files and any files that the build tools must copy into place before a build. The list of mmp files is contained in a section named PRJ_MMPFILES. Abld.inf file is required even if the project only contains a single mmp file. Here is the contents of a typical bld.inf, for the filesystem browser application which accompanies this tutorial. You can find more information about each of the sections used in the Build Tools Reference:
Bld.inf // Platforms built if no platform is specified in abld build PRJ_PLATFORMS WINSCW GCCE // Files exported from the project PRJ_EXPORTS // None // Project definition files PRJ_MMPFILES filebrowseapp.mmp // Project definition files for test code PRJ_TESTMMPFILES ..\test\FileBrowseTest.mmp
In the example above, for a command line build, the component is built by default for WINSCW and GCC-E, as specified using thePRJ_PLATFORMS statement. When you build code for the emulator using CodeWarrior, you use the WINSCW platform, sonamed because the resultant code runs on WINdows, in a Single process, and was built with CodeWarrior. The platform name is used when building code from the command line, and to identify the platform for which executable code is intended. Thus, as described in the SDK Contents section, when the code is built the
resultant executables are created under \epoc32\release\winscw (in the\udeb or \urel subdirectories, according to whether it is a debug or release build). The platform name for code built for phone hardware using GCC-E is GCCE and executables are built to \epoc32\release\gcce\. The platform name for RVCT builds is ARMV5 and, likewise, executables for that platform are built to \epoc32\release\armv5\.
Project definition file (mmp) file syntax

Each statement in a mmp file starts with a keyword. This section describes the syntax of these keywords by using the contents of the mmp file for the S60 filesystem browser application as an example. You can find more information about mmp file syntax in themmp file syntax reference.
// filebrowseapp.mmp // // Copyright (c) 2006 Symbian Software Ltd. // TARGET TARGETTYPE UID VENDORID filebrowseapp.exe exe 0x100039CE 0xE80000A6 0
All rights reserved.
#ifdef __WINSCW__ CAPABILITY AllFiles // AllFiles on emulator since no signing i s required #else CAPABILITY NONE // No capabilities on hardware otherwise SIS file signing is required #endif SOURCEPATH SOURCE SOURCE SOURCE SOURCE SOURCE SYSTEMINCLUDE USERINCLUDE ..\src FileBrowseAppUi.cpp FileBrowseDocument.cpp FileBrowseApplication.cpp FileBrowseBaseView.cpp RFsEngine.cpp \epoc32\include ..\inc
SOURCEPATH START RESOURCE TARGETPATH HEADER END START RESOURCE TARGETPATH END START RESOURCE TARGETPATH LANG HEADER END START BITMAP TARGETPATH HEADER SOURCEPATH SOURCE SOURCE SOURCE
..\data filebrowseapp.rss \resource\apps
filebrowseapp_reg.rss \private\10003A3F\apps
filebrowseapp_loc.rss \resource\apps SC
filebrowseapp.mbm \resource\apps ..\gfx C16 folder.bmp C16 file.bmp 8 mask.bmp
END LIBRARY euser.lib efsrv.lib cone.lib eikcore.lib eikcoctl.lib eikdl g.lib egul.lib eikctl.lib apparc.lib LIBRARY bafl.lib avkon.lib CommonEngine.lib
LIBRARY TARGET
This keyword specifies the name of the output file that will be built.
TARGETTYPE
This indicates the type of file generated by the project, in this case an executable. The most common target types are dll, exeand plugin.
UID
The UID keyword specifies two of the target's three Unique Identifiers (UIDs) which identify the component. The target will have three UIDs but the first value (known as UID1) does not need to be specified because it is automatically applied by the build tools. It is a general identifier which is assigned according to the TARGETTYPE specified. Thus, the first UID specified here, is actually UID2, which further identifies the component type and can be thought of as an interface identifier. The value (0x100039CE) identifies the file as an application; the same value is used for all Symbian OS applications. The next UID specified should be unique to the application. It is also specified in the application registration resource file (which is described in the Resources section) and the applications installation package file (which is described in the pkg file formatsection). No two executables may have the same UID3 value, and, to ensure uniqueness, you must request UID values from Symbian which allocates UID values from a central database. The Symbian Signed web site has more information on how to acquire UIDs for your project. There is also a range of test values, such as the value for UID3 used in the filesystem browser application (0xE80000A6), which can be used to get started but must not be used in your final product.
SECUREID
This is an optional keyword and is not used in the example above. The keyword is used to define the Secure Identifier (SID) for an executable which is used to determine which private directory a process can access and identify it as a caller, for example, when making client-server requests. The SID can be specified by a SECUREID statement in the project's mmp file. If this statement is not specified, as in the example given, the UID3 of the application is used instead. If that value is not set,KNullUID (=0) is used.
VENDORID
This keyword is new in Symbian OS v9.1. Each executable may contain a vendor ID (VID) which identifies its origin, specified by the VENDORID keyword. A vendor ID is not mandatory and, in many cases, will be omitted from the mmp file, or included and set to zero, which means that the source of the executable is not required for security checks. VIDs are allocated to Symbian licensees, partners, operators and Independent Software Vendors through sign-up programs, for instance Symbian Signed. If an application needs a VID its installation package must be signed as described in the Application signing section. Unsigned applications have no vendor ID since without a signature it cannot be verified.
CAPABILITY
This keyword is new in Symbian OS 9.1. A capability is a unit of protection, or privilege and, in Symbian OS 9.1, some Symbian OS APIs now have a capability associated with them. The capability is used to restrict use of the API to callers with at least that same level of privilege. The capabilities that an executable is assigned are listed following the capability keyword. If the CAPABILITY keyword is not present in the .mmp file, the default of CAPABILITY NONE is used. In the example above, the application is assigned different capabilities in emulator builds (AllFiles) to hardware builds (NONE). This is unusual, but has been done to illustrate the Platform Security concept called "data caging". On the emulator, the filesystem browser code is assigned AllFiles capabilities, and can view more private areas of the filesystem than when it runs on a phone handset with no capabilities. It is instructive to run the application on both the emulator and a phone for comparison. For a process running without AllFiles capability, nothing in the \sys\ directory is visible, and the only directory under\private\ that can be seen is \private\<SID>\ where <SID> is the sub-directory named with the Secure Identifier of that process. For the same process running with AllFiles capability, the contents of the \sys\ directory is visible, as are all the subdirectories under \private\. The AllFiles capability is one of a group of tightly controlled capabilities called system capabilities, which can only be granted to an executable after certification. Certificates and Symbian Signed are described later in the Application signing section of this tutorial.
SOURCEPATH
, SOURCE
The SOURCEPATH keyword specifies the location of the source or resource files listed subsequently using the SOURCE declaration. It can either be used as a location relative to the directory that holds the mmp file or as a fully qualified path. The
keyword can be used to multiple times to specify different directories if necessary. Alternatively, it can be omitted entirely if all source files are located in the same place as the mmp file, although this is usually not the case for more complex projects, which typically organise their directories as described earlier in the Project directory layout section.
SYSTEMINCLUDE
The SYSTEMINCLUDE keyword specifies the location in which files included in the code using #include <> can be found. The\epoc32\include directory is where the Symbian OS system headers are stored, and a line identical to this should appear in allmmp files.
USERINCLUDE
This keyword specifies the directory in which files included in code using #include "" will be located, relative to the directory which holds the mmp file or as a fully qualified path. Directories specified with USERINCLUDE are only one of three locations that may be searched of header files; the other directories being that in which the source file which uses the include statement is stored and the SYSTEMINCLUDE directory.
START RESOURCEEND
Used to specify a resource file, which contains text and specifications of user interface elements. These keywords replace the RESOURCE statement used in mmp files prior to Symbian OS v9.1. The START RESOURCE keyword indicates the beginning of a block which provides information about how an application resource file is to be compiled. At least one of these is needed if the application has a UI. The resource file itself should be the same location as the mmp file itself or in the directory specified by the last preceding SOURCEPATH declaration. The end of the information block is indicated by the END keyword and an application may have several resource files, each of which is specified separately using the START RESOURCEEND block. In the example shown here, the second block specifies a registration resource file for the application. This contains non-localisable information to display the application correctly in the application launcher, and includes the application's name, UID and properties. All UI applications must provide a registration file, as described in the Resources section, which should be built to\private\10003a3f\apps using the TARGETPATH keyword, described below.
TARGETPATH
is used to specify the build location for a compiled resource. In this example, the location of the first compiled resource file is specified
TARGETPATH
as \resource\apps, which is a public, read-only directory and is the standard location for resource files. The registration file is built to \private\10003a3f\apps. Note: The location to which the C++ code buildt used to be specified using the TARGETPATH keyword in versions of Symbian OS prior to 9.0. However, for reasons of security, in this and future releases of Symbian OS, all executable code must run from the phone's \sys\bin\ directory, which is inaccessible to all but the trusted computing base that forms the heart of Symbian OS. (For the emulator, this is equivalent to the PC's \epoc32\release\winscw\build variant\ directory). The TARGETPATH keyword is, therefore, only used to build resource files to their appropriate locations. There is no longer any need to specify a target path for the executable in the mmp file and it will be ignored except when used within a START RESOURCEEND block.
HEADER
This is an optional keyword which, when used, causes a resource header file (.rsg) to be created in the system include directory,\epoc32\include\. The header provides identifiers that allow C++ code to refer to specific resources.
LIBRARY
This keyword lists the import libraries needed by the application. The build will report link errors (unresolved externals) if you don't specify all the required libraries. The class-level documentation in the Developer Library tells you which library to import for each class. No path needs to be specified and each library statement may contain several libraries, separated by a space. More than one library statement may also be used.
STATICLIBRARY
is used to specify statically linked libraries (object code that is built into your application).
STATICLIBRARY
All UIQ applications should link against a UIQ-specific heap allocator library, which is designed to be more effective in out of memory situations. This is done as follows in a mmp file:
STATICLIBRARY qikalloc.lib LIBRARY qikallocdll.lib START BITMAPEND
This section contains the bitmaps for application icons and specifies how to compile bitmap (.bmp) files into a Symbian OS format multi-bitmap (.mbm) file. Different sizes of source bitmap should be supplied for different view sizes. In UIQ, the most appropriate icon size for the UI's current zoom state is selected to avoid the need for the icon to be dynamically scaled when it is drawn at a different size. Note that the S60 platform also allows icons to be specified in Scalable Vector Graphics - Tiny (SVG-T) format, and has additional tools (mifconv) to support this.
For each image, an image bitmap and a mask bitmap are needed. The mask should be black for the parts of the image that should be visible, and white for the transparent areas. For more information about these see Application icons and captions.
EPOCSTACKSIZE
This is an optional keyword and is not used in the example above. In previous versions of Symbian OS, the default stack size was 0x5000 bytes. In v9.1, the default value is 0x2000. To increase the stack size, you can use the EPOCSTACKSIZE keyword, for example, to increase the stack size of 0x5000:
EPOCSTACKSIZE 0x5000
Note, the stack size setting only applies when building for the phone and is not supported for WINSCW emulator builds. The stack size is not limited on the emulator since the stack will expand as needed to the much larger limit set by the Windows platform. This may cause programs that overuse the stack to work on the emulator, but fail on hardware with a stack overflow panic (KERN-EXEC 3). It is one of the differences between phone hardware and the emulator which make hardware testing essential. See "Why test on hardware?" for more details.
EPOCHEAPSIZE
This is an optional keyword and is not used in the example above. Use the EPOCHEAPSIZE statement to specify the minimum and maximum sizes of the initial heap for a process. The default sizes are 4KB minimum and 1MB maximum. The minimum size specifies the RAM that is initially mapped for the heap's use. The process can then obtain more heap memory on demand until the maximum value is reached, incremented in steps of 4KB or 1 page. This directive is applicable from Symbian OS v9.1, EKA2 releases. EKA2 supports multiple process creation and allows the heap size to be calibrated between the minimum and maximum limits. Using EPOCHEAPSIZE allows applications built on the emulator to be tested more precisely, thus emulating the behaviour on the actual device more closely.
Building code
This section briefly describes how to build a program using an IDE or the command line.
Building code using Carbide.c++

If you want to build the FileBrowse example project that accompanies this tutorial using Carbide.c++, you must first import it into the IDE:

Choose the File | Import... command, and from the list of the available import wizards, select Symbian MMP File. Browse to the project file to import. For the UIQ version of the example, selectFileBrowse\uiq\FileBrowse\group\fileBrowseapp.mmp; for S60, selectFileBrowse\s60\FileBrowse\group\fileBrowseapp.mmp. The dialog will show the available kits that can be used to build the project. Select the appropriate S60 or UIQ kit to use.
To build the project, select the Project | Build Project menu item or right-click the project name in the C/C++ Projects view and select Build Project. During the build, the build progress can be shown in a dialog or in the task bar at the bottom right of the window. Messages from the build tools are shown in the Console view, while errors and warnings appear in the Problems view. Note that the Problems view may show a number of warnings such as "the following label is used but has not been declared" and "the STRUCT that this resource is based on contains a STRUCT[] data member which has not been used in this resource": these can be ignored. After building, you can run the application. To do this:
Start the emulator by right-clicking the project name in the C/C++ Projects view, and selecting the Run As | Run Symbian OS Application menu command. The emulator will then start: note that this can take some time.
Run the application from the emulator. To do this on S60, open the FB example icon from the Installat. folder. On UIQ, open the File Browser example icon on the main Applications screen.
Building code using CodeWarrior

If you want to build the FileBrowse example project that accompanies this tutorial using CodeWarrior, you must first import it into the IDE:

Choose the Import Project From mmp File option (from the File menu). CodeWarrior uses the devices setting described earlier in this tutorial, in What you will need to start development, to determine which Symbian OS SDKs have been installed to your PC, and their location.
Select Symbian and UIQ_30 from the list to use a UIQ 3 SDK, or Nokia and S60 to use the S60 SDK.
Browse to the project file to import. For the UIQ version of the example, selectFileBrowse\uiq\FileBrowse\group\fileBrowseapp.mmp; for S60, selectFileBrowse\s60\FileBrowse\group\fileBrowseapp.mmp. CodeWarrior then creates a project in the same location as the mmp file with the same name, filebrowseapp, but with a.mcp extension, and opens it in the IDE. It also creates some other files, including a subdirectory which contains intermediate files that are used in the build.
To build the project, go to the Targets tab, right click on the appropriate target (for example, WINSCW UDEB for a debug emulator build) and select Make. There are various possible target instruction sets, each of which can have a debug (called UDEB) and release (UREL) build variant. Selecting Build All will build all of them a spinning square icon shows you which one is currently being built. After building, you can run the application. To do this:
Start the emulator using the Project
| Run
menu command.
The emulator will then start: note that this can take some time.
Run the application from the emulator. To do this on S60, open the FB example icon from the Installat. folder. On UIQ, open the File Browser example icon on the main Applications screen.
Building code using the command line

You can build for any target from the command line once you have a component definition file (bld.inf) and project definition file (mmp file). Firstly, run bldmake from the project directory (usually \group) where the bld.inf file is located:
> bldmake bldfiles
This creates a batch file, called abld.bat, which you use in the next step. To build the project, you call abld build which will build the project for all default targets in both release and debug variants. To build for a particular target and variant, use abld build target-name variant, for example:
> abld build winscw udeb
builds the project for the debug variant of WINSCW only.
Inputs to the bldmake and abld.bat commands, and the resulting outputs. Some of the other commands supported by abld are as follows:
clean
Removes everything built with abld target Removes files moved into position by abld export export Exports files listed in bld.inf to their specified destinations help Displays commands, options or help about a particular command makefile Creates makefiles or IDE workspaces reallyclean As clean, but also removes exported files and makefiles resource Creates resources files, bitmaps and aif files
cleanexport
There are also various additional switches, for example, to build with a verbose flag (-v) or to keep a build going for other unrelated targets if it fails on others (k). You can find more information about the bldmake command and the supported abld syntax from the Build Tools Guide and Build Tools Reference in the SDK.
Debugging code on the emulator
Both CodeWarrior and Carbide.c++ allow you to interactively debug programs running in the emulator. Both IDEs allow you to use standard debugging techniques such as setting breakpoints in the source code, stepping through code, and examining memory and variables. To use these techniques, you must run the debug build of your project. To do this with Carbide.c++, right-click the project name in the C/C++ Projects view and select the Debug As | Debug Symbian OS Application menu command. To do the same thing using CodeWarrior, select the Project | Debug menu command. The emulator will then start, and you can run the application. For S60, the icon is called FB example and is in the Installat. folder. For UIQ, the File Browse example icon is on main applications screen. Another technique for debugging using the emulator is to add RDebug::Print() statements to your code (you'll need to include thee32debug.h header file to use RDebug). This function is used to print formatted text to a log file called epocwind.out, which is created in the Windows Temp directory as described in more detail in Debug output (system message log) from the emulator. You can use % followed by a format character in the arguments to RDebug::Print() to print out variables. For example the following code will write "Error value: -10" to the log file:
TInt error=-10; _LIT(KMsgDebug,"Error value: %d"); RDebug::Print(KMsgDebug,error);
Format string syntax is documented in the developer library. Message logging in the CodeWarrior IDE, including DLL loading and unloading, and RDebug::Print() messages, is enabled by ticking the Log System Messages checkbox (select WINSCW UDEB Settings then the Debugger Settings panel). If you are running a GUI application on the debug emulator, there are some key combinations which can be useful when debugging. For instance ctrl+alt+shift+p invokes a dialog that lets you simulate memory allocation failure. This is useful to test that your code handles leaves correctly. Other emulator debug keys are documented in the Symbian OS Library under Debug facilities.
Deploying code on hardware

Developing a Symbian OS application is typically a two stage process. First, you build, test and debug the application on the PC using the emulator to eliminate bugs which manifest on the emulator. Then you rebuild the code to run on the phone using a different toolchain, and install the application onto a phone and test
it. The following section describes why it is necessary to re-test on hardware, and how to do so. Why test on hardware? You cannot assume that, because your code runs perfectly on the emulator, your development is complete. Code must always be tested on hardware before releasing it. Although it provides as faithful an emulation of Symbian OS on hardware as possible, these are just some of the differences:
unlike the emulator, the ARM processor requires all 32-bit quantities to be aligned on 32-bit boundaries, or an access violation will result on the emulator, the stack grows as required. On target hardware, it is limited to 8kb by default per process. If the stack overflows this limit, a panic occurs. This can sometimes be avoided by using heap-based objects instead of stack-based ones. Additionally, the stack size can be increased by using the epocstacksize keyword in the mmp file. the Windows emulator runs as a single process with each Symbian OS process running within it as a separate thread. These threads share writable memory and have no process boundary to give them memory protection, unlike the same processes running on phone hardware. On the emulator it is possible, though highly undesirable, to access another emulated process's address space. On target hardware, attempting to do this will cause an access violation.
You can find more information about these and other differences in the Emulator/native platform differences section of the Symbian OS Library. Installing software onto a phone There are various ways to transfer an application to a phone:

by connecting the phone to a PC using the appropriate connectivity hardware and software (PC Connect, Bluetooth or IR) sending the application by Bluetooth, IR or SMS from another phone sending the application to the phone by email downloading it onto the phone over the internet (OTI) over the air (OTA) distribution if the handset supports removable media cards, you can use a card reader to copy the installation file from the PC and install the application onto the phone from the card. The application can still be installed to the phones internal memory and does not necessarily need to be installed to the card itself.
Installation Files
Regardless of how the application is delivered to the phone, it can only be installed using a .sis installation file ("sis" stands forSymbian OS Installation System). These files are also sometimes described as sisx files because the installation file format has been changed and extended in Symbian 9.1 from the original sis file format of previous versions of Symbian OS. The Symbian OS software installer uses this installation file to control which files are installed onto the phone and restrict installation of those which require privileged access to system services and data to those it can verify as trusted. A PC-based tool called CreateSIS, located in the epoc32\tools\ directory, is used to create an installation sis file. CreateSIS is a wrapper around three separate tools which may alternatively be used separately:

MakeSIS, which creates a .sis file from a text-based SignSIS, the installation file signer MakeKeys, the certificate generator
.pkg
file
The following diagram illustrates the use of these tools:
Creation of a signed sis file from executable files compiled for phone hardware. This installation package is generated using PC-based tools CreateSIS, MakeSIS, MakeKeys, and SignSIS with instructions detailed in a human-readable package file. Additional documentation for these tools can be found in the Installation Guide of the Symbian OS Library. CreateSIS takes as input a package file (.pkg extension), which you create to specify which application files (executable files and resources) need to be installed onto the phone. The package file has a list of where the files are located on the PC,
that is, the locations to which they were built as part of the ARMV5 or GCCE builds, and the location to which they must be installed. Optionally, CreateSIS also takes a developer certificate and private key as input, to output a signed sis file. As a developer, you can get these from the Symbian Signed program for testing. If you do not supply a key/certificate pair, CreateSIS will create them for you. In this case, the output sis file is known as self signed. Applications installed via self signed sis files are restricted in the privileges (that is, the Platform Security capabilities) they can possess. The section on Application signing discusses this in more detail.
pkg
file format
The format of package files is documented in the Symbian OS Library in the Package file format section, but here's an example of a package file for the FileBrowse application for UIQ, and a brief summary. Note that the lines preceded by semi-colons are comments (blank lines are also ignored).
; filebrowseapp_gcce.pkg ; ; Specify the languages - as previously supported ; Languages ; none - English only by default ; List of localised vendor names one per language. At least one must be provided (English [EN]). ; List must correspond to list of languages specified elsewhere in the .pkg %{"Symbian"} ; The non-localised, globally unique vendor name (mandatory) :"Symbian" ; Package header ; Name, Package UID, Major, Minor, Build, Package-type #{"FileBrowse example"}, (0xE80000A6), 1, 0, 0, TYPE=SA ; ProductID for UIQ 3.0 ; Product/platform version UID, Major, Minor, Build, Product ID (0x101F6300), 3, 0, 0, {"UIQ30ProductID"} ; Files to install for my directory application ; If you have changed the default UIQ SDK installation path than you also n eed to change these paths. "\Symbian\UIQ3SDK\epoc32\release\gcce\urel\filebrowseapp.exe""!:\sys\bin\filebrowseapp.exe" "\Symbian\UIQ3SDK\epoc32\data\Z\Resource\Apps\filebrowseapp.rsc""!:\Resource\Apps\filebrowseapp.rsc" "\Symbian\UIQ3SDK\epoc32\data\Z\Resource\Apps\filebrowseapp_loc.rsc""!:\Resource\Apps\filebrowseapp_loc.rsc" "\Symbian\UIQ3SDK\epoc32\data\Z\Resource\Apps\filebrowseapp.mbm""!:\Resource\Apps\filebrowseapp.mbm" "\Symbian\UIQ3SDK\epoc32\data\z\Private\10003a3f\Apps\filebrowseapp_reg.rsc""!:\private\10003a3f\import\apps\filebrowseapp_reg.rsc"
Languages Symbian OS applications can be localised by defining all the localisable text and images in language-specific resource and icon files. At install time, depending on the language selected by the user, only a single version of each set of language-
specific files will be installed. A package file can specify the available language options with a line starting with a '&', followed by the supported language variants using two character codes. For example,
&EN,FR
would indicate that English and French options are available. If you omit this line, the user is presented with a default language of English (UK). For more details, see How to create an installation file for a multilingual application page of the Symbian OS Library. Localised and non-localised vendor names The sections preceded by '%' and ':' are the localised and non-localised vendor names respectively. Package header The line beginning with '#' is the package header. This line must always be specified. It provides the name of the application (localised with one name for each language supported), as it will be displayed in the installation dialogs, the package UID, version information and package type. The package UID is used to identify packages when they are installed, upgraded or removed. You can get a new UID from Symbian Signed, or you can use the same value as the UID3 of an executable installed by the package. The package type indicates the type of installation, since different types have different rules on how files may be installed or uninstalled. The example above uses TYPE=SISAPP, which can also be specified using the abbreviation SA, or omitted entirely, since it is the default option if no type is specified. This type identifies the component to be installed as an application. Other types include a patch type and a partial upgrade type, as described in the package-header section of the Symbian OS Library. Hardware Dependency The line beginning with a hexadecimal UID in brackets is mandatory and is used to ensure that only applications that are compatible with the phone hardware in question are installed onto it. The syntax of this statement is described in more detail in the dependency page of the Symbian OS Library. The important parts of this line for the example above are the hexadecimal UID (0x101F6300) and the string in quotes (UIQ30ProductID). The string which ends with ProductID must be specified as well as the UID. This is used for reporting rather than matching purposes. For more information, see the phone or UI platform manufacturer's technical documentation.
This combination specifies that the program can be installed on any phone that uses the UIQ v3.0 platform. The equivalent for a phone which runs on the S60 3.x platform is:
[0x101F7961], 0, 0, 0, {"S60ProductID"}
For UIQ installation, the numbers between the UID and the string specify the required phone or UI version number, or the upper and lower bounds for a range of versions (if separated by ~). These numbers must be specified, but in practice, the target hardware version may be inherent in the product UID, as in this example. For S60, the version field is unused and must always be 0,0,0. Files to install The rest of the package file lists the files to install (the filenames preceding the hyphens are files on the PC), and their respective destinations on the phone. Specifying an exclamation mark in place of a drive letter in the target filename is recommended because it means that the user will be given a choice of drive on which to install the application. From v9.3 onwards, an alternative is to use the $ sign in place of a hard-coded drive letter, as this denotes the system drive. Symbian OS v9.1 is a secure platform, which imposes various restrictions on file locations. This is known as data caging and the rules for the file installation locations are as follows:
executable code, such as filebrowseapp.exe, is installed to \sys\bin\ (on whichever drive is selected by the user). This location is inaccessible to all but the most trusted Symbian OS code (possessing TCB or AllFiles capabilities), so the integrity of the code is guaranteed. Tamper-protection is in place for this directory if code is installed to removable media. UI resource files such as filebrowseapp.rsc and any icon bitmap files (.mbm extension) are installed to \resource\apps\. This location is public, but read-only for all but trusted system processes. registration files (such as filebrowseapp_reg.rsc in the example above) are installed to\private\10003a3f\import\apps\. private data files used only by the application itself can be installed to the application's private directory, \private\<SID>(where SID is the secure ID, in this case, UID3 of the FileBrowse application). Only highly trusted code (with TCB orAllFiles capability) or code compiled with this secure ID can read or write to this directory.
Locations not listed above are public and writable by any program.
Application signing
Application signing is a way of adding a tamper-proof "digital signature" to an application to guarantee that it has not been maliciously altered and that its originator can be traced. A signature issued by a signing authority is used to ensure that an installation file has not been tampered with, that it is from a trusted source, and, where it is signed by Symbian Signed, that it has passed an approved set of test criteria. On S60 phones, all sis files must be signed before they can be used to install applications to the phone. On UIQ phones, it is not mandatory but smartphone users will be encouraged only to download and install applications which have been signed, so it is advantageous to do so. No signing is required to run applications on either the S60 or UIQ emulators. A sis file may either be self signed, signed using a developer certificate (during application development) or submitted toSymbian Signed, which is the signing and verification program which authenticates the originator of an application, tests the application against a set of industry-agreed criteria and, when it has been proved to be acceptable, signs it. Self-signing Around 60% of the APIs that are in Symbian OS dont have any capabilities associated with them and are freely accessible to all applications - just as with earlier releases of Symbian OS. There is also a set of APIs which require capabilities that are broadly understandable by the user. These capabilities are:

(access to local personal area network for example, using Bluetooth) UserEnvironment (access to confidential information in users environment) NetworkServices (access to remote communication e.g. Voice, data, but not Internet Access Point set-up) Location (access to the location of the phone) ReadUserData (read access to data that is confidential to the phone user) WriteUserData (write access to data that is confidential to the phone user).
LocalServices
The user may authorise programs which need these user-understandable capabilities, although it is at the discretion of the phone manufacturer to determine which of the previous capabilities are included in the basic set. This policy may vary between phone manufacturers, individual phone model and also between locales, depending on the market requirements. You should check the phone manufacturer's SDK for further details.
When an application requires no capabilities, or only uses capabilities from the basic unrestricted set, it can be self-signed both for testing and shipping. This is recommended as suitable for freeware applications which use unrestricted capabilities. A self-signed sis file is said to be untrusted and the user will be warned of this at install time. The user also would typically provide authorisation of the appropriate capabilities by accepting a prompt at install time. If the user refuses to provide this authorisation the application install will be terminated. Signing with a developer certificate APIs associated with more sensitive capabilities are described as system or extended capabilities. These system capabilities would be difficult for a user to understand, so it is inappropriate to give users the ability to grant them at install time, since the risks of doing so would be unclear to them. Applications requiring these capabilities will need to be signed as trusted to receive them. However, before submitting an application for signing as trustworthy, the developer needs to test it on a target phone as well as on the emulator. For applications that need system capabilities to be tested on hardware before they are submitted to a signing programme, 'developer mode' certificates will be issued. These certificates are subject to various constraints:

they are valid for only six months they may be limited to certain device IDs (IMEIs) they may be valid to grant only a limited set of capabilities they may be valid only for software with a particular vendor ID or secure ID.
For more information on how to acquire developer certificates, see the Symbian Signed website. When applying for a developer certificate, the system capabilities that an application requires will need to be considered. The system capabilities are subdivided into three sets
a basic set (PowerManagement, ProtServ, ReadUserData, SurroundingsDD, SWEvent) for which a developer certificate is granted, subject to registration. The developer certificate can also be used to sign applications which require the user capabilities (ReadUserData , WriteUserData, NetworkServices, LocalServices, UserEnvironment an d Location) which means that the user will not be asked to grant them at installation or run time. those system capabilities which are sensitive and require registration to include a valid ACS Publisher ID to guarantee an additional level of trust beyond that required to register for a standard developer certificate (ReadDeviceData,WriteDeviceData, TrustedUI)
a highly sensitive set which require approval from the manufacturer of the phone on which you intend to deploy the application (AllFiles, CommDD, DiskAdmin, DRM, MultimediaDD, NetworkControl, TCB). You will need to go through a review process with the manufacturer due to the sensitive nature of these capabilities.
If an application requires capabilities that are not authorised by the user, or requests more capabilities than the certificate it is signed with can grant, the application will not install on the phone. How do I know which capabilities my application will need? Each system API is documented in the Symbian OS Library with the capabilities it needs. If you are linking to third party binaries, you can use the petran tool, which ships with all SDKs as standard, to get information about the capabilities of DLLs and EXEs. For example, the following will dump information for utility.dll:
petran dump s utility.dll
If you run a debug build of your application on the emulator with the Platform Security diagnostic output and enforcement flags enabled in epoc.ini as described in the Emulator section of this tutorial, you can also inspect the epocwind.out debug output to confirm that there are no Platform Security errors or warnings generated. If you application has insufficient capabilities, those capabilities which are needed will be logged when your application tries to use the APIs which require the missing capabilities.
SYMBIAN OS V9.4
Feedback
The filesystem browser application

This section introduces the generic Symbian OS UI framework using a simple example application. It describes the fundamental classes that form the application framework and compares the differences between an implementation of the filesystem browser application for S60 (3rd Edition) and for UIQ (3.0).
This section also discusses common strategies used to maximise code re-use when writing a GUI application to run on both UI platforms. Contents

The filesystem browser application Introducing the application framework Can I write one application that runs on both S60 and UIQ platforms? The filesystem browser UI classes Resources filebrowseapp.rss resource file filebrowseapp.rss file for UIQ filebrowseapp.rss file for S60 CFileBrowseBaseView implementation Application icons and captions The filesystem browser engine class and console test code
The filesystem browser application

Now this tutorial has described what you need to start work on an application for S60 or UIQ, it will walk through a simple filesystem browser application ("FileBrowse") and explain some of the aspects of application development on these platforms. The example is a simple illustration of the fundamental application framework classes, working with application resource files, how to use a list box control and how to handle user input. When the file browser application starts, it displays the 'C' and 'D' drives of the phone or emulator in a list box, giving the user to option to browse through the directories of either drive.
The start up view for the S60 filesystem browser application. The user sees folders and files, which are distinguished by different icons, and may open directories to view their contents, but may not open files, receiving an information message if they try to do so. On UIQ, the user navigates by tapping on a directory to open it, or uses the up and down keys and the confirmation key to open the directory selected. On S60, the user navigates using the joystick and may either open a selected directory by pressing the confirmation key of the joystick, or the 'Open' option from the left soft key menu. When a new folder is opened, the application scans its content and the content in the list box is updated to reflect it.
The directory browse view for the UIQ filesystem browser application.
A view of files and directories in the UIQ filesystem browser application.
The user navigates back up the directory hierarchy on UIQ or S60 by selecting the top 'go back' directory. In addition, on S60, the user may use the right soft key, to go back to the parent directory.
The directory browse view for the S60 filesystem browser application.
A view of files and directories in the S60 filesystem browser application.
Introducing the application framework

The classes described in this section provide the basic functionality of an application and provide the interface needed for the platform framework to drive the application. A quick summary of each of the classes follows; they will be described in more detail as the implementation of the filesystem browser application is discussed. The core Symbian OS UI framework is called Uikon. One of the most important libraries within it is eikcore.dll, which contains the UI framework classes such as CEikApplication, CEikAppUI and CEikonEnv. UIQ and S60 extend the the framework by adding libraries to provide platformspecific controls. The UIQ-specific library is calledQikon and the S60-specific library is called Avkon. You can view these as UI layers on top of the core Symbian OS UI. Each contains different components, appropriate to the platform in question, although, because they both have Uikon as a base, their APIs are often very similar.
When creating a UI application for either platform, you will derive from base classes supplied by the platform-specific libraries (which themselves usually derive from classes in the Symbian OS framework), and call framework functions specific to the platform. To do this, you will need to include the appropriate header files and link against libraries accordingly. For example, for UIQ, you will link against qikctrl.lib, while for S60 the equivalent is avkon.lib. Likewise for header files; the header files to include for each of the application framework classes are shown in the table below. Every Symbian OS GUI application, regardless of the UI platform on which it is based, will use the application framework architecture, which means it will derive from a particular set of UI-specific classes: application, document, application UI and application view. Application An object of this class is the first to be created by the GUI framework when the application starts. When instantiated, the object is used to identify the application, by returning its UID. It also creates the applications document class. Application document The document class handles any persistent non-GUI data for the application and instantiates the application UI class. Application UI The application UI handles UI events generated from the users actions (except low-level touch screen events and alphanumeric keyboard input). It also instantiates the applications default view. Application view This is the root GUI control which activates the main application window and acts as a container for other controls used. The following table shows the generic Symbian OS application framework classes, with the S60 and UIQ equivalents: Class Generic Uikon class S60 (Avkon) S60 header file
aknapp.h
UIQ (Qikon)
UIQ header file

qikapplication .h
Applicatio CEikApplication (whi CAknApplicati on n ch derives from CApaApplication ) Document CEikDocument (which CAknDocument derives
CQikApplication
akndoc.h
CQikDocument
qikdocument.h
fromCApaDocument) Applicatio n UI View

CEikAppUi CAknAppUi aknappui. CQikAppUi h coecntrl. CQikViewBase h CCoeControl qikappui.h
CCoeControl
CCoeControl
from ew)
qikviewbase.h (derives and MCoeVi
Note that the 'CEik' prefix of the generic Symbian OS classes is replaced with 'CQik' for UIQ classes and 'CAkn' for S60 classes. This convention is used throughout the UI application framework, for classes, headers and libraries. Additionally, in general, if a class does not have any prefix, such as CCoeControl, it is part of the generic Symbian OS set. Note: If you're wondering why the classes are prefixed with 'CEik' rather than 'CUik', the reason is historical. The original Symbian OS UI framework was called Eikon, in the days when Symbian OS itself was known as 'EPOC'. The framework was renamed Uikon in a later release of Symbian OS, but the class names themselves were not changed.
Can I write one application that runs on both S60 and UIQ platforms?
No. As the previous section described, although each of the platforms are based on the generic Symbian OS Uikon framework, S60 and UIQ each extend it differently. When you write an application for UIQ, you must use the UIQ specific classes to achieve the correct look and feel for the application. The resulting code will be different from that of an S60 application, which would use a set of classes, specific to S60. To appreciate the extent of the differences, compare the source code for the S60 filesystem browser which accompanies this tutorial with that for the UIQ version. Splitting into an application engine and application UI You can reduce the amount of work required to write an application to run on both S60 and UIQ platforms by separating the code into two parts:

platform-specific code for the application's user interface (which will be different for each platform) generic code, which is commonly known as an application engine, which runs on both platforms.
The idea is to facilitate the code's portability simply by minimising the amount of code that will need to be ported. Typically, the application engine will need little or no modification while the application UI will need re-designing and re-coding.
Splitting the code into an engine and UI also means that development can proceed in parallel, with separate specialist developers working on the engine and UI sections. Not only can the engine code often be re-used without many changes; it can also be tested automatically on each platform by using generic console test code without UI components as described later in The filesystem browser engine class and console test code. The split can be very distinct, with the engine forming a separate component, typically a dll, or it can be more simple, such as putting the implementation of the engine code in a separate source file, which can be shared by every version of the application. The filesystem browser example uses the second approach, because it has a single, very simple engine class, CRFsEngine, to illustrate the technique of splitting an application into a UI and an engine. The engine class is described later in The filesystem browser engine class. The following diagrams show the class hierarchies for the filesystem browser application for both S60 and UIQ implementations.
Class diagram for the filesystem browser on UIQ.
Class diagram for the filesystem browser on S60.
The filesystem browser UI classes

This section will examine each of the application framework classes in more detail and relate them to the implementation of the filesystem browser application on both S60 and UIQ platforms. The application class Every Symbian OS application must implement the following functions which are called by the framework as it starts the application. The first one is a non-leaving function which creates a new instance of the application class. For the filesystem browser example application used in this tutorial, the code is as follows:
EXPORT_C CApaApplication* NewApplication() { return new CFileBrowseApplication; }
This factory function is expected by the framework to have exactly this prototype. It constructs and returns an instance of the application class, or NULL if it cannot be instantiated. The second function is the applications entry point function, called E32Main(), which looks like this:
GLDEF_C TInt E32Main() { return EikStart::RunApplication(NewApplication); }
calls EikStart::RunApplication(), passing as an argument a pointer to the factory function which creates an instance of the application class.
E32Main()
The application class represents the properties that are the same for every instance of the application. This includes the information specified in the registration file, for instance the caption and the capabilities, and other information, for instance the UID. At a minimum, it must also implement two functions:

, which returns the applications UID , which is a factory function for creating an object of the document class. Note that, although the application creates the document, the framework is responsible for destroying it.
AppDllUid() CreateDocumentL()
The application class in both S60 and UIQ versions of the filesystem browser is called CFileBrowseApplication and its implementation is identical in each. For AppDllUid():
TUid CFileBrowseApplication::AppDllUid() const { return KUidFileBrowseID; // Defined in filebrowseglobals.h }
This function is called by the framework to get the applications UID, just after calling NewApplication(). One of the reasons it needs the UID is to check whether there is a running instance of the application that it can switch to. The value returned must be the same as the value of the UID3 value specified in the mmp file. Once the UID has been verified, the framework calls theCreateDocumentL() method, which is implemented for the filesystem browser as follows:
CApaDocument* CFileBrowseApplication::CreateDocumentL() { return CFileBrowseDocument::NewL(*this); }
The document class As described above, the document class is constructed and returned by the applications CreateDocumentL() function, which is called internally by the application framework. It represents the data that relates to a particular instance of the application, and typically owns the application's engine.
In the filesystem browser example, the document class does not store any data but could be extended, for example, to store the current directory opened by the user. If the application is closed and then restarted later, this stored value can be used to open the directory previously viewed, rather than default to view the root directories of the C and D drives on startup. To implement persistent application data, the document class should store and restore the necessary information by overriding theStoreL() and RestoreL() methods, both of which are empty by default. Where an engine provides functions to save and restore its data, the document would call these. Even if the application does not have savable data, an application must still instantiate the document class, which should implement the CreateAppUiL() function, inherited from the documents base class, CEikDocument. This function instantiates an object of the application UI class. For both S60 and UIQ implementations of the filesystem browser, the code is the same:
CEikAppUi* CFileBrowseDocument::CreateAppUiL() { return new(ELeave) CFileBrowseAppUi; }
This function is called by the framework. Note that CreateAppUiL() only carries out first phase construction. In other words, it does not call the app UI's ConstructL() the framework is responsible for calling this. The framework will also take ownership of the app UI object, so the destructor of the document class does not need to destroy it. The application UI class The application UI class is constructed and returned by the documents CreateAppUiL() function, described above. Its second phase construction method, ConstructL() is an important method. It is called by the framework and should include a call to the base class second phase constructor (either CQikAppUi::ConstructL() for UIQ or CAknAppUi::ConstructL() for S60 each of which ultimately calls CEikAppUi::BaseConstructL()). Among other things, the base class constructor method will read the applications resource file and create the visible GUI elements. The ConstructL() method should also construct the application view. For S60, the implementation is as follows:
void CFileBrowseAppUi::ConstructL() { CAknAppUi::ConstructL(); iBaseView = CFileBrowseBaseView::NewL(ClientRect()); iBaseView->SetMopParent(this); AddToStackL(iBaseView); }
For UIQ it differs slightly:

void CFileBrowseAppUi::ConstructL() { BaseConstructL();
CFileBrowseBaseView* baseView = CFileBrowseBaseView::NewLC(*this); AddViewL(*baseView); CleanupStack::Pop(baseView); }
In the UIQ implementation, AddViewL() registers the view with the system and adds it implicitly to the control stack, which enables the view to receive key and pointer input. The first view that is added becomes the default view for the application. In the S60 implementation of ConstructL(), this is done by calling AddToStackL() explicitly (the view is removed from the control stack in the application UI class destructor). The control stack has a prioritised list of controls that should be offered key events to process, and ensures that the events are offered to those controls in priority order. In addition to controls from GUI applications, the stack also contains controls associated with any front-end processors or active dialogs and handles debug key combinations. The S60 implementation also calls SetMopParent() to set itself as the parent of the view control object. The ownership of the view is transferred to the app UI, and it is later unregistered and deleted automatically in the app UI's destructor. It is interesting to note that, in S60, the derived application UI class takes ownership of the view object and is responsible for deleting it, while in the UIQ implementation, the base class takes this responsibility and the destructor for the application UI class does nothing at all. The destructor for the S60 application UI class is as follows:
CFileBrowseAppUi::~CFileBrowseAppUi() { if (iBaseView) {// Remove it from the control stack RemoveFromStack(iBaseView); delete iBaseView; } }
In S60, the application UI class also handles command events, which may originate from a range of sources such as menu bars, or the soft keys. This is done by implementing the HandleCommandL() function:
void CFileBrowseAppUi::HandleCommandL(TInt aCommand) { ASSERT(iBaseView); switch (aCommand) { case ECmdFileBrowseExit: // Generated by the left soft key 'Exit' option case EEikCmdExit: // Generated by a system command to close the application Exit(); break; case ECmdFileBrowseOpen: iBaseView->CmdOpenL(); break; case EAknSoftkeyBack: iBaseView->CmdBackL(); break; default: // All other commands are passed to the base class CAknAppUi::HandleCommandL(aCommand); break; } }
Here a command is an instruction, identified by an integer value known as a command ID. Command IDs are enumerated constants defined in header files that are traditionally given the extension .hrh. In the code shown above, the commandsECmdFileBrowseOpen and ECmdFileBrowseExit are defined by the filesystem browser example code (in filebrowse.hrh) while the other commands (EEikCmdExit, EAknSoftkeyBack and all other commands handled) are defined by the system. In the S60 implementation, the UI framework calls HandleCommandL() when either of the menu options available from the left soft key are selected which defers to the application view to handle the Open command and calls Exit() to handle 'Exit'.
The menu invoked by a left soft key press in the S60 filesystem browser application. The right soft key generates an EAknSoftkeyBack command (because it has been set up to do so in the resource file for the application, as described in the section on Filebrowse resource file for S60). The back command is also passed to the view class to handle. All other commands are passed to the CAknAppUi base class. In UIQ, commands are usually handled by application views, which are discussed in the next section.
The application view In a simple case, such as the filesystem browser which accompanies this tutorial, there is a single view class which derives from the Uikon base class, CCoeControl. In more complex examples, it is common for an application to use more than one view, in which case the application UI class is responsible for creating and destroying the views, registering them with the view server, adding them to the control stack, activating them, passing events to the correct view for handling and setting a default view. For both the S60 and UIQ implementations of the filesystem browser, the CFileBrowseBaseView view class is responsible for the following:

construction and control initialisation updating data in the list box handling list box control events instantiation and ownership of the engine class, CRFsEngine. (Typically, in more complex multiple-view examples, the document or application UI class will create and own the engine object).
The view class is where most of the divergence between code for the S60 and UIQ platforms can be observed. For this reason, the view class for each will be discussed separately. The UIQ application view In UIQ, views are the primary means of displaying data, and handling commands and other user input events. Views can be configured and their initial commands and controls set in resource files using a number of resource structures, includingQIK_VIEW_CONFIGURATION, QIK_VIEW, and QIK_VIEW_PAGE. Each view has a class, derived from the framework classCQikViewBase, which handles construction and activation of the view, command handling, and use of the view's controls. A view object is constructed in several stages to minimise the startup time of the application. The first stage constructs as little as possible. The static factory function, NewL(), follows the standard Symbian OS two phase construction rules. The function instantiates the object, which calls CQikViewBases constructor, and then calls the second phase ConstructL() method, which calls CQikViewBase::BaseConstructL() to register the view with the view server to allow navigation between applications. The next stage of construction occurs in the ViewConstructL() method which is called the first time the view needs to be activated. For applications which use multiple views, the ViewConstructL() method is valuable because it reduces application start up time by only initialising views which are used immediately the application starts. It also avoids wasting memory, particularly if some views are not be used at all. will fully construct the view by reading the views configuration resource structure and initialising its controls, in the case of the filesystem browser, the list box. CFileBrowseBaseView::ViewConstructL() also constructs the engine object, used to scan the filesystem, by calling CRFsEngine::NewL().
ViewConstructL()
The last stage is the initialisation of the view by ViewActivatedL(), which is called each time the view becomes visible. This method can be used to re-populate the view with user data, if necessary. For the filesystem browser, ViewActivatedL() callsShowRootL() which displays the C and D drives of the phone. In UIQ, all views are uniquely identified by a view ID (a TVwsViewId object), consisting of the UID of the application and an ID that uniquely identifies the view within the application. The view ID is returned by CQikViewBase::ViewId(), a pure virtual method which is called for each view by CQikAppUi::AddViewL(). All view classes must implement this method. In UIQ, a command can be located on a softkey, in a toolbar or in a menu, depending on the interaction style of the phone. To allow for this flexibility, commands are defined in a more abstract way, rather than being explicitly coded as particular GUI elements such as menu items. This is usually done in a resource file using the QIK_COMMAND_LIST structure. Commands are associated with views, and so are handled within view classes. This is done by reimplementing theHandleCommandL(CQikCommand& aCommand) method defined by CQikViewBase. This looks something like this:
/** Handles all commands in the view. Called by the UI framework when a command has been issued. The command Ids are defined in an .hrh file. */ void CHelloWorldView::HandleCommandL(CQikCommand& aCommand) { switch(aCommand.Id()) { // Here you can take care of your view specific commands. /** case EFooCmd: { DoSomethingL();; break; } */ // Go back and exit command will be passed to the CQikViewBase to handle. default: CQikViewBase::HandleCommandL(aCommand); break; } }
Note that, in UIQ, applications do not provide an exit command. When you start an application, it remains running and persistent; you do not close it but simply switch away from them to use other applications. It is useful though to provide an exit command indebug builds only, to test that the application exits cleanly without leaking memory. The UIQ implementation of the filesystem browser does this in its r_filebrowser_commands resource. The S60 application view The S60 application view derives from CCoeControl and is, in effect, a control which itself owns a list box control which is used to display the filesystem. The application view is fully constructed by static factory function, NewL() which
instantiates the object and then calls the second phase ConstructL() method to perform any initialisation which may leave.
void CFileBrowseBaseView::ConstructL(const TRect& aRect) { CreateWindowL(); iEngine = CRFsEngine::NewL(); SetUpListBoxL(); ShowRootL(); SetRect(aRect); ActivateL(); }
The ConstructL() method calls CreateWindowL() to create the views associated window. When the filesystem engine object has been constructed, by calling CRFsEngine::NewL() and the list box created and initialised, ConstructL() calls SetRect() to set the area on the screen that the view will occupy and ActivateL() to indicate that the view is ready to draw itself. The code used to create and initialise the list box is described in the CFileBrowseBaseView implementation section below.
Resources
Many elements of a user interface, for instance dialogs, the button bar and menu panes, generally known as resources, are defined using a Symbian OSspecific resource language rather than directly in C++. Resources are expressed in text files which are then compiled into a compressed binary form using the Symbian resource compiler. Resources are added to a project by including them within START RESOURCE...END blocks within the project's mmp file, as described in the section on mmp file syntax. The IDEs invokes the resource compiler as needed when you build a project, and you can also compile resource files separately on the command line using the abld resource command. See Building code using the command line for more details. An advantage of being able to separate the resources from the C++ code is that the resource files can be edited separately, for instance by a localisation team, without any impact on the rest of the program, in particular, there is no need to recompile it. The resource language syntax is documented in the Symbian OS Library: see Resource file source format. The table below describes the resource files used in the filesystem browser. It is followed by section which describes in depth how resources are defined in the filebrowse resource file.
Resource files used in the filesystem browser

filebrowseapp.rss
filebrowseapp.rsc
filebrowseapp.rsg
filebrowse.hrh
Contains the GUI definitions. See the section below for a discussion of its contents for both S60 and UIQ implementations of the filesystem browser. The compiled resource file, generated from filebrowseapp.rss by the resource compiler. The compiler generated resource header which contains the symbolic IDs of every resource defined infilebrowseapp.rss. It is created in epoc32\include\ and can be included in the source files which need to refer to resources. Defines the IDs of application-specific commands and controls using C++ syntax. It is included both infilebrowseapp.rss and in various .cpp files, on each platform. For example, in the S60 implementation, the command IDs (TFileBrowseCommands) are associated in the .rss and .cpp files with the buttons, menu options and soft keys that issue them. The UIQ filesystem browser implementation does not use them because it does not have any commandgenerating resources. Contains localisation strings which are displayed in the GUI, for instance in dialog titles or in menus. These strings are referred to in the resource file or in code using their symbolic names. Defining the text in its own file, separate from the .rss file makes the task of translating the application into different languages (localisation) much easier. A special type of resource file, called a registration file, which provides the information that allows the application to be displayed in the application launcher. As seen in the section on mmp file syntax, when specifying this file in a project's mmp file, it must always place the compiled resource file into\private\10003A3F\apps (the private use area of the apparc server, which is responsible for application registration). This file includes the name of the application binary, the MIME types it can handle, and the location of the localisable registration information (built from filebrowseapp_loc.rss). The latter includes the icons and captions. This file is identical for both S60 and UIQ implementations of the filesystem browser.
filebrowseapp.rls
filebrowseapp_reg.rss
filebrowseapp_loc.rss
Its format is documented in the Symbian OS Library, see Application registration information. Contains location specific registration information (such as an application caption). The registration resource file (filebrowseapp_reg.rss) described above contains only non-localisable information and simply includes the location of this compiled resource file.
The _loc-file defines a single structure called LOCALISABLE_APP_INFO which contains the caption and the icon bitmap locations for the application. This file is identical for both S60 and UIQ implementations of the filesystem browser. avkon.rh, qikon.rh,eikon.rh, appinfo.rhand Standard GUI framework and S60- or UIQ-specific others. resource headers. These specify the standard resource structs used to define UI elements in the .rss file. avkon.hrh, uikon.hrh,qikon.hrh, eikon.hrhand Standard GUI framework and S60- or UIQ-specific others. symbolic IDs, for instance flags and control IDs for the standard controls. The following diagram summarises how each of the resource files are compiled and combined with other binary files, built from the application source code and bitmaps, to generate an installable application.
The filesystem browser resource files and the resulting application binaries on compilation.
filebrowseapp.rss
Each resource file must include a NAME statement before the first resource definition:
NAME SFSB
The four character long name identifies the resource file, so it must be unique among the resource files used by the application. The following three unnamed resources are also required:
RESOURCE RSS_SIGNATURE { }
This lets you specify a version number, but can be empty as is the case for both S60 and UIQ implementations of the filesystem browser example.
RESOURCE TBUF { buf = ""; }
This is the application's default filename; this is only required for applications that need to load or save their data when opened or closed (called file-based applications), otherwise it can be an empty string,
RESOURCE EIK_APP_INFO {}
In S60, this can be used to specify the toolbar, menu bar and associated hot keys to use when the application is launched, as described below in filebrowseapp.rss in S60. It was used in UIQ 2.1 but is no longer used in UIQ 3.0, although it must still be specified as an empty resource. The rest of the resource file contains resource definitions in any order, each prefixed with RESOURCE to indicate a separate resource structure. Since the filesystem browser application resource files for UIQ and S60 are almost completely different, they will be discussed separately. The only common factor in both resource files are the string resource definitions which hold strings that are used in the C++ source code, for instance, the text used in information messages. These are defined as follows:
RESOURCE TBUF r_filebrowse_driveC { buf = STRING_r_filebrowse_driveC; } RESOURCE TBUF r_filebrowse_driveD { buf = STRING_r_filebrowse_driveD; } RESOURCE TBUF r_filebrowse_infonote { buf = STRING_r_information_note; }
The resource strings to be displayed are not hard-coded into the resource file, but defined in the separate localisation header file (filebrowseapp.rls) as follows:
rls_string STRING_r_filebrowse_driveC rls_string STRING_r_filebrowse_driveD rls_string STRING_r_information_note "Cannot open file" "Drive C:" "Drive D:"
An rls_string is similar to a C++ #define macro: for example, "Cannot open file" will be substituted in the resource file wherever STRING_r_information_note is referred to. But an rls_string doesn't by itself define resources that you can use in C++ code.
filebrowseapp.rss
in UIQ
The UIQ platform supports the demands of different phone input and screen modes by using high level, global settings (UI configuration parameters) to define screen
layout (landscape or portrait, screen size), touch screen, menu or soft key input and orientation. These UI configuration parameters combine to create the look and feel of different configuration modes. The platform pre-defines five modes: Softkey Style, Pen Style, Softkey Style Small, Softkey Style Touch and Pen Style Landscape. See the UIQ SDK or information on the UIQ website for more information. In a resource file, the QIK_VIEW_CONFIGURATIONS resource structure is used to define which UI configuration modes an application supports. If a mode is supported, the framework will automatically switch view layout and commands when the windowserver changes to that mode. The filesystem browser supports the five modes and, for each, specifies the same view to be displayed in aQIK_VIEW structure, which itself identifies the pages to display using QIK_VIEW_PAGES. For each page, the content is specified in a container, using the QIK_CONTAINER_SETTINGS resource structure, which can contain an array of controls, each within a QIK_CONTAINER_ITEM_CI_LI structure. The filesystem browser view consists of a single control, a list box, whose behaviour is defined in the resource file as follows:
// Specifies controls and how they are laid out RESOURCE QIK_CONTAINER_SETTINGS r_filebrowse_baseview_page_control { // Specifies layout settings layout_manager_type = EQikRowLayoutManager; layout_manager = r_row_layout_default; // Specifies controls controls = { // A reference to the listbox control QIK_CONTAINER_ITEM_CI_LI { unique_handle = EFileBrowseListbox; type = EQikCtListBox; control = r_filebrowse_baseview_listbox; layout_data = r_row_layout_data_fill; } }; } // Layout manager RESOURCE QIK_ROW_LAYOUT_MANAGER r_row_layout_default { default_layout_data = QIK_ROW_LAYOUT_DATA {}; } // Layout parameters RESOURCE QIK_ROW_LAYOUT_DATA r_row_layout_data_fill { vertical_alignment = EQikLayoutVAlignFill; vertical_excess_grab_weight = 1; } // Resource that defines a listbox RESOURCE QIK_LISTBOX r_filebrowse_baseview_listbox { layouts = { r_filebrowse_baseview_normal_layout_pair }; } // Layout for listbox RESOURCE QIK_LISTBOX_LAYOUT_PAIR r_filebrowse_baseview_normal_layout_pair { // standard layout standard_normal_layout = EQikListBoxIconLine; }
For more information about these resource structures, you should consult the appropriate sections of the UIQ SDK.
filebrowseapp.rss
in S60
The contents of filebrowseapp.rss for the S60 implementation is significantly less complex, as it uses the approach of configuring the list box control mostly in C++ code rather than using the resource file as in the UIQ implementation. The list box is simply identified in the resource file as follows:
RESOURCE LISTBOX r_filebrowse_baseview_listbox { flags = EAknListBoxSelectionList; }
For more information about the LISTBOX resource, see the Uikon Resources reference in the Symbian OS Library and the S60 SDK for information about the different list box types provided by Avkon. All other list box customisation occurs in the code, as described in the CFileBrowseBaseView implementation section below: In either the S60 or UIQ versions of the application, the filesystem can be navigated by selecting items in the list box, moving back up the directory hierarchy using the first item in the list box.
In the S60 application, the user can either navigate up the directory hierarchy using the top 'back' directory, or the right soft key. Additionally, the S60 application also has a menu which can be invoked using the left soft key, to open a directory or exit the application. The right soft key can be used to navigate back up the directory hierarchy. The resource file structures for this are as follows:
// Define command input and controls (menu and Control Button Array) RESOURCE EIK_APP_INFO { menubar=r_filebrowse_menubar; cba=R_AVKON_SOFTKEYS_OPTIONS_BACK; }
// Top level menu resource - defines the menu pane used RESOURCE MENU_BAR r_filebrowse_menubar { titles= { MENU_TITLE { menu_pane=r_filebrowse_menu; txt=""; } }; } // Defines the menu items that comprise a menu pane RESOURCE MENU_PANE r_filebrowse_menu { items= { MENU_ITEM { command=ECmdFileBrowseOpen; txt = STRING_r_filebrowse_loc_Open; }, MENU_ITEM { command=EAknCmdExit; txt = STRING_r_filebrowse_loc_Exit; } }; }
The MENU_PANE resource structure is used to add items to the menu (note that the options are, again, defined using strings from the localisation header file rather than hard-coded into the resource). A command is associated with each option, which is defined in either the filebrowse.hrh example header file (ECmdFileBrowseOpen) or the avkon.hrh system header file (EAknCmdExit). The menu pane is referenced by the MENU_TITLE section of the MENU_BAR resource structure. Note that the title of the menu, which is not used in S60, is left blank. The commands and labels associated with the soft keys are set up using the cba attribute of the EIK_APP_INFO structure (where cba stands for 'Control Button Array'). In the filesystem browser application, a standard pair is used from avkon.rsg, which sets the left soft key label to "Options" and the right soft key to "Back", which, when pressed, sends a EAknSoftkeyBack command to the HandleCommandL() method of the application UI class.
CFileBrowseBaseView
implementation
The display for CFileBrowseBaseView is quite straightforward, consisting of a single list box which displays the subdirectories and files of a particular directory in the phone's filesystem. This section will examine some of the more important features of the view code for both the S60 and UIQ implementations. For more information, consult the App framework CONE section of the Symbian OS Library, or the relevant sections of the UIQ or S60 SDKs. Controls A control is a rectangular area of the screen that can be drawn and can handle key and pointer events. All controls are derived from CCoeControl. Some are intended as base classes for other controls, while others are intended to be instantiated and used as they are. Application developers can write their own concrete controls, or can use the ones supplied by UIQ or S60. In the filesystem browser, the application view is a control. It is known as a compound control because it owns another control, the list box, iListBox, which displays files and directories. The characteristics of the list box can be mostly specified in a resource file, as in the UIQ filesystem browser, or by settings in C++ code as in the S60 implementation. The list box handles the basics of input, such as highlighting the selected item, so you don't need to write code to do this. In the S60 implementation, the list box is created and initialised by CFileBrowseBaseView::ConstructL() which calls a private method in the view class, SetUpListBoxL(), defined as follows:
void CFileBrowseBaseView::SetUpListBoxL() { iListBox = new (ELeave) CAknSingleGraphicStyleListBox(); iListBox->SetContainerWindowL(*this); TResourceReader reader; iEikonEnv>CreateResourceReaderLC(reader, R_FILEBROWSE_BASEVIEW_LISTBOX); // Create the list box iListBox->ConstructFromResourceL(reader); CleanupStack::PopAndDestroy(); // reader
// Add this to observe the list box iListBox->SetListBoxObserver(this); SetupListIconsL(); // Add vertical scroll bars (which are visible when necessary) iListBox->CreateScrollBarFrameL(ETrue); iListBox->ScrollBarFrame()>SetScrollBarVisibilityL(CEikScrollBarFrame::EOff, \ CEikScrollBarFrame::EAuto); }
The list box is created as an object of class CAknSingleGraphicStyleListBox and its container window and observer object (both are the owning view class object) are set by calling SetContainerWindowL() and SetListBoxObserver() respectively upon it. The scroll bars are configured to be invisible for horizontal scroll and automatic for
vertical scrolling, which means that they are displayed when there are more entries in the list box than can be displayed on the screen without scrolling. The icons that the list box will display for a file or folder are created in icon 'slots' in advance by the SetupListIconsL() method (in comparison to the UIQ implementation, which creates an object to represent the icons each time they are required). For more information about list box controls in S60 or UIQ, you should consult the SDK documentation for the appropriate platform, or refer to the Additional resources section of this tutorial. Control observers Compound controls normally need to observe their components for events such as when the user scrolls through the contents of a list box or clicks to select an item. MQikListBoxObserver is a UIQ interface designed for handling list box-specific events, while the S60 implementation uses MEikListBoxObserver. In both cases, the view sets itself as a list box observer by calling:
iListBox->SetListBoxObserver(this);
The list box observer interface specifies a single function called HandleListBoxEventL(), that the view class implements to handle events generated when an item in the list box is selected, either by a pointer tap (in UIQ) or key press selection.
Static()
All controls in a GUI application have an iEikonEnv member, which is a pointer to the GUI environment, CEikonEnv. CEikonEnvprovides many useful functions, for instance access to standard fonts, formatting and colours, a connection with the file server, and the ability to display information messages. Objects that are not controls can get a GUI environment pointer by callingCEikonEnv::Static(). Drawing Views may be redrawn either by the system, or by the application. Systeminitiated redraws occur when the window is first created and when another window is moved away, exposing the control. Application-initiated redraws are needed when the application's data has changed, for instance, in the filesystem browser example, when an item is added to a list box.
CAknInformationNote
and InfoWinL()
The S60 filesystem browser uses an information note to indicate to the user that they cannot open a file. TheCAknInformationNote class is a pre-defined dialog class which requires no definition in the resource file. It is used as follows
HBufC* noteBuf = StringLoader::LoadLC(R_FILEBROWSE_INFONOTE); CAknInformationNote* note = new (ELeave) CAknInformationNote(); note->ExecuteLD(*noteBuf); CleanupStack::PopAndDestroy(noteBuf)
This code follows a standard pattern:
Prepares a string to display in the information note. The static StringLoader::LoadLC() method looks up the string associated with the resource identifier passed to it, then allocates a heap buffer to store and return it. Note that in the.rss file, resource IDs like r_filebrowse_infonote are specified using lower case, but when they are used in the C++ code, as in the above code, they must be referred to using upper case. This is due to a quirk in the resource compiler that builds resource IDs into the generated .rsg file as their upper case equivalent. Creates the information note object. Calls ExecuteLD(), passing in the string to display. This displays the information note as a waiting dialog, which means that the function executes synchronously and only returns when the dialog is closed, either by the user or when the time it is to be displayed has elapsed. For non-waiting dialogs, an alternative overload of ExecuteLD() displays the dialog then returns immediately, and notifies the caller asynchronously when the dialog closes later. Destroys the heap buffer.
The
CAknInformationNote
dialog which indicates that the file cannot be opened in the S60 version of the filesystem browser.
The UIQ filesystem browser uses a stock dialog common to all the Uikon platforms to indicate that a file cannot be opened. TheCEikonEnv::InfoWinL() call can display one or two lines of text in a waiting information dialog which the user must dismiss before continuing to use the application.
The information dialog resulting from a call CEikonEnv::InfoWinL() to indicate that the file cannot be opened in the UIQ version of the filesystem browser.
Application icons and captions

The application has an icon and a caption associated with it in both the main 'Applications' screen (used to navigate the installed applications available on the smartphone) and when the application itself is running. The application caption and compiled icon bitmap file (.mbm) are both specified in the localisable resource file described in the Resources section. If no images are provided, or the size is invalid, a default icon is substituted. This is the case in the filesystem browser application, which only supplies icons for the file and folder images displayed within the application.
The "FileBrowse" caption displayed for the filesystem browser and the default application icon for S60 (top) and UIQ (bottom). Each icon actually consists of two bmp files, one for the image itself and the other a mask for the bitmap. The mask is used to give a transparent effect; for every black pixel in the mask, the corresponding image pixel is displayed. For any other coloured mask pixel, the equivalent image pixel is not displayed, which results in image transparency. For the filesystem browser, the same mask image is used for both the file and folder icons. Icon bitmaps are typically stored in a project's gfx (S60) or images (UIQ) directory. They should be specified in the project definition file, as described in the mmp file syntax section. For more information see the Defining application icons, captions and properties section of the Symbian OS Library.
The filesystem browser engine class and console test code

The filesystem browser engine class, CRFsEngine, is a very simple example to illustrate the use of generic engine code with platform-specific application UI code. The class is defined (in rfsengine.h) and implemented (in rfsengine.cpp) by both S60 and UIQ projects but, in fact, the files are identical and a single copy could be shared by both implementations. If engine code is more complex, it is often desirable to implement it as a separate dll which each version of the filesystem browser application can link against. However, in this case, the class is simply a wrapper around access to the Symbian OS file server, through the file server session class RFs. The class wraps a call to RFs::GetDir() to get the contents of a directory. For more information about using the Symbian OS filesystem, consult the File Server Client Side documentation in the Symbian OS Library.
The Symbian OS console can be used to test application engine code, even before the UI which uses it has been written. The filesystem browser example includes test code for the CRFsEngine class, under the \test directory. The .mmp file for the console test is as follows:
TARGET TARGETTYPE UID SOURCEPATH SOURCE FileBrowseTest.exe exe 0 . FileBrowseTest.cpp
// Include the code for CRFsEngine which will be tested SOURCEPATH ..\src SOURCE rfsengine.cpp USERINCLUDE SYSTEMINCLUDE LIBRARY euser.lib efsrv.lib . \epoc32\include ..\inc
There are several differences between this file and the .mmp file for a typical GUI application:
UIDs are only relevant for applications launched from within the GUI environment; so, although the UID line must be included, its value can be zero because the console application doesn't have a user interface, or things like an icon or caption, it does not need any resource files or a registration file the console test only links against the core Symbian OS user library (euser.lib) and filesystem library (efsrv.lib) since it does not use any of the UI framework base classes or supporting code.
The implementation of the E32Main() entry point of the executable is as follows. The numbered lines are explained in more detail below.
GLDEF_C TInt E32Main() // 1 { __UHEAP_MARK; // 2 // Create the cleanup stack CTrapCleanup* cleanup = CTrapCleanup::New(); // 3 TRAPD(result, CallExampleL()); // 4 __ASSERT_ALWAYS(result==KErrNone, User::Panic(KFileBrowseTest, result)) ; // 5 // Destroy the cleanup stack delete cleanup; // 3 __UHEAP_MARKEND; // 2 return 0; }
1. GLDEF_C (for "Global definition") is an empty macro. It is only used to denote entry point functions such as this global function. 2. __UHEAP_MARK and __UHEAP_MARKEND are debug-only macros that are used to check that the program does not leak memory. In debug builds, if there is a difference in the number of heap cells allocated between the __UHEAP_MARK and the__UHEAP_MARKEND, the code will panic. During development of any type of application, these macros can
be used around your code to test whether it deallocates memory properly. Note that the GUI framework calls all the code in an application, from startup to exit, within its own pair of __UHEAP_MARKand __UHEAP_MARKEND macros.
3. Console programs must provide a cleanup stack for for themselves. CTrapCleanup::New() is used to create an instance of the cleanup stack. It should be deleted before the console program closes. 4. As described in The cleanup stack and leaves, TRAPD is a trap harness macro. The code calls the test method calledCallExampleL() and if it leaves, stores the resulting leave code in the variable calledresult (which TRAPD declares as aTInt). If CallExampleL() doesn't leave, then result will be set to KErrNone. 5. __ASSERT_ALWAYS is one of two assertion macros which are the standard way of asserting that a condition is true, and invoking a panic function if it is not. assertions are called in both debug and release builds to prevent release code from continuing after an unrecoverable error. __ASSERT_DEBUG are only called in debug builds and are useful for tracking down fatal bugs during development. The use of debug assertions is strongly recommended to test the internal consistency of your code logic.
__ASSERT_ALWAYS
The code for CallExampleL() is as follows. It creates a test console using the CConsoleBase class which is defined in e32cons.h:
LOCAL_C void CallExampleL() { console = Console::NewL(KFileBrowseTest, TSize(KConsFullScreen, KConsFu llScreen)); CleanupStack::PushL(console); RunTestsL(); // Runs the tests on class CRFsEngine CleanupStack::PopAndDestroy(console); // close and clean up the console }
The code shown is "boiler plate code" which any test console can use. Test code for a class or library should then be implemented within the RunTestsL() method, as you can see within the FileBrowseTest.cpp file for the filesystem browser engine's test code.
SYMBIAN OS V9.4
Feedback
Appendix: Symbian OS APIs

A major part of any software development project involves finding and understanding the application programming interfaces (APIs) you'll need to use to achieve your tasks. The basic elements of these APIs are the header files you include in your code, the libraries you link against and their documentation. However, with over 600 libraries and over 2500 headers in a typical SDK, understanding the whole system isn't easy. The Symbian OS system documentation attempts to make things simpler by grouping the elements into about 150 larger functional areas corresponding to OS components and into around 20 top-level areas (termed subsystems). This top-down view of the system is introduced in the Symbian OS Library in Subsystems and APIs. Another way to understand the APIs is to compare them with the interfaces of other systems that you already know well. This appendix maps Symbian OS interfaces to those of other, commonly used platforms (ANSI C, the C++ standard library, Java, and Windows/MFC). If you find this approach useful, and want to read case studies and discussions of moving to Symbian OS from other systems, there are papers on the Symbian Developer Network in the Migrating to Symbian OS section. ANSI C standard library The following table lists the ANSI C standard library headers, and provides links to where similar functionality can be found in Symbian OS.
assert.h
Asserts are provided by system macros, see system macros and E32_EKA2. ctype.h Character functions are provided by TChar. errno.h System wide error codes are defined as integers, see e32err.h Global variables. Apps can add their own errors, and instruct the system how to display them through ERROR_ARRAY resources. float.h Constant definitions are in the header e32math.h. limits.h No direct equivalent. locale.h Locale settings are encapsulated by Locale settings. math.h Maths functions are provided by Maths services. setjmp.h No equivalent. However, the trap and leave mechanism error handling system is similar in principle. signal.h No equivalent. stdarg.h Variable argument handling is provided by various macros,
including VA_START, VA_LIST. Closest equivalent is the header e32def.h. stdio.h File handling is provided by the File Server. Consoles are accessed through Console, though their use is unusual in production code. stdlib.h For conversion functions, see the descriptor classes (e.g. the base class TDes16). For random numbers, see Math. Memory management is usually done through C++ new and delete operators, but direct access to the heap is available, using classes like RHeap. Environment variables are not used, though Publish and Subscribe provides an effective equivalent. For basic sorts, see User. string.h String handling is provided by the descriptor family of classes. time.h Equivalents are provided by the Date and Time Handling API.
stdef.h
C++ standard library The following table lists the C++ standard library headers, and provides links to where similiar functionality can be found in Symbian OS.
<algorithm>
No direct equivalents, though for min/max see Basic Types; for basic sorts, see User. <bitset> No equivalent. <complex> No equivalent. <deque> Queues are typically implemented using a list: see Singly Linked Lists. <exception> The main exception handling is provided by the trap and leave mechanism. Thread-level handling of processor exceptions is provided by Threads and Processes. <fstream> See File Stores. <functional> No equivalent. <iomanip> No equivalent. <ios> See Streaming. <iosfwd> No equivalent. <iostream> No equivalent. Console handling is provided by the Console class. <istream> See Streaming. <iterator> No equivalent. <limits> Constant definitions are in the header e32math.h. <list> See Singly Linked Lists. <locale> See Locale settings. <map> See Array keys. <memory> No equivalent. Dynamic Arrays have various types for different pre-defined allocators. <numeric> No equivalent. <ostream> See Streaming. <queue> Queues are typically implemented using a list: see Singly Linked Lists. <set> See Array Keys.
<sstream>
<stack> <stdexcept> <streambuf> <string> <strstream>
<utility> <valarray> <vector>
Descriptors can be streamed as described in Externalising and internalising descriptors; see also classes such asRBufReadStream, RBufWriteStream, RDesReadStream, RDesWriteStream. See CStack. System wide error codes, see e32err.h Global variables are defined as integers. See the stream buffer classes, for instance MStreamBuf, TStreamBuf. String handling is provided by the descriptor family of classes. Descriptors can be streamed as described in Externalising and internalising descriptors; see also classes such asRBufReadStream, RBufWriteStream, RDesReadStream, RDesWriteStream. No equivalent. No equivalent. See Dynamic Arrays.
Java The following table lists the top-level packages in the Java(TM) 2 Platform Standard Edition 5.0, and provides links to where similiar functionality can be found in Symbian OS. java.applet java.awt No equivalent. Graphics primitives are provided by the Graphics API. Controls, the equivalent of AWT Components, are defined abstractly in the UI Control Framework. Concrete components are provided by UIQ. No equivalent. Streaming provides an abstract stream interface; streams can be combined into Stores. Concrete streams and stores for the file system are provided by File Stores. The user library provides equivalents, particuarly Basic Types, and the User class. There is no equivalent to the reference-object and reflective packages. High precision floating point is provided by Maths services; 64-bit integers by TInt64. Sockets are provided by Sockets Client; URL handling by the Internet Protocol Utility component. Character-set encoders and decoders are available from the Character Conversion component; the channel and regular expression packages have no equivalent. No equivalent. See Certificate Manager. Cryptography algorithm interfaces are not exposed. DBMS provides database management, including SQL. Locale settings provides formatting for locale-sensitive information. Collection classes are provided by Arrays and Lists; event handling by active objects; date and time facilities by Date and Time handling;
java.beans java.io
java.lang
java.math java.net java.nio
java.rmi java.security java.sql java.text java.util
string tokenizer by Lexical Analysis; random-number generator by Math; zip handling by EZLIB (undocumented at v9.1); logging by File Logging; the regular expression packages have no equivalent. javax.accessibility No equivalent. javax.crypto No equivalent. javax.imageio See Image Conversion Library. javax.management No equivalent. javax.naming Naming services (e.g. DNS) are available through the Sockets Client RHostResolver class. There is no directory service support. javax.net See Secure Sockets. javax.print See Print Framework. javax.rmi No equivalent. javax.security For certficates, see Certificate Manager. For authentication, see MCTAuthObject.h (undocumented at v9.1). javax.sound For sampled sound and MIDI packages, see Multimedia Framework. javax.sql See comments for java.sql. javax.swing See comments for java.awt. javax.transaction No equivalent. javax.xml No equivalent. org.ietf.jgss No equivalent. org.omg No equivalent. Symbian OS's ECom provides a management system for local component binaries. org.w3c.dom No equivalent. org.xml No equivalent. Windows MFC The following table lists the top-level MFC API categories, and provides links to where similiar functionality can be found in Symbian OS. Root Class: CObject MFC Application Architecture Classes All Symbian OS classes that allocate resources on the heap are derived from CBase. Uikon defines a roughly similar application architecture with application, document, and view classes (note though that commands are handled by the view class rather than command routing base classes). The platform UI layer, such as UIQ supplies, can specialise the application architecture classes. Window, Dialog, Frame windows: Symbian OS applications do not have a frame window as and Control such. The app UI class creates screen furniture such as menus and toolbars. Classes Drawing and Like MFC, Symbian OS has an abstract graphics device, and sub-classes Printing Classes for device types such as windows and printers. Instead of separate drawing tool objects such as CPen, drawing is done through the functions on agraphics context. Simple Data Simple geometric types are defined in various Geometry classes. Strings
Type Classes
are handled by descriptors; date and time facilities by Date and Time Handling. Array, List, and For arrays, see Dynamic Arrays; for lists, see Singly Linked Map Classes Lists and Doubly Linked Lists; for maps, see Array Keys. File and File handling is done through the File Server. An abstract interface for Database Classes many types of storage is provided byStreaming: the specialisation of streaming for files is provided by File Stores. A compound file of multiple files is referred to as a store. DBMS provides database management. Sockets are provided by the Sockets Client; HTTP services by HTTP Client. There is no gopher or FTP support in Symbian OS. There is no equivalent. The Symbian OS application architecture supports embedding of documents, but this facility is not used in UIQ. UIQ prefers applications to link using dynamic navigational links (DNLs) in views. The emulator provides debug facilities for manipulating and checking memory and other resources. Debug builds of applications automatically check for memory leaks and report unfreed cells on exit. Errors are indicated by the System wide error codes, see e32err.h Global variables The Symbian Developer Network paper Symbian OS for Windows programmers may also be helpful to Windows programmers migrating code to Symbian OS.
Internet and Networking Classes OLE Classes
Debugging and Exception Classes

Symbianapi

Загружено:

Сведения о документе

Исходное описание:

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Symbianapi

Загружено:

Авторское право:

Доступные форматы

S60 5th Edition C++ Developer's Library v2.1 > Symbian Developer's Library v9.4 > Symbian OS v9.

Telephony ISV API overview

Find out about the phone

Voice call control

Voice call operations

is an API that everyone can use.

Copyright 2005-2008 Symbian Software Ltd.

Phone, battery and subscriber information

Get current value writes the flags to a packaged CTelephony::TPhoneIdV1.

This is an asynchronous call; use CTelephony::EGetPhoneIdCancel to cancel it. For example:

Remember to link to the Etel3rdParty.lib and Request notification of changes

This information is constant and therefore does not change.

writes the value to a packaged CTelephony::TSubscriberIdV1.

This is an asynchronous call; use CTelephony::EGetSubscriberIdCancel to cancel it. For example:

Remember to link to the Etel3rdParty.lib and Request notification of changes

You cannot receive notification when this information changes.

Flight mode status

This is an asynchronous call; use CTelephony::EGetFlightModeCancel to cancel it. For example:

Remember to link to the Etel3rdParty.lib and Request notification of changes

This is an asynchronous call; use CTelephony::EGetBatteryInfoCancel to cancel it. For example:

Remember to link to the Etel3rdParty.lib and Request notification of changes

Battery charger information

This is an asynchronous call; use CTelephony::EGetIndicatorCancel to cancel it. For example:

Remember to link to the Etel3rdParty.lib and Request notification of changes

Remember to link to the Etel3rdParty.lib and Request notification of changes

Copyright 2005-2008 Symbian Software Ltd.

Line and call information

This is an asynchronous call; use CTelephony::EGetIndicatorCancel to cancel it.

Remember to link to the Etel3rdParty.lib and Request notification of changes

Fax line status

This is a synchronous call and cannot be cancelled. For example:

Data line status

This is a synchronous call and cannot be cancelled. For example:

Voice line information

Voice line status

This is a synchronous call and cannot be cancelled. For example:

Status of voice calls you own

writes the information to a packaged CTelephony::TCallStatusV1. Pass the method aCTelephony::TCallId.

Detailed call information

writes the information to a packaged CTelephony::TCallInfoV1.

Remember to link to the Etel3rdParty.lib library. Request notification of changes

Remote party information

Dynamic call capabilities

Copyright 2005-2008 Symbian Software Ltd.

GSM/WCDMA networks CDMA networks

Network signal indicator

This is an asynchronous call; use CTelephony::EGetIndicatorCancel to cancel it. For example:

Remember to link to the Etel3rdParty.lib and Request notification of changes

This is an asynchronous call; use CTelephony::EGetSignalStrengthCancel to cancel it. For example:

Remember to link to the Etel3rdParty.lib and Request notification of changes

This is an asynchronous call; use CTelephony::EGetNetworkRegistrationStatusCancel to cancel it. For example:

Remember to link to the Etel3rdParty.lib and Request notification of changes

Current network information

Information for all networks GSM/WCDMA networks CDMA networks

This is an asynchronous call; use CTelephony::EGetCurrentNetworkInfoCancel to cancel it. For example:

Remember to link to the Etel3rdParty.lib and Request notification of changes

The service provider name is returned in a descriptor of up to 16 characters by calling CTelephony::GetOperatorName().

This is an asynchronous call; use CTelephony::EGetOperatorNameCancel to cancel it.

Copyright 2005-2008 Symbian Software Ltd.

Supplementary services setting information

Call barring status Call waiting status

GSM/WCDMA networks only: