Connection Settings API Specification

Contents 1 Overview 1.1 Description 1.2 Changes 1.3 Use Cases 1.4 Class Structure 2 Using The API 2.1 Creating, modifying and deleting a Destination 2.2 Reading the list of existing Destinations 2.3 Creatign, copying, moving, removing and deleting a Connection Method 2.4 Reading the list of existing Connection Methods 2.5 Reading the existing Connection Methods in a Destination 2.6 Reading and writing the attributes of a Connection Method 2.7 Reading the attributes of a bearer type 2.8 Handling of an Embedded Destination 2.9 Error handling 2.10 Memory and Performance Considerations 2.11 Limitations of the API 2.12 Security issues 3 Glossary 3.1 Abbreviations 3.2 Definitions

1 Overview

The Connection Settings API provides access to Destinations and Connection Methods. Destinations and Connection Methods are the basic components of the Bearer Mobility concept. Bearer Mobility enables automatic selection of the most appropriate access technology (bearer type) in a certain situation or environment, and roaming between access technologies, thus providing the always-on experience from the end-user point-of-view.

API category	public
API type	c++
Existed since	Legacy S60 3.2
API libraries	cmmanager.lib
Location	/sf/mw/ipconnmgmt/ipcm_pub/connection_settings_api
Buildfiles	/sf/mw/ipconnmgmt/ipcm_pub/connection_settings_api/group/bld.inf

1.1 Description

Bearer Mobility becomes concrete on the UI level through the destination network perspective. Instead of explicit Internet Access Point (IAP) association, the application can ask for a connection to a certain destination, for exmaple Internet or Intranet. Each destination can contain numerous access technologies that can be used to reach the destination or service domain in question. When a connection to a destination is being established, the device can automatically select the best connection method available, and roam between the connection methods defined inside that particular destination.

The Connection Settings API provides access functions to

• read existing Destinations and Connection Methods
• read the attributes of Connection Methods
• read the attributes of a bearer type
• create, delete, move and copy Destinations and Connection Methods
• Access functions to write attributes to Destinations and Connection Methods.

The connection Method Manager runs in the process of the client application. All the methods in the API are synchronous. Some UI related methods such as querying a bearer icon ( ECmBearerIcon ) requires UI context from the client application.

1.2 Changes

The Connection Settings API is an SDK API and introduced in Symbian OS, S60 5.1.

1.3 Use Cases

• Creating, modifying and deleting a Destination
• Reading the list of existing Destinations
• Creating, copying, moving, removing and deleting a Connection Method
• Reading the list of existing Connection Methods
• Reading the existing Connection Methods in a Destination
• Reading and writing the attributes of a Connection Method
• Reading the attributes of a bearer type
• Handling of Embedded Destination

1.4 Class Structure

Summary of API classes and header files

Classes	Files

CCmSettingsUi /epoc32/include/mw/cmsettingsui.h RCmConnectionMethod /epoc32/include/mw/cmconnectionmethod.h RCmDestination /epoc32/include/mw/cmdestination.h RCmManager /epoc32/include/mw/cmmanager.h TBearerPriority /epoc32/include/mw/cmmanagerdef.h No classes/epoc32/include/mw/cmconnectionmethod.inl, /epoc32/include/mw/cmconnectionmethoddef.h, /epoc32/include/mw/cmdefconnvalues.h, /epoc32/include/mw/cmgenconnsettings.h, /epoc32/include/mw/cmmanager.inl, /epoc32/include/mw/cmplugincsddef.h, /epoc32/include/mw/cmplugindialcommondefs.h, /epoc32/include/mw/cmpluginembdestinationdef.h, /epoc32/include/mw/cmpluginhscsddef.h, /epoc32/include/mw/cmpluginpacketdatadef.h, /epoc32/include/mw/cmplugintundriverdef.h, /epoc32/include/mw/cmpluginvpndef.h, /epoc32/include/mw/cmpluginwlandef.h

