Figure 3: Example screenshot of running the selection dialog
cmmanager.lib has to be linked to the application before the API is used. The following line has to be added to the MMP file of the application.
LIBRARY cmmanager.lib
The default selection dialog is provided by the CCmApplicationSettingsUi class.
The default dialog provides the same dialog as the customizable RunApplicationSettingsL do
(see the next use case) with the list items Default Connection, Destinations
and Connection Methods without any filtering.
The result of the user interaction is given back in the TCmSettingSelection type.
Empty destinations are automatically filtered out from the selection dialog.
The client application needs an initialized UI context for running this dialog.
Below is an example of how to invoke the CCmApplicationSettingsUi::RunApplicationSettingsL method.
The definitions of the types used in the example are in the cmapplicationsettingsui.h header.
CCmApplicationSettingsUi* settingsUi =
CCmApplicationSettingsUi::NewL();
CleanupStack::PushL(settingsUi);
TCmSettingSelection selection;
TBool selected = settingsUi->RunApplicationSettingsL(selection);
CleanupStack::PopAndDestroy(settingsUi);
The result of RunApplicationSettingsL (selected) indicates
if the user selected something or canceled the dialog.
Below is an example of how to process the result of the dialog.
if(selected)
{
switch(selection.iResult)
{
case EDestination:
TUint destinationId = selection.iId;
User::InfoPrint(_L("Destination was selected."));
break;
case EConnectionMethod:
TUint connectionMethodId = selection.iId;
User::InfoPrint(_L("Connection Method was selected."));
break;
default:
// Invalid result
User::InfoPrint(_L("Selection result is invalid."));
User::Leave(KErrGeneral);
break;
}
}
else
{
// User has canceled the selection dialog.
User::InfoPrint(_L("Selection dialog was canceled."));
}
Below is an example screenshot of running the selection dialog.
Figure 3: Example screenshot of running the selection dialog
The extended (customizable) selection dialog is provided by the CCmApplicationSettingsUi class.
The result of the user interaction is given back in the TCmSettingSelection type.
Using this version of RunApplicationSettingsL is the preferred
way of using the API, because the applications should define what connection
management items they support. Only those are then shown in the UI and can
get selected by the user.
The content of the dialog can be controlled by the list items and the filter array parameters.
The list items (aListItems) is a bit field which can be
filled using the TCmSelectionDialogItems enumeration values.
E.g. if you want to show the Connection Methods and the Default Connection
then EShowDefaultConnection | EShowConnectionMethods must
be used as the input parameter.
Filter array (aFilterArray) controls what Connection Methods
can be shown in the selection dialog. The elements of the TBearerFilterArray are
bearer type IDs. The IDs are defined in the bearer type specific cmplugin...def.h files.
E.g. the ID of the CSD bearer type (KUidCSDBearerType) can
be found in the cmplugincsddef.h header. No filtering is done if the
array is empty. In other cases only the Connection Methods with the specified
bearer types in the filter array are shown.
Empty destinations are automatically filtered out from the selection dialog. The client application needs an initialized UI context for running this dialog.
Below is an example of how to invoke the extended CCmApplicationSettingsUi::RunApplicationSettingsL method.
The definitions of the types used in the example are in the cmapplicationsettingsui.h header.
For the two bearer type IDs (KUidCSDBearerType, KUidPacketDataBearerType) cmplugincsddef.h and cmpluginpacketdatadef.h headers should be included.
TCmSettingSelection selection;
TBearerFilterArray filter;
CleanupClosePushL(filter);
filter.AppendL(KUidCSDBearerType);
filter.AppendL(KUidPacketDataBearerType);
CCmApplicationSettingsUi *settingsUI =
CCmApplicationSettingsUi::NewLC();
TBool selected = settingsUI->RunApplicationSettingsL(
selection,
EShowConnectionMethods | EShowAlwaysAsk,
filter);
CleanupStack::PopAndDestroy(settingsUI);
CleanupStack::PopAndDestroy(&filter);
The result of RunApplicationSettingsL (selected) indicates
that the user selected something or canceled the dialog.
Below is an example of how to process the result of the dialog.
if(selected)
{
switch(selection.iResult)
{
case EConnectionMethod:
TUint connectionMethodId = selection.iId;
User::InfoPrint(_L("Connection Method was selected."));
break;
case EAlwaysAsk:
User::InfoPrint(_L("AlwaysAsk was selected."));
break;
default:
// Invalid result
User::InfoPrint(_L("Selection result is invalid."));
User::Leave(KErrGeneral);
break;
}
}
else
{
// User has cancelled the selection dialog.
User::InfoPrint(_L("Selection dialog was canceled."));
}
Below is an example screenshot of running the selection dialog.
Figure 4: Example screenshot of running the customizable selection dialog
Below is an example on how to call the extended method to get the same
result as calling the default dialog. In the example filter is an empty array.
settingsUI->RunApplicationSettingsL(
selection,
EShowDestinations | EShowConnectionMethods | EShowDefaultConnection,
filter);
Connection Settings UI 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.
Running the selection dialog takes about 30-40 Kbytes. Memory consumption slightly depends on the number of Destinations and Connection Methods. Adding six Destinations and three Connection Methods to each Destination means about an additional 4 kb in memory consumption.
This selection dialog does not provide any managing functionality of Destinations and Connection Methods. Destinations and Connection Methods cannot be created, deleted and edited through this API.
The client application needs an initialized UI context to successfully invoke the selection dialog. Default Connection is displayed only if the Default Connection feature is switched on.
