/*

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

* All rights reserved.

* This component and the accompanying materials are made available

* 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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  Offers functionality for resolving corresponding error texts

*                for error codes. 

*

*/

#if !defined TEXT_RESOLVER_H

#define TEXT_RESOLVER_H

#include <coemain.h>    //  CCoeEnv

#include <TextResolver.hrh> // Resource flags 

// 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:

        /**

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

         * of the CTextResolver class. The implementation uses the passed 

         * CCoeEnv instance to access the resource files.

         *

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

         * files.

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

         */

        IMPORT_C static CTextResolver* NewL(CCoeEnv& aEnv);

         /**

         * Constructor creates a new instance of CTextResolver. The 

         * implementation uses the passed CCoeEnv instance to access the 

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

         *

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

         * files.

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

         */

        IMPORT_C static CTextResolver* NewLC(CCoeEnv& aEnv);

         /**

         * Constructor creates a new instance of CTextResolver. Resource files 

         * are accessed through the RResourceFile API.

         *

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

         */

        IMPORT_C static CTextResolver* NewL();

         /**

         * Constructor creates a new instance of CTextResolver.Resource files 

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

         * the cleanup stack.

         *

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

         */

        IMPORT_C static CTextResolver* NewLC();

        /** 

        * Destructor 

        */

        IMPORT_C ~CTextResolver();

        /**

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

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

        * is for advanced use

        *

        * @param aError The error code to be resolved.

        * @param aTextId ID of the returned text.

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

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

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

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

        * ECtxAutomatic. 

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

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

        * unknown errors blank error flag (flags are defined in 

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

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

        * can be.

        */

		IMPORT_C const TDesC& ResolveErrorString(

             TInt aError,

             TInt& aTextId,

             TUint& aFlags,

             TErrorContext aContext = ECtxAutomatic);

        /**

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

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

        * is for "normal" use.

        *

        * @param aError The error code to be resolved.

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

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

        * ECtxAutomatic. 

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

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

        * unknown errors blank error flag (flags are defined in 

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

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

        * can be.

        */

	    IMPORT_C const TDesC& ResolveErrorString(

             TInt aError,

             TErrorContext aContext = ECtxAutomatic);

	private:

        virtual TInt ResourceForError(TInt aError);

        virtual void LoadResourceFilesL();

        // Construction

        CTextResolver(CCoeEnv& aEnv);

        CTextResolver();

        void ConstructL();

        // Utility

        void FindFullPathOfResourceFile(TFileName& aResFile) const;

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

        void Reset();

        void PrepareReaderLC(TResourceReader& reader);

        // returns NULL if fails

        HBufC* ReadUnicodeString(const 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);

    private:

        CCoeEnv*                            iCoe;

        RResourceFile                       iRFile;

        TInt                                iRDSupport;

        TInt                                iBaseResourceFileOffset;

        CArrayFix<TInt>*                    iStartError;

        CArrayFix<TInt>*                    iAppTexts;

        CArrayPtr<CErrorResourceIdArray>*   iErrorTexts;

        CArrayPtr<CErrorResourceFlagArray>* iFlags;

        HBufC*                              iTextBuffer;

        HBufC*                              iAppNameText;

        HBufC*                              iContextSeparator;

        RFs                                 iFs;

        TPtrC                               iTruncatedTextPointer;

    };

#endif

// End of File