/*

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

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of "Eclipse Public License v1.0"

 * which accompanies this distribution, and is available

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

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:

 *

 */

 #ifndef TEXT_RESOLVER_H

 #define TEXT_RESOLVER_H

 #include <coemain.h>    //  CCoeEnv

 #include <textresolver.hrh> // Resource flags 

 #include <eikenv.h>    //  CEikonEnv

 // DEFINES

 typedef CArrayFixFlat<TInt> CErrorResourceIdArray;

 typedef CArrayFixFlat<TInt> CErrorResourceFlagArray;

 /**

 * Class offers functionality for resolving corresponding error texts for 

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

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

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

 * component. 

 *

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

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

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

 *

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

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

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

 *

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

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

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

 *

 *

 * Usage:

 *

 * @code

 *  #include <textresolver.h>

 *

 *  // Typically used as an instance variable.

 *  

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

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

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

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

 *

 *  // // Error Resolving, simple:

 *

 *  // Get error code to be resolved.

 *  // TInt err1 = MyMethod(KInvalidValue);

 *  TInt err1 = KErrNoMemory;

 *    

 *  TPtrC buf1;  // For returned error text

 *    

 *  if (err1 != KErrNone)

 *      {

 *      // Resolve the given error code. 

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

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

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

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

 *      }

 *  else

 *      {

 *      // Do something.

 *      }

 *        

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

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

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

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

 *

 *  // Error Resolving, advanced:

 * 

 *  // Get error code to be resolved.

 *  // TInt err2 = MyMethod(KInvalidValue);

 *  TInt err2 = KErrNotSupported;

 *        

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

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

 *  TPtrC buf2;      // For returned error text

 *   

 *  if (err2 != KErrNone)

 *      {

 *      // Resolve the given error code.

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

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

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

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

 *

 *      if (flags & EErrorResUnknownErrorFlag)

 *          {

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

 *          // the error code. 

 *          // Do something.

 *          }

 *      }

 *  else

 *      {

 *      // Do something.

 *      }

 *    

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

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

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

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

 *

 *  // iTextResolver, Free loaded resources

 *  CleanupStack::PopAndDestroy(); 

 * @endcode

 *

 * @lib commonengine.lib

 * @since S60 2.0

 */

 class CTextResolver : public CBase

     {

 public:

     /**

     * Defines used error contexts. 

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

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

     * that error codes are unique.

     */

     enum TErrorContext

         {

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

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

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

         ECtxAutomatic = 0,

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

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

         ECtxNoCtx = 1,

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

         * beginning of the resolved error text. */

         ECtxNoCtxNoSeparator = 2

         };

 public:

     IMPORT_C static CTextResolver* NewL(CCoeEnv& aEnv);

     IMPORT_C static CTextResolver* NewLC(CCoeEnv& aEnv);

     IMPORT_C static CTextResolver* NewL();

 	IMPORT_C static CTextResolver* NewLC();

     IMPORT_C ~CTextResolver();

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

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

 private: // Construction

     virtual TInt ResourceForError(TInt aError);

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

     CTextResolver(CCoeEnv& aEnv);

     CTextResolver();

     void ConstructL();

     // Utility

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

     void Reset();

     void ReadLocalizedSeparatorCharacterFromResourceL(CCoeEnv& aCoeEnv);

     void ReadLocalizedSeparatorCharacterFromResourceAndPrepareResourceReaderLC(TResourceReader& aResReader);

     // returns NULL if fails

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

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

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

     TBool AddContextAndSeparator(TErrorContext aContext);

     void AllocBuffersL();

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

 private:

     CCoeEnv* iCoe;

     RResourceFile iResFile;

     TInt iRDSupport;

     TInt iBaseResourceFileOffset;

     CArrayFix<TInt>* iStartError;

     CArrayFix<TInt>* iAppTexts;

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

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

     HBufC* iTextBuffer;

     HBufC* iTitleText;

     HBufC* iContextSeparator;

     RFs iFs;

     TPtrC  iTruncatedTextPointer;

 	};

 #endif