--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ipcm_pub/connection_settings_ui_api/inc/cmapplicationsettingsui.h Thu Dec 17 08:55:21 2009 +0200
@@ -0,0 +1,300 @@
+/*
+* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description:
+*
+*/
+
+#ifndef C_CMAPPLICATIONSETTINGSUI_H
+#define C_CMAPPLICATIONSETTINGSUI_H
+
+#include <E32def.h>
+#include <e32base.h>
+
+class CCmConnSettingsUiImpl;
+namespace CMManager
+ {
+
+ /**
+ * CCmApplicationSettingsUi::RunApplicationSettingsL leaves with this
+ * error code if the selection dialog would have zero elements caused
+ * by filtering out all the Connection Methods with the aFilterArray
+ * and not requesting other list elements by the aListItems bitfield.
+ * See the comment of the RunApplicationSettingsL method for more
+ * detailes.
+ * This error code is supported by the error resolver.
+ */
+ const TInt KErrConnectionNotFound = -32700;
+
+ /**
+ * The selection type of a list item in application settings UI
+ */
+ enum TCmSettingSelectionMode
+ {
+ EAlwaysAsk, /**<
+ * The user selected Always ask
+ */
+ EDestination, /**<
+ * The user selected a destination
+ */
+ EConnectionMethod, /**<
+ * The user selected a connection method
+ */
+ EDefaultConnection // The user selected Default Connection
+
+ };
+
+
+ /**
+ * These bitmasks controls what items does the selection UI containes.
+ * Bitmasks not listed in the enum are reserved for future usage and they
+ * are disabled by default. So extending these bitmasks does not cause
+ * BC break later.
+ */
+ enum TCmSelectionDialogItems
+ {
+ EShowAlwaysAsk = 0x01, /**<
+ * AlwaysAsk is added to the
+ * selection UI.
+ */
+ EShowDefaultConnection = 0x02, /**<
+ * DefaultConnection is added to the
+ * selection UI.
+ */
+
+ /**
+ * The following enumerations controls how destinations and
+ * Connection Methods are presented in the selection UI.
+ * EShowDestinations is set and EShowConnectionMethods is set:
+ * Destination list is added to the selection UI and a Connection
+ * Method can be selected inside a Destination.
+ * EShowDestinations is set and EShowConnectionMethods is not set:
+ * Destination list is added to the selection UI and no Connection
+ * Method can be selected inside a Destination.
+ * EShowDestinations is not set and EShowConnectionMethods is set:
+ * Connection Method list is added to the selection UI. Connection
+ * Methods are ordered according to the global bearer type
+ * priorities. Destination cannot be selected.
+ * EShowDestinations is not set and EShowConnectionMethods is not set:
+ * The selection UI will not contain any Destination or Connection
+ * Method. E.g. If EShowAlwaysAsk and EShowDefaultConnection was set
+ * then the selection UI will contain two entries (AlwaysAsk and
+ * DefaultConnection).
+ */
+ EShowDestinations = 0x04, /**<
+ * Destination list is added to the
+ * selection UI. Destinations which
+ * does not contain any Connection
+ * Methods are not shown.
+ */
+ EShowConnectionMethods = 0x08, /**<
+ * If EShowDestinations is set:
+ * Connection Method can be selected
+ * inside a destination.
+ * If EShowDestinations is not set:
+ * Connection Method list is added to
+ * the selection UI.
+ */
+ };
+
+ }// namespace CMManger
+
+
+ // Structs
+
+/**
+ * Stores the details of a setting selection
+ *
+ * @lib cmmanager.lib
+ * @since S60 3.2
+ */
+NONSHARABLE_STRUCT( TCmSettingSelection )
+ {
+ /**
+ * Selection mode, refers to the type of the list item which is selected
+ */
+ CMManager::TCmSettingSelectionMode iResult;
+
+ /**
+ * Id of the selected destination or connection method
+ */
+ TUint iId;
+ };
+
+/**
+* Typedef of the bearer filter array.
+* This type of array is used to filter Connection Methods
+* by bearer types.
+*
+* The array elements are bearer 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.
+*/
+typedef RArray<TUint32> TBearerFilterArray;
+
+/**
+ * For launching the Application Settings UI
+ *
+ * Displays a radio button page for an application used to select
+ * a destination or connection method
+ *
+ * @lib cmmanager.lib
+ * @since S60 3.2
+ */
+NONSHARABLE_CLASS( CCmApplicationSettingsUi ) : public CBase
+ {
+
+ public: // construction/destruction
+
+ /** Epoc constructor */
+ IMPORT_C static CCmApplicationSettingsUi* NewL();
+
+ /** Epoc constructor
+ * Pushes the object on the cleanup stack
+ */
+ IMPORT_C static CCmApplicationSettingsUi* NewLC();
+
+ /** Destructor. */
+ virtual ~CCmApplicationSettingsUi();
+
+ //=======================================================================
+ // UI API
+ //
+ public:
+
+ /**
+ * Launches the 'easy to use' Settings UI provided for applications
+ * for handling Destinations and Connection Methods.
+ * This function call launches the same selection dialog as the
+ * the extended RunApplicationSettingsL do (see below) with the
+ * list items Default Connection, Destinations and Connection Methods
+ * without any filtering.
+ *
+ * @since 3.2
+ * @param aSelection If initialised to a valid value, sets the higlight to the
+ * corresponding list item at startup. If a list of Destinations is displayed, and
+ * the initial highlight is set to a Connection Method, the parent Destination
+ * gets highlighted. On return, holds user selection.
+ * @return TBool seleceted or not.
+ */
+ IMPORT_C TBool RunApplicationSettingsL(
+ TCmSettingSelection& aSelection );
+
+ /**
+ * Launches the 'easy to use' Settings UI provided for applications
+ * for handling Destinations and Connection Methods
+ *
+ * @since 3.2
+ * @param aSelection If initialised to a valid value, sets the higlight to the
+ * corresponding list item at startup. If a list of Destinations is displayed, and
+ * the initial highlight is set to a Connection Method, the parent Destination
+ * gets highlighted. On return, holds user selection.
+ * @param aListItems A bit field which indicates which items shoud be
+ * shown in the selection dialog. The bitmasks are
+ * defined in the TCmSelectionDialogItems enum.
+ *
+ * The function leaves with KErrNotSupported if all the items which
+ * were set to be shown are not supported/enabled.
+ * E.g. Default Connection availability/support is controlled by the
+ * Feature Manager so if only EShowDefaultConnection is set and the
+ * Default Connection feature is not enabled than the function leaves
+ * with KErrNotSupported.
+ *
+ * In other cases (when an item or items are not supported/enabled but
+ * not all) the selected but not supported/enabled items are not added
+ * to the list. The request to show such an item is silently ignored.
+ *
+ *
+ * Special note about the EShowDestinations and EShowConnectionMethods
+ * bitmasks:
+ * The following enumerations controls how how destinations and
+ * Connection Methods are presented in the selection UI.
+ * General rule about the EShowDestinations:
+ * Destinations which does not contain any Connection Methods are
+ * not shown in the selection dialog. The same rule is applied if
+ * the Destination containes Connection Methods but all of them
+ * are filtered out by the filtering criteria.
+ * EShowDestinations is set and EShowConnectionMethods is set:
+ * Destination list is added to the selection UI and a Connection
+ * Method can be selected inside a Destination.
+ * EShowDestinations is set and EShowConnectionMethods is not set:
+ * Destination list is added to the selection UI and no Connection
+ * Method can be selected inside a Destination.
+ * EShowDestinations is not set and EShowConnectionMethods is set:
+ * Connection Method list is added to the selection UI. Connection
+ * Methods are ordered according to the global bearer type
+ * priorities. Destination cannot be selected.
+ * EShowDestinations is not set and EShowConnectionMethods is not set:
+ * The selection UI will not contain any Destination or Connection
+ * Method. E.g. If EShowAlwaysAsk and EShowDefaultConnection was
+ * set then the selection UI will contain two entries (AlwaysAsk
+ * and DefaultConnection).
+ *
+ * @param aFilterArray Only Connection Methods with bearer types from
+ * the aFilterArray will be shown.
+ * All Connection Methods will be listed if the
+ * array has no element.
+ * @return TBool seleceted or not.
+ *
+ * @leave KErrArgument If the selection dialog would have zero
+ * elements based on the aListItems bitmask
+ * (aListItems is equal to zero).
+ *
+ * @leave KErrNotSupported
+ * If the selection dialog would have zero
+ * elements based on the aListItems bitmask
+ * (all the selected elements in aListItems
+ * are not supported/disabled).
+ * E.g. aListItems = EShowDefaultConnection but
+ * Default Connection feature is not enabled.
+ *
+ * @leave KErrConnectionNotFound
+ * If the selection dialog would have zero
+ * elements caused by filtering out all the
+ * Connection Methods with the aFilterArray
+ * and not requesting other list elements by
+ * the aListItems bitfield than the function
+ * call leaves with KErrConnectionNotFound
+ * error code. A corresponding error note can
+ * be shown using the error resolver.
+ * E.g.
+ * - aListItems = EShowConnectionMethods
+ * but all Connection Methods are filtered
+ * out by the aFilterArray.
+ */
+ IMPORT_C TBool RunApplicationSettingsL(
+ TCmSettingSelection& aSelection,
+ TUint aListItems,
+ TBearerFilterArray& aFilterArray);
+
+ private:
+
+ /** C++ constructor */
+ CCmApplicationSettingsUi();
+
+ /**
+ * Epoc 2nd phase constructor
+ *
+ * @since S60 3.2
+ */
+ void ConstructL();
+
+ private: // data
+
+ /**
+ * implementation of the class
+ */
+ CCmConnSettingsUiImpl* iImpl;
+ };
+
+#endif // C_CMAPPLICATIONSETTINGSUI_H