The diagram below contains only the relevant details of the types of Connection Settings API. The full reference can be found in the header files.

RCmManager is a general interface to the Connection Method Manager. It can be used to:

• Get the bearer specific information, for exmaple use ECmBearerHasUi to query if a bearer type has a UI dialog for the settings or not.
• Get the Connection Method specific information such as ECmBearer type to query the bearer type of the Connection Method.
• Get the Connection Method or a list of Connection Methods using ConnectionMethodL.
• Get the a list of Destinations using AllDestinationsL.
• Read and change the priority values of the Connection Methods in Destination.
• Read and write the Default Connection.
• Create a Destination.
• Create, move, remove, copy and delete a Connection Method.

RCmDestination is a representation of a Destination. It can be used to:

• Get and set the information of the Destination.
• Get the Name, ID, icon, protection, hidden value and connection status.
• Get the Metadata information.
• Get the count of Connection Methods
• Get a Connection Method (in this Destination)
• Get a priority of a Connection Method
• Create a Connection Method (to this Destination)
• Add a Connection Method (to this Destination)
• Remove and delete a Connection Method (from this Destination)
• Modify the priority of a Connection Method
• Add an Embedded Destination

RCmConnectionMethod is a representation of a Connection Method. It can be used to:

• Get and set the attributes of the Connection Methods.
• Create copy of the Connection Method.
• Delete the Connection Method.

The Connection Settings API also contains the following DEF header files, which contain constants and enumerations inside the CMManager namespace. The cmpluginpacketdatadef.h file for the packet data bearer type contains the TConnectionMethodPacketDataSpecificAttributes enumeration type.

Some of these file names refer to plug-ins, such as cmpluginpacketdatadef.h. However, the plug-in architecture (different bearer types are realized as plug-ins in the Connection Method Manager) is hidden for the API clients. Usage of the API does not require any knowledge about the plug-in architecture of Connection Method Manager.

• cmmanagerdef.h
• cmconnectionmethoddef.h
• cmdefconnvalues.h
• cmpluginpacketdatadef.h
• cmplugindialcommondefs.h
• cmplugincsddef.h
• cmpluginhscsddef.h
• cmpluginembdestinationdef.h
• cmpluginvpndef.h
• cmpluginwlandef.h

The rest of the headers contain the type definitions of the RCmManager , RCmDestination and the RCmConnectionMethod classes.

• cmmanager.h contains the type definition of RCmManager
• cmdestination.h contains the type definition of RCmDestination
• cmconnectionmethod.h contains the type definition of RCmConnectionMethod

2 Using The API

cmmanager.lib must be linked to the application before the Connection Settings API is used. Add the following line to the MMP file of the application.

LIBRARY         cmmanager.lib

When using types in The Connection Settings API for getting information about Destinations and Connection Methods, the first step is to open a Connection Method Manager session.

Below is an example of the initialization process of Connection Settings API. Thecmmanager.h header file must be included for using the RCmManager type.

RCmManager cmManager;
cmManager.OpenLC();

The session has to be closed when it is not used any more:
CleanupStack::PopAndDestroy(); // cmManager

2.1 Creating, modifying and deleting a Destination

After the Connection Method Manager is initialized, a Destination can be created in two ways. The recommended way is to call the RCmManager::CreateDestinationL method with the name parameter (there is also another method which has also Destination ID as input parameter). The cmdestination.h header file must be included to use RCmDestination .

//Create a Destination:
RCmDestination destination;

destination = iCmManager.CreateDestinationL( _L("Destination1") );
destination.UpdateL();

//The Destination can be modified, change the name of it in the following way:
destination.SetNameL( _L("Destination2") );
CleanupClosePushL(destinations);
destination.UpdateL();

Delete the destination:
destination.DeleteLD();

2.2 Reading the list of existing Destinations

The list of existing Destination IDs can be queried by invoking the RCmManager::AllDestinationsL method.

