1 /*

     2 * Copyright (c) 2006-2009 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 "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef TEXT_RESOLVER_H

    22 #define TEXT_RESOLVER_H

    23 

    24 #include <coemain.h>    //  CCoeEnv

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

    26 #include <eikenv.h>    //  CEikonEnv

    27 

    28 // DEFINES

    29 typedef CArrayFixFlat<TInt> CErrorResourceIdArray;

    30 typedef CArrayFixFlat<TInt> CErrorResourceFlagArray;

    31 

    32 /**

    33 * Class offers functionality for resolving corresponding error texts for 

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

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

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

    37 * component. 

    38 *

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

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

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

    42 *

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

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

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

    46 *

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

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

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

    50 *

    51 *

    52 * Usage:

    53 *

    54 * @code

    55 *  #include <textresolver.h>

    56 *

    57 *  // Typically used as an instance variable.

    58 *  

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

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

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

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

    63 *

    64 *  // // Error Resolving, simple:

    65 *

    66 *  // Get error code to be resolved.

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

    68 *  TInt err1 = KErrNoMemory;

    69 *    

    70 *  TPtrC buf1;  // For returned error text

    71 *    

    72 *  if (err1 != KErrNone)

    73 *      {

    74 *      // Resolve the given error code. 

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

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

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

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

    79 *      }

    80 *  else

    81 *      {

    82 *      // Do something.

    83 *      }

    84 *        

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

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

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

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

    89 *

    90 *  // Error Resolving, advanced:

    91 * 

    92 *  // Get error code to be resolved.

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

    94 *  TInt err2 = KErrNotSupported;

    95 *        

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

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

    98 *  TPtrC buf2;      // For returned error text

    99 *   

   100 *  if (err2 != KErrNone)

   101 *      {

   102 *      // Resolve the given error code.

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

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

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

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

   107 *

   108 *      if (flags & EErrorResUnknownErrorFlag)

   109 *          {

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

   111 *          // the error code. 

   112 *          // Do something.

   113 *          }

   114 *      }

   115 *  else

   116 *      {

   117 *      // Do something.

   118 *      }

   119 *    

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

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

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

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

   124 *

   125 *  // iTextResolver, Free loaded resources

   126 *  CleanupStack::PopAndDestroy(); 

   127 * @endcode

   128 *

   129 * @lib commonengine.lib

   130 * @since S60 2.0

   131 */

   132 class CTextResolver : public CBase

   133     {

   134 public:

   135     /**

   136     * Defines used error contexts. 

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

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

   139     * that error codes are unique.

   140     */

   141     enum TErrorContext

   142         {

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

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

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

   146         ECtxAutomatic = 0,

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

   148         * just context separator ':' and newline are added. */

   149         ECtxNoCtx = 1,

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

   151         * beginning of the resolved error text. */

   152         ECtxNoCtxNoSeparator = 2

   153         };

   154 public:

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

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

   157     IMPORT_C static CTextResolver* NewL();

   158 	IMPORT_C static CTextResolver* NewLC();

   159     IMPORT_C ~CTextResolver();

   160 	IMPORT_C const TDesC& ResolveErrorString(TInt aError, TInt& aTextId, TUint& aFlags,TErrorContext aContext = ECtxAutomatic);

   161     IMPORT_C const TDesC& ResolveErrorString(TInt aError, TErrorContext aContext = ECtxAutomatic);

   162 private: // Construction

   163     virtual TInt ResourceForError(TInt aError);

   164     virtual void LoadResourceFilesL() { ASSERT(0); }	// deprecated

   165     CTextResolver(CCoeEnv& aEnv);

   166     CTextResolver();

   167     void ConstructL();

   168     

   169     // Utility

   170     void DoRawReadOfSystemErrorResourcesToArraysL(TInt& aError, TInt& aTextId);

   171     void Reset();

   172     void ReadLocalizedSeparatorCharacterFromResourceL(CCoeEnv& aCoeEnv);

   173     void ReadLocalizedSeparatorCharacterFromResourceAndPrepareResourceReaderLC(TResourceReader& aResReader);

   174 

   175     // returns NULL if fails

   176     static HBufC* AllocReadUnicodeString(RResourceFile& aResFile, TInt aTextId);

   177     /** Returns false if any memory allocation fails or initial values 

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

   179     TBool AddContextAndSeparator(TErrorContext aContext);

   180     void AllocBuffersL();

   181     void DoResolveErrorStringL(TInt aError, TInt& aTextId, TUint& aFlags);

   182 private:

   183     CCoeEnv* iCoe;

   184     RResourceFile iResFile;

   185     TInt iRDSupport;

   186     TInt iBaseResourceFileOffset;

   187     CArrayFix<TInt>* iStartError;

   188     CArrayFix<TInt>* iAppTexts;

   189     CArrayPtr<CErrorResourceIdArray>*   iErrorTexts;	// Array of arrays of ints

   190     CArrayPtr<CErrorResourceFlagArray>* iFlags;			// Array of arrays of ints

   191     HBufC* iTextBuffer;

   192     HBufC* iTitleText;

   193     HBufC* iContextSeparator;

   194     RFs iFs;

   195     TPtrC  iTruncatedTextPointer;

   196 	};

   197 

   198 #endif

   199