Network information in Using the Telephony ISV API

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:

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.

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 signal from the network is present?
If so, is a network signal currently present?

Get current value

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

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.

Unfortunately, you do not know which flags have changed. The code that detects the EIndicatorChange event must store the old flags for comparison.

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

CTelephony::GetSignalStrength() writes the value into a packaged CTelephony::TSignalStrengthV1.

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);
    }

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

Request notification of changes

Use the CTelephony::ESignalStrengthChange notification event, the CTelephony::TSignalStrengthV1Pckg information class and the CTelephony::ESignalStrengthChangeCancel cancellation code; see Get notification when information changes.

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

CTelephony::GetNetworkRegistrationStatus() writes the value to a packaged CTelephony::TNetworkRegistrationV1.

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 iNetworkRegistrationV1Pckg;

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 = iNetworkRegistrationV1.iRegStatus;
       }
    }

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

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

Request notification of changes

Use the CTelephony::ENetworkRegistrationStatusChange notification event, the CTelephony::TNetworkRegistrationV1Pckg information class and the CTelephony::ENetworkRegistrationStatusChangeCancel cancellation code; see Get notification when information changes.

Description

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

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

CTelephony::GetCurrentNetworkInfo() writes the value to a packaged CTelephony::TNetworkInfoV1.

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 == CTelephony::ENetworkModeCdma95))
          {} // CDMA network; process CDMA-specific information
       }
    }

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

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

Request notification of changes

Use the CTelephony::ECurrentNetworkInfoChange notification event, the CTelephony::TNetworkInfoV1Pckg information class and the CTelephony::ECurrentNetworkInfoChangeCancel cancellation code; see Get notification when information changes.

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.

This information is available from GSM/WCDMA 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 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 Compact and 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 calling CTelephony::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.

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

Network information

Get current value

Request notification of changes

Network signal indicator

Signal strength

Registration status

Current network information

All networks

GSM/WCDMA networks

More names for GSM/WCDMS networks

CDMA networks