1 featdiscovery.h

     1 /*

     2 * Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * 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

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Offers functionality for querying whether a feature is 

    15 *                supported in the current environment.

    16 *

    17 */

    18 

    19 

    20 #ifndef FEATUREDISCOVERY_H

    21 #define FEATUREDISCOVERY_H

    22 

    23 //  INCLUDES

    24 #include <e32std.h>

    25 

    26 

    27 /**

    28 * Class used to query which features are suppported in the environment. 

    29 * Feature Discovery API provides methods which are used to query which

    30 * features are supported in the environment. A feature is a functionality that

    31 * can be optionally left out of some product configurations. Features often 

    32 * depend on the underlying hardware. For example, MMC support or USB support

    33 * can be features. The API consist of the CFeatureDiscovery class which is 

    34 * used together with feature IDs defined in the featureinfo.h file.

    35 *

    36 *

    37 * Usage:

    38 *

    39 * @code

    40 *  #include <FeatDiscovery.h>

    41 *  #include <featureinfo.h> // for feature definitions

    42 *

    43 *  // If querying only one feature, it is more efficient to use the class

    44 *  // via the static method, IsFeatureSupportedL().

    45 *  // When querying more than one feature, it is more efficient to use the 

    46 *  // class by creating an instance and calling the IsSupported() method.

    47 *

    48 *  // Static way of using the class:

    49 *  TBool isSupported = CFeatureDiscovery::IsFeatureSupportedL(KFeatureIdUsb);

    50 *

    51 *  // Dynamic way of using the class using NewL():

    52 *  

    53 *  // Call NewL() to create an instance of CFeatureDiscovery. 

    54 *  CFeatureDiscovery* testA = CFeatureDiscovery::NewL();

    55 * 

    56 *  // Call the exported IsSupported() method to query whether features 

    57 *  // are supported in the current environment or not.

    58 *  TBool usbSupported = testA->IsSupported(KFeatureIdUsb);

    59 *  TBool mmcSupported = testA->IsSupported(KFeatureIdMmc);

    60 *

    61 *  // Delete the created instance of CFeatureDiscovery.

    62 *  delete testA;

    63 *

    64 *  // Dynamic way of using the class using NewLC():

    65 * 

    66 *  // Call NewLC() to create an instance of CFeatureDiscovery.

    67 *  // The method leaves the instance of the object on the cleanup stack.

    68 *  CFeatureDiscovery* testB = CFeatureDiscovery::NewLC();

    69 *

    70 *  // Call the exported IsSupported() method to query whether features 

    71 *  // are supported in the current environment or not. 

    72 *  TBool wcdmaSupported = testB->IsSupported(KFeatureIdProtocolWcdma);

    73 *  TBool gsmSupported = testB->IsSupported(KFeatureIdProtocolGsm);

    74 *

    75 *  // Pop and delete the created instance of CFeatureDiscovery.

    76 *  CleanupStack::PopAndDestroy();

    77 * @endcode

    78 *

    79 * @lib featdiscovery.lib

    80 * @since S60 2.8

    81 */

    82 

    83 class CFeatureDiscovery : public CBase

    84     {

    85     public:

    86 

    87         /**

    88         * This is a two-phase constructor method that is used to create

    89         * a new instance of the CFeatureDiscovery class.

    90         *

    91         * @return a pointer to a new instance of the CFeatureDiscovery class.

    92         *

    93         * @leave One of the Symbian OS error codes

    94         */

    95 		IMPORT_C static CFeatureDiscovery* NewL();

    96 

    97         /**

    98         * This is a two-phase constructor method that is used to create

    99         * a new instance of the CFeatureDiscovery class. This method leaves

   100         * the instance of the object on the cleanup stack.

   101         *

   102         * @return a pointer to a new instance of the CFeatureDiscovery class.

   103         *

   104         * @leave One of the Symbian OS error codes

   105         */

   106 		IMPORT_C static CFeatureDiscovery* NewLC();

   107 

   108         /**

   109         * Destructor.

   110         */

   111 		virtual ~CFeatureDiscovery();

   112 

   113 		/**

   114         * Static way to fetch information whether a certain feature is 

   115         * supported in the current envinronment. There is no need to create

   116         * an instance of the class when using this method.

   117         *

   118         * @param aFeature is the feature ID of the feature that is queried.

   119         * @return a TBool indicating whether the feature is supported (ETrue)

   120         * or not (EFalse). If the feature does not exist, the return value is 

   121         * EFalse.

   122         *

   123         * @leave One of the Symbian OS error codes.

   124         */

   125 		IMPORT_C static TBool IsFeatureSupportedL(TInt aFeature);

   126 

   127 		/**

   128         * Dynamic way to fetch information whether a certain feature is 

   129         * supported in the current environment. Before calling the method 

   130         * an instance of the CFeatureDiscovery class need to be created by 

   131         * using one of the factory methods, NewL() or NewLC(). The created 

   132         * instance must be deleted after use.

   133         *

   134         * @param aFeature is the feature ID of the feature that is queried.

   135         * @return a TBool indicating whether the feature is supported (ETrue)

   136         * or not (EFalse). If the feature does not exist, the return value is 

   137         * EFalse.

   138         */

   139 		IMPORT_C TBool IsSupported(TInt aFeature) const ;

   140 

   141     private:

   142 

   143         /**

   144         * C++ default constructor.

   145         */

   146 		CFeatureDiscovery();

   147 

   148         /**

   149         * By default Symbian OS constructor is private.

   150         */

   151         void ConstructL();

   152     } ;

   153 

   154 

   155 #endif  // FEATUREDISCOVERY_H

   156 

   157 // EOF