S60 Connection Monitor Server API Specification C: Using RConnectionMonitor

S60 Connection Monitor Server API Specification C: Using RConnectionMonitor

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.

Attribute query and setting and event notification operations

A client application gets and sets attribute values from/to Connection Monitor Server by using the methods provided by the RConnectionMonitor class.

The client needs to implement the MConnectionMonitorObserver class to receive events from Connection Monitor server. It has one pure virtual method:

virtual void EventL(const CConnMonEventBase& aConnMonEvent) = 0

It is called by the Connection Monitor Server Client API when it needs to notify the client application about an event. Note that the RConnectionMonitor object providing the events must not be closed or destroyed inside the EventL() method.

The CConnMonEventBase class is the base class for all Connection Monitor Server events. It inherits from the CBase class. It has two methods to identify the connection and the type of the event.

IMPORT_C TInt EventType(void) const: Returns the Connection Monitor Server event type.

IMPORT_C TUint ConnectionId(void) const: Returns the connection ID of the connection that this event applies to.

The client must register itself to the server to be able to receive events.

Connecting to Connection Monitor Server

For establishing a connection to Connection Monitor Server. It has to be called first when starting to use Connection Monitor Server. Returns KErrNone if the operation is successful, and otherwise leaves.

IMPORT_C TInt ConnectL(void)

Closing a connection to Connection Monitor Server

For closing the connection to Connection Monitor Server.

IMPORT_C void Close(void)

Fetching the number of connections

For fetching the number of current data connections. This method has to be called before calling GetConnectionInfo(). It can be cancelled with CancelAsyncRequest(EConnMonGetConnectionCount). Note that this method returns the number of connections known by Connection Monitor Server regardless of their state. For example, a connection that is being activated at the moment of the method call (but whose activation may fail) is counted in.

IMPORT_C void GetConnectionCount(TUint& aConnectionCount, TRequestStatus& aStatus)

Parameter	Explanation
`TUint& aConnectionCount`	On completion, contains the number of connections.
`TRequestStatus& aStatus`	On completion, contains an error code (or `KErrNone`).

Fetching basic connection information

For getting the connection ID of a single connection and the number of its sub-connections. GetConnectionCount() must be called to gather the information on active connections before calling this method. This method has to be called before getting or setting any attribute values for any connection. Note that the connection information is actually gathered already at the time of the GetConnectionCount() method call and therefore the client has to be prepared to receive KErrNotFound when this is called. That happens if the connection has been deleted between calling GetConnectionCount() and GetConnectionInfo().

IMPORT_C TInt GetConnectionInfo(const TUint aIndex, TUint& aConnectionId, TUint& aSubconnectionCount)

Parameter	Explanation
`const TUint aIndex`	A number between 1 and `aConnectionCount` received with the `GetConnectionCount` method. This number does not remain the same during the lifetime of the connection and it must not be used to refer to a certain connection.
`TUint& aConnectionId`	On return, contains the connection ID of the connection. The connection ID can be used as a reference to the connection and it remains the same during the lifetime of the connection. The value 0 is reserved for notifications that apply to all connections (not currently used).
`TUint& aSubconnectionCount`	On return, contains the number of sub-connections.

Fetching basic sub-connection information

For getting the sub-connection ID of a single connection. This method is not needed if there are no sub-connections used or if sub-connections exist but do not need to be monitored. Note that sub-connections are not currently supported.

IMPORT_C TInt GetSubconnectionInfo(const TUint aConnectionId, const TUint aIndex, TUint& aSubconnectionId)

Parameter	Explanation
`const TUint aConnectionId`	Connection identifier.
`const TUint aIndex`	A number between 1 and `aSubconnectionCount` received with the `GetConnectionInfo` method. This number does not remain the same during the lifetime of the sub-connection and it must not be used to refer to a certain sub-connection.
`TUint& aSubconnectionId`	On return, contains the sub-connection ID of the connection. The sub-connection ID can be used as a reference to the sub- connection. The sub-connection ID is unique within the connection and it remains the same during the lifetime of the connection.

Fetching the integer attribute

For fetching the value for the TInt type attribute. It can be cancelled with CancelAsyncRequest(EConnMonGetIntAttribute).

IMPORT_C void GetIntAttribute(const TUint aConnectionId, const TUint aSubconnectionId, const TUint aAttribute, TInt& aValue, TRequestStatus& aStatus)

Parameter	Explanation
`const TUint aConnectionId`	Connection identifier.
`const TUint aSubconnectionId`	Sub-connection identifier. If this is set to 0, the method applies to the connection, otherwise to the sub-connection.
`const TUint aAttribute`	Identifies the attribute to be retrieved.
`TInt& aValue`	On completion, contains the value of the retrieved attribute.
`TRequestStatus& aStatus`	On completion, contains an error code (or `KErrNone`).

