Workaround for Bug 3854 - featuremgr bld.inf no longer exports features.dat for emulator
/*
* 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