The following example shows how to get the Destination ID list. Destination Ids can be used to get the Destination objects.

RArray<TUint32> destinations;
CleanupClosePushL(destinations);

iCmManager.AllDestinationsL(destinations);

The example goes through all the Destinations and retrieves the names of them.

RCmDestination destination;
HBufC *name = NULL;

for(TInt i = 0; i < destinations.Count(); i++)
    {
    destination = iCmManager.DestinationL( destinations(i) );
    CleanupClosePushL(destination);

    name = destination.NameLC();

    CleanupStack::PopAndDestroy(name); // destination.NameLC()
    name = NULL;
    CleanupStack::PopAndDestroy(); // destination
    }

2.3 Creatign, copying, moving, removing and deleting a Connection Method

A Connection Method can be created through

• RCmManager API. In this case, the Connection Method must be added to some Destination or it will be a legacy and put to Uncategorized folder. The cmconnectionmethod.h header file must be included to use RCmConnectionMethod .

RCmConnectionMethod connectionMethod;
connectionMethod = iCmManager.CreateConnectionMethodL( KUidPacketDataBearerType );
destination.Add( connectionMethod );
destination.UpdateL();

• RCmDestination API

connetionMethod = destination.CreateConnectionMethodL( KUidPacketDataBearerType);
destination.UpdateL();

A Connection Method can be copied by using RCmManager API. In the example ID of the Connection Method is known.

RCmConnectionMethod connectionMethod = iCmManager.ConnectionMethodL( cmId );
RCmDestination targetDestination = iCmManager.DestinationL( targetDestId );
iCmManagerExt.CopyConnectionMethodL( targetDestination, connectionMethod );

Moving a Connection Method from one Destination to another can be achieved using RCmManager API:

RCmConnectionMethod connectionMethod = iCmManager.ConnectionMethodL( cmId );

RCmDestination sourceDestination = iCmManager.DestinationL( sourceId );
RCmDestination targetDestination = iCmManager.DestinationL( targetId );
iCmManager.MoveConnectionMethodL( sourceDestination, targetDestination, connectionMethod );

Removing a Connection Method from a Destination means that the link between that Connection Method and Destination is removed. Normally this means that the removed Connection Method is in the Uncategorized folder after removing.

RCmDestination destination = iCmManager.DestinationL( destId );
RCmConnectionMethod connectionMethod = iCmManager.ConnectionMethodL( cmId );
destination.RemoveConnectionMethodL( connectionMethod );
destination.UpdateL();

Deleting a Connection Method can be achieved through RCmDestination where that Connection Method exists or deleted through RCmConnectionMethod API. The recommended way is to delete it through the RCmDestination API.

RCmConnectionMethod connectionMethod = destination.ConnectionMethodL( cmId );
destination.DeleteL( connectionMethod );
destination.UpdateL();
//or without the destination
RCmConnectionMethod connectionMethod = iCmManager.ConnectionMethodL( cmId );
TBool deleted = connectionMethod.DeleteL();

2.4 Reading the list of existing Connection Methods

The list of existing Destination IDs can be queried by invoking the RCmManager::ConnectionMethodL method.

This example shows how to get the Connection Method ID list. Connection Method IDs can be used to get the Connection Method objects.

RArray<TUint32> connectionMethods;
CleanupClosePushL( connectionMethods );

iCmManager.ConnectionMethodL( connectionMethods );

The example goes through all the Destinations and retrieves the names of them.

RCmConnectionMethod connectionMethod;
HBufC *name = NULL;

for(TInt i = 0; i < connectionMethods.Count(); i++)
    {
    connectionMethod = iCmManager.ConnectionMethodL( connectionMethods(i) );
    CleanupClosePushL( connectionMethod );

    name = ConenctionMethod.GetStringAttributeL( ECmName );
	  // name can be e.g. printed out
    delete name;
    name = NULL;
 
    CleanupStack::PopAndDestroy(); // connectionMethod
    }