Fetching the unsigned integer attribute

For fetching the value for the TUint type attribute. Can be cancelled with CancelAsyncRequest(EConnMonGetUintAttribute).

IMPORT_C void GetUIntAttribute(const TUint aConnectionId, const TUint aSubconnectionId, const TUint aAttribute, TUint& aValue, TRequestStatus& aStatus)

Parameter	Explanation
`const TUint aConnectionId`	Connection identifier.
`const TUint aSubconnectionId`	Sub-connection identifier. If this is set to 0, the method applies to the connection, otherwise to the sub-connection.
`const TUint aAttribute`	Identifies the attribute to be retrieved.
`TUint& aValue`	On completion, contains the value of the retrieved attribute.
`TRequestStatus& aStatus`	On completion, contains an error code (or `KErrNone`).

Fetching the Boolean attribute

For fetching the value for the TBool type attribute. Can be cancelled with CancelAsyncRequest(EConnMonGetBoolAttribute).

IMPORT_C void GetBoolAttribute(const TUint aConnectionId, const TUint aSubconnectionId, const TUint aAttribute, TBool& aValue, TRequestStatus& aStatus)

Parameter	Explanation
`const TUint aConnectionId`	Connection identifier.
`const TUint aSubconnectionId`	Sub-connection identifier. If this is set to 0, the method applies to the connection, otherwise to the sub-connection.
`const TUint aAttribute`	Identifies the attribute to be retrieved.
`TBool& aValue`	On completion, contains the value of the retrieved attribute.
`TRequestStatus& aStatus`	On completion, contains an error code (or `KErrNone`).

Fetching the string attribute

For fetching the value for the string attribute. Can be cancelled with CancelAsyncRequest(EConnMonGetStringAttribute). The client is responsible for allocating and freeing the memory for the string. The maximum size of the string is 50 characters.

IMPORT_C void GetStringAttribute(const TUint aConnectionId, const TUint aSubconnectionId, const TUint aAttribute, TDes& aValue, TRequestStatus& aStatus) const

Parameter	Explanation
`const TUint aConnectionId`	Connection identifier.
`const TUint aSubconnectionId`	Sub-connection identifier. If this is set to 0, the method applies to the connection, otherwise to the sub-connection.
`const TUint aAttribute`	Identifies the attribute to be retrieved.
`TDes& aValue`	On completion, contains the value of the retrieved attribute.
`TRequestStatus& aStatus`	On completion, contains an error code (or `KErrNone`).

Fetching the package buffer attribute

For fetching the data structure represented by a descriptor in a type-safe way. The package buffer attributes are type defined and the type definitions can be found in Section 4.1.4. Can be cancelled with CancelAsyncRequest(EConnMonGetPckgAttribute).

IMPORT_C void GetPckgAttribute( const TUint aConnectionId, const TUint aSubConnectionId, const TUint aAttribute, TDes8& aValue, TRequestStatus& aStatus ) const

Parameter	Explanation
`const TUint aConnectionId`	Connection identifier.
`const TUint aSubconnectionId`	Sub-connection identifier. If this is set to 0, the method applies to the connection, otherwise to the sub-connection.
`const TUint aAttribute`	Identifies the attribute to be retrieved.
`TDes8& aValue`	On completion, contains the value of the retrieved attribute.
`TRequestStatus& aStatus`	On completion, contains an error code (or `KErrNone`).

Fetching the package buffer attributes KWLANetworks or KSNAPsAvailability

Requesting of the mentioned attributes use the same API, but allows extended functionality, e.g. dynamic length data exchange. The meaning of the parameters are a bit different. The package buffer attributes are type defined. and Can be cancelled with CancelAsyncRequest(EConnMonGetPckgAttribute).

IMPORT_C void GetPckgAttribute( const TUint aAny, const TUint aBufferSize, const TUint aAttribute, TDes& aValue, TRequestStatus& aStatus ) const

Parameter	Explanation
`const TUint aAny`	The parameter is not taken into account.
`const TUint aBufferSize`	Size of the buffer, transferred to a server for fetching data.
`const TUint aAttribute`	Identifies the attribute to be retrieved.
`TDes& aValue`	Buffer for the requested data. On completion, contains the value of the retrieved attribute.
`TRequestStatus& aStatus`	On completion, contains an error code (or `KErrNone`).

Note: this is not a new function in the API. Its name, types and amount of the parameters the same, as of previously used function. Connection Monitor Server itself will separate calls, if there is need, to interpret parameters differently.

Setting the value for the integer attribute

For setting the value for the TInt type attribute. Returns an error code or KErrNone.

IMPORT_C TInt SetIntAttribute(const TUint aConnectionId, const TUint aSubconnectionId, const TUint aAttribute, const TInt aValue) const

