API description
Connection Method Manager API provides:
-
Access functions to read existing Destinations and Connection Methods
-
Access functions to read the attributes of Connection Methods
-
Access functions to read the attributes of a bearer type
-
Access functions to create, delete, move and copy Destinations and Connection
Methods
-
Access functions to write attributes to Destinations and Connection Methods
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.
As Connection Method Manager runs in the process of the client application
it has the same capabilities as the client application so the client application
needs the
ReadDeviceData
capability to access private user
data such as user names or passwords through the API.
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.
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
Related APIs
AllDestinationsL
CMManager
ConnectionMethodL
ECmBearer
ECmBearerHasUi
RCmConnectionMethod
RCmDestination
RCmManager
TConnectionMethodPacketDataSpecificAttributes
Related APIs
ECmBearerIcon
ReadDeviceData
Using Connection Settings API
cmmanager.lib has to be linked to the application before the Connection
Settings API is used. The following line has to be added to the MMP file of
the application.
LIBRARY cmmanager.lib
When using types in 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. The
cmmanager.h header file has to 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
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();
Related APIs
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
}
Related APIs
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();
Related APIs
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
}
Related APIs
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
}
Related APIs
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
Related APIs
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.
Related APIs
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
}
Related APIs
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.
Related APIs
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.
Related APIs