williamr@2: /* williamr@4: * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@4: * under the terms of "Eclipse Public License v1.0" williamr@2: * which accompanies this distribution, and is available williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@4: * Description: williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@2: williamr@4: williamr@4: #ifndef TEXT_RESOLVER_H williamr@2: #define TEXT_RESOLVER_H williamr@2: williamr@2: #include <coemain.h> // CCoeEnv williamr@4: #include <textresolver.hrh> // Resource flags williamr@4: #include <eikenv.h> // CEikonEnv 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: class CTextResolver : public CBase williamr@2: { williamr@4: public: williamr@4: /** williamr@4: * Defines used error contexts. williamr@4: * Optional error contexes for aiding the mapping of error codes to williamr@4: * texts in a unique way. If no context is given the assumption is williamr@4: * that error codes are unique. williamr@4: */ williamr@4: enum TErrorContext williamr@4: { williamr@4: /** Context is defined automatically from error code value. williamr@4: * Here it is assumed that each error code is unique and in williamr@4: * own range. This is a default value when resolving errors. */ williamr@4: ECtxAutomatic = 0, williamr@4: /** Context text is not added to the beginning of the resolved error text, williamr@4: * just context separator ':' and newline are added. */ williamr@4: ECtxNoCtx = 1, williamr@4: /** No context text, context separator ':' or newline added to the williamr@4: * beginning of the resolved error text. */ williamr@4: ECtxNoCtxNoSeparator = 2 williamr@4: }; williamr@4: public: williamr@4: IMPORT_C static CTextResolver* NewL(CCoeEnv& aEnv); williamr@4: IMPORT_C static CTextResolver* NewLC(CCoeEnv& aEnv); williamr@4: IMPORT_C static CTextResolver* NewL(); williamr@4: IMPORT_C static CTextResolver* NewLC(); williamr@4: IMPORT_C ~CTextResolver(); williamr@4: IMPORT_C const TDesC& ResolveErrorString(TInt aError, TInt& aTextId, TUint& aFlags,TErrorContext aContext = ECtxAutomatic); williamr@4: IMPORT_C const TDesC& ResolveErrorString(TInt aError, TErrorContext aContext = ECtxAutomatic); williamr@4: private: // Construction williamr@4: virtual TInt ResourceForError(TInt aError); williamr@4: virtual void LoadResourceFilesL() { ASSERT(0); } // deprecated williamr@4: CTextResolver(CCoeEnv& aEnv); williamr@4: CTextResolver(); williamr@4: void ConstructL(); williamr@4: williamr@4: // Utility williamr@4: void DoRawReadOfSystemErrorResourcesToArraysL(TInt& aError, TInt& aTextId); williamr@4: void Reset(); williamr@4: void ReadLocalizedSeparatorCharacterFromResourceL(CCoeEnv& aCoeEnv); williamr@4: void ReadLocalizedSeparatorCharacterFromResourceAndPrepareResourceReaderLC(TResourceReader& aResReader); williamr@2: williamr@4: // returns NULL if fails williamr@4: static HBufC* AllocReadUnicodeString(RResourceFile& aResFile, TInt aTextId); williamr@4: /** Returns false if any memory allocation fails or initial values williamr@4: of necessary pointers are NULL, indicating alloc failure earlier.*/ williamr@4: TBool AddContextAndSeparator(TErrorContext aContext); williamr@4: void AllocBuffersL(); williamr@4: void DoResolveErrorStringL(TInt aError, TInt& aTextId, TUint& aFlags); williamr@4: private: williamr@4: CCoeEnv* iCoe; williamr@4: RResourceFile iResFile; williamr@4: TInt iRDSupport; williamr@4: TInt iBaseResourceFileOffset; williamr@4: CArrayFix<TInt>* iStartError; williamr@4: CArrayFix<TInt>* iAppTexts; williamr@4: CArrayPtr<CErrorResourceIdArray>* iErrorTexts; // Array of arrays of ints williamr@4: CArrayPtr<CErrorResourceFlagArray>* iFlags; // Array of arrays of ints williamr@4: HBufC* iTextBuffer; williamr@4: HBufC* iTitleText; williamr@4: HBufC* iContextSeparator; williamr@4: RFs iFs; williamr@4: TPtrC iTruncatedTextPointer; williamr@4: }; williamr@2: williamr@2: #endif williamr@2: