/*

* 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