williamr@2: /*
williamr@2: * Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies). 
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * 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
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:  Offers functionality for resolving corresponding error texts
williamr@2: *                for error codes. 
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #if !defined TEXT_RESOLVER_H
williamr@2: #define TEXT_RESOLVER_H
williamr@2: 
williamr@2: #include <coemain.h>    //  CCoeEnv
williamr@2: #include <TextResolver.hrh> // Resource flags 
williamr@2: 
williamr@2: // DEFINES
williamr@2: typedef CArrayFixFlat<TInt> CErrorResourceIdArray;
williamr@2: typedef CArrayFixFlat<TInt> CErrorResourceFlagArray;
williamr@2: 
williamr@2: /**
williamr@2: * Class offers functionality for resolving corresponding error texts for 
williamr@2: * error codes. Text Resolver API provides operations with which a specific 
williamr@2: * error code can be resolved to a human readable text. Descriptions for the
williamr@2: * different error codes must be defined in the resource files of this 
williamr@2: * component. 
williamr@2: *
williamr@2: * Text Resolver uses the CCoeEnv environment class to access the resource
williamr@2: * files if the CCoeEnv environment is available. If the CCoeEnv environment
williamr@2: * is not available, the files are accessed through the RResourceFile API.
williamr@2: *
williamr@2: * The API consist of the CTextResolver class which is used together with 
williamr@2: * Text Resolver flags defined in textresolver.hrh file. The flags are used
williamr@2: * to tell the priority of the error to the client:
williamr@2: *
williamr@2: * - EErrorResBlankErrorFlag is used to tell that error has no proper explanation.
williamr@2: * - EErrorResUnknownErrorFlag indicates that Text Resolver does not support the error. 
williamr@2: * - EErrorResOOMFlag Flag is returned while processing KErrNoMemory error code. 
williamr@2: *
williamr@2: *
williamr@2: * Usage:
williamr@2: *
williamr@2: * @code
williamr@2: *  #include <textresolver.h>
williamr@2: *
williamr@2: *  // Typically used as an instance variable.
williamr@2: *  
williamr@2: *  // Call the factory method NewLC() to create a new instance of CTextResolver.
williamr@2: *  // NewLC() method leaves the instance of the object on the cleanup stack.	
williamr@2: *  // The passed CCoeEnv instance is needed to access the resource files.
williamr@2: *  CTextResolver* iTextResolver = CTextResolver::NewLC(*iCoeEnv); 
williamr@2: *
williamr@2: *  // // Error Resolving, simple:
williamr@2: *
williamr@2: *  // Get error code to be resolved.
williamr@2: *  // TInt err1 = MyMethod(KInvalidValue);
williamr@2: *  TInt err1 = KErrNoMemory;
williamr@2: *    
williamr@2: *  TPtrC buf1;  // For returned error text
williamr@2: *    
williamr@2: *  if (err1 != KErrNone)
williamr@2: *      {
williamr@2: *      // Resolve the given error code. 
williamr@2: *      // The operation returns the error text for the resolved error.
williamr@2: *      // There's no limit how long the resolved string can be.
williamr@2: *      // Add context to 2nd param if needed.
williamr@2: *      buf1.Set(iTextResolver->ResolveErrorString(err)); 
williamr@2: *      }
williamr@2: *  else
williamr@2: *      {
williamr@2: *      // Do something.
williamr@2: *      }
williamr@2: *        
williamr@2: *  // Note that buf1 will only be valid as long as CTextResolver 
williamr@2: *  // instance is alive and no new error is resolved by the same instance.
williamr@2: *  // If for some reason you need to store the resolved error
williamr@2: *  // beyond immediate use, make a copy of it.
williamr@2: *
williamr@2: *  // Error Resolving, advanced:
williamr@2: * 
williamr@2: *  // Get error code to be resolved.
williamr@2: *  // TInt err2 = MyMethod(KInvalidValue);
williamr@2: *  TInt err2 = KErrNotSupported;
williamr@2: *        
williamr@2: *  TInt textId(0);    // ID of the returned text
williamr@2: *  TUint flags(0);    // Priority of the returned error 
williamr@2: *  TPtrC buf2;      // For returned error text
williamr@2: *   
williamr@2: *  if (err2 != KErrNone)
williamr@2: *      {
williamr@2: *      // Resolve the given error code.
williamr@2: *      // The operation returns the error text for the resolved error.
williamr@2: *      // There's no limit on how long the resolved string can be.
williamr@2: *      // Add Context to 4th param if needed.
williamr@2: *      buf2.Set(iTextResolver->ResolveErrorString(err, textId, flags)); 
williamr@2: *
williamr@2: *      if (flags & EErrorResUnknownErrorFlag)
williamr@2: *          {
williamr@2: *          // The flag indicates that Text Resolver does not support
williamr@2: *          // the error code. 
williamr@2: *          // Do something.
williamr@2: *          }
williamr@2: *      }
williamr@2: *  else
williamr@2: *      {
williamr@2: *      // Do something.
williamr@2: *      }
williamr@2: *    
williamr@2: *  // Note that buf2 will only be valid as long as CTextResolver 
williamr@2: *  // instance is alive and no new error is resolved by the same instance.
williamr@2: *  // If for some reason you need to store the resolved error
williamr@2: *  // beyond immediate use, make a copy of it.
williamr@2: *
williamr@2: *  // iTextResolver, Free loaded resources
williamr@2: *  CleanupStack::PopAndDestroy(); 
williamr@2: * @endcode
williamr@2: *
williamr@2: * @lib commonengine.lib
williamr@2: * @since S60 2.0
williamr@2: */
williamr@2: 
williamr@2: class CTextResolver : public CBase
williamr@2:     {
williamr@2: 
williamr@2:     public:
williamr@2: 
williamr@2:         /**
williamr@2:         * Defines used error contexts. 
williamr@2:         * Optional error contexes for aiding the mapping of error codes to 
williamr@2:         * texts in a unique way. If no context is given the assumption is 
williamr@2:         * that error codes are unique.
williamr@2:         */
williamr@2:         enum TErrorContext
williamr@2:             {
williamr@2:             /** Context is defined automatically from error code value.
williamr@2:             * Here it is assumed that each error code is unique and in
williamr@2:             * own range. This is a default value when resolving errors.
williamr@2:             */
williamr@2:             ECtxAutomatic = 0,
williamr@2:             /** Context text is not added to the beginning of the resolved error text,
williamr@2:             * just context separator ':' and newline are added.
williamr@2:             */
williamr@2:             ECtxNoCtx = 1,
williamr@2:             /** No context text, context separator ':' or newline added to the 
williamr@2:             * beginning of the resolved error text.
williamr@2:             */
williamr@2:             ECtxNoCtxNoSeparator = 2
williamr@2:             };
williamr@2:     public:
williamr@2:         /**
williamr@2:          * Two-phase constructor method that is used to create a new instance
williamr@2:          * of the CTextResolver class. The implementation uses the passed 
williamr@2:          * CCoeEnv instance to access the resource files.
williamr@2:          *
williamr@2:          * @param aEnv the CCoeEnv instance to be used to access the resource
williamr@2:          * files.
williamr@2:          * @return a pointer to a new instance of the CTextResolver class.
williamr@2:          */
williamr@2:         IMPORT_C static CTextResolver* NewL(CCoeEnv& aEnv);
williamr@2:            
williamr@2:          /**
williamr@2:          * Constructor creates a new instance of CTextResolver. The 
williamr@2:          * implementation uses the passed CCoeEnv instance to access the 
williamr@2:          * resource files. Leaves the object on the cleanup stack.
williamr@2:          *
williamr@2:          * @param aEnv the CCoeEnv instance to be used to access the resource
williamr@2:          * files.
williamr@2:          * @return a pointer to a new instance of the CTextResolver class.
williamr@2:          */
williamr@2:         IMPORT_C static CTextResolver* NewLC(CCoeEnv& aEnv);
williamr@2:         
williamr@2:          /**
williamr@2:          * Constructor creates a new instance of CTextResolver. Resource files 
williamr@2:          * are accessed through the RResourceFile API.
williamr@2:          *
williamr@2:          * @return a pointer to a new instance of the CTextResolver class.
williamr@2:          */
williamr@2:         IMPORT_C static CTextResolver* NewL();
williamr@2: 
williamr@2:          /**
williamr@2:          * Constructor creates a new instance of CTextResolver.Resource files 
williamr@2:          * are accessed through the RResourceFile API. Leaves the object on 
williamr@2:          * the cleanup stack.
williamr@2:          *
williamr@2:          * @return a pointer to a new instance of the CTextResolver class.
williamr@2:          */
williamr@2:         IMPORT_C static CTextResolver* NewLC();
williamr@2: 
williamr@2:         
williamr@2:         /** 
williamr@2:         * Destructor 
williamr@2:         */
williamr@2:         IMPORT_C ~CTextResolver();
williamr@2: 
williamr@2:         /**
williamr@2:         * Resolves the given error code and returns the error text for the
williamr@2:         * resolved error. Resolved text can be of any length. This version
williamr@2:         * is for advanced use
williamr@2:         *
williamr@2:         * @param aError The error code to be resolved.
williamr@2:         * @param aTextId ID of the returned text.
williamr@2:         * @param aFlags The priority of the returned error. The priority is 
williamr@2:         * defined by the this module! Flags are defined in textresolver.hrh.
williamr@2:         * @param aContext Optional context for error numbers. If the aContext 
williamr@2:         * parameter is not passed to the function, it uses the default value
williamr@2:         * ECtxAutomatic. 
williamr@2:         * @return the error text for the resolved error. "System error" (in 
williamr@2:         * English localisation) is returned when error code is not known. For 
williamr@2:         * unknown errors blank error flag (flags are defined in 
williamr@2:         * textresolver.hrh) is also set to hide errors without proper 
williamr@2:         * explanation. There is no limit on how long the resolved string 
williamr@2:         * can be.
williamr@2:         */
williamr@2: 		IMPORT_C const TDesC& ResolveErrorString(
williamr@2:              TInt aError,
williamr@2:              TInt& aTextId,
williamr@2:              TUint& aFlags,
williamr@2:              TErrorContext aContext = ECtxAutomatic);
williamr@2: 
williamr@2:         /**
williamr@2:         * Resolves the given error code and returns the error text for the
williamr@2:         * resolved error. Resolved text can be of any length. This version 
williamr@2:         * is for "normal" use.
williamr@2:         *
williamr@2:         * @param aError The error code to be resolved.
williamr@2:         * @param aContext Optional context for error numbers. If the aContext 
williamr@2:         * parameter is not passed to the function, it uses the default value
williamr@2:         * ECtxAutomatic. 
williamr@2:         * @return the error text for the resolved error. "System error" (in 
williamr@2:         * English localisation) is returned when error code is not known. For 
williamr@2:         * unknown errors blank error flag (flags are defined in 
williamr@2:         * textresolver.hrh) is also set to hide errors without proper 
williamr@2:         * explanation. There is no limit on how long the resolved string
williamr@2:         * can be.
williamr@2:         */
williamr@2: 	    IMPORT_C const TDesC& ResolveErrorString(
williamr@2:              TInt aError,
williamr@2:              TErrorContext aContext = ECtxAutomatic);
williamr@2: 
williamr@2: 	private:
williamr@2:         
williamr@2:         virtual TInt ResourceForError(TInt aError);
williamr@2:         virtual void LoadResourceFilesL();
williamr@2: 
williamr@2:         // Construction
williamr@2:         CTextResolver(CCoeEnv& aEnv);
williamr@2:         CTextResolver();
williamr@2:         void ConstructL();
williamr@2: 
williamr@2:         // Utility
williamr@2:         void FindFullPathOfResourceFile(TFileName& aResFile) const;
williamr@2:         void ReadResourcesToArraysL(TInt& aError, TInt& aTextId);
williamr@2:         void Reset();
williamr@2:         void PrepareReaderLC(TResourceReader& reader);
williamr@2: 
williamr@2:         // returns NULL if fails
williamr@2:         HBufC* ReadUnicodeString(const TInt& aTextId);
williamr@2: 
williamr@2:         // returns false if any memory allocation fails or initial values 
williamr@2:         // of necessary pointers are NULL, indicating alloc failure earlier.
williamr@2:         TBool AddContextAndSeparator(TErrorContext aContext);
williamr@2: 
williamr@2:     private:
williamr@2:         
williamr@2:         CCoeEnv*                            iCoe;
williamr@2:         RResourceFile                       iRFile;
williamr@2:         TInt                                iRDSupport;
williamr@2:         TInt                                iBaseResourceFileOffset;
williamr@2:         CArrayFix<TInt>*                    iStartError;
williamr@2:         CArrayFix<TInt>*                    iAppTexts;
williamr@2:         CArrayPtr<CErrorResourceIdArray>*   iErrorTexts;
williamr@2:         CArrayPtr<CErrorResourceFlagArray>* iFlags;
williamr@2:         HBufC*                              iTextBuffer;
williamr@2:         HBufC*                              iAppNameText;
williamr@2:         HBufC*                              iContextSeparator;
williamr@2:         RFs                                 iFs;
williamr@2:         TPtrC                               iTruncatedTextPointer;
williamr@2:     };
williamr@2: 
williamr@2: #endif
williamr@2: 
williamr@2: // End of File