1 textresolver.h

     1 /*

     2 * Copyright (c) 2002-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 resolving corresponding error texts

    15 *                for error codes. 

    16 *

    17 */

    18 

    19 

    20 

    21 #if !defined TEXT_RESOLVER_H

    22 #define TEXT_RESOLVER_H

    23 

    24 #include <coemain.h>    //  CCoeEnv

    25 #include <TextResolver.hrh> // Resource flags 

    26 

    27 // DEFINES

    28 typedef CArrayFixFlat<TInt> CErrorResourceIdArray;

    29 typedef CArrayFixFlat<TInt> CErrorResourceFlagArray;

    30 

    31 /**

    32 * Class offers functionality for resolving corresponding error texts for 

    33 * error codes. Text Resolver API provides operations with which a specific 

    34 * error code can be resolved to a human readable text. Descriptions for the

    35 * different error codes must be defined in the resource files of this 

    36 * component. 

    37 *

    38 * Text Resolver uses the CCoeEnv environment class to access the resource

    39 * files if the CCoeEnv environment is available. If the CCoeEnv environment

    40 * is not available, the files are accessed through the RResourceFile API.

    41 *

    42 * The API consist of the CTextResolver class which is used together with 

    43 * Text Resolver flags defined in textresolver.hrh file. The flags are used

    44 * to tell the priority of the error to the client:

    45 *

    46 * - EErrorResBlankErrorFlag is used to tell that error has no proper explanation.

    47 * - EErrorResUnknownErrorFlag indicates that Text Resolver does not support the error. 

    48 * - EErrorResOOMFlag Flag is returned while processing KErrNoMemory error code. 

    49 *

    50 *

    51 * Usage:

    52 *

    53 * @code

    54 *  #include <textresolver.h>

    55 *

    56 *  // Typically used as an instance variable.

    57 *  

    58 *  // Call the factory method NewLC() to create a new instance of CTextResolver.

    59 *  // NewLC() method leaves the instance of the object on the cleanup stack.	

    60 *  // The passed CCoeEnv instance is needed to access the resource files.

    61 *  CTextResolver* iTextResolver = CTextResolver::NewLC(*iCoeEnv); 

    62 *

    63 *  // // Error Resolving, simple:

    64 *

    65 *  // Get error code to be resolved.

    66 *  // TInt err1 = MyMethod(KInvalidValue);

    67 *  TInt err1 = KErrNoMemory;

    68 *    

    69 *  TPtrC buf1;  // For returned error text

    70 *    

    71 *  if (err1 != KErrNone)

    72 *      {

    73 *      // Resolve the given error code. 

    74 *      // The operation returns the error text for the resolved error.

    75 *      // There's no limit how long the resolved string can be.

    76 *      // Add context to 2nd param if needed.

    77 *      buf1.Set(iTextResolver->ResolveErrorString(err)); 

    78 *      }

    79 *  else

    80 *      {

    81 *      // Do something.

    82 *      }

    83 *        

    84 *  // Note that buf1 will only be valid as long as CTextResolver 

    85 *  // instance is alive and no new error is resolved by the same instance.

    86 *  // If for some reason you need to store the resolved error

    87 *  // beyond immediate use, make a copy of it.

    88 *

    89 *  // Error Resolving, advanced:

    90 * 

    91 *  // Get error code to be resolved.

    92 *  // TInt err2 = MyMethod(KInvalidValue);

    93 *  TInt err2 = KErrNotSupported;

    94 *        

    95 *  TInt textId(0);    // ID of the returned text

    96 *  TUint flags(0);    // Priority of the returned error 

    97 *  TPtrC buf2;      // For returned error text

    98 *   

    99 *  if (err2 != KErrNone)

   100 *      {

   101 *      // Resolve the given error code.

   102 *      // The operation returns the error text for the resolved error.

   103 *      // There's no limit on how long the resolved string can be.

   104 *      // Add Context to 4th param if needed.

   105 *      buf2.Set(iTextResolver->ResolveErrorString(err, textId, flags)); 

   106 *

   107 *      if (flags & EErrorResUnknownErrorFlag)

   108 *          {

   109 *          // The flag indicates that Text Resolver does not support

   110 *          // the error code. 

   111 *          // Do something.

   112 *          }

   113 *      }

   114 *  else

   115 *      {

   116 *      // Do something.

   117 *      }

   118 *    

   119 *  // Note that buf2 will only be valid as long as CTextResolver 

   120 *  // instance is alive and no new error is resolved by the same instance.

   121 *  // If for some reason you need to store the resolved error

   122 *  // beyond immediate use, make a copy of it.

   123 *

   124 *  // iTextResolver, Free loaded resources

   125 *  CleanupStack::PopAndDestroy(); 

   126 * @endcode

   127 *

   128 * @lib commonengine.lib

   129 * @since S60 2.0

   130 */

   131 

   132 class CTextResolver : public CBase

   133     {

   134 

   135     public:

   136 

   137         /**

   138         * Defines used error contexts. 

   139         * Optional error contexes for aiding the mapping of error codes to 

   140         * texts in a unique way. If no context is given the assumption is 

   141         * that error codes are unique.

   142         */

   143         enum TErrorContext

   144             {

   145             /** Context is defined automatically from error code value.

   146             * Here it is assumed that each error code is unique and in

   147             * own range. This is a default value when resolving errors.

   148             */

   149             ECtxAutomatic = 0,

   150             /** Context text is not added to the beginning of the resolved error text,

   151             * just context separator ':' and newline are added.

   152             */

   153             ECtxNoCtx = 1,

   154             /** No context text, context separator ':' or newline added to the 

   155             * beginning of the resolved error text.

   156             */

   157             ECtxNoCtxNoSeparator = 2

   158             };

   159     public:

   160         /**

   161          * Two-phase constructor method that is used to create a new instance

   162          * of the CTextResolver class. The implementation uses the passed 

   163          * CCoeEnv instance to access the resource files.

   164          *

   165          * @param aEnv the CCoeEnv instance to be used to access the resource

   166          * files.

   167          * @return a pointer to a new instance of the CTextResolver class.

   168          */

   169         IMPORT_C static CTextResolver* NewL(CCoeEnv& aEnv);

   170            

   171          /**

   172          * Constructor creates a new instance of CTextResolver. The 

   173          * implementation uses the passed CCoeEnv instance to access the 

   174          * resource files. Leaves the object on the cleanup stack.

   175          *

   176          * @param aEnv the CCoeEnv instance to be used to access the resource

   177          * files.

   178          * @return a pointer to a new instance of the CTextResolver class.

   179          */

   180         IMPORT_C static CTextResolver* NewLC(CCoeEnv& aEnv);

   181         

   182          /**

   183          * Constructor creates a new instance of CTextResolver. Resource files 

   184          * are accessed through the RResourceFile API.

   185          *

   186          * @return a pointer to a new instance of the CTextResolver class.

   187          */

   188         IMPORT_C static CTextResolver* NewL();

   189 

   190          /**

   191          * Constructor creates a new instance of CTextResolver.Resource files 

   192          * are accessed through the RResourceFile API. Leaves the object on 

   193          * the cleanup stack.

   194          *

   195          * @return a pointer to a new instance of the CTextResolver class.

   196          */

   197         IMPORT_C static CTextResolver* NewLC();

   198 

   199         

   200         /** 

   201         * Destructor 

   202         */

   203         IMPORT_C ~CTextResolver();

   204 

   205         /**

   206         * Resolves the given error code and returns the error text for the

   207         * resolved error. Resolved text can be of any length. This version

   208         * is for advanced use

   209         *

   210         * @param aError The error code to be resolved.

   211         * @param aTextId ID of the returned text.

   212         * @param aFlags The priority of the returned error. The priority is 

   213         * defined by the this module! Flags are defined in textresolver.hrh.

   214         * @param aContext Optional context for error numbers. If the aContext 

   215         * parameter is not passed to the function, it uses the default value

   216         * ECtxAutomatic. 

   217         * @return the error text for the resolved error. "System error" (in 

   218         * English localisation) is returned when error code is not known. For 

   219         * unknown errors blank error flag (flags are defined in 

   220         * textresolver.hrh) is also set to hide errors without proper 

   221         * explanation. There is no limit on how long the resolved string 

   222         * can be.

   223         */

   224 		IMPORT_C const TDesC& ResolveErrorString(

   225              TInt aError,

   226              TInt& aTextId,

   227              TUint& aFlags,

   228              TErrorContext aContext = ECtxAutomatic);

   229 

   230         /**

   231         * Resolves the given error code and returns the error text for the

   232         * resolved error. Resolved text can be of any length. This version 

   233         * is for "normal" use.

   234         *

   235         * @param aError The error code to be resolved.

   236         * @param aContext Optional context for error numbers. If the aContext 

   237         * parameter is not passed to the function, it uses the default value

   238         * ECtxAutomatic. 

   239         * @return the error text for the resolved error. "System error" (in 

   240         * English localisation) is returned when error code is not known. For 

   241         * unknown errors blank error flag (flags are defined in 

   242         * textresolver.hrh) is also set to hide errors without proper 

   243         * explanation. There is no limit on how long the resolved string

   244         * can be.

   245         */

   246 	    IMPORT_C const TDesC& ResolveErrorString(

   247              TInt aError,

   248              TErrorContext aContext = ECtxAutomatic);

   249 

   250 	private:

   251         

   252         virtual TInt ResourceForError(TInt aError);

   253         virtual void LoadResourceFilesL();

   254 

   255         // Construction

   256         CTextResolver(CCoeEnv& aEnv);

   257         CTextResolver();

   258         void ConstructL();

   259 

   260         // Utility

   261         void FindFullPathOfResourceFile(TFileName& aResFile) const;

   262         void ReadResourcesToArraysL(TInt& aError, TInt& aTextId);

   263         void Reset();

   264         void PrepareReaderLC(TResourceReader& reader);

   265 

   266         // returns NULL if fails

   267         HBufC* ReadUnicodeString(const TInt& aTextId);

   268 

   269         // returns false if any memory allocation fails or initial values 

   270         // of necessary pointers are NULL, indicating alloc failure earlier.

   271         TBool AddContextAndSeparator(TErrorContext aContext);

   272 

   273     private:

   274         

   275         CCoeEnv*                            iCoe;

   276         RResourceFile                       iRFile;

   277         TInt                                iRDSupport;

   278         TInt                                iBaseResourceFileOffset;

   279         CArrayFix<TInt>*                    iStartError;

   280         CArrayFix<TInt>*                    iAppTexts;

   281         CArrayPtr<CErrorResourceIdArray>*   iErrorTexts;

   282         CArrayPtr<CErrorResourceFlagArray>* iFlags;

   283         HBufC*                              iTextBuffer;

   284         HBufC*                              iAppNameText;

   285         HBufC*                              iContextSeparator;

   286         RFs                                 iFs;

   287         TPtrC                               iTruncatedTextPointer;

   288     };

   289 

   290 #endif

   291 

   292 // End of File