Parameter	Explanation
`const TUint aConnectionId`	Connection identifier.
`const TUint aSubconnectionId`	Sub-connection identifier. If this is set to 0, the method applies to the connection, otherwise to the sub-connection.
`const TUint aAttribute`	Identifies the attribute to be set.
`const TInt aValue`	The value to be set for the attribute.

Setting the value for the unsigned integer attribute

For setting the value for the TUint type attribute. Returns an error code or KErrNone.

IMPORT_C TInt SetUIntAttribute(const TUint aConnectionId, const TUint aSubconnectionId, const TUint aAttribute, const TUint aValue) const

Parameter	Explanation
`const TUint aConnectionId`	Connection identifier.
`const TUint aSubconnectionId`	Sub-connection identifier. If this is set to 0, the method applies to the connection, otherwise to the sub-connection.
`const TUint aAttribute`	Identifies the attribute to be set.
`const TUint aValue`	The value to be set for the attribute.

Setting the value for the Boolean attribute

For setting the value for the TBool type attribute. Returns an error code or KErrNone.

IMPORT_C TInt SetBoolAttribute(const TUint aConnectionId, const TUint aSubconnectionId, const TUint aAttribute, const TBool aValue) const

Parameter	Explanation
`const TUint aConnectionId`	Connection identifier.
`const TUint aSubconnectionId`	Sub-connection identifier. If this is set to 0, the method applies to the connection, otherwise to the sub-connection.
`const TUint aAttribute`	Identifies the attribute to be set.
`const TBool aValue`	The value to be set for the attribute.

Setting the value for the string attribute

For setting the value for the string attribute. The client is responsible for allocating and freeing the memory for the string. The maximum size of the string is 50 characters. Returns an error code or KErrNone.

IMPORT_C TInt SetStringAttribute(const TUint aConnectionId, const TUint aSubconnectionId, const TUint aAttribute, const TDes& aValue) const

Parameter	Explanation
`const TUint aConnectionId`	Connection identifier.
`const TUint aSubconnectionId`	Sub-connection identifier. If this is set to 0, the method applies to the connection, otherwise to the sub-connection.
`const TUint aAttribute`	Identifies the attribute to be set.
`const TDes& aValue`	The value to be set for the attribute.

Setting the value for the package buffer attribute

For setting the value for the package buffer attribute. Returns an error code or KErrNone.

IMPORT_C TInt SetPckgAttribute(const TUint aConnectionId, const TUint aSubConnectionId, const TUint aAttribute, const TDes8& aValue ) const

Parameter	Explanation
`const TUint aConnectionId`	Connection identifier.
`const TUint aSubconnectionId`	Sub-connection identifier. If this is set to 0, the method applies to the connection, otherwise to the sub-connection.
`const TUint aAttribute`	Identifies the attribute to be set.
`const TDes8& aValue`	The value to be set for the attribute.

Canceling an asynchronous request

Cancels a specific type of the asynchronous request identified by aReqToCancel. Note that all the pending requests of the type aReqToCancel are cancelled.

IMPORT_C void CancelAsyncRequest(TInt aReqToCancel)

Parameter	Explanation
`TInt aReqToCancel`	Identifies the type of the request to be cancelled.

Registering to receive events from Connection Monitor Server

Registers an event observer to catch Connection Monitor Server events. Returns an error code or KErrNone.

IMPORT_C TInt NotifyEventL(MConnectionMonitorObserver& aObserver)

Parameter	Explanation
`MConnectionMonitorObserver& aObserver`	The event observer.

The following events are enabled after NotifyEventL() has been called:

EConnMonCreateConnection
EConnMonDeleteConnection
EConnMonCreateSubConnection (not supported at the moment)
EConnMonDeleteSubConnection (not supported at the moment)
EConnMonNetworkStatusChange
EConnMonConnectionStatusChange
EConnMonNetworkRegistrationChange
EConnMonBearerChange
EconnMonIapAvailabilityChange
EConnMonTransmitPowerChange
EConnMonSNAPsAvailabilityChange

The following events are enabled only when the client has set the threshold that applies to the event:

EConnMonDownlinkDataThreshold

EConnMonUplinkDataThreshold

EConnMonConnectionActivityChange

EConnMonSignalStrengthChange

EConnMonBearerAvailabilityChange

EConnMonBearerInfoChange

EConnMonBearerGroupChange

Canceling event registration

Cancels the notifications. When this method is called, the client application does not receive anymore Connection Monitor Server notifications.

IMPORT_C void CancelNotifications()

New connection created event

Class: CConnMonCreateConnection

A class for EConnMonCreateConnection event. Inherits from CConnMonEventBase. This event is triggered when a new connection is created.

Methods: None.

Connection deleted event

