Contents

• Changes
• Purpose
  • Constraints
  • Classification and release information
• API description
  • Use cases
  • API class structure
• Using Connection Settings API
  • Create, modify and delete a Destination
  • Reading the list of existing Destinations
  • Create, copy, move, remove and delete 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
  • Error handling
  • Memory overhead
  • Limitations of the API
• Glossary
  • Abbreviations
  • Definitions

Constraints

This API is valid from S60 5th Edition Feature Pack 1 onwards.

Classification and release information

Connection Settings API is an SDK API and was first published in S60 3rd Edition Feature Pack 2 with reading functionality. Writing functionality was published in S60 5th Edition Feature Pack 1

Use cases

The main use cases of the Connection Settings API are:

• Create, modify and delete a Destination

• Read the list of existing Destinations

• Create, copy, move, remove and delete a Connection Method

• Read the list of existing Connection Methods

• Read the existing Connection Methods in a Destination

• Read and write the attributes of a Connection Method

• Read the attributes of a bearer type

• Handling of Embedded Destination

API class structure

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

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

  • Get the bearer specific information, e.g. ECmBearerHasUi to query if a bearer type has a UI dialog for the settings or not.

  • Get the Connection Method specific information, e.g. 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.

    • Name, ID, icon, protection, hidden value, connection status

    • Metadata

  • 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

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

Some of these file names refer to plug-ins such as cmpluginpacketdatadef.h.

• cmmanagerdef.h

• cmconnectionmethoddef.h

• cmdefconnvalues.h

• cmpluginpacketdatadef.h

• cmplugindialcommondefs.h

• cmplugincsddef.h

• cmpluginhscsddef.h

• cmpluginembdestinationdef.h

• cmpluginvpndef.h

• cmpluginwlandef.h

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

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

• AllDestinationsL
• CMManager
• ConnectionMethodL
• ECmBearer
• ECmBearerHasUi
• RCmConnectionMethod
• RCmDestination
• RCmManager
• TConnectionMethodPacketDataSpecificAttributes

            
             LIBRARY         cmmanager.lib
            
           

            
             RCmManager cmManager;
             

             

             cmManager.OpenLC();
            
           

            
             CleanupStack::PopAndDestroy(); // cmManager
            
           

Create, modify and delete a Destination

After the Connection Method Manager has been 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 has to be included for using RCmDestination .

An example of how to create a Destination:

             
              RCmDestination destination;
              

              

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

              destination.UpdateL();
              

              

              

              Destination can be modified e.g. change the name of it in a following way:
              

              

              destination.SetNameL( _L("Destination2") );
              

              CleanupClosePushL(destinations);
              

              destination.UpdateL();
              

              

              

              How to delete the destination:
              

              

              destination.DeleteLD();
             
            

• RCmDestination
• RCmManager::CreateDestinationL

Reading the list of existing Destinations

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

An example of how to get the Destination ID list.

             
              RArray<TUint32> destinations;
              

              CleanupClosePushL(destinations);
              

              

              iCmManager.AllDestinationsL(destinations);
             
            

Destination Ids can be used to get the Destination objects.

The example goes through all the Destinations and get's 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
               

                   }
              
             

• RCmManager::AllDestinationsL

Create, copy, move, remove and delete a Connection Method

Connection Method can be created through RCmManager API or RCmDestination API. method. If RCmManager API is used 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 has to be included for using RCmConnectionMethod .

             
              RCmConnectionMethod connectionMethod;
              

              connectionMethod = iCmManager.CreateConnectionMethodL( KUidPacketDataBearerType );
              

              destination.Add( connectionMethod );
              

              destination.UpdateL();
             
            

or if RCmDestination API is used

             
              connetionMethod = destination.CreateConnectionMethodL( KUidPacketDataBearerType);
              

              destination.UpdateL();
             
            

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 done by 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 done through RCmDestination where that Connection Method exists or 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();
             
            

• RCmConnectionMethod
• RCmDestination
• RCmManager

Reading the list of existing Connection Methods

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

An example of how to get the Connection Method ID list.

             
              RArray<TUint32> connectionMethods;
              

              CleanupClosePushL( connectionMethods );
              

              

              iCmManager.ConnectionMethodL( connectionMethods );
             
            

Connection Method IDs can be used to get the Connection Method objects.

The example goes through all the Destinations and gets 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
              

                  }
             
            

• RCmManager::ConnectionMethodL

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 has to 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();
              

                  // name can be e.g. 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 );
              

                       // name can be e.g. printed out
              

                       delete name;
              

                       name = NULL;
              

                       CleanupStack::PopAndDestroy(); // connectionMethod
              

                       }
              

                  CleanupStack::PopAndDestroy(); // destination
              

                  }
             
            

• ECmName
• RCmDestination::ConnectionMethodCount

Reading and writing the attributes of a Connection Method

Connection Methods has a set of common attributes and a set of bearer specific attributes. The common attributes can be found in the cmconnectionmethoddef.h file, e.g. ECmBearerType – the bearer type of a Connection Method, and ECmName – the name of the Connection Method (this attribute was already used in the example above).

The bearer specific attributes can be found in the def.h files of bearer headers, e.g. cmpluginpacketdatadef.h that contains the bearer specific attributes of packet data bearer type, e.g. EPacketDataOutGoing .

Each attribute has a type, e.g. 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.

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
             
            

• ECmBearerType
• ECmName
• EPacketDataOutGoing
• GetBoolAttributeL
• GetIntAttributeL
• GetString8AttributeL
• GetStringAttributeL
• RCmConnectionMethod
• SetBoolAttributeL
• SetIntAttributeL
• SetString8AttributeL
• SetStringAttributeL
• TBool

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, e.g. ECmBearerHasUi which 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 header cmpluginpacketdatadef.h .

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

              

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

Be aware that some attributes including bearer specific and Connection Method specific attributes require initialized UI context in the client application, e.g. ECmBearerIcon which gives back the bearer specific icon requires it.

• ECmBearerHasUi
• ECmBearerIcon
• GetBearerInfoIntL
• GetBearerInfoString8L
• GetBearerInfoStringL
• KUidPacketDataBearerType
• RCmManager::GetBearerInfoBoolL

Handling of Embedded Destination

Special handling is needed for Embedded Destinations. A destination can contain a link to another destination, thus making 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 the phone user.

In Connection Settings API an Embedded Destination is represented as a Connection Method with Embedded Destination bearer type. So to be prepared for Embedded Destination first the bearer type of the actual Connection Method has to be checked. If the bearer type is Embedded Destination then 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 relevant codes about handling Embedded Destinations are in bold. The cmpluginembdestinationdef.h header has to 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
              

                  }
             
            

• KUidEmbeddedDestination
• RCmConnectionMethod::DestinationL

Error handling

Connection Settings API uses the standard Symbian platform error reporting mechanism. Leaves and system wide error codes as function return values are used if the error is recoverable. A client application can handle these errors similarly as a normal Symbian platform application.

Memory overhead

Opening a CMManager session takes about 8 kb using in a system which supports five kinds of bearer types.

Using an example setup with six Destinations each containing three Connection Methods, getting 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.

• CMManager
• RCmConnectionMethod
• RCmDestination

Limitations of the API

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

Abbreviations

Abbreviations

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

Definitions

Definitions

Connection Method	Connection Method is the new term for Internet Access Point. The naming has been 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, thus making 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 via the user interface.