2.5 Reading the existing Connection Methods in a Destination

The number of Connection Methods in a Destination can be queried by calling the RCmDestination::ConnectionMethodCount method.

The example lists the names of the Connection Methods in all Destinations. The cmconnectionmethoddef.h header file must be included for using ECmName with Connection Method attribute enumeration.

RArray<TUint32> destinations;
CleanupClosePushL(destinations);

iCmManager.AllDestinationsL(destinations);

RCmDestination destination;
HBufC* name = NULL;

for(TInt i = 0; i < destinations.Count(); i++)
    {
    destination = cmManager.DestinationL( destinations(i) );
    CleanupClosePushL(destination);

    name = destination.NameLC();
    // The name can be, for example, printed out
    CleanupStack::PopAndDestroy( name ); // destination.NameLC()
    name = NULL;

    RCmConnectionMethod connectionMethod;

    for( TInt j = 0; destination.ConnectionMethodCount(); j++ )
        {
         connectionMethod = destination.connectionMethodL( j);
         CleanupClosePushL( connectionMethod );

         name = ConenctionMethod.GetStringAttributeL( ECmName );
         //The name can be printed out
         delete name;
         name = NULL;
         CleanupStack::PopAndDestroy(); // connectionMethod
         }
    CleanupStack::PopAndDestroy(); // destination
    }

2.6 Reading and writing the attributes of a Connection Method

A Connection Method has a set of common attributes and a set of bearer specific attributes. The common attributes can be found in the cmconnectionmethoddef.h file, For exmaple, ECmBearerType contains the bearer type of a Connection Method. ECmName contains the name of the Connection Method.

The bearer specific attributes can be found in the def.h files of bearer headers. For example, cmpluginpacketdatadef.h contains the bearer specific attributes of packet data bearer type, such as EPacketDataOutGoing .

Each attribute has a type. For example, the type of EPacketDataOutGoing is TBool .

Get methods of RCmConnectionMethod can be used for reading the attributes of a Connection Method:

• GetStringAttributeL for reading a string
• GetIntAttributeL for reading an integer
• GetBoolAttributeL for reading a Boolean
• GetString8AttributeL for reading an 8 bit string attribute

Set methods of RCmConnectionMethod can be used for writing the attributes of a Connection Method:

• SetStringAttributeL for writing a string
• SetIntAttributeL for writing an integer
• SetBoolAttributeL for writing a Boolean
• SetString8AttributeL for writing an 8 bit string attribute.

The following is an example of reading and writing a couple of common attributes of the Connection Methods:

RCmConnectionMethod connectionMethod;

connectionMethod = iCmManager.GetConnectionMethodL( cmId );
CleanupClosePushL( connectionMethod );
name = connectionMethod.GetStringAttributeL( ECmName );
delete name;
name = NULL;
// change the name
connectionMethod.SetStringAttributeL( ECmName, _L("NewName") );
// change the hidden value
TBool hidden = connectionMethod.GetBoolAttributeL( ECmHidden );
if ( hidden )
    {
    connectionMethod.SetBoolAttributeL( ECmHidden, EFalse );
    }
else
    {
    connectionMethod.SetBoolAttributeL( ECmHidden, ETrue );
    }
CleanupStack::PopAndDestroy(); // connectionMethod

2.7 Reading the attributes of a bearer type

Some attributes do not belong to a concrete Connection Method but they are the attributes of a bearer type. For example, ECmBearerHasUi indicates if the bearer has a UI Settings dialog or not. These attributes can be queried by the RCmManager::GetBearerInfoBoolL}}, GetBearerInfoIntL, GetBearerInfoStringL and GetBearerInfoString8L methods.

The next example reads some attributes of the Packet Data bearer type. KUidPacketDataBearerType comes from the Packet Data DEF cmpluginpacketdatadef.h header file.

