Connection Monitor Server API: Using the Connection Monitor Server API

The client application first instantiates the RConnectionMonitor class. Then it can access all API methods. If the client application wants to listen to notifications, it must implement the MConnectionMonitorObserver class and register an instance of it to the API. Most of the API calls are asynchronous and can be cancelled.

Connecting and disconnecting

For simplicity, the instance of RConnectionMonitor is an automatic variable in the example below. When the instance of RConnectionMonitor is a member variable, ConnectL() should be called when constructing the object and Close() should be called when destructing.

#include <rconnmon.h>

RConnectionMonitor monitor;



// Open RConnectionMonitor object

monitor.ConnectL();



// ...



// Close RConnectionMonitor object when it is not needed any more

monitor.Close();

Getting basic connection level information

The following example shows how to retrieve various connection level information.

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;

TUint connectionCount( 0 );

TUint subConnectionCount( 0 );

TUint connectionId( 0 );



monitor.ConnectL(); // Open RConnectionMonitor object



// Get connection count

monitor.GetConnectionCount(

        connectionCount,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }

if ( connectionCount == 0 ) { /* No connection */ }



// Get connection info (1st connection)

TInt error = monitor.GetConnectionInfo(

        1,

        connectionId,

        subConnectionCount );

if ( error != KErrNone ) { // Error }



TBuf<KConnMonMaxStringAttributeLength> iapName;

TUint iapId = 0;

TUint downlinkData = 0;

TUint uplinkData = 0;

TInt signalStrength = 0;

TBool connectionActivity = EFalse;

TInt bearer = 0;



TBuf<CConnMonWlanNetwork::KMaxNameLength> ssid;

TUint transmitPower = 0;

TInt networkMode = 0;

TInt securityMode = 0;



TBuf<KConnMonMaxStringAttributeLength> apName;



// Get connection IAP name

monitor.GetStringAttribute(

        connectionId,

        0,

        KIAPName,

        iapName,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



// Get connection IAP ID

monitor.GetUintAttribute(

        connectionId,

        0,

        KIAPId,

        iapId,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



// Get connection downlink data (in bytes)

monitor.GetUintAttribute(

        connectionId,

        0,

        KDownlinkData,

        downlinkData,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



// Get connection uplink data (in bytes)

monitor.GetUintAttribute(

        connectionId,

        0,

        KUplinkData,

        uplinkData,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



// Get the signal strength (in mW)

monitor.GetIntAttribute(

        connectionId,

        0,

        KSignalStrength,

        signalStrength,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



// Get the current connection activity

monitor.GetBoolAttribute(

        connectionId,

        0,

        KConnectionActive,

        connectionActivity,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



// Get the connection bearer

monitor.GetIntAttribute(

        connectionId,

        0,

        KBearer,

        bearer,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



if ( bearer == EBearerWLAN )

    {

    // Get ssid name

    monitor.GetStringAttribute(

            connectionId,

            0,

            KNetworkName,

            ssid,

            status );

    User::WaitForRequest( status );

    if ( status.Int() != KErrNone ) { /* Error */ }



    // Get WLAN transmit power

    monitor.GetUintAttribute(

            connectionId,

            0,

            KTransmitPower,

            transmitPower,

            status );

    User::WaitForRequest( status );

    if ( status.Int() != KErrNone ) { /* Error */ }



    // Get network mode

    monitor.GetIntAttribute(

            connectionId,

            0,

            KNetworkMode,

            networkMode,

            status );

    User::WaitForRequest( status );

    if ( status.Int() != KErrNone ) { /* Error */ }



    // Get security mode

    monitor.GetIntAttribute(

            connectionId,

            0,

            KSecurityMode,

            securityMode,

            status );

    User::WaitForRequest( status );

    if ( status.Int() != KErrNone ) { /* Error */ }

    }

else

    {

    // Get access point name

    monitor.GetStringAttribute(

            connectionId,

            0,

            KAccessPointName,

            apName,

            status );

    User::WaitForRequest( status );

    if ( status.Int() != KErrNone ) { /* Error */ }

    }



monitor.Close(); // Close RConnectionMonitor object

Cancelling a request

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;

TInt error( KErrNone );



monitor.ConnectL(); // Open RConnectionMonitor object



// Buffer for WLAN information

CConnMonWlanNetworksPtrArrayPckg* wlanBuf =

        new( ELeave ) CConnMonWlanNetworksPtrArrayPckg( 2048 );

TPtr wlanPtr( wlanBuf->Buf()->Des() );



// Set a 120 second WLAN scan delay

TUint scanDelay = 120;

error = monitor.SetUintAttribute(

        EBearerIdWLAN,

        0,

        KWlanScanMaxDelay,

        scanDelay );

if ( error != KErrNone ) { /* Error */ }



// Request a WLAN scan. Scan will complete in 2 minutes, or sooner if some

// other process initiates a WLAN scan.

monitor.GetPckgAttribute(

        EBearerIdWLAN,

        0,

        KWlanNetworks,

        wlanPtr,

        status );



// To cancel the WLAN scan request:

monitor.CancelAsyncRequest( EConnMonGetPckgAttribute );



User::WaitForRequest( status ); // Should return immediately

error = status.Int();

if ( error == KErrNone ) { /* Request was completed before cancel */ }

else if ( error == KErrCancel ) { /* Request has been cancelled */ }

else { /* Error */ }



delete wlanBuf;

monitor.Close(); // Close RConnectionMonitor object

Stopping a connection

// To close a specific connection:

// (requires NetworkServices and NetworkControl capabilities)

TInt error = monitor.SetBoolAttribute(

        connectionId,

        0,

        KConnectionStop,

        ETrue );

if ( error != KErrNone ) { /* Error */ }





// To close all connections:

// (requires NetworkServices and NetworkControl capabilities)

TInt error = monitor.SetBoolAttribute(

        EBearerIdAll,

        0,

        KConnectionStopAll,

        ETrue );

if ( error != KErrNone ) { /* Error */ }

Registering for events

The following example shows how to register as an event listener for ConnMon events. Most events are sent to registered listeners by default, but some events are disabled by default because they are heavier and cause extra processing. If the client is interested in these special events, the relevant threshold values need to be set before calling NotifyEventL(). See Section 3.5.1 for a list of these events.

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;

TUint connectionCount( 0 );

TUint subConnectionCount( 0 );

TUint connectionId( 0 );



monitor.ConnectL(); // Open RConnectionMonitor object



// Get connection count

monitor.GetConnectionCount(

        connectionCount,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }

if ( connectionCount == 0 ) { /* No connection */ }



// Get connection info (1st connection)

TInt error = monitor.GetConnectionInfo(

        1,

        connectionId,

        subConnectionCount );

if ( error != KErrNone ) { /* Error */ }



// Some events are not sent by default. To receive them, relevant threshold

// values need to be set before registering the event listener.



// To receive EConnMonConnectionActivityChange events for a specific connection

error = monitor.SetUintAttribute( connectionId, 0, KActivityTimeThreshold, 10 );

if ( error != KErrNone ) { /* Error */ }



// To receive EConnMonDownlinkDataThreshold events for a specific connection

error = monitor.SetUintAttribute( connectionId, 0, KDownlinkDataThreshold, 32768 );

if ( error != KErrNone ) { /* Error */ }



// To receive EConnMonUplinkDataThreshold events for a specific connection

error = monitor.SetUintAttribute( connectionId, 0, KUplinkDataThreshold, 16384 );

if ( error != KErrNone ) { /* Error */ }



// To receive EConnMonBearerAvailabilityChange events

error = monitor.SetUintAttribute( EBearerIdAll, 0, KBearerAvailabilityThreshold, 1 );

if ( error != KErrNone ) { /* Error */ }



// To receive EConnMonSignalStrengthChange events

error = monitor.SetUintAttribute( EBearerIdAll, 0, KSignalStrengthThreshold, 1 );

if ( error != KErrNone ) { /* Error */ }



// To receive EConnMonBearerInfoChange and EConnMonBearerGroupChange events

// instead of the more limited EConnMonBearerChange event

error = monitor.SetUintAttribute( EBearerIdAll, 0, KBearerGroupThreshold, 1 );

if ( error != KErrNone ) { /* Error */ }



// Register for events. iObserver is an instance of the class that implements

// the event handler. In this example it’s an instance of MyClass (See next

// use case)

CMyConnMonObserver* iObserver = new( ELeave ) CMyConnMonObserver();

error = monitor.NotifyEventL( *iObserver );

if ( error != KErrNone ) { /* Error */ }



// ...



// Events must be cancelled and RConnectionMonitor object closed when not

// needed any more.

monitor.CancelNotifications();

delete iObserver;

iObserver = NULL;



monitor.Close(); // Close RConnectionMonitor object

Events that are disabled by default

The following events are disabled by default. For a client to receive these events, the corresponding threshold variable needs to be set.

Catching events

The following example shows an example implementation of a ConnMon event handler. Normally a client is only interested in a limited set of ConnMon events and ignores the rest.

class CMyConnMonObserver : public CBase, public MConnectionMonitorObserver

    {

    private:

        void EventL( const CConnMonEventBase& aEvent );

    };



void CMyConnMonObserver::EventL( const CConnMonEventBase& aEvent )

    {

    switch( aEvent.EventType() )

        {

        case EConnMonCreateConnection:

            {

            CConnMonCreateConnection* realEvent;

            realEvent = ( CConnMonCreateConnection* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId();

            }

            break;

        case EConnMonDeleteConnection:

            {

            CConnMonDeleteConnection* realEvent;

            realEvent = ( CConnMonDeleteConnection* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId();

            TUint downlinkData = realEvent->DownlinkData();

            TUint uplinkData = realEvent->UplinkData();

            TBool authoritativeDelete = realEvent->AuthoritativeDelete();

            }

            break;

        case EConnMonCreateSubConnection:

            {

            CConnMonCreateSubConnection* realEvent;

            realEvent = ( CConnMonCreateSubConnection* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId();

            TUint subConnectionId = realEvent->SubConnectionId();

            }

            break;

        case EConnMonDeleteSubConnection:

            {

            CConnMonDeleteSubConnection* realEvent;

            realEvent = ( CConnMonDeleteSubConnection* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId();

            TUint subConnectionId = realEvent->SubConnectionId();

            TUint downlinkData = realEvent->DownlinkData();

            TUint uplinkData = realEvent->UplinkData();

            TBool authoritativeDelete = realEvent->AuthoritativeDelete();

            }

            break;

        case EConnMonDownlinkDataThreshold:

            {

            CConnMonDownlinkDataThreshold* realEvent;

            realEvent = ( CConnMonDownlinkDataThreshold* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId();

            TUint subConnectionId = realEvent->SubConnectionId();

            TUint downlinkData = realEvent->DownlinkData();

            }

            break;

        case EConnMonUplinkDataThreshold:

            {

            CConnMonUplinkDataThreshold* realEvent;

            realEvent = ( CConnMonUplinkDataThreshold* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId();

            TUint subConnectionId = realEvent->SubConnectionId();

            TUint uplinkData = realEvent->UplinkData();

            }

            break;

        case EConnMonNetworkStatusChange:

            {

            CConnMonNetworkStatusChange* realEvent;

            realEvent = ( CConnMonNetworkStatusChange* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId(); // generic

            // TConnMonNetworkStatus

            TInt networkStatus = realEvent->NetworkStatus();

            }

            break;

        case EConnMonConnectionStatusChange:

            {

            CConnMonConnectionStatusChange* realEvent;

            realEvent = ( CConnMonConnectionStatusChange* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId();

            TUint subConnectionId = realEvent->SubConnectionId();

            TInt connectionStatus = realEvent->ConnectionStatus();

            // See nifvar.h for details on connection status values

            }

            break;

        case EConnMonConnectionActivityChange:

            {

            CConnMonConnectionActivityChange* realEvent;

            realEvent = ( CConnMonConnectionActivityChange* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId();

            TUint subConnectionId = realEvent->SubConnectionId();

            TBool connectionActivity = realEvent->ConnectionActivity();

            }

            break;

        case EConnMonNetworkRegistrationChange:

            {

            CConnMonNetworkRegistrationChange* realEvent;

            realEvent = ( CConnMonNetworkRegistrationChange* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId(); // generic

            // TConnMonNetworkRegistration

            TInt networkRegistrationStatus = realEvent->RegistrationStatus();

            }

            break;

        case EConnMonBearerChange:

            {

            CConnMonBearerChange* realEvent;

            realEvent = ( CConnMonBearerChange* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId(); // generic

            TInt bearerChange = realEvent->Bearer();

            }

            break;

        case EConnMonSignalStrengthChange:

            {

            CConnMonSignalStrengthChange* realEvent;

            realEvent = ( CConnMonSignalStrengthChange* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId(); // generic

            TInt signalStrengthChange = realEvent->SignalStrength();

            }

            break;

        case EConnMonBearerAvailabilityChange:

            {

            CConnMonBearerAvailabilityChange* realEvent;

            realEvent = ( CConnMonBearerAvailabilityChange* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId(); // generic

            TBool bearerAvailability = realEvent->Availability();

            }

            break;

        case EConnMonIapAvailabilityChange:

            {

            CConnMonIapAvailabilityChange* realEvent;

            realEvent = ( CConnMonIapAvailabilityChange* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId(); // generic

            TConnMonIapInfo iaps = realEvent->IapAvailability();



            for ( TUint i = 0; i < iaps.Count(); i++ )

                {

                TUint iapId = iaps.iIap[i].iIapId;

                }

            }

            break;

        case EConnMonTransmitPowerChange:

            {

            CConnMonTransmitPowerChange* realEvent;

            realEvent = (CConnMonTransmitPowerChange* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId();

            TUint txPwrNow = realEvent->TransmitPower();

            }

            break;

        case EConnMonSNAPsAvailabilityChange:

            {

            CConnMonSNAPsAvailabilityChange* realEvent;

            realEvent = ( CConnMonSNAPsAvailabilityChange* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId(); // generic

            TUint snapCount = realEvent->SNAPsAvailabile();

            TConnMonSNAPInfo snaps = realEvent->SNAPAvailability();



            for ( TUint i = 0; i < snaps.Count(); i++ )

                {

                TUint snapId = snaps.iSNAP[i].iSNAPId;

                }

            }

            break;

        case EConnMonNewWLANNetworkDetected:

            {

            CConnMonNewWLANNetworkDetected* realEvent;

            realEvent = ( CConnMonNewWLANNetworkDetected* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId(); // generic

            }

            break;

        case EConnMonOldWLANNetworkLost:

            {

            CConnMonOldWLANNetworkLost* realEvent;

            realEvent = ( CConnMonOldWLANNetworkLost* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId(); // generic

            }

            break;

        case EConnMonPacketDataAvailable:

            {

            CConnMonPacketDataAvailable* realEvent;

            realEvent = ( CConnMonPacketDataAvailable* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId(); // generic

            }

            break;

        case EConnMonPacketDataUnavailable:

            {

            CConnMonPacketDataUnavailable* realEvent;

            realEvent = ( CConnMonPacketDataUnavailable* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId(); // generic

            }

            break;

        case EConnMonBearerInfoChange:

            {

            CConnMonBearerInfoChange* realEvent;

            realEvent = ( CConnMonBearerInfoChange* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId();

            TInt bearerInfo = realEvent->BearerInfo(); // TConnMonBearerInfo

            }

            break;

        case EConnMonBearerGroupChange:

            {

            CConnMonBearerGroupChange* realEvent;

            realEvent = ( CConnMonBearerGroupChange* ) &aEvent;



            TUint connectionId = realEvent->ConnectionId();

            TBool bearerGroupInternal = realEvent->Internal();

            TUint bearerGroups1 = 0;

            TUint bearerGroups2 = 0;

            // TConnMonBearerGroup

            realEvent->BearerGroups( bearerGroups1, bearerGroups2 );

            }

            break;

        default:

            // For future events, unrecognized events must not crash the application

            break;

        }

    }

EConnMonCreateConnection event

This event is triggered when a new connection has been created. The connection ID passed in the event is a new ID number ConnMon assigned to the new connection.

EConnMonDeleteConnection event

This event is triggered when a connection has been deleted. The connection ID passed in the event is the connection ID of the deleted connection.

EConnMonCreateSubConnection event

This event is triggered when a new subconnection has been created. Subconnections are not supported currently.

EConnMonDeleteSubConnection event

This event is triggered when a subconnection has been deleted. Subconnections are not supported currently.

EConnMonDownlinkDataThreshold event

This event is triggered when there is a sufficient change in the volume of downlink data for a specific connection. The event is sent each time a client specified amount (KDownlinkDataThreshold) of new data has been sent. If another ConnMon client has requested for these events for the same connection, the smallest threshold value is used globally. If KDownlinkDataThreshold is 0 (default), events are not sent for that connection. To prevent rapid flooding of these events, different bearers have appropriate minimum threshold values which is used to override too small thresholds when necessary.

EConnMonUplinkDataThreshold event

This event is triggered when there is a sufficient change in the volume of uplink data for a specific connection. The event is sent each time a client specified amount (KUplinkDataThreshold) of new data has been received. If another ConnMon client has requested for these events for the same connection, the smallest threshold value will be used globally. If KUplinkDataThreshold is 0 (default), events are not sent for that connection. To prevent rapid flooding of these events, different bearers have appropriate minimum threshold values which are used to override too small thresholds when necessary.

EConnMonNetworkStatusChange event

This event is triggered when network status changes for some packet data connection. The connection ID passed in the event is a bearer specific connection ID (see TConnMonBearerId). The same information can be retrieved with TInt attribute KNetworkStatus.

EConnMonConnectionStatusChange event

This event is triggered when the status of some connection changes. The same information can be retrieved with TInt attribute KConnectionStatus. Connection status values are defined in nifvar.h.

EConnMonConnectionActivityChange event

This event is triggered when some connection changes from active to idle or vice versa. The client must set KActivityTimeThreshold to receive these events. KActivityTimeThreshold defines the period (in seconds) for checking whether the connection is active or not. The minimum allowed value is 5 seconds. The connection is considered active, if data has been passed during the last period, otherwise it is considered inactive. The same information can be retrieved with TBool attribute KConnectionActive.

EConnMonNetworkRegistrationChange event

This event is triggered when network registration status (GSM/GPRS/WCDMA) changes. The connection ID passed in the event is a bearer specific connection ID (see TConnMonBearerId). The same information can be retrieved with TInt attribute KNetworkRegistration. Network registration values are defined in TConnMonNetworkRegistration.

EConnMonBearerChange event

This event is triggered when bearer type (GPRS/EdgeGPRS/WCDMA) changes. The connection ID passed in the event is a bearer specific connection ID, either EBearerIdGPRS or EBearerIdWCDMA (see TConnMonBearerId). The new bearer passed in the event can be EBearerGPRS, EBearerEdgeGPRS or EBearerWCDMA (see TConnMonBearerType). The same information can be retrieved with TInt attribute KBearer.

Note: If TUint attribute KBearerGroupThreshold is set, these events are disabled and events EConnMonBearerInfoChange and EConnMonBearerGroupChange are used instead. Use these events, for example, if HSDPA related information is required.

EConnMonSignalStrengthChange event

This event is triggered when signal strength changes. The connection ID passed in the event is a bearer specific connection ID (see TConnMonBearerId). This event is valid only for cellular (GPRS, WCDMA, etc.) bearers and not for other bearers, e.g. WLAN. The client must set KSignalStrengthThreshold to 1 to receive these events.

EConnMonBearerAvailabilityChange event

This event is triggered when the availability of some bearer changes. The connection ID passed in the event is a bearer specific connection ID (see TConnMonBearerId). The client must set KBearerAvailabilityThreshold to 1 to receive these events. Using this event for detecting changes in WLAN availability requires WLAN background scanning to be enabled.

EConnMonIapAvailabilityChange event

This event is triggered when IAP availability changes. The connection ID passed in the event is the generic connection ID EBearerIdAll. The ID numbers of available IAPs are included in the event (see TConnMonIapInfo). The same information can be retrieved with packaged attribute KIapAvailability.

EConnMonTransmitPowerChange event

This event is triggered when the used WLAN transmit power changes. The connection ID passed in the event is the bearer specific connection ID EBearerIdWLAN. Transmit power is given in milliwatts (mW). The same information can be retrieved with TUint attribute KTransmitPower.

EConnMonSNAPsAvailabilityChange event

This event is triggered when SNAP availability changes. The connection ID passed in the event is the generic connection ID EBearerIdAll. The ID numbers of available SNAPs are included in the event (see TConnMonSNAPInfo). The same information can be retrieved with packaged attributes KSNAPsAvailability and KAvailableSNAPsIds.

EConnMonNewWLANNetworkDetected event

This event is triggered when new WLAN networks are detected during a WLAN scan. The connection ID passed in the event is the bearer specific connection ID EBearerIdWLAN. To receive these events, WLAN background scanning must be enabled, or some other mechanism must be used to trigger the necessary WLAN scans.

EConnMonOldWLANNetworkLost event

This event is triggered when one or more WLAN networks have been lost since the last WLAN scan. The connection ID passed in the event is the bearer specific connection ID EBearerIdWLAN. To receive these events, WLAN background scanning must be enabled, or some other mechanism must be used to trigger the necessary WLAN scans.

EConnMonPacketDataAvailable event

This event is triggered when GPRS or WCDMA bearer availability changes, a phone call is started, or a phone call ends. The connection ID passed in the event is a bearer specific connection ID, either EBearerIdGPRS or EBearerIdWCDMA (see TConnMonBearerId).

EConnMonPacketDataAvailable and EConnMonPacketDataUnavailable events form a pair. Two events are always sent, one with connection ID EBearerIdGPRS for 2G network, and one with connection ID EBearerIdWCDMA for 3G network. The event for the network that the phone is not registered to is always of type EConnMonPacketDataUnavailable. If the phone does not support dual transfer mode and a call is started, a GPRS or WCDMA packet data connection is put on hold. In this scenario, both are of type EConnMonPacketDataUnavailable. The same information can be retrieved with TBool attribute KPacketDataAvailability.

EConnMonPacketDataUnavailable event

EConnMonPacketDataUnavailable and EConnMonPacketDataAvailable events form a pair. Two events are always sent, one with connection ID EBearerIdGPRS for 2G network, and one with connection ID EBearerIdWCDMA for 3G network. The event for the network that the phone is not registered to is always of type EConnMonPacketDataUnavailable. If the phone does not support dual transfer mode and a call is started, a GPRS or WCDMA packet data connection is put on hold. In this scenario, both are of type EConnMonPacketDataUnavailable. The same information can be retrieved with TBool attribute KPacketDataAvailability.

EConnMonBearerInfoChange

This event is triggered when there is a change in bearer information for an existing connection, or if the network mode changes e.g. from 2G to 3G. For connection specific events, the connection ID passed in the event is the respective connection specific ID, and for network level events, the connection ID is EBearerIdAll. The same connection level information can be retrieved with TInt attribute KBearerInfo. The bearer info values are defined in TConnMonBearerInfo.

Note: The client needs to set the TUint attribute KBearerGroupThreshold in order to receive these events. This also disables the EConnMonBearerChange events.

EConnMonBearerGroupChange event

This event is triggered when there is a change in bearer group information for an existing connection. The connection ID passed in the event is the respective connection specific ID. The same information can be retrieved with packaged attribute KBearerGroupInfo. The bearer group bitmask is defined in TConnMonBearerGroup.

Note: The client needs to set the TUint attribute KBearerGroupThreshold in order to receive these events. This also disables EConnMonBearerChange events.

Using TInt attributes

KBearer attribute

Used with GetIntAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection, or the bearer specific connection ID EBearerIdGPRS.

This attribute is used to retrieve the bearer of a connection. If the bearer specific connection ID EBearerIdGPRS is used as connection ID parameter, ConnMon checks if EDGE is in use. If yes, EBearerEdgeGPRS is returned, if not, EBearerGPRS is returned. Connection bearer types are defined in TConnMonBearerType.

KNetworkStatus attribute

Used with GetIntAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection, or a bearer specific connection ID. Supported bearer specific connection IDs are:

This attribute is used to retrieve the current network status of the phone. Network status values are defined in TConnMonNetworkStatus.

KConnectionStatus attribute

Used with GetIntAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

This attribute is used to retrieve the current status/progress information of a connection. Connection status values are defined in nifvar.h.

KProtocolType attribute

Used with GetIntAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

This attribute is used to retrieve the protocol type (type of PDP) of a connection. Protocol types are defined in TConnMonProtocolType.

KNetworkRegistration attribute

Used with GetIntAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection, or a bearer specific connection ID. Supported bearer specific connection IDs are:

This attribute is used to retrieve the current network registration status of the phone. Network registration values are defined in TConnMonNetworkRegistration.

KSignalStrength attribute

Used with GetIntAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection, or a bearer specific connection ID. Supported bearer specific connection IDs are:

This attribute is used to retrieve the current signal strength. For WLAN, if an active WLAN connection is present, the signal strength of that connection is returned. Otherwise a WLAN scan is performed and the signal strength of the strongest network found is returned.

KNetworkMode attribute

Used with GetIntAttribute(). Parameter aConnectionId must be a valid connection ID for an existing WLAN connection.

This attribute is used to retrieve the network mode of an active WLAN connection. WLAN network modes are defined in TConnMonNetworkMode.

KSecurityMode attribute

Used with GetIntAttribute(). Parameter aConnectionId must be a valid connection ID for an existing WLAN connection.

This attribute is used to retrieve the security mode of an active WLAN connection. WLAN connection security modes are defined in TConnMonSecurityMode.

KBearerInfo attribute

Used with GetIntAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

This attribute is used to retrieve the current bearer information for an existing connection. Bearer information values are defined in TConnMonBearerInfo.

KWlanScanCacheLifetime attribute

Used with GetIntAttribute() and SetIntAttribute(). Parameter aConnectionId must be a valid connection ID for an existing WLAN connection, or the bearer specific connection ID EBearerIdWLAN.

This attribute is used to control the behaviour of WLAN scanning together with TUint attribute KWlanScanMaxDelay. These attributes are client specific, and do not directly affect other ConnMon clients. KWlanScanCacheLifetime represents the age (in seconds) of WLAN scan results that the client is willing to accept. The valid value range is 0-60 seconds. Greater values are automatically set to the maximum allowed value. The value -1 represents the device specific default value (usually 7 seconds). The bigger this value is, the more likely it is there will be a suitable WLAN scan result in cache when a WLAN scan request is made. This leads to faster completion of WLAN scan requests and also less frequent WLAN scanning performed by the device, which in turn leads to longer battery life.

Note: KWlanScanCacheLifetime attribute is ignored unless TUint attribute KWlanScanMaxDelay is set to 0.

Using TUint attributes

KDownlinkData attribute

Used with GetUintAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

This attribute is used to retrieve the amount of data in bytes transferred by this connection from the remote endpoint.

KUplinkData attribute

Used with GetUintAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

This attribute is used to retrieve the amount of data in bytes transferred by this connection to the remote endpoint.

KIAPId attribute

Used with GetUintAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

KNetworkIdentifier attribute

Used with GetUintAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

KTransmitPower attribute

Used with GetUintAttribute(). Parameter aConnectionId must be a valid connection ID for an existing WLAN connection.

This attribute is used to retrieve the transmit power of an active WLAN connection.

KMobilePhoneNetworkMode attribute

Used with GetUintAttribute(). Parameter aConnectionId is not used with this attribute.

This attribute is used to retrieve the current phone network mode. The network modes are defined in TConnMonMobilePhoneNetworkMode.

KActivityTimeThreshold attribute

Used with GetUintAttribute() and SetUintAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

This attribute controls connection activity monitoring for a connection. It defines the period (in seconds) for checking whether the connection is active or not. The minimum allowed value is 5 seconds. The default value 0 means monitoring is disabled and EConnMonConnectionActivityChange events are not sent for this connection. If set to a value in between these, the minimum allowed value is used.

KDownlinkDataThreshold attribute

Used with GetUintAttribute() and SetUintAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

This attribute controls downlink data amount monitoring for a connection. It defines the amount of data (in bytes) that needs to be received by a connection before a new EConnMonDownlinkDataThreshold event is generated. The minimum allowed value is 4096 bytes, but this can be higher depending on the bearer of the connection. This is to prevent event flooding on higher bandwidth networks. The default value 0 means monitoring is disabled and the EConnMonDownlinkDataThreshold events are not sent for this connection.

KUplinkDataThreshold attribute

Used with GetUintAttribute() and SetUintAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

This attribute controls uplink data amount monitoring for a connection. It defines the amount of data (in bytes) that needs to be sent by a connection before a new EConnMonUplinkDataThreshold event is generated. The minimum allowed value is 4096 bytes, but this can be higher depending on the bearer of the connection. This is to prevent event flooding on higher bandwidth networks. The default value 0 means monitoring is disabled and the EConnMonUplinkDataThreshold events are not sent for this connection.

KBearerAvailabilityThreshold attribute

Used with GetUintAttribute() and SetUintAttribute(). Parameter aConnectionId is not used with this attribute.

This attribute controls bearer availability monitoring. Set to 1 to receive notifications from ConnMon when bearer availability changes. The default value 0 means monitoring is disabled and the EConnMonBearerAvailabilityChange events are not sent.

KSignalStrengthThreshold attribute

Used with GetUintAttribute() and SetUintAttribute(). Parameter aConnectionId is not used with this attribute.

This attribute controls cellular network signal strength monitoring. Set to 1 to receive notifications from ConnMon when cellular network signal strength changes. The default value 0 means monitoring is disabled and the EConnMonSignalStrengthChange events are not sent.

KBearerGroupThreshold attribute

Used with GetUintAttribute() and SetUintAttribute(). Parameter aConnectionId is not used with this attribute.

This attribute controls whether ConnMon is sending a client EConnMonBearerChange events, or EConnMonBearerInfoChange and EConnMonBearerGroupChange events. The new EConnMonBearerChange and EConnMonBearerInfoChange events are more up to date, and designed to be extendable. Set to 1 to take them into use. The default value 0 means EConnMonBearerChange events are used instead, and EConnMonBearerInfoChange and EConnMonBearerGroupChange are not sent.

KWlanScanMaxDelay attribute

Used with GetUintAttribute() and SetUintAttribute(). Parameter aConnectionId must be a valid connection ID for an existing WLAN connection, or the bearer specific connection ID EBearerIdWLAN.

This attribute is used to control the behaviour of WLAN scanning together with TInt attribute KWlanScanCacheLifetime. These attributes are client specific, and do not directly affect other ConnMon clients. KWlanScanMaxDelay represents the time (in seconds) the client is willing to wait for WLAN scan results. These WLAN scan results will be up to date, and thus the device is forced to perform a WLAN scan. The valid value range is 0-1200 seconds. Greater values are automatically set to the maximum allowed value. If another process triggers a WLAN scan while a scan request is waiting for this delay, the request is completed early with the fresh scan results.

Note: When KWlanScanMaxDelay is set to 0 (the default value), cached WLAN scan results may be used instead. TInt attribute KWlanScanCacheLifetime can be used to control the maximum allowed age of these cached WLAN scan results.

Using TBool attributes

KConnectionActive attribute

Used with GetBoolAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

This attribute is used to check if a connection is active or not. If EConnMonConnectionActivityChange events are enabled for this connection, ConnMon returns the current cached information immediately. If these events are not enabled (default), ConnMon completes this request in approximately 1 second. The connection is considered active, if data has been passed during this time, otherwise it is considered inactive.

KBearerAvailability attribute

Used with GetBoolAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection, or a bearer specific connection ID. Supported bearer specific connection IDs are:

This attribute is used to find out if a bearer is currently available. To check for a specific bearer, the given connection ID should be one of the bearer specific connection IDs. If the given connection ID belongs to a valid connection, the availability of the bearer used by that connection is checked.

KPacketDataAvailability attribute

Used with GetBoolAttribute(). Parameter aConnectionId must be a bearer specific connection ID. Supported bearer specific connection IDs are:

This attribute is used to retrieve the packet data availability status for a 2G or 3G network. The status is false if the bearer is not available, or the phone does not support dual transfer mode and a phone call is currently active.

KConnectionStop attribute

Used with SetBoolAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

By setting this attribute to ETrue, the connection referred to by the connection ID is closed.

Note: The client must have the NetworkServices and NetworkControl capabilities to use this attribute.

KConnectionStopAll attribute

Used with SetBoolAttribute(). Parameter aConnectionId is not used with this attribute.

Note: The client must have the NetworkServices and NetworkControl capabilities to use this attribute.

Using string attributes

KIAPName attribute

Used with GetStringAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

This attribute is used to retrieve the IAP name a connection is connected through.

KAccessPointName attribute

Used with GetStringAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

This attribute is used to retrieve the access point name from the IAP the connection is connected through.

KTelNumber attribute

Used with GetStringAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

This attribute is used to retrieve the used telephone number for a connection, when applicable.

KNetworkName attribute

Used with GetStringAttribute(). Parameter aConnectionId must be a valid connection ID for an existing WLAN connection.

This attribute is used to retrieve the network name (SSID) of the WLAN that a connection is connected to. A WLAN name can be up to 32 characters long.

KWlanSsid attribute

Used with GetStringAttribute() and SetStringAttribute(). Parameter aConnectionId must be a valid connection ID for an existing WLAN connection, or the bearer specific connection ID EBearerIdWLAN.

This attribute is used to set the SSID value to be used when performing a WLAN scan for networks with a specific SSID.

Using packaged attributes

KStartTime attribute

Used with GetPckgAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

This attribute is used to retrieve a connections start time. The information is transferred through a package (see TConnMonTimeBuf).

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;

TUint connectionCount( 0 );

TUint subConnectionCount( 0 );

TUint connectionId( 0 );



monitor.ConnectL(); // Open RConnectionMonitor object



// Get connection count

monitor.GetConnectionCount(

        connectionCount,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }

if ( connectionCount == 0 ) { /* No connection */ }



// Get connection info (1st connection)

TInt error = monitor.GetConnectionInfo(

        1,

        connectionId,

        subConnectionCount );

if ( error != KErrNone ) { /* Error */ }



// Get connection duration (1st connection)

TConnMonTimeBuf timeBuffer;

monitor.GetPckgAttribute(

        connectionId,

        0,

        KStartTime,

        timeBuffer,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



TTimeIntervalSeconds connectionDurationInSecs;

TTime now;

now.UniversalTime();

now.SecondsFrom( timeBuffer(), connectionDurationInSecs );



monitor.Close(); // Close RConnectionMonitor object

KClientInfo attribute

Used with GetPckgAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

This attribute is used to retrieve the client UID for all clients using a specific connection. ConnMon does not include itself in the results. The information is transferred through a package (see TConnMonClientEnumBuf). The package class has a fixed size array and is limited to a maximum of 10 (KConnMonMaxClientUids) UIDs.

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;

TUint connectionCount( 0 );

TUint subConnectionCount( 0 );

TUint connectionId( 0 );



monitor.ConnectL(); // Open RConnectionMonitor object



// Get connection count

monitor.GetConnectionCount(

        connectionCount,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }

if ( connectionCount == 0 ) { /* No connection */ }



// Get connection info (1st connection)

TInt error = monitor.GetConnectionInfo(

        1,

        connectionId,

        subConnectionCount );

if ( error != KErrNone ) { /* Error */}



// Get connection client info

TConnMonClientEnumBuf buf;

monitor.GetPckgAttribute(

        connectionId,

        0,

        KClientInfo,

        buf,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



TUint clientCount = buf().iCount;

for ( TInt i = 0; i < clientCount; i++ )

    {

    TInt32 clientUid = buf().iUid[i].iUid;

    // ...

    }



monitor.Close(); // Close RConnectionMonitor object

KNetworkNames attribute

Used with GetPckgAttribute(). Parameter aConnectionId must be a valid connection ID for an existing WLAN connection, or the bearer specific connection ID EBearerIdWLAN.

This attribute is used to retrieve information about available WLANs. This includes the network name (SSID), signal strength and mode (see TConnMonNetworkMode). A WLAN scan is performed to obtain this information. The networks are sorted according to signal strength, strongest network first. The information is transferred through a package (see TConnMonNetworkNamesBuf). The package class has a fixed size array and is limited to a maximum of 10 (KConnMonMaxNetworkCount) network information objects.

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;



monitor.ConnectL(); // Open RConnectionMonitor object



// Buffer for basic WLAN information (max. 10 networks)

TConnMonNetworkNamesBuf buf;



monitor.GetPckgAttribute(

        EBearerIdWLAN,

        0,

        KNetworkNames,

        buf,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



TInt wlanCount = buf().Count();

TBuf<CConnMonWlanNetwork::KMaxNameLength> wlanName;

TInt wlanSignalStrength = 0;

TInt wlanMode = 0; // TConnMonNetworkMode



for ( TInt i = 0; i < wlanCount; i++ )

    {

    wlanName.Copy( buf().iNetwork[i].iName );

    wlanSignalStrength = buf().iNetwork[i].iSignalStrength;

    wlanMode = buf().iNetwork[i].iType;

    // ...

    }



monitor.Close(); // Close RConnectionMonitor object

KIapAvailability attribute

Used with GetPckgAttribute(). Parameter aConnectionId must be a bearer specific connection ID. Supported bearer specific connection IDs are:

This attribute is used to retrieve bearer specific available IAP IDs, or all available IAP IDs, depending on the given connection ID. The information is transferred through a package (see TConnMonIapInfoBuf). The package class has a fixed size array and is limited to a maximum of 25 (KConnMonMaxIAPCount) IDs.

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;



monitor.ConnectL(); // Open RConnectionMonitor object



// Buffer for IAP info

TConnMonIapInfoBuf iapBuffer;



monitor.GetPckgAttribute(

        EBearerIdAll,

        0,

        KIapAvailability,

        iapBuffer,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



TUint iapCount = iapBuffer().Count();

for ( TInt i = 0; i < iapCount; i++ )

    {

    TUint iapId = iapBuffer().iIap[i].iIapId;

    // ...

    }



monitor.Close(); // Close RConnectionMonitor object

KSNAPsAvailability attribute

Used with GetPckgAttribute(). Parameter aConnectionId is not used with this attribute.

This attribute is used to retrieve available SNAP IDs. The information is transferred through a package (see TConnMonSNAPInfoBuf). The package class has a fixed size array and is limited to a maximum of 25 (KConnMonMaxSNAPsCount) IDs.

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;



monitor.ConnectL(); // Open RConnectionMonitor object



// Buffer for SNAP information

TConnMonSNAPInfoBuf snapBuffer;



monitor.GetPckgAttribute(

        EBearerIdAll,

        0,

        KSNAPsAvailability,

        snapBuffer,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



TUint snapCount = snapBuffer().Count();

for ( TInt i = 0; i < snapCount; i++ )

    {

    TUint snapId = snapBuffer().iSNAP[i].iSNAPId;

    // ...

    }



monitor.Close(); // Close RConnectionMonitor object

KAvailableSNAPsIds attribute

Used with GetPckgAttribute(). Parameter aConnectionId is not used with this attribute.

This attribute is used to retrieve available SNAP IDs. The information is transferred through a package (see ConnMonIdsArrayPckg). The package class has a buffer that the client needs to allocate memory for, thus the size is not limited. The buffer also contains the total amount of available SNAPs and how many of those fit inside the buffer.

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;



monitor.ConnectL(); // Open RConnectionMonitor object



// Buffer for SNAP information

ConnMonIdsArrayPckg idBuffer( 32 ); // Buffer size 32

TPtr idBufferPtr( idBuffer.Buf()->Des() );



monitor.GetPckgAttribute(

        EBearerIdAll,

        0,

        KAvailableSNAPsIds,

        idBufferPtr,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }





// Amount of available SNAP IDs on the phone

TUint totalAmount = idBuffer.Buf()->Des()[0];

// Amount of available SNAP IDs that fit inside the buffer

TUint bufferAmount = idBuffer.Buf()->Des()[1];



if ( bufferAmount != totalAmount )

    {

    // Buffer was too small, all IDs did not fit.

    // Minimum space needed is ( totalAmount * 2 ) + 2

    }



// Unpack buffer to an RArray<TConnMonId>

RConnMonIdsArray idArray;

idBuffer.UnpackToL( idArray );

for ( TInt i = 0; i < idArray.Count(); i++ )

    {

    TConnMonId id = idArray[i];

    TUint idNumber = id.Id();

    // ...

    }

idArray.Close();



monitor.Close(); // Close RConnectionMonitor object

KWlanNetworks attribute

Used with GetPckgAttribute(). Parameter aConnectionId must be a valid connection ID for an existing WLAN connection, or the bearer specific connection ID EBearerIdWLAN.

This attribute is used to perform a broadcast WLAN scan. The information is transferred through a package (see CConnMonWlanNetworksPtrArrayPckg). The package class has a buffer that the client needs to allocate memory for. The buffer is filled with WLANs sorted by signal strength, strongest network first. The buffer also contains the total amount of available WLANs and how many of those fit inside the buffer.

Note: TInt attribute KWlanScanCacheLifetime and TUint attribute KWlanScanMaxDelay can be used to control the timing and age of the actual scan results.

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;



monitor.ConnectL(); // Open RConnectionMonitor object



// Buffer for WLAN information

CConnMonWlanNetworksPtrArrayPckg* wlanBuf =

        new( ELeave ) CConnMonWlanNetworksPtrArrayPckg( 2048 );

TPtr wlanPtr( wlanBuf->Buf()->Des() );



monitor.GetPckgAttribute(

        EBearerIdWLAN,

        0,

        KWlanNetworks,

        wlanPtr,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



RConnMonWlanNetworksPtrArray wlanPtrArray;

wlanBuf->UnpackToL( wlanPtrArray );



// Amount of WLANs found

TUint totalAmount = wlanBuf->Buf()->Des()[0];

// Amount of WLANs that fit inside the buffer

TUint bufferAmount = wlanBuf->Buf()->Des()[1];



for ( TInt i = 0; i < wlanPtrArray.Count(); i++ )

    {

    TBuf<CConnMonWlanNetwork::KMaxNameLength> wlanName = wlanPtrArray[i]->Name();

    TBuf8<CConnMonWlanNetwork::KWlanBssId> wlanBssid = wlanPtrArray[i]->WlanBssid();

    TUint wlanConnectionMode = wlanPtrArray[i]->ConnectionMode();

    TUint wlanSignalStrength = wlanPtrArray[i]->SignalStrength();

    TUint wlanSecurityMode = wlanPtrArray[i]->SecurityMode();



    // ...

    delete wlanPtrArray[i];

    }

wlanPtrArray.Close();

delete wlanBuf;



monitor.Close(); // Close RConnectionMonitor object

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;



monitor.ConnectL(); // Open RConnectionMonitor object



// Buffer for WLAN information

CConnMonWlanNetworksPtrArrayPckg* wlanBuf =

        new( ELeave ) CConnMonWlanNetworksPtrArrayPckg( 2048 );

TPtr wlanPtr( wlanBuf->Buf()->Des() );



// Set a 120 second WLAN scan delay

TUint scanDelay = 120;

TInt error = monitor.SetUintAttribute(

        EBearerIdWLAN,

        0,

        KWlanScanMaxDelay,

        scanDelay );

if ( error != KErrNone ) { /* Error */ }



// Request a WLAN scan. Scan will complete in 2 minutes, or sooner if some

// other process initiates a WLAN scan.

monitor.GetPckgAttribute(

        EBearerIdWLAN,

        0,

        KWlanNetworks,

        wlanPtr,

        status );

User::WaitForRequest( status ); // Will take up to 2 minutes

if ( status.Int() != KErrNone ) { /* Error */ }



RConnMonWlanNetworksPtrArray wlanPtrArray;

wlanBuf->UnpackToL( wlanPtrArray );



// Amount of WLANs found

TUint totalAmount = wlanBuf->Buf()->Des()[0];

// Amount of WLANs that fit inside the buffer

TUint bufferAmount = wlanBuf->Buf()->Des()[1];



for ( TInt i = 0; i < wlanPtrArray.Count(); i++ )

    {

    TBuf<CConnMonWlanNetwork::KMaxNameLength> wlanName = wlanPtrArray[i]->Name();

    TBuf8<CConnMonWlanNetwork::KWlanBssId> wlanBssid = wlanPtrArray[i]->WlanBssid();

    TUint wlanConnectionMode = wlanPtrArray[i]->ConnectionMode();

    TUint wlanSignalStrength = wlanPtrArray[i]->SignalStrength();

    TUint wlanSecurityMode = wlanPtrArray[i]->SecurityMode();



    // ...

    delete wlanPtrArray[i];

    }

wlanPtrArray.Close();

delete wlanBuf;



monitor.Close(); // Close RConnectionMonitor object

KBearerGroupInfo attribute

Used with GetPckgAttribute(). Parameter aConnectionId must be a valid connection ID for an existing connection.

This attribute is used to retrieve bearer group information for a connection. The bearer group information is a bitmask containing bearer type related information. The bitmask is defined in TConnMonBearerGroup. The information is transferred through a package (see TConnMonBearerGroupInfoBuf).

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;

TUint connectionCount( 0 );

TUint subConnectionCount( 0 );

TUint connectionId( 0 );



monitor.ConnectL(); // Open RConnectionMonitor object



// Get connection count

monitor.GetConnectionCount(

        connectionCount,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }

if ( connectionCount == 0 ) { /* No connection */ }



// Get connection info (1st connection)

TInt error = monitor.GetConnectionInfo(

        1,

        connectionId,

        subConnectionCount );

if ( error != KErrNone ) { /* Error */ }



// Get bearer group info

TConnMonBearerGroupInfoBuf bearerGroupInfoBuf;

monitor.GetPckgAttribute(

        connectionId,

        0,

        KBearerGroupInfo,

        bearerGroupInfoBuf,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



TBool internal = bearerGroupInfoBuf().iInternal;

TUint bearerGroupMask = bearerGroupInfoBuf().iBearerGroups;



monitor.Close(); // Close RConnectionMonitor object

KWlanSsidNetworks attribute

Used with GetPckgAttribute(). Parameter aConnectionId must be a valid connection ID for an existing WLAN connection, or the bearer specific connection ID EBearerIdWLAN.

This attribute is used to perform a WLAN scan for networks with a specific SSID. The SSID is set with the string attribute KWlanSsid. If the SSID is empty (default), a normal broadcast scan is made. The request works the same way as package attribute KWlanNetworks, but multiple simultaneous SSID scan requests from one client are not allowed. Any extra concurrent requests are completed with error code KErrInUse. The information is transferred through a package (see CConnMonWlanNetworksPtrArrayPckg). The package class has a buffer that the client needs to allocate memory for. The buffer is filled with WLANs sorted by signal strength, strongest network first. The buffer also contains the total amount of available WLANs and how many of those fit inside the buffer.

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;



monitor.ConnectL(); // Open RConnectionMonitor object



// Buffer for WLAN information

CConnMonWlanNetworksPtrArrayPckg* wlanBuf =

        new( ELeave ) CConnMonWlanNetworksPtrArrayPckg( 1024 );

TPtr wlanPtr( wlanBuf->Buf()->Des() );



// String attribute for SSID scan

TBuf<32> ssidString;

ssidString.Copy( _L("MyWlan") );



TInt error = monitor.SetStringAttribute(

        EBearerIdWLAN,

        0,

        KWlanSsid,

        ssidString );

if ( error != KErrNone ) { /* error */ }



monitor.GetPckgAttribute(

        EBearerIdWLAN,

        0,

        KWlanSsidNetworks,

        wlanPtr,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



RConnMonWlanNetworksPtrArray wlanPtrArray;

wlanBuf->UnpackToL( wlanPtrArray );



// Amount of WLANs found

TUint totalAmount = wlanBuf->Buf()->Des()[0];

// Amount of WLANs that fit inside the buffer

TUint bufferAmount = wlanBuf->Buf()->Des()[1];



for ( TInt i = 0; i < wlanPtrArray.Count(); i++ )

    {

    TBuf<CConnMonWlanNetwork::KMaxNameLength> wlanName = wlanPtrArray[i]->Name();

    TBuf8<CConnMonWlanNetwork::KWlanBssId> wlanBssid = wlanPtrArray[i]->WlanBssid();

    TUint wlanConnectionMode = wlanPtrArray[i]->ConnectionMode();

    TUint wlanSignalStrength = wlanPtrArray[i]->SignalStrength();

    TUint wlanSecurityMode = wlanPtrArray[i]->SecurityMode();



    // ...

    delete wlanPtrArray[i];

    }

wlanPtrArray.Close();

delete wlanBuf;



monitor.Close(); // Close RConnectionMonitor object

KWlanCurrentNetwork attribute

Used with GetPckgAttribute(). Parameter aConnectionId must be a valid connection ID for an existing WLAN connection, or the bearer specific connection ID EBearerIdWLAN.

This attribute is used to retrieve information about the currently used WLAN. The request works the same way as package attribute KWlanNetworks. The information is transferred through a package (see CConnMonWlanNetworksPtrArrayPckg). The package class has a buffer that the client needs to allocate memory for, but it only needs enough memory to contain one WLAN object. If the connection ID given as parameter is for an existing connection, the request succeeds only if that connection is using WLAN bearer. In case the connection ID is invalid or the connection bearer is not WLAN, the request is completed with KErrArgument. If the connection ID given as parameter is EBearerIdWLAN, the request succeeds if there is a WLAN connection active. If not, the request is completed with KErrNotFound.

Retrieving information about currently used WLAN using the bearer specific connection ID:

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;



monitor.ConnectL(); // Open RConnectionMonitor object



// Buffer for WLAN information

CConnMonWlanNetworksPtrArrayPckg* currentWlanBuf =

        new( ELeave ) CConnMonWlanNetworksPtrArrayPckg( 80 );

TPtr currentWlanPtr( currentWlanBuf->Buf()->Des() );



// Get info for currently used WLAN

monitor.GetPckgAttribute(

        EBearerIdWLAN,

        0,

        KWlanCurrentNetwork,

        currentWlanPtr,

        status );

User::WaitForRequest( status );

if ( status.Int() == KErrNotFound ) { /* No WLAN connection active */ }

else if ( status.Int() != KErrNone ) { /* Error */ }

else

    {

    // Process the results

    RConnMonWlanNetworksPtrArray currentWlan;

    currentWlanBuf->UnpackToL( currentWlan );



    // With KWlanCurrentNetwork and no errors, both should be 1

    TUint totalAmount = currentWlanBuf->Buf()->Des()[0];

    TUint bufferAmount = currentWlanBuf->Buf()->Des()[1];



    for ( TInt i = 0; i < currentWlan.Count(); i++ )

        {

        TBuf<CConnMonWlanNetwork::KMaxNameLength> name = currentWlan[i]->Name();

        TBuf8<CConnMonWlanNetwork::KWlanBssId> bssid = currentWlan[i]->WlanBssid();

        TUint connectionMode = currentWlan[i]->ConnectionMode();

        TUint signalStrength = currentWlan[i]->SignalStrength();

        TUint securityMode = currentWlan[i]->SecurityMode();



        // ...

        delete currentWlan[i];

        }

    currentWlan.Close();

    }

delete currentWlanBuf;



monitor.Close(); // Close RConnectionMonitor object

Retrieving information about currently used WLAN using a connection specific connection ID:

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;

TUint connectionCount( 0 );

TUint subConnectionCount( 0 );

TUint connectionId( 0 );



monitor.ConnectL(); // Open RConnectionMonitor object



// Get connection count

monitor.GetConnectionCount(

        connectionCount,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }

if ( connectionCount == 0 ) { /* No connection */ }



// Get connection info (1st connection)

TInt error = monitor.GetConnectionInfo(

        1,

        connectionId,

        subConnectionCount );

if ( error != KErrNone ) { /* Error */ }



// Buffer for WLAN information, need space for only 1 WLAN

CConnMonWlanNetworksPtrArrayPckg* currentWlanBuf =

        new( ELeave ) CConnMonWlanNetworksPtrArrayPckg( 80 );

TPtr currentWlanPtr( currentWlanBuf->Buf()->Des() );



// Get info for currently used WLAN

monitor.GetPckgAttribute(

        connectionId,

        0,

        KWlanCurrentNetwork,

        currentWlanPtr,

        status );

User::WaitForRequest( status );

if ( status.Int() == KErrArgument ) { /* Bad connection ID or bearer was not WLAN */ }

else if ( status.Int() != KErrNone ) { /* Error */ }

else

    {

    // Process the results

    RConnMonWlanNetworksPtrArray currentWlan;

    currentWlanBuf->UnpackToL( currentWlan );



    // With KWlanCurrentNetwork and no errors, both should be 1

    TUint totalAmount = currentWlanBuf->Buf()->Des()[0];

    TUint bufferAmount = currentWlanBuf->Buf()->Des()[1];



    if ( bufferAmount == 1 )

        {

        TBuf<CConnMonWlanNetwork::KMaxNameLength> name = currentWlan[0]->Name();

        TBuf8<CConnMonWlanNetwork::KWlanBssId> bssid = currentWlan[0]->WlanBssid();

        TUint connectionMode = currentWlan[0]->ConnectionMode();

        TUint signalStrength = currentWlan[0]->SignalStrength();

        TUint securityMode = currentWlan[0]->SecurityMode();



        // ...

        delete currentWlan[0];

        }

    currentWlan.Close();

    }

delete currentWlanBuf;



monitor.Close(); // Close RConnectionMonitor object

KWlanProbeRawBuffers attribute

Used with GetPckgAttribute(). Parameter aConnectionId must be a valid connection ID for an existing WLAN connection, or the bearer specific connection ID EBearerIdWLAN.

This attribute is used to perform a broadcast WLAN scan and retrieve the beacon frames for found WLANs. The information is transferred through a package (see CConnMonWlanProbeRawBuffersPckg). The package class has a buffer that the client needs to allocate memory for. The buffer is filled with WLAN beacon frames in no specific order, until all frames are entered, or the buffer runs out of space. The buffer also contains the total amount of available WLANs and the amount of beacon frames that fit inside the buffer. The size of a beacon frame is usually somewhere between 60 and 300 bytes. It consists of a fixed length header and a variable length body.

#include <rconnmon.h>

RConnectionMonitor monitor;

TRequestStatus status;



monitor.ConnectL(); // Open RConnectionMonitor object



// Buffer for WLAN beacon frame information

CConnMonWlanProbeRawBuffersPckg* wlanBeaconsBuf =

        new( ELeave ) CConnMonWlanProbeRawBuffersPckg( 4096 );

TPtr8 wlanBeaconsPtr( wlanBeaconsBuf->Buf()->Des() );



monitor.GetPckgAttribute(

        EBearerIdWLAN,

        0,

        KWlanProbeRawBuffers,

        wlanBeaconsPtr,

        status );

User::WaitForRequest( status );

if ( status.Int() != KErrNone ) { /* Error */ }



// Amount of WLAN networks found

TUint totalAmount = wlanBeaconsBuf->Total();

// Amount of beacon frames that fit inside the buffer

TUint bufferAmount = wlanBeaconsBuf->Count();



RConnMonWlanProbeRawBuffersPtrArray wlanBeaconsPtrArray;

wlanBeaconsBuf->UnpackToL( wlanBeaconsPtrArray );



for ( TInt i = 0; i < wlanBeaconsPtrArray.Count(); i++ )

    {

    CConnMonWlanProbeRawBuffer* beacon( wlanBeaconsPtrArray[i] );

    TInt beaconLength = beacon->RawBuffer()->Length();



    TInt ieCount = 0; // Number if IEs

    TInt ieId = 0;

    TInt ieLength = 0;

    // Header is 36 bytes, body (Information Elements) starts at position 36

    TInt index = 36;



    while ( index < beaconLength )

        {

        ieCount++;

        ieId = beacon->RawBuffer()->Des()[index++];

        ieLength = beacon->RawBuffer()->Des()[index++];

        index += ieLength;

        // ...

        }

    if ( index != beaconLength ) { /* error */ }

    // ...

    delete beacon;

    }

wlanBeaconsPtrArray.Close();

delete wlanBeaconsBuf;



monitor.Close(); // Close RConnectionMonitor object

Error handling

Connection Monitor Server may return Symbian OS generic error codes, and it uses them according to the Symbian OS conventions. The following table contains the most common ConnMon error codes and a likely explanation of the cause.

Memory overhead

The memory overhead caused by the usage of the interface is negligible. It is highest when using WLAN scanning related functionality, about 16 Kbytes at its peak.

Extensions to the API

Connection Monitor Server API has been designed to be extensible with new query attributes and notifications without breaking the binary compatibility in clients. However, it requires that the clients can handle the unrecognized notifications. That can be done, for example, by ignoring them.

Error code	Likely explanation
`KErrNotFound`	A request was made with an invalid connection ID parameter, or the connection has already closed.
`KErrCancel`	A request has been cancelled by the client, and ConnMon completed it with `KErrCancel`.
`KErrNoMemory`	There was not enough free memory in the system to complete an operation.
`KErrNotSupported`	The requested functionality is not supported by ConnMon.
`KErrArgument`	A request was made with a bad attribute/connection ID combination.