Class: CConnMonDeleteConnection

A class for an EConnMonDeleteConnection event. Inherits from CConnMonEventBase. This event is triggered when an existing connection is deleted. It also means that its sub-connections are deleted.

Methods:

IMPORT_C TUint DownlinkData(void) const:

Returns the amount of data transferred from the network to the mobile during the connection in bytes.
IMPORT_C TUint UplinkData(void) const:

Returns the amount of data transferred from the mobile to the network during the connection in bytes.
IMPORT_C TBool AuthoritativeDelete(void) const:

Returns ETrue, if the user has selected to deactivate the connection using Connection Monitor or if an application has issued RConnection::Stop(RConnection::EStopAuthoritative). Otherwise, (that is, in normal cases) returns EFalse.

New sub-connection created event

Class: CConnMonCreateSubconnection

A class for an EConnMonCreateSubconnection event. It inherits from CConnMonEventBase. This event is triggered when a new sub-connection is created to the existing connection.

Note that sub-connections are not supported at the moment.

Methods:

IMPORT_C TUint SubconnectionId() const:

Returns the sub-connection ID of the sub-connection that this event applies to.

Sub-connection deleted event

Class: CConnMonDeleteSubconnection

A class for an EConnMonDeleteSubconnection event. Inherits from CConnMonEventBase. This event is triggered when a sub-connection is deleted from the existing connection.

Note that sub-connections are not currently supported.

Methods:

IMPORT_C TUint SubconnectionId(void) const:

Returns the sub-connection ID of the sub-connection that this event applies to.
IMPORT_C TUint DownlinkData(void) const:

Returns the amount of data transferred from the network to the device during the sub-connection in bytes.
IMPORT_C TUint UplinkData(void) const:

Returns the amount of data transferred from the device to the network during the sub-connection in bytes.
IMPORT_C TBool AuthoritativeDelete(void) const:

Returns ETrue, if the user has selected to deactivate the sub-connection using Connection Monitor or if an application has issued RConnection::Stop(RConnection::EStopAuthoritative). Otherwise (that is, in normal cases), returns EFalse.

Downlink data threshold exceeded event

Class: CConnMonDownlinkDataThreshold

A class for an EConnMonDownlinkDataThreshold event. Inherits from CConnMonEventBase. This event is triggered when KDownlinkDataThreshold is exceeded. KDownlinkDataThreshold can be set for a (sub-)connection with RConnectionMonitor::SetUIntAttribute() (default value is 0). This event is not supported for external connections.

Methods:

IMPORT_C TUint SubconnectionId(void) const:

Returns the sub-connection ID of the sub-connection that this event applies to.
IMPORT_C TUint DownlinkData(void) const:

Returns the number of bytes transferred to the mobile using the connection (if the sub-connection ID is 0) or sub-connection (if the sub- connection ID is not 0).

Uplink data threshold exceeded event

Class: CConnMonUplinkDataThreshold

A class for an EConnMonUplinkDataThreshold event. Inherits from CConnMonEventBase. This event is triggered when KUplinkDataThreshold is exceeded. KUplinkDataThreshold can be set for a (sub-)connection with RConnectionMonitor::SetUIntAttribute() (default value is 0). This event is not supported for external connections.

Methods:

IMPORT_C TUint SubconnectionId(void) const:

Returns the sub-connection ID of the sub-connection that this event applies to.
IMPORT_C TUint UplinkData(void) const:

Returns the number of bytes transferred from the mobile using the connection (if the sub-connection ID is 0) or the sub-connection (if the sub- connection ID is not 0).

Status of the network changed event

Class: CConnMonNetworkStatusChange

A class for an EConnMonNetworkStatusChange event. Inherits from CConnMonEventBase. This event is triggered when the status of the network changes. The connection ID used in the event is a bearer specific connection ID defined in TConnMonBearerId.

Methods:

IMPORT_C TInt NetworkStatus(void) const:

Returns the new status of the network. The possible status values are enumerated in TConnMonNetworkStatus.

Status of the connection changed event

Class: CConnMonConnectionStatusChange

A class for an EConnMonConnectionStatusChange event. Inherits from CConnMonEventBase. This event is triggered when the status of the connection changes.

Methods:

IMPORT_C TUint SubconnectionId(void) const:

Returns the sub-connection ID of the sub-connection that this event applies to.
IMPORT_C TInt ConnectionStatus(void) const:

Returns the new status of the connection (if the sub-connection ID is 0) or sub-connection (if the sub-connection ID is not 0). The possible status values are defined in the nifvar.h header file, which is a part of the Symbian OS delivery.

Connection activity changed event

Class: CConnMonConnectionActivityChange

A class for an EConnMonConnectionActivityChange event. Inherits from CConnMonEventBase. This event is triggered when the connection changes from active to idle or vice versa.

