1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/persistentdata/featuremgmt/featuremgr/inc/featurecontrol.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,508 @@
1.4 +/*
1.5 +* Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +
1.23 +
1.24 +
1.25 +#ifndef FEATURECONTROL_H
1.26 +#define FEATURECONTROL_H
1.27 +
1.28 +// INCLUDES
1.29 +#include <e32std.h>
1.30 +#include <e32svr.h>
1.31 +#include <featmgr/featurecmn.h>
1.32 +
1.33 +// FORWARD DECLARATIONS
1.34 +
1.35 +// DEFINES
1.36 +
1.37 +// CLASS DECLARATION
1.38 +
1.39 +// CONSTANTS
1.40 +
1.41 +// MACROS
1.42 +
1.43 +/**
1.44 +
1.45 + The Feature Control API provides methods that can be used to query which
1.46 + features are supported on the device. The API also provides methods to
1.47 + get status flags that define that behaviour of the feature flag and data
1.48 + associated with the feature.
1.49 +
1.50 + The Feature Control API provides methods to enable and disable features at
1.51 + runtime e.g. when new software is installed or uninstalled. The API provides
1.52 + also methods for setting feature data, adding a new feature to the device
1.53 + and listing all supported features on the device.
1.54 +
1.55 + It is only possible to enable or disable a feature or set feature data
1.56 + at runtime if that feature is modifiable (this is defined by the status
1.57 + 32 bit word associated with the feature flag). It is also possible to enable or
1.58 + disable a feature UID that is not even defined in the device yet.
1.59 + When adding a new feature to the device status flags and data of the feature
1.60 + must be set.
1.61 +
1.62 + The meaning of the bits of the 32-bit feature status flags are as follows:
1.63 +
1.64 + Bit Flag Name Meaning
1.65 + - 0 Supported If set, feature is supported and available for use;
1.66 + if not, feature is not supported.
1.67 + - 1 Upgradeable If set, feature is upgradeable. The feature is known to
1.68 + the device but it must be upgraded to enable it. If a feature
1.69 + is blacklisted, its upgradeable flag is unset.
1.70 + - 2 Modifiable If set, the feature is modifiable and may be enabled/disabled at
1.71 + run-time. The initial flag values for such a feature flag are
1.72 + defined in a ROM image obey file.
1.73 + - 3 Blacklisted If set, the feature has been blacklisted, and may not be changed
1.74 + at run-time. This also prevents a feature from being upgraded.
1.75 + - 4 Uninitialised If set, the status flag Supported is unknown at build-time and is
1.76 + initialised at run-time by system software. The Feature Manager
1.77 + will ignore the Supported flag in the file. A run-time call to
1.78 + RFeatureControl will be needed to set the feature's supported
1.79 + flag. Look ups of uninitialised features result in a KErrNotReady
1.80 + error code.
1.81 + - 5 Persisted If set, this flag is saved to the system drive when modified
1.82 + preserving its value across reboots/power downs
1.83 + - 6 ..23 Reserved for future use, always zero.
1.84 + - 24..31 Reserved for internal use.
1.85 +
1.86 + Enumeration TFeatureFlags defined in featurecmn.h should be used for
1.87 + accessing feature status flags e.g. flags.IsSet( EFeatureUpgradeable ),
1.88 + flags.IsSet( EFeatureModifiable ).
1.89 +
1.90 + Feature data is 32-bit word for client read and write. Feature data can
1.91 + contain any data that needs to be associated with the Feature Flag.
1.92 + Feature data can only be set if the feature is modifiable or a new feature.
1.93 +
1.94 + The use of the Feature Manager API to set the supported status of a feature,
1.95 + it in no way means that the functionality itself is modified on the device.
1.96 + All the corresponding DLLs, including feature functionality and resources still
1.97 + remain on the device. To properly support runtime activation/deactivation
1.98 + of the feature, all feature APIs need to implement runtime checking of the
1.99 + feature status in their code.
1.100 +
1.101 + The API consists of the RFeatureControl class which is
1.102 + used together with feature UIDs defined in featureUIDs.h, TFeatureFlags,
1.103 + TFeatureEntry and RFeatureUidArray defined in featurecmn.h.
1.104 +
1.105 +
1.106 + Usage:
1.107 +
1.108 + Before calling any other methods the client must call the Open()
1.109 + method that connects to the Feature Manager Server.
1.110 + When the client has finished using the RFeatureControl it should
1.111 + disconnect using the Close() method.
1.112 +
1.113 +@publishedPartner
1.114 +@released
1.115 +*/
1.116 +NONSHARABLE_CLASS(RFeatureControl)
1.117 + {
1.118 + public:
1.119 + /**
1.120 + C++ default constructor.
1.121 + */
1.122 + IMPORT_C RFeatureControl();
1.123 +
1.124 + /**
1.125 + Connect() must be called before calling any other methods of
1.126 + RFeatureControl.
1.127 + It connects to the Feature Manager Server.
1.128 + After usage Close() function must be called.
1.129 +
1.130 + @return Error Code. One of the Symbian error codes.
1.131 +
1.132 + @deprecated Use Open() instead.
1.133 + */
1.134 + IMPORT_C TInt Connect();
1.135 +
1.136 + /**
1.137 + Open() must be called before calling any other methods of
1.138 + RFeatureControl.
1.139 + After usage Close() function must be called.
1.140 +
1.141 + @return Error Code. One of the Symbian error codes.
1.142 + */
1.143 + IMPORT_C TInt Open();
1.144 +
1.145 + /**
1.146 + Remember to call Close after using RFeatureControl.
1.147 + */
1.148 + IMPORT_C void Close();
1.149 +
1.150 + /**
1.151 + This method returns the supported status on the device of the feature
1.152 + specified in the aFeature parameter.
1.153 +
1.154 + @param aFeature Feature UID.
1.155 + @return KFeatureSupported if the feature is supported.
1.156 + KFeatureUnsupported if the feature is not supported.
1.157 + KErrNotFound if the feature does not exist.
1.158 + KErrNotReady it the feature is uninitialized.
1.159 + Otherwise one of the Symbian error codes.
1.160 +
1.161 +
1.162 + */
1.163 + IMPORT_C TInt FeatureSupported( TUid aFeature );
1.164 +
1.165 + /**
1.166 + This method returns the supported status on the device of the feature
1.167 + described by the aFeature parameter. The feature UID should be set in
1.168 + TFeatureEntry class before the FeatureSupported method is called. If
1.169 + FeatureSupported returns successufully the TFeatureEntry parameter will
1.170 + also have been populated with the feature's status flags and the data
1.171 + word associates with the feature.
1.172 +
1.173 + @param aFeature A reference to a a client owned TFeatureEntry object.
1.174 + Must contain UID of the queried feature.
1.175 + After returning contains status flags and data of
1.176 + the feature.
1.177 + @return KFeatureSupported if the feature is supported.
1.178 + KFeatureUnsupported if the feature is not supported.
1.179 + KErrNotFound if the feature does not exist.
1.180 + KErrNotReady if the feature is uninitialized.
1.181 + Otherwise one of the Symbian error codes.
1.182 +
1.183 +
1.184 + */
1.185 + IMPORT_C TInt FeatureSupported( TFeatureEntry& aFeature );
1.186 +
1.187 + /**
1.188 + This method allows the user to pass an array of type TFeatureEntry
1.189 + to Feature Manager. In this way the user can retrieve the supported status and
1.190 + associated information for the features whose UIDs have been set in
1.191 + TFeatureEntry classes. In order for the client to know whether
1.192 + feature is just disabled or does not exist at all it must check
1.193 + this from response feature array. If the feature exists the EFeatureSupported
1.194 + status bit will contain the support status. If the feature does not exist
1.195 + it will be removed from array after the query. For this reason instead of hard
1.196 + coding array accesses for features the Find method should always
1.197 + be used to query feature index in array after query.
1.198 +
1.199 + @param aFeatures A reference to a a client owned RFeatureArray array.
1.200 + Must contain UIDs of the queried features.
1.201 + @return KErrNone if fetching of features statuses successful.
1.202 + KErrArgument if query made with empty array.
1.203 + Otherwise one of the Symbian error codes.
1.204 +
1.205 + */
1.206 + IMPORT_C TInt FeaturesSupported( RFeatureArray& aFeatures );
1.207 +
1.208 + /**
1.209 + Enables the specified feature. WriteDeviceData capability required.
1.210 +
1.211 + @param aFeature Feature UID.
1.212 + @return Error Code. KErrNone if the feature was succesfully enabled.
1.213 + KErrAccessDenied if the feature is not modifiable.
1.214 + KErrPermissionDenied if a capability check fails.
1.215 + KErrNotFound if the feature does not exist.
1.216 + KErrArgument if the maximum number of cached features
1.217 + during a Software Installer (SWI) install/uninstall
1.218 + session has been exceeded.
1.219 + Otherwise one of the Symbian error codes.
1.220 + */
1.221 + IMPORT_C TInt EnableFeature( TUid aFeature );
1.222 +
1.223 + /**
1.224 + Disables the specified feature. WriteDeviceData capability required.
1.225 +
1.226 + @param aFeature Feature UID.
1.227 + @return Error Code. KErrNone if the feature was succesfully disabled.
1.228 + KErrAccessDenied if the feature is not modifiable.
1.229 + KErrPermissionDenied if a capability check fails.
1.230 + KErrNotFound if the feature does not exist.
1.231 + KErrArgument if the maximum number of cached features
1.232 + during a Software Installer (SWI) install/uninstall
1.233 + session has been exceeded.
1.234 + Otherwise one of the Symbian error codes.
1.235 + */
1.236 + IMPORT_C TInt DisableFeature( TUid aFeature );
1.237 +
1.238 + /**
1.239 + Enables or disables the specified feature and sets feature data.
1.240 + WriteDeviceData capability required.
1.241 +
1.242 + @param aFeature Feature UID.
1.243 + @param aEnabled ETrue if enabling the feature, EFalse if disabling.
1.244 + @param aData Feature data.
1.245 + @return Error Code. KErrNone if the feature was succesfully enabled.
1.246 + KErrAccessDenied if the feature is not modifiable.
1.247 + KErrPermissionDenied if a capability check fails.
1.248 + KErrNotFound if the feature does not exist.
1.249 + KErrArgument if the maximum number of cached features
1.250 + during a Software Installer (SWI) install/uninstall
1.251 + session has been exceeded.
1.252 + Otherwise one of the Symbian error codes.
1.253 + */
1.254 + IMPORT_C TInt SetFeature( TUid aFeature, TBool aEnabled, TUint32 aData );
1.255 +
1.256 + /**
1.257 + Sets feature data. WriteDeviceData capability required.
1.258 +
1.259 + @param aFeature Feature UID.
1.260 + @param aData Feature data.
1.261 + @return Error Code. KErrNone if the feature data was succesfully set.
1.262 + KErrAccessDenied if the feature is not modifiable.
1.263 + KErrPermissionDenied if a capability check fails.
1.264 + KErrNotFound if the feature does not exist.
1.265 + KErrArgument if the maximum number of cached features
1.266 + during a Software Installer (SWI) install/uninstall
1.267 + session has been exceeded.
1.268 + Otherwise one of the Symbian error codes.
1.269 + */
1.270 + IMPORT_C TInt SetFeature( TUid aFeature, TUint32 aData );
1.271 +
1.272 + /**
1.273 + Adds a new feature and sets status flags and data of the feature.
1.274 + Note: When adding a new feature to the device status flags and
1.275 + data of the feature must be set. WriteDeviceData capability required.
1.276 +
1.277 + @param aFeature A reference to a client owned TFeatureEntry object.
1.278 + Must contain UID, status flags and data of the feature.
1.279 + @return Error Code. KErrNone if the feature was succesfully added.
1.280 + KErrPermissionDenied if capability check fails.
1.281 + KErrAlreadyExists if the feature already exists
1.282 + in the device.
1.283 + KErrArgument if the maximum number of cached features
1.284 + during a Software Installer (SWI) install/uninstall
1.285 + session has been exceeded, or when "out of memory"
1.286 + occured in a previous call to this function during
1.287 + the caching process.
1.288 + KErrNoMemory if out-of-memory occured during caching.
1.289 + Otherwise one of the Symbian error codes.
1.290 +
1.291 + @see TFeatureEntry
1.292 + @see TFeatureFlags
1.293 + */
1.294 + IMPORT_C TInt AddFeature( TFeatureEntry& aFeature );
1.295 +
1.296 + /**
1.297 + Deletes a feature.
1.298 + Note: WriteDeviceData capability required.
1.299 +
1.300 + @param aFeature Feature UID.
1.301 + @return Error Code. KErrNone if the feature was successfully deleted.
1.302 + KErrAccessDenied if the feature is not runtime.
1.303 + KErrPermissionDenied if capability check fails.
1.304 + KErrNotFound if the feature does not exist.
1.305 + KErrArgument if the maximum number of cached features
1.306 + during a Software Installer (SWI) install/uninstall
1.307 + session has been exceeded.
1.308 + KErrNoMemory if out-of-memory occured during caching.
1.309 + Otherwise one of the Symbian error codes.
1.310 +
1.311 + @see TFeatureEntry
1.312 + @see TFeatureFlags
1.313 + */
1.314 + IMPORT_C TInt DeleteFeature( TUid aFeature );
1.315 +
1.316 + /**
1.317 + Lists all supported features.
1.318 +
1.319 + @param aSupportedFeatures A reference to a client owned RFeatureUidArray array which
1.320 + will be filled with the UIDs of supported features.
1.321 + @return Error code. KErrNone if client owned array was successfully
1.322 + filled with IDs of supported features.
1.323 + KErrServerBusy if there was ongoing enabling or
1.324 + disabling of some feature(s) and Feature Manager Server
1.325 + could not return unambiguous list of supported features.
1.326 + KErrNoMemory if out-of-memory occured during caching.
1.327 + Otherwise one of the Symbian error codes.
1.328 + */
1.329 + IMPORT_C TInt ListSupportedFeatures( RFeatureUidArray& aSupportedFeatures );
1.330 +
1.331 + /**
1.332 + Calling this method informs Feature Manager that a software installer (SWI)
1.333 + launched executable is going to set, add, delete, enable or disable features
1.334 + in Feature Manager. This mandates Feature Manager to cache all modification
1.335 + calls issued by that executable until a call to SWIEnd is made to commit them
1.336 + to Feature Manager. This prevents against situations where the installation is
1.337 + user-aborted without being able to roll back direct feature manipulations.
1.338 +
1.339 + @return Error code. KErrNone if Feature Manager has accepted the request to use
1.340 + the caching APIs.
1.341 + KErrInUse if the caching APIs are already in use by another
1.342 + exe launched by the SWI.
1.343 + KErrNotReady if there is no software installation in progress.
1.344 + */
1.345 + IMPORT_C TInt SWIStart();
1.346 +
1.347 + /**
1.348 + Mandates Feature Manager to stop caching and prepare to commit the cached
1.349 + feature manipulations performed by the executable launched by SWI during
1.350 + installation into Feature Manager. The cached features are committed only
1.351 + after that installation of the executable is successfully completed.
1.352 + This API must be called before a timeout managed by Feature Manager times
1.353 + out. Otherwise the cached features will be dumped.
1.354 +
1.355 + @return Error code. KErrNone when SWIEnd call is received by a client or when an abort occurs
1.356 + prior to the timeout managed by Feature Manager expires.
1.357 + KErrNotReady if SWIStart was not called before calling this
1.358 + function, or because the timeout managed by Feature Manager
1.359 + had timed out.
1.360 + KErrGeneral an indication that an out-of-memory condition
1.361 + was encountered during caching which will force FeatMgr to
1.362 + disregard the whole cache.
1.363 + KErrNoMemory if an out-of-memory condition was encountered
1.364 + whilst reserving memory in the features list for the new
1.365 + features t be added, or if an out-of-memory occured in a call
1.366 + to AddFeaure() during caching..
1.367 + Otherwise one of the Symbian error codes.
1.368 + */
1.369 + IMPORT_C TInt SWIEnd();
1.370 +
1.371 + private:
1.372 +
1.373 + /**
1.374 + Used for resource counting.
1.375 + */
1.376 + TBool iInitialized;
1.377 +
1.378 + /**
1.379 + Reserved for future use. Initialised to 0 on construction.
1.380 + */
1.381 + TUint32 iReserved1;
1.382 +
1.383 + /**
1.384 + Reserved for future use. Initialised to 0 on construction.
1.385 + */
1.386 + TUint32 iReserved2;
1.387 +
1.388 + };
1.389 +
1.390 +/**
1.391 + @code
1.392 + // replace <featureUID> with a real UID )
1.393 +
1.394 + #include <featmgr/featurecontrol.h>
1.395 + #include <featmgr/featureinfo.h> // for feature definitions
1.396 +
1.397 + CMyClass::MyMethodL()
1.398 + {
1.399 + // Replace KFeatureUidx with real feature uid.
1.400 + // Open() must be called before calling any other methods.
1.401 + // Disconnect is done by calling the Close() method.
1.402 + RFeatureControl featureControl;
1.403 + TInt err = featureControl.Open();
1.404 +
1.405 + if ( err == KErrNone )
1.406 + {
1.407 + // Query multiple features statuses (single IPC-call, so less overhead)
1.408 +
1.409 + RFeatureArray uids;
1.410 + CleanupClosePushL(uids);
1.411 +
1.412 + uids.AppendL( KFeatureUid1 );
1.413 + uids.AppendL( KFeatureUid2 );
1.414 + TInt err = control.FeaturesSupported( uids );
1.415 +
1.416 + if ( err == KErrNone )
1.417 + {
1.418 + TInt index;
1.419 +
1.420 + index = uids.Find( KFeatureUid1 );
1.421 + if(index == KErrNotFound)
1.422 + {
1.423 + // Feature does not exist (result is analogous if KFeatureUid1
1.424 + // is not appended in uids array before query).
1.425 + }
1.426 + else
1.427 + {
1.428 + iFeature1Supported = uids[index].FeatureFlags().IsSet( EFeatureSupported );
1.429 + }
1.430 +
1.431 + index = uids.Find( KFeatureUid2 );
1.432 + if(index == KErrNotFound)
1.433 + {
1.434 + // Feature does not exist (result is analogous if KFeatureUid2
1.435 + // is not appended in uids array before query).
1.436 + }
1.437 + else
1.438 + {
1.439 + TBool feature2Supported = uids[index].FeatureFlags().IsSet( EFeatureSupported );
1.440 + TUint32 data = uids[index].FeatureData();
1.441 + // Do something with support-information and data
1.442 + ...
1.443 + }
1.444 + }
1.445 + CleanupStack::PopAndDestroy(&uids);
1.446 +
1.447 +
1.448 + // Query single feature status
1.449 +
1.450 + err = control.FeatureSupported( KFeatureUid3 );
1.451 + if( err == KFeatureSupported )
1.452 + {
1.453 + // do something with enabled feature
1.454 + }
1.455 +
1.456 +
1.457 + // Query single feature status and data
1.458 +
1.459 + TFeatureEntry entry( KFeatureUid4 );
1.460 + err = control.FeatureSupported( entry );
1.461 + if( err == KFeatureSupported )
1.462 + {
1.463 + TUint32 data = entry.FeatureData();
1.464 + // do something with enabled feature's data
1.465 + }
1.466 + else if( err == KFeatureUnsupported )
1.467 + {
1.468 + // do or do not something with disabled feature's data
1.469 + }
1.470 +
1.471 +
1.472 + // Enable some feature.
1.473 +
1.474 + // EnableFeature() and DisableFeature() methods return
1.475 + // KErrNone if the feature was succesfully enabled or disabled,
1.476 + // KErrAccessDenied if the feature is not modifiable.
1.477 + // KErrPermissionDenied a capability check fails,
1.478 + // KErrNotFound if the feature does not exist and
1.479 + // otherwise one of the Symbian error codes.
1.480 + err = featureControl.EnableFeature( <featureUID> );
1.481 +
1.482 + // do something
1.483 +
1.484 +
1.485 + // List all supported features.
1.486 +
1.487 + // A client owned RFeatureUidArray array which will be filled with
1.488 + // the UIDs of supported features.
1.489 + RFeatureUidArray supportedFeatures;
1.490 +
1.491 + // ListSupportedFeatures() returns one of the Symbian error codes.
1.492 + err = featureControl.ListSupportedFeatures( supportedFeatures );
1.493 +
1.494 + // do something
1.495 +
1.496 + // Closes the array and frees all memory allocated to the array.
1.497 + supportedFeatures.Close();
1.498 +
1.499 +
1.500 + // Remember to call CloseL after using RFeatureControl.
1.501 + // It disconnects the Feature Manager server.
1.502 + featureControl.Close();
1.503 + }
1.504 +
1.505 + }
1.506 + @endcode
1.507 +*/
1.508 +
1.509 +#endif // FEATURECONTROL_H
1.510 +
1.511 +// End of File