Phone, battery and subscriber information in Using the Telephony ISV API

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.

Description

The phone idenitifcation is returned in a packaged CTelephony::TPhoneIdV1. It contains the following member variables, each a TBuf 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

CTelephony::GetPhoneId() writes the flags to a packaged CTelephony::TPhoneIdV1.

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 = iPhoneIdV1.iManufacturer;
       TBuf<CTelephony::KPhoneModelIdSize> model = iPhoneIdV1.iModel;
       TBuf<CTelephony::KPhoneSerialNumberSize> serialNumber = iPhoneIdV1.iSerialNumber;
       }
    }

void CClientApp::DoCancel()
    {
    iTelephony->CancelAsync(CTelephony::EGetPhoneIdCancel);
    }

Remember to link to the Etel3rdParty.lib and euser.lib libraries.

Request notification of changes

This information is constant and therefore does not change.

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

CTelephony::GetSubscriberId() writes the value to a packaged CTelephony::TSubscriberIdV1.

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.iSubscriberId;
       }
    }

void CClientApp::DoCancel()
    {
    iTelephony->CancelAsync(CTelephony::EGetSubscriberIdCancel);
    }

Remember to link to the Etel3rdParty.lib and euser.lib libraries.

Request notification of changes

You cannot receive notification when this information changes.

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 Call-in-progress indicator is unnavailable.
In Network information, all information except the Network signal indicator is unnavailable.

Get current value

CTelephony::GetFlightMode() writes the value to a packaged CTelephony::TFlightModeV1. The method returns KErrNotSupported if the phone does not support the flight mode feature.

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.iFlightModeStatus;
       if(flightMode == CTelephony::EFlightModeOff)
          {} // Flight mode is off, so all operations are allowed
       }
    }

void CClientApp::DoCancel()
    {
    iTelephony->CancelAsync(CTelephony::EGetFlightModeCancel);
    }

Remember to link to the Etel3rdParty.lib and euser.lib libraries.

Request notification of changes

Use the CTelephony::EFlightModeChange notification event, the CTelephony::TFlightModeV1Pckg information class and the CTelephony::EFlightModeChangeCancel cancellation code; see Get notification when information changes.

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

CTelephony::GetBatteryInfo() writes the value to a packaged CTelephony::TBatteryInfoV1.

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.iStatus;
       TUint chargeLevel = iBatteryInfoV1.iChargeLevel;
       }
    }

void CClientApp::DoCancel()
    {
    iTelephony->CancelAsync(CTelephony::EGetBatteryInfoCancel);
    }

Remember to link to the Etel3rdParty.lib and euser.lib libraries.

Request notification of changes

Use the CTelephony::EBatteryInfoChange notification event, the CTelephony::TBatteryInfoV1Pckg information class and the CTelephony::EBatteryInfoChangeCancel cancellation code; see Get notification when information changes.

Description

You can read a number of flags that indicate several conditions. Two of them answer the questions below:

Can the phone detect when a charger is connected?
If so, is a charger currently connected?

Get current value

CTelephony::GetIndicator() 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::KIndChargerConnected)
          {
          // We can detect when a charger is connected
          if(iIndicatorV1.iIndicator & CTelephony::KIndChargerConnected)
             {} // 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);
    }

Remember to link to the Etel3rdParty.lib and euser.lib libraries.

Request notification of changes

The CTelephony::EIndicatorChange notification event indicates when any of the flags change. Use the CTelephony::TIndicatorV1Pckg information class and the CTelephony::EIndicatorChangeCancel cancellation code; see Get notification when information changes.

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

CTelephony::GetLockInfo() writes lock 1 or lock 2 information into a packaged CTelephony::TIccLockInfoV1. Pass the method a CTelephony::TIccLock to choose the lock you are interested in.

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::EStatusUnlocked)
          {
          // Lock 2 is available for the phone to use 
          // and its current statues is open, 
          // The user can access functionality governed by this lock.
          }
       }
    }

void CClientApp::DoCancel()
    {
    iTelephony->CancelAsync(CTelephony::EGetLockInfoCancel);
    }

Remember to link to the Etel3rdParty.lib and euser.lib libraries.

Request notification of changes

Use the CTelephony::EPin1LockInfoChange or CTelephony::EPin2LockInfoChangenotification event for lock 1 or 2 respectively.

Use the CTelephony::TIccLockInfoV1Pckg information class.

Use the CTelephony::EPin1LockInfoChangeCancel or CTelephony::EPin2LockInfoChangeCancel cancellation codes; see Get notification when information changes.

Phone, battery and subscriber information

Get current value

Request notification of changes

Phone identification

Subscriber identification

Flight mode status

Battery information

Battery charger information

Lock information