This event is enabled when KActivityTimeThreshold is > 0 (default is 0). KActivityTimeThreshold can be set with RConnectionMonitor::SetUIntAttribute(). KActivityTimeThreshold is defined in seconds. The allowed minimum is 5 seconds.

The Connection Activity Changed event tells whether any data is passed for a time period defined by the threshold. If data is passed the connection is considered active; otherwise it is considered inactive.

Methods:

IMPORT_C TUint SubconnectionId(void) const:

Returns the sub-connection ID of the sub-connection that this event applies to.
IMPORT_C TBool ConnectionActivity(void) const:

Indicates whether the connection (if the sub-connection ID is 0) or sub-connection (if the sub-connection ID is not 0) is active or idle. The (sub-)connection is active when this method returns ETrue and idle when the return value is EFalse.

Network registration status changed event

Class: CConnMonNetworkRegistrationChange

A class for EConnMonNetworkRegistrationChange event. Inherits from CConnMonEventBase. This event is triggered when network registration status changes. The connection ID used in the event is bearer specific connection ID defined in TConnMonBearerId.

Methods:

IMPORT_C TInt RegistrationStatus(void) const:

Returns the new network registration status. Possible status values are enumerated in TConnMonNetworkRegistration.

Bearer changed event

Class: CConnMonBearerChange

A class for an EConnMonBearerChange event. Inherits from CConnMonEventBase. This event is triggered when the bearer of the connection (or some set of connections) changes, e.g. from GPRS to E-GPRS or from (E-)GPRS to WCDMA. The connection ID used in the event is the bearer specific connection ID that is defined in TConnMonBearerId.

Methods:

IMPORT_C TInt Bearer(void) const:

Returns the new bearer. Possible bearer values are enumerated in TConnMonBearerType.

Signal strength changed event

Class: CConnMonSignalStrengthChange

A class for EConnMonSignalStrengthChange event. Inherits from CConnMonEventBase. This event is triggered when the signal strength of a bearer changes. Connection ID used in the event is bearer specific connection ID defined in TConnMonBearerId.

This event is enabled when KSignalStrengthThreshold is set to 1 (default is 0). KSignalStrengthThreshold can be set with RConnectionMonitor::SetUIntAttribute().

Methods:

IMPORT_C TInt SignalStrength(void) const:

Returns the new signal strength.

Bearer availability changed event

Class: CConnMonBearerAvailabilityChange

A class for EConnMonBearerAvailabilityChange event. Inherits from CConnMonEventBase. This event is triggered when the availability of a bearer changes. Connection ID used in the event is bearer specific connection ID defined in TConnMonBearerId.

This event is enabled when KBearerAvailabilityThreshold is set to 1 (default is 0). KBearerAvailabilityThreshold can be set with RConnectionMonitor::SetUIntAttribute().

Methods:

IMPORT_C TBool Availability(void) const:

Returns the new availability information.

BearerInfo changed

Class: CConnMonBearerInfoChange

A class for EConnMonBearerInfoChange event. Inherits from CConnMonEventBase. This event is triggered in 2 cases:

When the bearer of the connection changes, e.g. from GPRS to E-GPRS or from WCDMA to HSPA and vice versa. The connection ID used in the event is the unique ID of the connection.
When the mode of the network changes e.g. from GSM to WCDMA. The connection ID used in the event is zero.

Methods:

IMPORT_C TInt BearerInfo() const:

Returns the bearer info value defined in TConnMonBearerInfo.

This event is recommended to be used instead of EConnMonBearerChange event. This event is enabled when KBearerGroupThreshold is set to 1 (default is 0). By enabling this event EConnMonBearerGroupChange is enabled too. If the threshold is set to 1 EConnMonBearerChange event is disabled. It is recommended to use this event because this event supports all the new bearers in the future (EConnMonBearerChange does not support even HSDPA).

BearerGroup changed

Class: CConnMonBearerGroupChange

A class for EConnMonBearerGroupChange event. Inherits from CConnMonEventBase. This event is triggered when the BearerInfo changes and the new BearerInfo has different BearerGroup mask. Bearer groups values are defined in TConnMonBearerGroup. This event is connection specific. The connection ID used in the event is the unique ID of the connection.

Methods:

IMPORT_C void BearerGroups( TUint& aBearerGroups1, TUint& aBearerGroups2 ) const:

Returns the bearer masks in the parameters.
IMPORT_C TBool Internal() const:

Returns ETrue if the connection of this event is internal. Returns EFalse if the connection of this event is external (dial-up).

This event is enabled when KBearerGroupThreshold is set to 1 (default is 0).

IAP availability changed event

Class: CConnMonIapAvailabilityChange

