--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/featuremgmt/featuremgr/inc/featurecontrol.h Fri Jan 22 11:06:30 2010 +0200
@@ -0,0 +1,508 @@
+/*
+* Copyright (c) 2007-2009 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 FEATURECONTROL_H
+#define FEATURECONTROL_H
+
+// INCLUDES
+#include <e32std.h>
+#include <e32svr.h>
+#include <featmgr/featurecmn.h>
+
+// FORWARD DECLARATIONS
+
+// DEFINES
+
+// CLASS DECLARATION
+
+// CONSTANTS
+
+// MACROS
+
+/**
+
+ The Feature Control API provides methods that can be used to query which
+ features are supported on the device. The API also provides methods to
+ get status flags that define that behaviour of the feature flag and data
+ associated with the feature.
+
+ The Feature Control API provides methods to enable and disable features at
+ runtime e.g. when new software is installed or uninstalled. The API provides
+ also methods for setting feature data, adding a new feature to the device
+ and listing all supported features on the device.
+
+ It is only possible to enable or disable a feature or set feature data
+ at runtime if that feature is modifiable (this is defined by the status
+ 32 bit word associated with the feature flag). It is also possible to enable or
+ disable a feature UID that is not even defined in the device yet.
+ When adding a new feature to the device status flags and data of the feature
+ must be set.
+
+ The meaning of the bits of the 32-bit feature status flags are as follows:
+
+ Bit Flag Name Meaning
+ - 0 Supported If set, feature is supported and available for use;
+ if not, feature is not supported.
+ - 1 Upgradeable If set, feature is upgradeable. The feature is known to
+ the device but it must be upgraded to enable it. If a feature
+ is blacklisted, its upgradeable flag is unset.
+ - 2 Modifiable If set, the feature is modifiable and may be enabled/disabled at
+ run-time. The initial flag values for such a feature flag are
+ defined in a ROM image obey file.
+ - 3 Blacklisted If set, the feature has been blacklisted, and may not be changed
+ at run-time. This also prevents a feature from being upgraded.
+ - 4 Uninitialised If set, the status flag Supported is unknown at build-time and is
+ initialised at run-time by system software. The Feature Manager
+ will ignore the Supported flag in the file. A run-time call to
+ RFeatureControl will be needed to set the feature's supported
+ flag. Look ups of uninitialised features result in a KErrNotReady
+ error code.
+ - 5 Persisted If set, this flag is saved to the system drive when modified
+ preserving its value across reboots/power downs
+ - 6 ..23 Reserved for future use, always zero.
+ - 24..31 Reserved for internal use.
+
+ Enumeration TFeatureFlags defined in featurecmn.h should be used for
+ accessing feature status flags e.g. flags.IsSet( EFeatureUpgradeable ),
+ flags.IsSet( EFeatureModifiable ).
+
+ Feature data is 32-bit word for client read and write. Feature data can
+ contain any data that needs to be associated with the Feature Flag.
+ Feature data can only be set if the feature is modifiable or a new feature.
+
+ The use of the Feature Manager API to set the supported status of a feature,
+ it in no way means that the functionality itself is modified on the device.
+ All the corresponding DLLs, including feature functionality and resources still
+ remain on the device. To properly support runtime activation/deactivation
+ of the feature, all feature APIs need to implement runtime checking of the
+ feature status in their code.
+
+ The API consists of the RFeatureControl class which is
+ used together with feature UIDs defined in featureUIDs.h, TFeatureFlags,
+ TFeatureEntry and RFeatureUidArray defined in featurecmn.h.
+
+
+ Usage:
+
+ Before calling any other methods the client must call the Open()
+ method that connects to the Feature Manager Server.
+ When the client has finished using the RFeatureControl it should
+ disconnect using the Close() method.
+
+@publishedPartner
+@released
+*/
+NONSHARABLE_CLASS(RFeatureControl)
+ {
+ public:
+ /**
+ C++ default constructor.
+ */
+ IMPORT_C RFeatureControl();
+
+ /**
+ Connect() must be called before calling any other methods of
+ RFeatureControl.
+ It connects to the Feature Manager Server.
+ After usage Close() function must be called.
+
+ @return Error Code. One of the Symbian error codes.
+
+ @deprecated Use Open() instead.
+ */
+ IMPORT_C TInt Connect();
+
+ /**
+ Open() must be called before calling any other methods of
+ RFeatureControl.
+ After usage Close() function must be called.
+
+ @return Error Code. One of the Symbian error codes.
+ */
+ IMPORT_C TInt Open();
+
+ /**
+ Remember to call Close after using RFeatureControl.
+ */
+ IMPORT_C void Close();
+
+ /**
+ This method returns the supported status on the device of the feature
+ specified in the aFeature parameter.
+
+ @param aFeature Feature UID.
+ @return KFeatureSupported if the feature is supported.
+ KFeatureUnsupported if the feature is not supported.
+ KErrNotFound if the feature does not exist.
+ KErrNotReady it the feature is uninitialized.
+ Otherwise one of the Symbian error codes.
+
+
+ */
+ IMPORT_C TInt FeatureSupported( TUid aFeature );
+
+ /**
+ This method returns the supported status on the device of the feature
+ described by the aFeature parameter. The feature UID should be set in
+ TFeatureEntry class before the FeatureSupported method is called. If
+ FeatureSupported returns successufully the TFeatureEntry parameter will
+ also have been populated with the feature's status flags and the data
+ word associates with the feature.
+
+ @param aFeature A reference to a a client owned TFeatureEntry object.
+ Must contain UID of the queried feature.
+ After returning contains status flags and data of
+ the feature.
+ @return KFeatureSupported if the feature is supported.
+ KFeatureUnsupported if the feature is not supported.
+ KErrNotFound if the feature does not exist.
+ KErrNotReady if the feature is uninitialized.
+ Otherwise one of the Symbian error codes.
+
+
+ */
+ IMPORT_C TInt FeatureSupported( TFeatureEntry& aFeature );
+
+ /**
+ This method allows the user to pass an array of type TFeatureEntry
+ to Feature Manager. In this way the user can retrieve the supported status and
+ associated information for the features whose UIDs have been set in
+ TFeatureEntry classes. In order for the client to know whether
+ feature is just disabled or does not exist at all it must check
+ this from response feature array. If the feature exists the EFeatureSupported
+ status bit will contain the support status. If the feature does not exist
+ it will be removed from array after the query. For this reason instead of hard
+ coding array accesses for features the Find method should always
+ be used to query feature index in array after query.
+
+ @param aFeatures A reference to a a client owned RFeatureArray array.
+ Must contain UIDs of the queried features.
+ @return KErrNone if fetching of features statuses successful.
+ KErrArgument if query made with empty array.
+ Otherwise one of the Symbian error codes.
+
+ */
+ IMPORT_C TInt FeaturesSupported( RFeatureArray& aFeatures );
+
+ /**
+ Enables the specified feature. WriteDeviceData capability required.
+
+ @param aFeature Feature UID.
+ @return Error Code. KErrNone if the feature was succesfully enabled.
+ KErrAccessDenied if the feature is not modifiable.
+ KErrPermissionDenied if a capability check fails.
+ KErrNotFound if the feature does not exist.
+ KErrArgument if the maximum number of cached features
+ during a Software Installer (SWI) install/uninstall
+ session has been exceeded.
+ Otherwise one of the Symbian error codes.
+ */
+ IMPORT_C TInt EnableFeature( TUid aFeature );
+
+ /**
+ Disables the specified feature. WriteDeviceData capability required.
+
+ @param aFeature Feature UID.
+ @return Error Code. KErrNone if the feature was succesfully disabled.
+ KErrAccessDenied if the feature is not modifiable.
+ KErrPermissionDenied if a capability check fails.
+ KErrNotFound if the feature does not exist.
+ KErrArgument if the maximum number of cached features
+ during a Software Installer (SWI) install/uninstall
+ session has been exceeded.
+ Otherwise one of the Symbian error codes.
+ */
+ IMPORT_C TInt DisableFeature( TUid aFeature );
+
+ /**
+ Enables or disables the specified feature and sets feature data.
+ WriteDeviceData capability required.
+
+ @param aFeature Feature UID.
+ @param aEnabled ETrue if enabling the feature, EFalse if disabling.
+ @param aData Feature data.
+ @return Error Code. KErrNone if the feature was succesfully enabled.
+ KErrAccessDenied if the feature is not modifiable.
+ KErrPermissionDenied if a capability check fails.
+ KErrNotFound if the feature does not exist.
+ KErrArgument if the maximum number of cached features
+ during a Software Installer (SWI) install/uninstall
+ session has been exceeded.
+ Otherwise one of the Symbian error codes.
+ */
+ IMPORT_C TInt SetFeature( TUid aFeature, TBool aEnabled, TUint32 aData );
+
+ /**
+ Sets feature data. WriteDeviceData capability required.
+
+ @param aFeature Feature UID.
+ @param aData Feature data.
+ @return Error Code. KErrNone if the feature data was succesfully set.
+ KErrAccessDenied if the feature is not modifiable.
+ KErrPermissionDenied if a capability check fails.
+ KErrNotFound if the feature does not exist.
+ KErrArgument if the maximum number of cached features
+ during a Software Installer (SWI) install/uninstall
+ session has been exceeded.
+ Otherwise one of the Symbian error codes.
+ */
+ IMPORT_C TInt SetFeature( TUid aFeature, TUint32 aData );
+
+ /**
+ Adds a new feature and sets status flags and data of the feature.
+ Note: When adding a new feature to the device status flags and
+ data of the feature must be set. WriteDeviceData capability required.
+
+ @param aFeature A reference to a client owned TFeatureEntry object.
+ Must contain UID, status flags and data of the feature.
+ @return Error Code. KErrNone if the feature was succesfully added.
+ KErrPermissionDenied if capability check fails.
+ KErrAlreadyExists if the feature already exists
+ in the device.
+ KErrArgument if the maximum number of cached features
+ during a Software Installer (SWI) install/uninstall
+ session has been exceeded, or when "out of memory"
+ occured in a previous call to this function during
+ the caching process.
+ KErrNoMemory if out-of-memory occured during caching.
+ Otherwise one of the Symbian error codes.
+
+ @see TFeatureEntry
+ @see TFeatureFlags
+ */
+ IMPORT_C TInt AddFeature( TFeatureEntry& aFeature );
+
+ /**
+ Deletes a feature.
+ Note: WriteDeviceData capability required.
+
+ @param aFeature Feature UID.
+ @return Error Code. KErrNone if the feature was successfully deleted.
+ KErrAccessDenied if the feature is not runtime.
+ KErrPermissionDenied if capability check fails.
+ KErrNotFound if the feature does not exist.
+ KErrArgument if the maximum number of cached features
+ during a Software Installer (SWI) install/uninstall
+ session has been exceeded.
+ KErrNoMemory if out-of-memory occured during caching.
+ Otherwise one of the Symbian error codes.
+
+ @see TFeatureEntry
+ @see TFeatureFlags
+ */
+ IMPORT_C TInt DeleteFeature( TUid aFeature );
+
+ /**
+ Lists all supported features.
+
+ @param aSupportedFeatures A reference to a client owned RFeatureUidArray array which
+ will be filled with the UIDs of supported features.
+ @return Error code. KErrNone if client owned array was successfully
+ filled with IDs of supported features.
+ KErrServerBusy if there was ongoing enabling or
+ disabling of some feature(s) and Feature Manager Server
+ could not return unambiguous list of supported features.
+ KErrNoMemory if out-of-memory occured during caching.
+ Otherwise one of the Symbian error codes.
+ */
+ IMPORT_C TInt ListSupportedFeatures( RFeatureUidArray& aSupportedFeatures );
+
+ /**
+ Calling this method informs Feature Manager that a software installer (SWI)
+ launched executable is going to set, add, delete, enable or disable features
+ in Feature Manager. This mandates Feature Manager to cache all modification
+ calls issued by that executable until a call to SWIEnd is made to commit them
+ to Feature Manager. This prevents against situations where the installation is
+ user-aborted without being able to roll back direct feature manipulations.
+
+ @return Error code. KErrNone if Feature Manager has accepted the request to use
+ the caching APIs.
+ KErrInUse if the caching APIs are already in use by another
+ exe launched by the SWI.
+ KErrNotReady if there is no software installation in progress.
+ */
+ IMPORT_C TInt SWIStart();
+
+ /**
+ Mandates Feature Manager to stop caching and prepare to commit the cached
+ feature manipulations performed by the executable launched by SWI during
+ installation into Feature Manager. The cached features are committed only
+ after that installation of the executable is successfully completed.
+ This API must be called before a timeout managed by Feature Manager times
+ out. Otherwise the cached features will be dumped.
+
+ @return Error code. KErrNone when SWIEnd call is received by a client or when an abort occurs
+ prior to the timeout managed by Feature Manager expires.
+ KErrNotReady if SWIStart was not called before calling this
+ function, or because the timeout managed by Feature Manager
+ had timed out.
+ KErrGeneral an indication that an out-of-memory condition
+ was encountered during caching which will force FeatMgr to
+ disregard the whole cache.
+ KErrNoMemory if an out-of-memory condition was encountered
+ whilst reserving memory in the features list for the new
+ features t be added, or if an out-of-memory occured in a call
+ to AddFeaure() during caching..
+ Otherwise one of the Symbian error codes.
+ */
+ IMPORT_C TInt SWIEnd();
+
+ private:
+
+ /**
+ Used for resource counting.
+ */
+ TBool iInitialized;
+
+ /**
+ Reserved for future use. Initialised to 0 on construction.
+ */
+ TUint32 iReserved1;
+
+ /**
+ Reserved for future use. Initialised to 0 on construction.
+ */
+ TUint32 iReserved2;
+
+ };
+
+/**
+ @code
+ // replace <featureUID> with a real UID )
+
+ #include <featmgr/featurecontrol.h>
+ #include <featmgr/featureinfo.h> // for feature definitions
+
+ CMyClass::MyMethodL()
+ {
+ // Replace KFeatureUidx with real feature uid.
+ // Open() must be called before calling any other methods.
+ // Disconnect is done by calling the Close() method.
+ RFeatureControl featureControl;
+ TInt err = featureControl.Open();
+
+ if ( err == KErrNone )
+ {
+ // Query multiple features statuses (single IPC-call, so less overhead)
+
+ RFeatureArray uids;
+ CleanupClosePushL(uids);
+
+ uids.AppendL( KFeatureUid1 );
+ uids.AppendL( KFeatureUid2 );
+ TInt err = control.FeaturesSupported( uids );
+
+ if ( err == KErrNone )
+ {
+ TInt index;
+
+ index = uids.Find( KFeatureUid1 );
+ if(index == KErrNotFound)
+ {
+ // Feature does not exist (result is analogous if KFeatureUid1
+ // is not appended in uids array before query).
+ }
+ else
+ {
+ iFeature1Supported = uids[index].FeatureFlags().IsSet( EFeatureSupported );
+ }
+
+ index = uids.Find( KFeatureUid2 );
+ if(index == KErrNotFound)
+ {
+ // Feature does not exist (result is analogous if KFeatureUid2
+ // is not appended in uids array before query).
+ }
+ else
+ {
+ TBool feature2Supported = uids[index].FeatureFlags().IsSet( EFeatureSupported );
+ TUint32 data = uids[index].FeatureData();
+ // Do something with support-information and data
+ ...
+ }
+ }
+ CleanupStack::PopAndDestroy(&uids);
+
+
+ // Query single feature status
+
+ err = control.FeatureSupported( KFeatureUid3 );
+ if( err == KFeatureSupported )
+ {
+ // do something with enabled feature
+ }
+
+
+ // Query single feature status and data
+
+ TFeatureEntry entry( KFeatureUid4 );
+ err = control.FeatureSupported( entry );
+ if( err == KFeatureSupported )
+ {
+ TUint32 data = entry.FeatureData();
+ // do something with enabled feature's data
+ }
+ else if( err == KFeatureUnsupported )
+ {
+ // do or do not something with disabled feature's data
+ }
+
+
+ // Enable some feature.
+
+ // EnableFeature() and DisableFeature() methods return
+ // KErrNone if the feature was succesfully enabled or disabled,
+ // KErrAccessDenied if the feature is not modifiable.
+ // KErrPermissionDenied a capability check fails,
+ // KErrNotFound if the feature does not exist and
+ // otherwise one of the Symbian error codes.
+ err = featureControl.EnableFeature( <featureUID> );
+
+ // do something
+
+
+ // List all supported features.
+
+ // A client owned RFeatureUidArray array which will be filled with
+ // the UIDs of supported features.
+ RFeatureUidArray supportedFeatures;
+
+ // ListSupportedFeatures() returns one of the Symbian error codes.
+ err = featureControl.ListSupportedFeatures( supportedFeatures );
+
+ // do something
+
+ // Closes the array and frees all memory allocated to the array.
+ supportedFeatures.Close();
+
+
+ // Remember to call CloseL after using RFeatureControl.
+ // It disconnects the Feature Manager server.
+ featureControl.Close();
+ }
+
+ }
+ @endcode
+*/
+
+#endif // FEATURECONTROL_H
+
+// End of File