Figure 3: Example output of listing Destination names
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 CM 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
After the CM Manager has been initialized, the list of IDs of existing
Destinations can be queried by invoking the RCmManager::AllDestinationsL method.
Below is an example of how to get the Destination ID list.
RArray<TUint32> destinations; CleanupClosePushL(destinations); cmManager.AllDestinationsL(destinations);
Now the Destination IDs can be used to get the actual Destination objects.
The example below goes through all the Destinations and writes the names
of the Destinations to the console. The cmdestination.h header file
has to be included for using the RCmDestination type.
RCmDestination destination;
HBufC *name = NULL;
for(int i = 0; i < destinations.Count(); i++)
{
destination = cmManager.DestinationL(destinations[i]);
CleanupClosePushL(destination);
name = destination.NameLC();
console->Printf(_L("%S\n"), name);
CleanupStack::PopAndDestroy(name); // destination.NameLC()
name = NULL;
CleanupStack::PopAndDestroy(); // destination
}
Below is an example output of the code above.
Figure 3: Example output of listing Destination names
The number of Connection Methods in a Destination can be queried by calling
the RCmDestination::ConnectionMethodCount method. The actual
Connection Method object can be queried by invoking the RCmDestination::ConnectionMethodL function.
The example below is an extension of the previous example. It lists the
names of the Connection Methods in all Destinations. The cmconnectionmethod.h header
file has to be included for using the RCmConnectionMethod type
and the cmconnectionmethoddef.h header file has to be included for
using the ECmName Connection Method attribute enumeration.
The new code is in bold.
Below is an example output of the code above.
Figure 5: Example output of listing Connection Methods
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, 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. cmpluginhscsddef.h – contains the bearer specific
attributes of HSCSD bearer type e.g. EHscsdChannelCoding.
Each attribute has a type e.g. the type of EHscsdChannelCoding is
TUint32.
Get methods of RCmConnectionMethod can be used for reading
the attributes of a Connection Method:
GetStringAttributeL for reading a string
GetIntAttributeL for reading an int
GetBoolAttributeL for reading a bool
GetString8AttributeL for reading an 8 bit string attribute.
In the code below the previous example is extended to read a couple of common attributes of the Connection Methods. The relevant code about reading attributes is in bold.
Below is an example output of the code above.
Figure 7: Example output of reading attributes of Connection Methods
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, GetBearerInfoString8L methods.
The next example reads some attributes of the Packet Data bearer type.
The KUidPacketDataBearerType comes from the Packet Data def
header cmpluginpacketdatadef.h.
Below is an example output of the code above.
Figure 9: Example output of reading bearer specific attributes
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.
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. It logs the name and the
number of Connection Methods in the Embedded Destinations. 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).
Below is an example output of the code above. In the example ‘MyDestination2’ Destination has an Embedded Destination which points to ‘MyDestination1’.
Figure 11: Example output of handling Embedded Destination
Connection Settings API uses standard Symbian OS 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.
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.
Destinations and Connection Methods cannot be created, deleted and edited through Connection Settings 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.
