1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/persistentdata/featuremgmt/featuremgr/inc/featdiscovery.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,307 @@
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 +#ifndef FEATDISCOVERY_H
1.24 +#define FEATDISCOVERY_H
1.25 +
1.26 +// INCLUDES
1.27 +#include <e32base.h>
1.28 +
1.29 +class CFeatureDiscoveryImpl;
1.30 +
1.31 +/**
1.32 +Wrapper class used for multiple feature queries.
1.33 +@publishedAll
1.34 +@released
1.35 +*/
1.36 +
1.37 +class TFeatureSet
1.38 + {
1.39 + public:
1.40 +
1.41 + /**
1.42 + Constructor
1.43 + */
1.44 + IMPORT_C TFeatureSet();
1.45 +
1.46 + /**
1.47 + Destructor
1.48 + */
1.49 + IMPORT_C ~TFeatureSet();
1.50 +
1.51 + /**
1.52 + Method to add features before querying support statuses. This
1.53 + method must be called to initialize feature array before querying
1.54 + support statuses from server with FeaturesSupported(L) and finally
1.55 + check the status with a call to IsFeatureSupported or AreAllFeaturesSupported.
1.56 +
1.57 + @return KErrNone if feature addition succeded.
1.58 + Otherwise one of the Symbian OS error codes
1.59 + */
1.60 + IMPORT_C TInt Append( TUid aFeature );
1.61 +
1.62 + /**
1.63 + Method to check feature's support status.
1.64 +
1.65 + @param aFeature is the feature UID of the feature that is queried.
1.66 + @return a TBool indicating whether the feature is supported (ETrue)
1.67 + or not (EFalse). If the feature does not exist, the return value is
1.68 + EFalse.
1.69 + */
1.70 + IMPORT_C TBool IsFeatureSupported( TUid aFeature ) const;
1.71 +
1.72 + /**
1.73 + Method to check whether all features queried are supported.
1.74 +
1.75 + @return ETrue if all features queried are supported or no features have been queried.
1.76 + Otherwise EFalse.
1.77 + */
1.78 + IMPORT_C TBool AreAllFeaturesSupported() const;
1.79 +
1.80 + public: // For CFeatureDiscoveryImpl internal use
1.81 +
1.82 + // Count number of features in TFeatureStat array.
1.83 + TInt Count();
1.84 +
1.85 + // Return id of feature in requested index from TFeatureStat array.
1.86 + TUid FeatureId( TInt aIndex ) const;
1.87 +
1.88 + // Reset TFeatureStat array.
1.89 + void Reset();
1.90 +
1.91 + // Append feature and status object into TFeatureStat array
1.92 + TInt Append( TUid aFeature, TBool aSupported );
1.93 +
1.94 + private:
1.95 + struct TFeatureStat
1.96 + {
1.97 + TUid iFeatureID;
1.98 + TBool iSupported;
1.99 + };
1.100 +
1.101 + private:
1.102 + // Feature id, status array
1.103 + RArray<TFeatureStat> iStatus;
1.104 +
1.105 + // Counter for checking feature count before and after query
1.106 + TInt iCount;
1.107 +
1.108 + // Reserved for future use.
1.109 + TUint32 iReserved;
1.110 + };
1.111 +
1.112 +/**
1.113 + The feature discovery API provides methods which are used to query which
1.114 + features are supported in the environment.
1.115 +
1.116 +@publishedAll
1.117 +@released
1.118 +*/
1.119 +class CFeatureDiscovery : public CBase
1.120 + {
1.121 + public:
1.122 +
1.123 + /**
1.124 + This is a two-phase constructor method that is used to create
1.125 + a new instance of the CFeatureDiscovery class.
1.126 +
1.127 + @return a pointer to a new instance of the CFeatureDiscovery class.
1.128 +
1.129 + @leave Any One of the Symbian OS system-wide error codes
1.130 + */
1.131 + IMPORT_C static CFeatureDiscovery* NewL();
1.132 +
1.133 + /**
1.134 + This is a two-phase constructor method that is used to create
1.135 + a new instance of the CFeatureDiscovery class. This method leaves
1.136 + the instance of the object on the cleanup stack.
1.137 +
1.138 + @return a pointer to a new instance of the CFeatureDiscovery class.
1.139 +
1.140 + @leave Any One of the Symbian OS system-wide error codes
1.141 + */
1.142 + IMPORT_C static CFeatureDiscovery* NewLC();
1.143 +
1.144 + /**
1.145 + Destructor.
1.146 + */
1.147 + virtual ~CFeatureDiscovery();
1.148 +
1.149 + /**
1.150 + Static method to query the supported status of a feature on the
1.151 + device.
1.152 +
1.153 + @deprecated Use IsFeatureSupportedL(TUid aFeature) instead.
1.154 +
1.155 + @param aFeature is the feature ID of the feature that is queried.
1.156 + @return a TBool indicating whether the feature is supported (ETrue)
1.157 + or not (EFalse). If the feature does not exist, the return value is
1.158 + EFalse.
1.159 +
1.160 + @leave Any One of the Symbian OS system-wide error codes
1.161 + */
1.162 + IMPORT_C static TBool IsFeatureSupportedL( TInt aFeature );
1.163 +
1.164 + /**
1.165 + Dynamic method to query the supported status of a feature on the
1.166 + device. Before calling the method an instance of the CFeatureDiscovery
1.167 + class must be created by using one of the factory methods,
1.168 + NewL() or NewLC(). The created instance must be deleted after use.
1.169 +
1.170 + @deprecated Use IsSupported(TUid aFeature) instead.
1.171 +
1.172 + @param aFeature is the feature ID of the feature that is queried.
1.173 + @return a TBool indicating whether the feature is supported (ETrue)
1.174 + or not (EFalse). If the feature does not exist, the return value is
1.175 + EFalse.
1.176 + */
1.177 + IMPORT_C TBool IsSupported( TInt aFeature ) const ;
1.178 +
1.179 + /**
1.180 + Static method to query the supported status of a feature on the device.
1.181 +
1.182 + @param aFeature is the feature UID of the feature that is queried.
1.183 + @return a TBool indicating whether the feature is supported (ETrue)
1.184 + or not (EFalse). If the feature does not exist, the return value is
1.185 + EFalse.
1.186 +
1.187 + @leave Any One of the Symbian OS system-wide error codes
1.188 + */
1.189 + IMPORT_C static TBool IsFeatureSupportedL( TUid aFeature );
1.190 +
1.191 + /**
1.192 + Dynamic method to query the supported status of a feature on the device.
1.193 +
1.194 + Before calling the method an instance of the CFeatureDiscovery class must
1.195 + be created by using one of the factory methods, NewL() or NewLC().
1.196 + The created instance must be deleted after use.
1.197 +
1.198 + @param aFeature is the feature UID of the feature that is queried.
1.199 + @return a TBool indicating whether the feature is supported (ETrue)
1.200 + or not (EFalse). If the feature does not exist, the return value is
1.201 + EFalse.
1.202 + */
1.203 + IMPORT_C TBool IsSupported( TUid aFeature ) const ;
1.204 +
1.205 + /**
1.206 + Static method to query the supported status of a set of features
1.207 + on the device.
1.208 +
1.209 + @param aFeatures is the wrapper class for feature array queried.
1.210 +
1.211 + @leave Any One of the Symbian OS system-wide error codes
1.212 + */
1.213 + IMPORT_C static void FeaturesSupportedL( TFeatureSet& aFeatures );
1.214 +
1.215 + /**
1.216 + Dynamic method to query the supported status of a set of features
1.217 + on the device. Before calling the method an instance of the
1.218 + CFeatureDiscovery class need to be created by using one of the
1.219 + factory methods, NewL() or NewLC(). The created instance must be
1.220 + deleted after use.
1.221 +
1.222 + @param aFeatures is the wrapper class for feature array queried.
1.223 + @return KErrNone if status query succeeded.
1.224 + Otherwise one of the Symbian OS error codes
1.225 + */
1.226 + IMPORT_C TInt FeaturesSupported( TFeatureSet& aFeatures ) const;
1.227 +
1.228 + private:
1.229 +
1.230 + /**
1.231 + C++ default constructor.
1.232 + */
1.233 + CFeatureDiscovery();
1.234 +
1.235 + /**
1.236 + By default Symbian OS constructor is private.
1.237 + */
1.238 + void ConstructL();
1.239 +
1.240 + private:
1.241 +
1.242 + // Feature discovery implementation class
1.243 + CFeatureDiscoveryImpl* iImpl;
1.244 + } ;
1.245 +
1.246 +/**
1.247 + Usage:
1.248 +
1.249 + @code
1.250 + #include <featdiscovery.h>
1.251 + #include <featureinfo.h> // for feature definitions
1.252 +
1.253 + // replace <featureUIDx> with a real UID )
1.254 +
1.255 + // If querying only one feature, it is more efficient to use the class
1.256 + // via the static method, IsFeatureSupportedL().
1.257 + // When querying more than one feature, it is more efficient to use the
1.258 + // class by creating an instance and calling the IsSupported() method.
1.259 +
1.260 + // Static way of using the class:
1.261 + TBool isSupported = CFeatureDiscovery::IsFeatureSupportedL(<featureUIDx>);
1.262 +
1.263 + // Dynamic way of using the class using NewL():
1.264 +
1.265 + // Call NewL() to create an instance of CFeatureDiscovery.
1.266 + CFeatureDiscovery* testA = CFeatureDiscovery::NewL();
1.267 +
1.268 + // Call the exported IsSupported() method to query whether features
1.269 + // are supported in the current environment or not.
1.270 + TBool usbSupported = testA->IsSupported(<featureUIDx>);
1.271 + TBool mmcSupported = testA->IsSupported(<featureUIDx>);
1.272 +
1.273 + // Delete the created instance of CFeatureDiscovery.
1.274 + delete testA;
1.275 +
1.276 + // Dynamic way of using the class using NewLC():
1.277 +
1.278 + // Call NewLC() to create an instance of CFeatureDiscovery.
1.279 + // The method leaves the instance of the object on the cleanup stack.
1.280 + CFeatureDiscovery* testB = CFeatureDiscovery::NewLC();
1.281 +
1.282 + // Call the exported IsSupported() method to query whether features
1.283 + // are supported in the current environment or not.
1.284 + TBool wcdmaSupported = testB->IsSupported(<featureUIDx>);
1.285 + TBool gsmSupported = testB->IsSupported(<featureUIDx>);
1.286 +
1.287 + // Dynamic way of using multiple feature query. This is preferred
1.288 + // way to fetch support statuses if there are several features to be
1.289 + // queried, because it involves less inter-process communication.
1.290 +
1.291 + TFeatureSet featset;
1.292 + User::LeaveIfError( featset.Append( <featureUIDx> ) );
1.293 + User::LeaveIfError( featset.Append( <featureUIDx> ) );
1.294 + TInt err = testB->FeaturesSupported( featset );
1.295 + if(!err)
1.296 + {
1.297 + TBool uid1Supported = featset.IsFeatureSupported(<featureUIDx>);
1.298 + TBool uid2Supported = featset.IsFeatureSupported(<featureUIDx>);
1.299 + // ... or whether all QUERIED features are supported
1.300 + TBool allSupported = featset.AreAllFeaturesSupported();
1.301 + }
1.302 + // featset cleans array up in destructor on scope exit
1.303 +
1.304 + // Pop and delete the created instance of CFeatureDiscovery.
1.305 + CleanupStack::PopAndDestroy();
1.306 + @endcode
1.307 +*/
1.308 +#endif // FEATDISCOVERY_H
1.309 +
1.310 +// End of File