A class for EConnMonIapAvailabilityChange event. Inherits from CConnMonEventBase. This event is triggered when the availability of some IAP(s) changes. Connection ID used in the event is EBearerIdAll. This means that all bearers are included when checking the availability of IAPs.

Methods:

IMPORT_C TConnMonIapInfo IapAvailability() const:

Returns information on the currently available IAPs.

Transmit power changed event

Class: CConnMonTransmitPowerChange

A class for EConnMonTransmitPowerChange event. Inherits from CConnMonEventBase. This event is triggered when the used transmit power changes. Connection ID used in the event is bearer specific connection ID defined in TConnMonBearerId.

Methods:

IMPORT_C TUint TransmitPower(void) const:

Returns the new transmit power (mW).

SNAPs availability changed event

Class: CConnMonSNAPsAvailabilityChange

A class for EConnMonSNAPsAvailabilityChange event. Inherits from CConnMonEventBase. This event is triggered when the availability of some SNAP changes. Connection ID used in the event is EBearerIdAll.

Methods:

IMPORT_C TConnMonSNAPsInfo SNAPsAvailability() const:

Returns array of IDs of available SNAPs. Max size of the array is set to KConnMonMaxSNAPCount.

IMPORT_C TUint SNAPsAvailable() const:

Returns amount of available SNAPs. The data exchanging buffer is limited to a maximum of KConnMonMaxSNAPsCount SNAPs’ ids. If the amount of available SNAPs is more than KConnMonMaxSNAPsCount, the value returned by this function will be different than TConnMonSNAPsInfo:iCount. In this case the client can request all available SNAPs by using GetPckgAttribute() with a parameter KSNAPsAvailability.

Generic event for plug-in specific events

Class: CConnMonGenericEvent

A class for plug-in specific events. Inherits from CConnMonEventBase. This event is triggered when a plug-in engine sends an event that is unknown to Connection Monitor Server. Connection ID used in the event is set to the plug-in’s bearer ID defined in TConnMonBearerId. The plug-in module must provide the application a header file that defines the event ID and data.

Methods:

IMPORT_C TAny* Data(void) const:

Returns a pointer to event data.

Examples

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.

RConnectionMonitor monitor;
// open RConnectionMonitor object 
monitor.ConnectL(); 
// close RConnectionMonitor object when it is not needed any more 
monitor.Close();

Getting basic connection level information

// get number of active connections
TUint          count;
TRequestStatus status;
TUint          ids[ 15 ];

monitor.GetConnectionCount( count, status );
User::WaitForRequest( status );
if ( status.Int() != KErrNone )
    {
    // error 
    }

// get connection ids of the active connections
TUint numSubConnections;

for ( TInt i = 1; i <= count; i++ )
    {
    TInt ret = monitor.GetConnectionInfo( i, ids[ i-1 ], numSubConnections );
    if ( ret != KErrNone )
        {
        // error
        }
    }

// get IAP name of the first connection
TBuf< 50 > iapName;

monitor.GetStringAttribute( ids[ 0 ], 0, KIAPName, iapName, status );
User::WaitForRequest( status );
if ( status.Int() != KErrNone )
    {
    // error  
    }

// get amount of downlink data transferred through the first connection
TUint dl( 0 );

monitor.GetUintAttribute( ids[ 0 ], 0, KDownlinkData, dl, status );
User::WaitForRequest( status );
if ( status.Int() != KErrNone )
    {
    // error  
    }

// get bearer of the first connection
TInt bearer( 0 );

monitor.GetIntAttribute( ids[ 0 ], 0, KBearer, bearer, status );
User::WaitForRequest( status );
if ( status.Int() != KErrNone )
    {
    // error  
    }

// Get the BearerInfo of the first connection
TInt bearerInfo( 0 );

monitor.GetIntAttribute( ids[ 0 ], 0, KBearerInfo, bearerInfo, status );
User::WaitForRequest( status );
if ( status.Int() != KErrNone )
    {
    // error  
    }

Using GetPckgAttribute

// get start time of the first connection
TConnMonTimeBuf timeBuf;

monitor.GetPckgAttribute(  ids[ 0 ],  0, KStartTime, timeBuf, status );
User::WaitForRequest( status ) ;	
if ( status.Int() != KErrNone )
    {
    // error
    }
else
    {		
    // calculate duration of the connection in seconds
    TTimeIntervalSeconds durationInSeconds;
    TTime                now;

    now.UniversalTime();
    now.SecondsFrom( timeBuf(), durationInSeconds ); 
    }

// get count and UIDs of applications using the first connection
TConnMonClientEnumBuf clientBuf;

monitor.GetPckgAttribute( ids[ 0 ], 0, KClientInfo, clientBuf, status );
User::WaitForRequest( status );	
if ( status.Int() != KErrNone )
    {
    // error
    }