TBool coverage = iCmManager.GetBearerInfoBoolL( KUidPacketDataBearerType, ECmCoverage );

TUint defaultPriority = iCmManager.GetBearerInfoIntL( KUidPacketDataBearerType, ECmDefaultPriority );

Note that some attributes including bearer specific and Connection Method specific attributes require initialized UI context in the client application. For example, ECmBearerIcon which gives back the bearer specific icon requires this.

2.8 Handling of an Embedded Destination

Special handling is needed for Embedded Destinations. A destination can contain a link to another destination. This makes it possible to utilize the Connection Methods of another destination when creating the connection. This is called an Embedded Destination.

Embedded Destination is rarely used. Embedded Destination cannot be created by end users.

In The Connection Settings API, an Embedded Destination is represented as a Connection Method with Embedded Destination bearer type. Therefore, to be prepared for Embedded Destination first, the bearer type of the actual Connection Method must be checked. If the bearer type is Embedded Destination, the linked destination can be queried by calling the RCmConnectionMethod::DestinationL method.

The next example is code fragment from a program, which iterates through the existing Destinations and Connection Methods. The cmpluginembdestinationdef.h header file must be included for the UID of the Embedded Destination bearer type (KUidEmbeddedDestination ).

RCmConnectionMethod connectionMethod;

for( TInt i = 0; destination.ConnectionMethodCount(); i++ )
    {
    connectionMethod = destination.connectionMethodL( i );
    CleanupClosePushL( connectionMethod );

    TUint bearerType = connectionMethod.GetIntAttributeL( ECmBearerType );
    if ( bearerType == KUidEmbeddedDestination )
        {
        RCmDestination embeddedDestination = connectionMethod.DestinationL();
        // now we can e.g. ask the count of the CMs in the embedded destination
        embeddedDestination.ConnectionMethodCount()
        embeddedDestination.Close()
        }
    CleanupStack::PopAndDestroy(); // connectionMethod
    }

2.9 Error handling

The Connection Settings API uses the standard Symbian error reporting mechanism. Leaves and system wide error codes are used if the error is recoverable. A client application can handle these errors using the standard leave and TRAP mechanism

2.10 Memory and Performance Considerations

Opening a CMManager session uses about 8 KB in a system, which supports five kinds of bearer types.

Using an example setup with six Destinations each containing three Connection Methods, and gettting the list of existing Destinations takes about 1 KB.

Getting an RCmDestination object uses about 1 KB. Getting an RCmConnectionMethod object uses about 2 KB.

2.11 Limitations of the API

In some cases, the client application needs an initialized UI context to successfully invoke the methods of the API, for example when reading some UI related attributes such as the bearer specific icon.

2.12 Security issues

The Connection Method Manager runs in the process of the client application, and it has the same capabilities as the client application. The client application needs the ReadDeviceData capability to access private user data such as user names or passwords through the API.

3 Glossary

3.1 Abbreviations

ID	Identifier
API	Application Programming Interface
IAP	Internet Access Point
CM	Connection Method
CM Manager	Connection Method Manager
SNAP	Service Network Access Point

3.2 Definitions

Connection Method	Connection Method is the new term for Internet Access Point. The naming is changed to make it easier for users to understand the concept of network connections within the new simplified UI structure.
Destination	Destination is an abstraction to hide the technical specific settings from the users of applications. Instead of Access Points the user can select destinations with its name such as Internet or Intranet, etc. Each destination can contain numerous access technologies (hence connection methods) that can be used to access the destination or service domain in question. When a connection to destination is going to be established, the device can automatically select the best available. Destination, Destination Network, SNAP refers to the same meaning.
Bearer type	Access technology such as WLAN, Packet Data, VPN.
Embedded Destination	A destination can contain a link to another destination. This makes it possible to utilize the Connection Methods of another destination when creating the connection. This is called an Embedded Destination. Embedded Destination cannot be configured through the user interface.