williamr@2: /*
williamr@4: * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@4: * Description:
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@4: 
williamr@4: #ifndef FEATDISCOVERY_H
williamr@4: #define FEATDISCOVERY_H
williamr@2: 
williamr@2: //  INCLUDES
williamr@4: #include <e32base.h>
williamr@2: 
williamr@4: class CFeatureDiscoveryImpl;
williamr@2: 
williamr@2: /**
williamr@4: Wrapper class used for multiple feature queries.
williamr@4: @publishedAll
williamr@4: @released
williamr@2: */
williamr@2: 
williamr@4: class TFeatureSet
williamr@4:     {
williamr@4:     public:
williamr@4: 
williamr@4: 		/**
williamr@4: 		Constructor
williamr@4: 	    */
williamr@4:         IMPORT_C TFeatureSet();
williamr@4: 
williamr@4: 		/**
williamr@4: 		Destructor
williamr@4: 	    */
williamr@4:         IMPORT_C ~TFeatureSet();
williamr@4: 
williamr@4: 		/**
williamr@4: 		 Method to add features before querying support statuses. This
williamr@4: 		 method must be called to initialize feature array before querying
williamr@4: 		 support statuses from server with FeaturesSupported(L) and finally
williamr@4: 		 check the status with a call to IsFeatureSupported or AreAllFeaturesSupported.
williamr@4: 
williamr@4: 	     @return KErrNone if feature addition succeded.
williamr@4: 	             Otherwise one of the Symbian OS error codes
williamr@4: 	    */
williamr@4: 	    IMPORT_C TInt Append( TUid aFeature );
williamr@4: 
williamr@4: 		/**
williamr@4: 	     Method to check feature's support status.
williamr@4: 
williamr@4: 	     @param aFeature is the feature UID of the feature that is queried.
williamr@4: 		 @return a TBool indicating whether the feature is supported (ETrue)
williamr@4: 		 or not (EFalse). If the feature does not exist, the return value is
williamr@4: 		 EFalse.
williamr@4: 	    */
williamr@4:         IMPORT_C TBool IsFeatureSupported( TUid aFeature ) const;
williamr@4: 
williamr@4: 		/**
williamr@4: 		 Method to check whether all features queried are supported.
williamr@4: 
williamr@4: 	     @return ETrue if all features queried are supported or no features have been queried.
williamr@4: 	             Otherwise EFalse.
williamr@4: 	    */
williamr@4: 	    IMPORT_C TBool AreAllFeaturesSupported() const;
williamr@4: 
williamr@4:     public: // For CFeatureDiscoveryImpl internal use
williamr@4: 
williamr@4:         // Count number of features in TFeatureStat array.
williamr@4:         TInt Count();
williamr@4: 
williamr@4:         // Return id of feature in requested index from TFeatureStat array.
williamr@4:         TUid FeatureId( TInt aIndex ) const;
williamr@4: 
williamr@4:         // Reset TFeatureStat array.
williamr@4:         void Reset();
williamr@4: 
williamr@4:         // Append feature and status object into TFeatureStat array
williamr@4:         TInt Append( TUid aFeature, TBool aSupported );
williamr@4: 
williamr@4:     private:
williamr@4:         struct TFeatureStat
williamr@4:         {
williamr@4:             TUid iFeatureID;
williamr@4:             TBool iSupported;
williamr@4:         };
williamr@4: 
williamr@4:     private:
williamr@4:         // Feature id, status array
williamr@4:         RArray<TFeatureStat> iStatus;
williamr@4: 
williamr@4:         // Counter for checking feature count before and after query
williamr@4:         TInt iCount;
williamr@4: 
williamr@4:         // Reserved for future use.
williamr@4:         TUint32 iReserved;
williamr@4:     };
williamr@4: 
williamr@4: /**
williamr@4:  The feature discovery API provides methods which are used to query which
williamr@4:  features are supported in the environment.
williamr@4: 
williamr@4: @publishedAll
williamr@4: @released
williamr@4: */
williamr@2: class CFeatureDiscovery : public CBase
williamr@2:     {
williamr@2:     public:
williamr@2: 
williamr@4: 	    /**
williamr@4: 	     This is a two-phase constructor method that is used to create
williamr@4: 	     a new instance of the CFeatureDiscovery class.
williamr@4: 
williamr@4: 	     @return a pointer to a new instance of the CFeatureDiscovery class.
williamr@4: 
williamr@4: 	     @leave Any One of the Symbian OS system-wide error codes
williamr@4: 	    */
williamr@2: 		IMPORT_C static CFeatureDiscovery* NewL();
williamr@2: 
williamr@4: 	    /**
williamr@4: 	     This is a two-phase constructor method that is used to create
williamr@4: 	     a new instance of the CFeatureDiscovery class. This method leaves
williamr@4: 	     the instance of the object on the cleanup stack.
williamr@4: 
williamr@4: 	     @return a pointer to a new instance of the CFeatureDiscovery class.
williamr@4: 
williamr@4: 	      @leave Any One of the Symbian OS system-wide error codes
williamr@4: 	    */
williamr@2: 		IMPORT_C static CFeatureDiscovery* NewLC();
williamr@2: 
williamr@4: 	    /**
williamr@4: 	     Destructor.
williamr@4: 	    */
williamr@2: 		virtual ~CFeatureDiscovery();
williamr@2: 
williamr@2: 		/**
williamr@4: 		 Static method to query the supported status of a feature on the
williamr@4: 		 device.
williamr@4: 
williamr@4: 		 @deprecated Use IsFeatureSupportedL(TUid aFeature) instead.
williamr@4: 
williamr@4: 		 @param aFeature is the feature ID of the feature that is queried.
williamr@4: 		 @return a TBool indicating whether the feature is supported (ETrue)
williamr@4: 		 or not (EFalse). If the feature does not exist, the return value is
williamr@4: 		 EFalse.
williamr@4: 
williamr@4: 		  @leave Any One of the Symbian OS system-wide error codes
williamr@4: 		*/
williamr@4: 		IMPORT_C static TBool IsFeatureSupportedL( TInt aFeature );
williamr@2: 
williamr@2: 		/**
williamr@4: 	     Dynamic method to query the supported status of a feature on the
williamr@4: 	     device. Before calling the method an instance of the CFeatureDiscovery
williamr@4: 	     class must be created by using one of the factory methods,
williamr@4: 	     NewL() or NewLC(). The created instance must be deleted after use.
williamr@4: 
williamr@4: 	     @deprecated Use IsSupported(TUid aFeature) instead.
williamr@4: 
williamr@4: 	     @param aFeature is the feature ID of the feature that is queried.
williamr@4: 	     @return a TBool indicating whether the feature is supported (ETrue)
williamr@4: 	     or not (EFalse). If the feature does not exist, the return value is
williamr@4: 	     EFalse.
williamr@4: 	    */
williamr@4: 		IMPORT_C TBool IsSupported( TInt aFeature ) const ;
williamr@4: 
williamr@4: 		/**
williamr@4: 	     Static method to query the supported status of a feature on the device.
williamr@4: 
williamr@4: 	     @param aFeature is the feature UID of the feature that is queried.
williamr@4: 	     @return a TBool indicating whether the feature is supported (ETrue)
williamr@4: 	     or not (EFalse). If the feature does not exist, the return value is
williamr@4: 	     EFalse.
williamr@4: 
williamr@4: 	     @leave Any One of the Symbian OS system-wide error codes
williamr@4: 	    */
williamr@4: 	    IMPORT_C static TBool IsFeatureSupportedL( TUid aFeature );
williamr@4: 
williamr@4: 		/**
williamr@4: 	     Dynamic method to query the supported status of a feature on the device.
williamr@4: 
williamr@4: 	     Before calling the method an instance of the CFeatureDiscovery class must
williamr@4: 	     be created by using one of the factory methods, NewL() or NewLC().
williamr@4: 	     The created instance must be deleted after use.
williamr@4: 
williamr@4: 	     @param aFeature is the feature UID of the feature that is queried.
williamr@4: 	     @return a TBool indicating whether the feature is supported (ETrue)
williamr@4: 	     or not (EFalse). If the feature does not exist, the return value is
williamr@4: 	     EFalse.
williamr@4: 	    */
williamr@4: 		IMPORT_C TBool IsSupported( TUid aFeature ) const ;
williamr@4: 
williamr@4: 		/**
williamr@4: 		 Static method to query the supported status of a set of features
williamr@4: 		 on the device.
williamr@4: 
williamr@4: 		 @param aFeatures is the wrapper class for feature array queried.
williamr@4: 
williamr@4: 		 @leave Any One of the Symbian OS system-wide error codes
williamr@4: 		*/
williamr@4: 		IMPORT_C static void FeaturesSupportedL( TFeatureSet& aFeatures );
williamr@4: 
williamr@4: 		/**
williamr@4: 	     Dynamic method to query the supported status of a set of features
williamr@4: 	     on the device. Before calling the method an instance of the
williamr@4: 	     CFeatureDiscovery class need to be created by using one of the
williamr@4: 	     factory methods, NewL() or NewLC(). The created instance must be
williamr@4: 	     deleted after use.
williamr@4: 
williamr@4: 	     @param aFeatures is the wrapper class for feature array queried.
williamr@4: 	     @return KErrNone if status query succeeded.
williamr@4: 	             Otherwise one of the Symbian OS error codes
williamr@4: 	    */
williamr@4: 		IMPORT_C TInt FeaturesSupported( TFeatureSet& aFeatures ) const;
williamr@2: 
williamr@2:     private:
williamr@2: 
williamr@4: 	    /**
williamr@4: 	     C++ default constructor.
williamr@4: 	    */
williamr@2: 		CFeatureDiscovery();
williamr@2: 
williamr@4: 	    /**
williamr@4: 	     By default Symbian OS constructor is private.
williamr@4: 	    */
williamr@4: 	    void ConstructL();
williamr@4: 
williamr@4:     private:
williamr@4: 
williamr@4: 		// Feature discovery implementation class
williamr@4: 		CFeatureDiscoveryImpl* iImpl;
williamr@2:     } ;
williamr@2: 
williamr@4: /**
williamr@4:  Usage:
williamr@2: 
williamr@4:  @code
williamr@4:   #include <featdiscovery.h>
williamr@4:   #include <featureinfo.h> // for feature definitions
williamr@2: 
williamr@4:   // replace <featureUIDx> with a real UID )
williamr@4: 
williamr@4:   // If querying only one feature, it is more efficient to use the class
williamr@4:   // via the static method, IsFeatureSupportedL().
williamr@4:   // When querying more than one feature, it is more efficient to use the
williamr@4:   // class by creating an instance and calling the IsSupported() method.
williamr@4: 
williamr@4:   // Static way of using the class:
williamr@4:   TBool isSupported = CFeatureDiscovery::IsFeatureSupportedL(<featureUIDx>);
williamr@4: 
williamr@4:   // Dynamic way of using the class using NewL():
williamr@4: 
williamr@4:   // Call NewL() to create an instance of CFeatureDiscovery.
williamr@4:   CFeatureDiscovery* testA = CFeatureDiscovery::NewL();
williamr@4: 
williamr@4:   // Call the exported IsSupported() method to query whether features
williamr@4:   // are supported in the current environment or not.
williamr@4:   TBool usbSupported = testA->IsSupported(<featureUIDx>);
williamr@4:   TBool mmcSupported = testA->IsSupported(<featureUIDx>);
williamr@4: 
williamr@4:   // Delete the created instance of CFeatureDiscovery.
williamr@4:   delete testA;
williamr@4: 
williamr@4:   // Dynamic way of using the class using NewLC():
williamr@4: 
williamr@4:   // Call NewLC() to create an instance of CFeatureDiscovery.
williamr@4:   // The method leaves the instance of the object on the cleanup stack.
williamr@4:   CFeatureDiscovery* testB = CFeatureDiscovery::NewLC();
williamr@4: 
williamr@4:   // Call the exported IsSupported() method to query whether features
williamr@4:   // are supported in the current environment or not.
williamr@4:   TBool wcdmaSupported = testB->IsSupported(<featureUIDx>);
williamr@4:   TBool gsmSupported = testB->IsSupported(<featureUIDx>);
williamr@4: 
williamr@4:   // Dynamic way of using multiple feature query. This is preferred
williamr@4:   // way to fetch support statuses if there are several features to be
williamr@4:   // queried, because it involves less inter-process communication.
williamr@4: 
williamr@4:   TFeatureSet featset;
williamr@4:   User::LeaveIfError( featset.Append( <featureUIDx> ) );
williamr@4:   User::LeaveIfError( featset.Append( <featureUIDx> ) );
williamr@4:   TInt err = testB->FeaturesSupported( featset );
williamr@4: 	if(!err)
williamr@4: 		{
williamr@4: 			TBool uid1Supported = featset.IsFeatureSupported(<featureUIDx>);
williamr@4: 			TBool uid2Supported = featset.IsFeatureSupported(<featureUIDx>);
williamr@4: 			// ... or whether all QUERIED features are supported
williamr@4: 			TBool allSupported = featset.AreAllFeaturesSupported();
williamr@4: 		}
williamr@4:   // featset cleans array up in destructor on scope exit
williamr@4: 
williamr@4:   // Pop and delete the created instance of CFeatureDiscovery.
williamr@4:   CleanupStack::PopAndDestroy();
williamr@4:  @endcode
williamr@4: */
williamr@4: #endif  // FEATDISCOVERY_H
williamr@4: 
williamr@4: // End of File