else
    {
    // get count of the clients using the connection
    TUint countClients = clientBuf().iCount;

    // get uid of the first client (max 10 uids in the array)
    TUid uid = clientBuf().iUid[ 0 ];
    }

// get all available IAPs
TConnMonIapInfoBuf iapBuf;

monitor.GetPckgAttribute(  EBearerIdAll,  0, KIAPAvailability, iapBuf, status );
User::WaitForRequest( status ) ;	

if ( status.Int() != KErrNone )
    {
    // error
    }
else
    {
    TInt countIaps = iapBuf().iCount;

    // Get the IAPId of the first IAP in the buffer.
    TInt iapId = iapBuf().iIap[ 0 ].iIapId;
    }

// Get the bearer group mask of the first connection
TConnMonBearerGroupInfoBuf groupInfoBuf;

monitor.GetPckgAttribute( ids[ 0 ], 
                          0, 
                          KBearerGroupInfo, 
                          groupInfoBuf, 
                          status );
User::WaitForRequest( status );

TBool internal = groupInfoBuf().iInternal;
TUint bearerGroups1 = groupInfoBuf().iBearerGroups;
TUint bearerGroups2 = groupInfoBuf().iBearerGroups2;

Using GetPckgAttribute for requesting KWlanNetworks

// defines buffer of size of 512 TChars; 
// client application sets the needed buffer size.
// min. value is 2, otherwise KErrArgument is returned.
CConnMonWlanNetworksPtrArrayPckg arr(512);

// make modifiable descriptor
TPtr ptr(arr.Buf()->Des()); 
monitor.GetPckgAttribute( EBearerIdAll,  // some parameter	
                          0,             // SubConnection Id
                          KWlanNetworks, // specify the request
                          ptr,			     // buffer for writing data
                          status );
// after completion, arr is filled with data
User::WaitForRequest( status );
TUint pointer(0);
// amount of array items totally to be transferred
TUint total(arr.Buf()[pointer++]);
// amount of actually received items
TUint count(arr.Buf()[pointer]);

if(total != count)
    {
    // not all data is received
    // act accordingly to a client's needs
    // for example, re-request the same data with bigger buffer size 
    // can be calculated exactly, by using “total” value
    }
	
// unpack data to an array
RConnMonWlanNetworksPtrArray wlanNetworks;

// here buffer will be converted to an array
arr.UnpackToL(wlanNetworks);

for(TUint i(0); i < wlanNetworks.Count(); i++)
    {
    CConnMonWlanNetwork* net( wlanNetworks[i] );
    // use net here
    }

Using GetPckgAttribute for requesting KSNAPsAvailability

// defines buffer of size of max. 512 TChars;
// client application sets the needed buffer size.
ConnMonSNAPsArrayPckg arr(512);

// make modifiable descriptor
TPtr ptr(arr.Buf()->Des()); 
monitor.GetPckgAttribute( EBearerIdAll, // some parameter
                          0, // pass the size of buffer
                          KSNAPsAvailability, // specify the request
                          ptr,	// buffer for writing data
                          status );
// after completion, arr is filled with data
User::WaitForRequest( status );
TUint pointer(0);

// amount of array items totally to be transferred
TUint total(arr.Buf()[pointer++]);

// amount of actually received items
TUint count(arr.Buf()[pointer]);

if(total != count)
    {
    // not all data is received
    // act accordingly to the client's needs
    // for example, re-request the same data with 
    // bigger buffer size (can be calculated exactly, by using “total” value)
    }
// unpack data to an array
RConnMonSNAPsArray sNAPs;
// here buffer will be converted to an array
arr.UnpackToL(sNAPs);

for(TUint i(0); i < sNAPs.Count(); ++i)
    {
    TConnMonId id(sNAPs[i]);
    // use SNAP’s id here
    }

Stopping a connection

// stop the first connection
TInt ret = monitor.SetBoolAttribute( ids[ 0 ], 
                                     0, 
                                     KConnectionStop, 
                                     ETrue );
if ( ret != KErrNone )
    {
    // error
    }

Getting network level information

// get registration status of a network
TInt registrationStatus( 0 );

monitor.GetIntAttribute( EBearerIdGSM,  // See bearer ids from TConnMonBearerId
                         0, 
                         KNetworkRegistration, 
                         registrationStatus, 
                         status );
User::WaitForRequest( status );
if ( status.Int() != KErrNone )
    {
    // error  
    }

// get status of a PSD network
TInt netwStatus;

monitor.GetIntAttribute( EBearerIdGPRS, // See bearer ids from TConnMonBearerId
                         0, 
                         KNetworkStatus, 
                         netwStatus, 
                         status );
User::WaitForRequest( status );
if ( status.Int() != KErrNone )
    {
    // error  
    }

Registering for events

