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