diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/featdiscovery.h --- a/epoc32/include/featdiscovery.h Wed Mar 31 12:27:01 2010 +0100 +++ b/epoc32/include/featdiscovery.h Wed Mar 31 12:33:34 2010 +0100 @@ -1,157 +1,307 @@ /* -* Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies). +* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members +* under the terms of "Eclipse Public License v1.0" * which accompanies this distribution, and is available -* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +* at the URL "http://www.eclipse.org/legal/epl-v10.html". * * Initial Contributors: * Nokia Corporation - initial contribution. * * Contributors: * -* Description: Offers functionality for querying whether a feature is -* supported in the current environment. +* Description: * */ -#ifndef FEATUREDISCOVERY_H -#define FEATUREDISCOVERY_H + +#ifndef FEATDISCOVERY_H +#define FEATDISCOVERY_H // INCLUDES -#include +#include +class CFeatureDiscoveryImpl; /** -* Class used to query which features are suppported in the environment. -* Feature Discovery API provides methods which are used to query which -* features are supported in the environment. A feature is a functionality that -* can be optionally left out of some product configurations. Features often -* depend on the underlying hardware. For example, MMC support or USB support -* can be features. The API consist of the CFeatureDiscovery class which is -* used together with feature IDs defined in the featureinfo.h file. -* -* -* Usage: -* -* @code -* #include -* #include // for feature definitions -* -* // If querying only one feature, it is more efficient to use the class -* // via the static method, IsFeatureSupportedL(). -* // When querying more than one feature, it is more efficient to use the -* // class by creating an instance and calling the IsSupported() method. -* -* // Static way of using the class: -* TBool isSupported = CFeatureDiscovery::IsFeatureSupportedL(KFeatureIdUsb); -* -* // Dynamic way of using the class using NewL(): -* -* // Call NewL() to create an instance of CFeatureDiscovery. -* CFeatureDiscovery* testA = CFeatureDiscovery::NewL(); -* -* // Call the exported IsSupported() method to query whether features -* // are supported in the current environment or not. -* TBool usbSupported = testA->IsSupported(KFeatureIdUsb); -* TBool mmcSupported = testA->IsSupported(KFeatureIdMmc); -* -* // Delete the created instance of CFeatureDiscovery. -* delete testA; -* -* // Dynamic way of using the class using NewLC(): -* -* // Call NewLC() to create an instance of CFeatureDiscovery. -* // The method leaves the instance of the object on the cleanup stack. -* CFeatureDiscovery* testB = CFeatureDiscovery::NewLC(); -* -* // Call the exported IsSupported() method to query whether features -* // are supported in the current environment or not. -* TBool wcdmaSupported = testB->IsSupported(KFeatureIdProtocolWcdma); -* TBool gsmSupported = testB->IsSupported(KFeatureIdProtocolGsm); -* -* // Pop and delete the created instance of CFeatureDiscovery. -* CleanupStack::PopAndDestroy(); -* @endcode -* -* @lib featdiscovery.lib -* @since S60 2.8 +Wrapper class used for multiple feature queries. +@publishedAll +@released */ +class TFeatureSet + { + public: + + /** + Constructor + */ + IMPORT_C TFeatureSet(); + + /** + Destructor + */ + IMPORT_C ~TFeatureSet(); + + /** + Method to add features before querying support statuses. This + method must be called to initialize feature array before querying + support statuses from server with FeaturesSupported(L) and finally + check the status with a call to IsFeatureSupported or AreAllFeaturesSupported. + + @return KErrNone if feature addition succeded. + Otherwise one of the Symbian OS error codes + */ + IMPORT_C TInt Append( TUid aFeature ); + + /** + Method to check feature's support status. + + @param aFeature is the feature UID of the feature that is queried. + @return a TBool indicating whether the feature is supported (ETrue) + or not (EFalse). If the feature does not exist, the return value is + EFalse. + */ + IMPORT_C TBool IsFeatureSupported( TUid aFeature ) const; + + /** + Method to check whether all features queried are supported. + + @return ETrue if all features queried are supported or no features have been queried. + Otherwise EFalse. + */ + IMPORT_C TBool AreAllFeaturesSupported() const; + + public: // For CFeatureDiscoveryImpl internal use + + // Count number of features in TFeatureStat array. + TInt Count(); + + // Return id of feature in requested index from TFeatureStat array. + TUid FeatureId( TInt aIndex ) const; + + // Reset TFeatureStat array. + void Reset(); + + // Append feature and status object into TFeatureStat array + TInt Append( TUid aFeature, TBool aSupported ); + + private: + struct TFeatureStat + { + TUid iFeatureID; + TBool iSupported; + }; + + private: + // Feature id, status array + RArray iStatus; + + // Counter for checking feature count before and after query + TInt iCount; + + // Reserved for future use. + TUint32 iReserved; + }; + +/** + The feature discovery API provides methods which are used to query which + features are supported in the environment. + +@publishedAll +@released +*/ class CFeatureDiscovery : public CBase { public: - /** - * This is a two-phase constructor method that is used to create - * a new instance of the CFeatureDiscovery class. - * - * @return a pointer to a new instance of the CFeatureDiscovery class. - * - * @leave One of the Symbian OS error codes - */ + /** + This is a two-phase constructor method that is used to create + a new instance of the CFeatureDiscovery class. + + @return a pointer to a new instance of the CFeatureDiscovery class. + + @leave Any One of the Symbian OS system-wide error codes + */ IMPORT_C static CFeatureDiscovery* NewL(); - /** - * This is a two-phase constructor method that is used to create - * a new instance of the CFeatureDiscovery class. This method leaves - * the instance of the object on the cleanup stack. - * - * @return a pointer to a new instance of the CFeatureDiscovery class. - * - * @leave One of the Symbian OS error codes - */ + /** + This is a two-phase constructor method that is used to create + a new instance of the CFeatureDiscovery class. This method leaves + the instance of the object on the cleanup stack. + + @return a pointer to a new instance of the CFeatureDiscovery class. + + @leave Any One of the Symbian OS system-wide error codes + */ IMPORT_C static CFeatureDiscovery* NewLC(); - /** - * Destructor. - */ + /** + Destructor. + */ virtual ~CFeatureDiscovery(); /** - * Static way to fetch information whether a certain feature is - * supported in the current envinronment. There is no need to create - * an instance of the class when using this method. - * - * @param aFeature is the feature ID of the feature that is queried. - * @return a TBool indicating whether the feature is supported (ETrue) - * or not (EFalse). If the feature does not exist, the return value is - * EFalse. - * - * @leave One of the Symbian OS error codes. - */ - IMPORT_C static TBool IsFeatureSupportedL(TInt aFeature); + Static method to query the supported status of a feature on the + device. + + @deprecated Use IsFeatureSupportedL(TUid aFeature) instead. + + @param aFeature is the feature ID of the feature that is queried. + @return a TBool indicating whether the feature is supported (ETrue) + or not (EFalse). If the feature does not exist, the return value is + EFalse. + + @leave Any One of the Symbian OS system-wide error codes + */ + IMPORT_C static TBool IsFeatureSupportedL( TInt aFeature ); /** - * Dynamic way to fetch information whether a certain feature is - * supported in the current environment. Before calling the method - * an instance of the CFeatureDiscovery class need to be created by - * using one of the factory methods, NewL() or NewLC(). The created - * instance must be deleted after use. - * - * @param aFeature is the feature ID of the feature that is queried. - * @return a TBool indicating whether the feature is supported (ETrue) - * or not (EFalse). If the feature does not exist, the return value is - * EFalse. - */ - IMPORT_C TBool IsSupported(TInt aFeature) const ; + Dynamic method to query the supported status of a feature on the + device. Before calling the method an instance of the CFeatureDiscovery + class must be created by using one of the factory methods, + NewL() or NewLC(). The created instance must be deleted after use. + + @deprecated Use IsSupported(TUid aFeature) instead. + + @param aFeature is the feature ID of the feature that is queried. + @return a TBool indicating whether the feature is supported (ETrue) + or not (EFalse). If the feature does not exist, the return value is + EFalse. + */ + IMPORT_C TBool IsSupported( TInt aFeature ) const ; + + /** + Static method to query the supported status of a feature on the device. + + @param aFeature is the feature UID of the feature that is queried. + @return a TBool indicating whether the feature is supported (ETrue) + or not (EFalse). If the feature does not exist, the return value is + EFalse. + + @leave Any One of the Symbian OS system-wide error codes + */ + IMPORT_C static TBool IsFeatureSupportedL( TUid aFeature ); + + /** + Dynamic method to query the supported status of a feature on the device. + + Before calling the method an instance of the CFeatureDiscovery class must + be created by using one of the factory methods, NewL() or NewLC(). + The created instance must be deleted after use. + + @param aFeature is the feature UID of the feature that is queried. + @return a TBool indicating whether the feature is supported (ETrue) + or not (EFalse). If the feature does not exist, the return value is + EFalse. + */ + IMPORT_C TBool IsSupported( TUid aFeature ) const ; + + /** + Static method to query the supported status of a set of features + on the device. + + @param aFeatures is the wrapper class for feature array queried. + + @leave Any One of the Symbian OS system-wide error codes + */ + IMPORT_C static void FeaturesSupportedL( TFeatureSet& aFeatures ); + + /** + Dynamic method to query the supported status of a set of features + on the device. Before calling the method an instance of the + CFeatureDiscovery class need to be created by using one of the + factory methods, NewL() or NewLC(). The created instance must be + deleted after use. + + @param aFeatures is the wrapper class for feature array queried. + @return KErrNone if status query succeeded. + Otherwise one of the Symbian OS error codes + */ + IMPORT_C TInt FeaturesSupported( TFeatureSet& aFeatures ) const; private: - /** - * C++ default constructor. - */ + /** + C++ default constructor. + */ CFeatureDiscovery(); - /** - * By default Symbian OS constructor is private. - */ - void ConstructL(); + /** + By default Symbian OS constructor is private. + */ + void ConstructL(); + + private: + + // Feature discovery implementation class + CFeatureDiscoveryImpl* iImpl; } ; +/** + Usage: -#endif // FEATUREDISCOVERY_H + @code + #include + #include // for feature definitions -// EOF + // replace with a real UID ) + + // If querying only one feature, it is more efficient to use the class + // via the static method, IsFeatureSupportedL(). + // When querying more than one feature, it is more efficient to use the + // class by creating an instance and calling the IsSupported() method. + + // Static way of using the class: + TBool isSupported = CFeatureDiscovery::IsFeatureSupportedL(); + + // Dynamic way of using the class using NewL(): + + // Call NewL() to create an instance of CFeatureDiscovery. + CFeatureDiscovery* testA = CFeatureDiscovery::NewL(); + + // Call the exported IsSupported() method to query whether features + // are supported in the current environment or not. + TBool usbSupported = testA->IsSupported(); + TBool mmcSupported = testA->IsSupported(); + + // Delete the created instance of CFeatureDiscovery. + delete testA; + + // Dynamic way of using the class using NewLC(): + + // Call NewLC() to create an instance of CFeatureDiscovery. + // The method leaves the instance of the object on the cleanup stack. + CFeatureDiscovery* testB = CFeatureDiscovery::NewLC(); + + // Call the exported IsSupported() method to query whether features + // are supported in the current environment or not. + TBool wcdmaSupported = testB->IsSupported(); + TBool gsmSupported = testB->IsSupported(); + + // Dynamic way of using multiple feature query. This is preferred + // way to fetch support statuses if there are several features to be + // queried, because it involves less inter-process communication. + + TFeatureSet featset; + User::LeaveIfError( featset.Append( ) ); + User::LeaveIfError( featset.Append( ) ); + TInt err = testB->FeaturesSupported( featset ); + if(!err) + { + TBool uid1Supported = featset.IsFeatureSupported(); + TBool uid2Supported = featset.IsFeatureSupported(); + // ... or whether all QUERIED features are supported + TBool allSupported = featset.AreAllFeaturesSupported(); + } + // featset cleans array up in destructor on scope exit + + // Pop and delete the created instance of CFeatureDiscovery. + CleanupStack::PopAndDestroy(); + @endcode +*/ +#endif // FEATDISCOVERY_H + +// End of File