1.1 --- a/epoc32/include/featdiscovery.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ b/epoc32/include/featdiscovery.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -1,157 +1,307 @@
1.4 /*
1.5 -* Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
1.7 * All rights reserved.
1.8 * This component and the accompanying materials are made available
1.9 -* 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
1.10 +* under the terms of "Eclipse Public License v1.0"
1.11 * which accompanies this distribution, and is available
1.12 -* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.13 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.14 *
1.15 * Initial Contributors:
1.16 * Nokia Corporation - initial contribution.
1.17 *
1.18 * Contributors:
1.19 *
1.20 -* Description: Offers functionality for querying whether a feature is
1.21 -* supported in the current environment.
1.22 +* Description:
1.23 *
1.24 */
1.25
1.26
1.27 -#ifndef FEATUREDISCOVERY_H
1.28 -#define FEATUREDISCOVERY_H
1.29 +
1.30 +#ifndef FEATDISCOVERY_H
1.31 +#define FEATDISCOVERY_H
1.32
1.33 // INCLUDES
1.34 -#include <e32std.h>
1.35 +#include <e32base.h>
1.36
1.37 +class CFeatureDiscoveryImpl;
1.38
1.39 /**
1.40 -* Class used to query which features are suppported in the environment.
1.41 -* Feature Discovery API provides methods which are used to query which
1.42 -* features are supported in the environment. A feature is a functionality that
1.43 -* can be optionally left out of some product configurations. Features often
1.44 -* depend on the underlying hardware. For example, MMC support or USB support
1.45 -* can be features. The API consist of the CFeatureDiscovery class which is
1.46 -* used together with feature IDs defined in the featureinfo.h file.
1.47 -*
1.48 -*
1.49 -* Usage:
1.50 -*
1.51 -* @code
1.52 -* #include <FeatDiscovery.h>
1.53 -* #include <featureinfo.h> // for feature definitions
1.54 -*
1.55 -* // If querying only one feature, it is more efficient to use the class
1.56 -* // via the static method, IsFeatureSupportedL().
1.57 -* // When querying more than one feature, it is more efficient to use the
1.58 -* // class by creating an instance and calling the IsSupported() method.
1.59 -*
1.60 -* // Static way of using the class:
1.61 -* TBool isSupported = CFeatureDiscovery::IsFeatureSupportedL(KFeatureIdUsb);
1.62 -*
1.63 -* // Dynamic way of using the class using NewL():
1.64 -*
1.65 -* // Call NewL() to create an instance of CFeatureDiscovery.
1.66 -* CFeatureDiscovery* testA = CFeatureDiscovery::NewL();
1.67 -*
1.68 -* // Call the exported IsSupported() method to query whether features
1.69 -* // are supported in the current environment or not.
1.70 -* TBool usbSupported = testA->IsSupported(KFeatureIdUsb);
1.71 -* TBool mmcSupported = testA->IsSupported(KFeatureIdMmc);
1.72 -*
1.73 -* // Delete the created instance of CFeatureDiscovery.
1.74 -* delete testA;
1.75 -*
1.76 -* // Dynamic way of using the class using NewLC():
1.77 -*
1.78 -* // Call NewLC() to create an instance of CFeatureDiscovery.
1.79 -* // The method leaves the instance of the object on the cleanup stack.
1.80 -* CFeatureDiscovery* testB = CFeatureDiscovery::NewLC();
1.81 -*
1.82 -* // Call the exported IsSupported() method to query whether features
1.83 -* // are supported in the current environment or not.
1.84 -* TBool wcdmaSupported = testB->IsSupported(KFeatureIdProtocolWcdma);
1.85 -* TBool gsmSupported = testB->IsSupported(KFeatureIdProtocolGsm);
1.86 -*
1.87 -* // Pop and delete the created instance of CFeatureDiscovery.
1.88 -* CleanupStack::PopAndDestroy();
1.89 -* @endcode
1.90 -*
1.91 -* @lib featdiscovery.lib
1.92 -* @since S60 2.8
1.93 +Wrapper class used for multiple feature queries.
1.94 +@publishedAll
1.95 +@released
1.96 */
1.97
1.98 +class TFeatureSet
1.99 + {
1.100 + public:
1.101 +
1.102 + /**
1.103 + Constructor
1.104 + */
1.105 + IMPORT_C TFeatureSet();
1.106 +
1.107 + /**
1.108 + Destructor
1.109 + */
1.110 + IMPORT_C ~TFeatureSet();
1.111 +
1.112 + /**
1.113 + Method to add features before querying support statuses. This
1.114 + method must be called to initialize feature array before querying
1.115 + support statuses from server with FeaturesSupported(L) and finally
1.116 + check the status with a call to IsFeatureSupported or AreAllFeaturesSupported.
1.117 +
1.118 + @return KErrNone if feature addition succeded.
1.119 + Otherwise one of the Symbian OS error codes
1.120 + */
1.121 + IMPORT_C TInt Append( TUid aFeature );
1.122 +
1.123 + /**
1.124 + Method to check feature's support status.
1.125 +
1.126 + @param aFeature is the feature UID of the feature that is queried.
1.127 + @return a TBool indicating whether the feature is supported (ETrue)
1.128 + or not (EFalse). If the feature does not exist, the return value is
1.129 + EFalse.
1.130 + */
1.131 + IMPORT_C TBool IsFeatureSupported( TUid aFeature ) const;
1.132 +
1.133 + /**
1.134 + Method to check whether all features queried are supported.
1.135 +
1.136 + @return ETrue if all features queried are supported or no features have been queried.
1.137 + Otherwise EFalse.
1.138 + */
1.139 + IMPORT_C TBool AreAllFeaturesSupported() const;
1.140 +
1.141 + public: // For CFeatureDiscoveryImpl internal use
1.142 +
1.143 + // Count number of features in TFeatureStat array.
1.144 + TInt Count();
1.145 +
1.146 + // Return id of feature in requested index from TFeatureStat array.
1.147 + TUid FeatureId( TInt aIndex ) const;
1.148 +
1.149 + // Reset TFeatureStat array.
1.150 + void Reset();
1.151 +
1.152 + // Append feature and status object into TFeatureStat array
1.153 + TInt Append( TUid aFeature, TBool aSupported );
1.154 +
1.155 + private:
1.156 + struct TFeatureStat
1.157 + {
1.158 + TUid iFeatureID;
1.159 + TBool iSupported;
1.160 + };
1.161 +
1.162 + private:
1.163 + // Feature id, status array
1.164 + RArray<TFeatureStat> iStatus;
1.165 +
1.166 + // Counter for checking feature count before and after query
1.167 + TInt iCount;
1.168 +
1.169 + // Reserved for future use.
1.170 + TUint32 iReserved;
1.171 + };
1.172 +
1.173 +/**
1.174 + The feature discovery API provides methods which are used to query which
1.175 + features are supported in the environment.
1.176 +
1.177 +@publishedAll
1.178 +@released
1.179 +*/
1.180 class CFeatureDiscovery : public CBase
1.181 {
1.182 public:
1.183
1.184 - /**
1.185 - * This is a two-phase constructor method that is used to create
1.186 - * a new instance of the CFeatureDiscovery class.
1.187 - *
1.188 - * @return a pointer to a new instance of the CFeatureDiscovery class.
1.189 - *
1.190 - * @leave One of the Symbian OS error codes
1.191 - */
1.192 + /**
1.193 + This is a two-phase constructor method that is used to create
1.194 + a new instance of the CFeatureDiscovery class.
1.195 +
1.196 + @return a pointer to a new instance of the CFeatureDiscovery class.
1.197 +
1.198 + @leave Any One of the Symbian OS system-wide error codes
1.199 + */
1.200 IMPORT_C static CFeatureDiscovery* NewL();
1.201
1.202 - /**
1.203 - * This is a two-phase constructor method that is used to create
1.204 - * a new instance of the CFeatureDiscovery class. This method leaves
1.205 - * the instance of the object on the cleanup stack.
1.206 - *
1.207 - * @return a pointer to a new instance of the CFeatureDiscovery class.
1.208 - *
1.209 - * @leave One of the Symbian OS error codes
1.210 - */
1.211 + /**
1.212 + This is a two-phase constructor method that is used to create
1.213 + a new instance of the CFeatureDiscovery class. This method leaves
1.214 + the instance of the object on the cleanup stack.
1.215 +
1.216 + @return a pointer to a new instance of the CFeatureDiscovery class.
1.217 +
1.218 + @leave Any One of the Symbian OS system-wide error codes
1.219 + */
1.220 IMPORT_C static CFeatureDiscovery* NewLC();
1.221
1.222 - /**
1.223 - * Destructor.
1.224 - */
1.225 + /**
1.226 + Destructor.
1.227 + */
1.228 virtual ~CFeatureDiscovery();
1.229
1.230 /**
1.231 - * Static way to fetch information whether a certain feature is
1.232 - * supported in the current envinronment. There is no need to create
1.233 - * an instance of the class when using this method.
1.234 - *
1.235 - * @param aFeature is the feature ID of the feature that is queried.
1.236 - * @return a TBool indicating whether the feature is supported (ETrue)
1.237 - * or not (EFalse). If the feature does not exist, the return value is
1.238 - * EFalse.
1.239 - *
1.240 - * @leave One of the Symbian OS error codes.
1.241 - */
1.242 - IMPORT_C static TBool IsFeatureSupportedL(TInt aFeature);
1.243 + Static method to query the supported status of a feature on the
1.244 + device.
1.245 +
1.246 + @deprecated Use IsFeatureSupportedL(TUid aFeature) instead.
1.247 +
1.248 + @param aFeature is the feature ID of the feature that is queried.
1.249 + @return a TBool indicating whether the feature is supported (ETrue)
1.250 + or not (EFalse). If the feature does not exist, the return value is
1.251 + EFalse.
1.252 +
1.253 + @leave Any One of the Symbian OS system-wide error codes
1.254 + */
1.255 + IMPORT_C static TBool IsFeatureSupportedL( TInt aFeature );
1.256
1.257 /**
1.258 - * Dynamic way to fetch information whether a certain feature is
1.259 - * supported in the current environment. Before calling the method
1.260 - * an instance of the CFeatureDiscovery class need to be created by
1.261 - * using one of the factory methods, NewL() or NewLC(). The created
1.262 - * instance must be deleted after use.
1.263 - *
1.264 - * @param aFeature is the feature ID of the feature that is queried.
1.265 - * @return a TBool indicating whether the feature is supported (ETrue)
1.266 - * or not (EFalse). If the feature does not exist, the return value is
1.267 - * EFalse.
1.268 - */
1.269 - IMPORT_C TBool IsSupported(TInt aFeature) const ;
1.270 + Dynamic method to query the supported status of a feature on the
1.271 + device. Before calling the method an instance of the CFeatureDiscovery
1.272 + class must be created by using one of the factory methods,
1.273 + NewL() or NewLC(). The created instance must be deleted after use.
1.274 +
1.275 + @deprecated Use IsSupported(TUid aFeature) instead.
1.276 +
1.277 + @param aFeature is the feature ID of the feature that is queried.
1.278 + @return a TBool indicating whether the feature is supported (ETrue)
1.279 + or not (EFalse). If the feature does not exist, the return value is
1.280 + EFalse.
1.281 + */
1.282 + IMPORT_C TBool IsSupported( TInt aFeature ) const ;
1.283 +
1.284 + /**
1.285 + Static method to query the supported status of a feature on the device.
1.286 +
1.287 + @param aFeature is the feature UID of the feature that is queried.
1.288 + @return a TBool indicating whether the feature is supported (ETrue)
1.289 + or not (EFalse). If the feature does not exist, the return value is
1.290 + EFalse.
1.291 +
1.292 + @leave Any One of the Symbian OS system-wide error codes
1.293 + */
1.294 + IMPORT_C static TBool IsFeatureSupportedL( TUid aFeature );
1.295 +
1.296 + /**
1.297 + Dynamic method to query the supported status of a feature on the device.
1.298 +
1.299 + Before calling the method an instance of the CFeatureDiscovery class must
1.300 + be created by using one of the factory methods, NewL() or NewLC().
1.301 + The created instance must be deleted after use.
1.302 +
1.303 + @param aFeature is the feature UID of the feature that is queried.
1.304 + @return a TBool indicating whether the feature is supported (ETrue)
1.305 + or not (EFalse). If the feature does not exist, the return value is
1.306 + EFalse.
1.307 + */
1.308 + IMPORT_C TBool IsSupported( TUid aFeature ) const ;
1.309 +
1.310 + /**
1.311 + Static method to query the supported status of a set of features
1.312 + on the device.
1.313 +
1.314 + @param aFeatures is the wrapper class for feature array queried.
1.315 +
1.316 + @leave Any One of the Symbian OS system-wide error codes
1.317 + */
1.318 + IMPORT_C static void FeaturesSupportedL( TFeatureSet& aFeatures );
1.319 +
1.320 + /**
1.321 + Dynamic method to query the supported status of a set of features
1.322 + on the device. Before calling the method an instance of the
1.323 + CFeatureDiscovery class need to be created by using one of the
1.324 + factory methods, NewL() or NewLC(). The created instance must be
1.325 + deleted after use.
1.326 +
1.327 + @param aFeatures is the wrapper class for feature array queried.
1.328 + @return KErrNone if status query succeeded.
1.329 + Otherwise one of the Symbian OS error codes
1.330 + */
1.331 + IMPORT_C TInt FeaturesSupported( TFeatureSet& aFeatures ) const;
1.332
1.333 private:
1.334
1.335 - /**
1.336 - * C++ default constructor.
1.337 - */
1.338 + /**
1.339 + C++ default constructor.
1.340 + */
1.341 CFeatureDiscovery();
1.342
1.343 - /**
1.344 - * By default Symbian OS constructor is private.
1.345 - */
1.346 - void ConstructL();
1.347 + /**
1.348 + By default Symbian OS constructor is private.
1.349 + */
1.350 + void ConstructL();
1.351 +
1.352 + private:
1.353 +
1.354 + // Feature discovery implementation class
1.355 + CFeatureDiscoveryImpl* iImpl;
1.356 } ;
1.357
1.358 +/**
1.359 + Usage:
1.360
1.361 -#endif // FEATUREDISCOVERY_H
1.362 + @code
1.363 + #include <featdiscovery.h>
1.364 + #include <featureinfo.h> // for feature definitions
1.365
1.366 -// EOF
1.367 + // replace <featureUIDx> with a real UID )
1.368 +
1.369 + // If querying only one feature, it is more efficient to use the class
1.370 + // via the static method, IsFeatureSupportedL().
1.371 + // When querying more than one feature, it is more efficient to use the
1.372 + // class by creating an instance and calling the IsSupported() method.
1.373 +
1.374 + // Static way of using the class:
1.375 + TBool isSupported = CFeatureDiscovery::IsFeatureSupportedL(<featureUIDx>);
1.376 +
1.377 + // Dynamic way of using the class using NewL():
1.378 +
1.379 + // Call NewL() to create an instance of CFeatureDiscovery.
1.380 + CFeatureDiscovery* testA = CFeatureDiscovery::NewL();
1.381 +
1.382 + // Call the exported IsSupported() method to query whether features
1.383 + // are supported in the current environment or not.
1.384 + TBool usbSupported = testA->IsSupported(<featureUIDx>);
1.385 + TBool mmcSupported = testA->IsSupported(<featureUIDx>);
1.386 +
1.387 + // Delete the created instance of CFeatureDiscovery.
1.388 + delete testA;
1.389 +
1.390 + // Dynamic way of using the class using NewLC():
1.391 +
1.392 + // Call NewLC() to create an instance of CFeatureDiscovery.
1.393 + // The method leaves the instance of the object on the cleanup stack.
1.394 + CFeatureDiscovery* testB = CFeatureDiscovery::NewLC();
1.395 +
1.396 + // Call the exported IsSupported() method to query whether features
1.397 + // are supported in the current environment or not.
1.398 + TBool wcdmaSupported = testB->IsSupported(<featureUIDx>);
1.399 + TBool gsmSupported = testB->IsSupported(<featureUIDx>);
1.400 +
1.401 + // Dynamic way of using multiple feature query. This is preferred
1.402 + // way to fetch support statuses if there are several features to be
1.403 + // queried, because it involves less inter-process communication.
1.404 +
1.405 + TFeatureSet featset;
1.406 + User::LeaveIfError( featset.Append( <featureUIDx> ) );
1.407 + User::LeaveIfError( featset.Append( <featureUIDx> ) );
1.408 + TInt err = testB->FeaturesSupported( featset );
1.409 + if(!err)
1.410 + {
1.411 + TBool uid1Supported = featset.IsFeatureSupported(<featureUIDx>);
1.412 + TBool uid2Supported = featset.IsFeatureSupported(<featureUIDx>);
1.413 + // ... or whether all QUERIED features are supported
1.414 + TBool allSupported = featset.AreAllFeaturesSupported();
1.415 + }
1.416 + // featset cleans array up in destructor on scope exit
1.417 +
1.418 + // Pop and delete the created instance of CFeatureDiscovery.
1.419 + CleanupStack::PopAndDestroy();
1.420 + @endcode
1.421 +*/
1.422 +#endif // FEATDISCOVERY_H
1.423 +
1.424 +// End of File