// register for events. iObserver is an instance of the class that implements 
// the event handler.
monitor.NotifyEventL( iObserver );

…

// events must be cancelled and RConnectionMonitor
// object closed when not needed any more.
monitor.CancelNotifications();

Catching events

class MyClass : public MyBaseClass, private MConnectionMonitorObserver
    {
    private:
    void EventL( const CConnMonEventBase& aEvent );
    …
    }

void MyClass::EventL( const CConnMonEventBase& aEvent )
    {
    switch( aEvent.EventType() )
        {
        case EConnMonCreateConnection:
            {
            CConnMonCreateConnection* eventCreate; 
            eventCreate = (CConnMonCreateConnection*)& aEvent
            TUint connectionId = eventCreate->ConnectionId();
            break;
            }
        case EConnMonDeleteConnection:
            {
            CConnMonDeleteConnection* eventDelete; 
            eventDelete = (CConnMonDeleteConnection*)& aEvent
            TUint connectionId  = eventDelete->ConnectionId();
            TUint totalDlVolume = eventDelete->DownlinkData();
            TUint totalUlVolume = eventDelete->UplinkData();
            TBool authDelete    = eventDelete->AuthoritativeDelete();
            break;
            }
        case EConnMonDownlinkDataThreshold:
            {
            CConnMonEventDownlinkDataThreshold *eventDlData;
            eventDlData = (CConnMonEventDownlinkDataThreshold*)& aEvent
            TUint connectionId = eventDlData->ConnectionId();
            TUint dlVolume     = eventDlData->DownlinkData();
            break;
            }
        case EConnMonNetworkRegistrationChange:
            {
            CConnMonNetworkRegistrationChange* eventNwReg;
            eventNwReg = (CConnMonNetworkRegistrationChange*)& aEvent
            // Get id of the network. See. TConnMonBearerId
            TUint bearerId    = eventNwReg->ConnectionId();
            Tint  nwRegStatus = eventNwReg->RegistrationStatus();
            break;
            }
        case EConnMonBearerInfoChange:
            {
            CConnMonBearerInfoChange* eventBearerInfo;
            eventBearerInfo = (CConnMonBearerInfoChange*)& aEvent
            TUint ConnectioId = eventBearerInfo->ConnectionId();
            TInt bearerInfo = eventBearerInfo->BearerInfo();
            break;
            }
        case EConnMonBearerGroupChange:
            {
            CConnMonBearerGroupChange* eventBearerInfo;
            eventBearerGroup = (CConnMonBearerGroupChange*)& aEvent
            TUint ConnectioId = eventBearerGroup->ConnectionId();
            TUint bearerGroups1( 0 );
            TUint bearerGroups2( 0 );
            eventBearerGroup->BearerGroups( bearerGroups1, bearerGroups2 );
            break;
            }
        case EConnMonSNAPsAvailabilityChange:
            {
            CConnMonSNAPsAvailabilityChange* eventSNAPsAvailChange;
            eventSNAPsAvailChange = (CConnMonSNAPsAvailabilityChange*)& aEvent
            // amount of ids, really available on server side
            TUint totalSNAPs(eventSNAPsAvailChange->SNAPsAvailable());
            if(totalSNAPs != eventSNAPsAvailChange->SNAPsAvailability().iCount)
                {
                // not all SNAPs Ids have been received
                // act accordingly to a client’s needs
                // for example, request SNAP’s ids by using GetPckgAttribute, 
                // and specifying bigger buffer (exact size of needed buffer 
                // can be calculated by using totalSNAPs value)
                }
            // here could be “else” – but this is just an example
            for(TUint i(0);i< eventSNAPsAvailChange->SNAPsAvailability().iCount;++i)
                {
                TUint SNAPId(eventSNAPsAvailChange->SNAPsAvailability().iSNAP[i]);
                // process SNAP’s id		
                } 
            break;
            }
        default:
        // for future events, unrecognized events must not crash application
        break;
        }
    }

Error handling

Connection Monitor Server may return Symbian OS generic error codes, and it uses them according to the Symbian OS conventions. Connection Monitor clients should be prepared to handle the following errors:

Error Code	Explanation
`KErrNotFound`	The connection or sub-connection does not exist. The client should not use the connection ID or the sub-connection ID anymore.
`KErrServerBusy`	All the message slots in Connection Monitor Server are occupied. The client should not make new requests until the pending ones return. It should be noted that having more than six pending requests may block events from getting to the client.
`KErrNoMemory`	Connection Monitor Server could not carry out the client’s request because there was insufficient amount of memory available. The client may want to display an Error message so that the user can close some applications to free memory.
`KErrNotSupported`	Connection Monitor Server does not support the attribute that the client requested.

Memory overhead

Memory overhead caused by the usage of the interface is negligible.

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.