diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/textresolver.h --- a/epoc32/include/textresolver.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/textresolver.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,292 @@ -textresolver.h +/* +* 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 // CCoeEnv +#include // Resource flags + +// DEFINES +typedef CArrayFixFlat CErrorResourceIdArray; +typedef CArrayFixFlat 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 +* +* // 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* iStartError; + CArrayFix* iAppTexts; + CArrayPtr* iErrorTexts; + CArrayPtr* iFlags; + HBufC* iTextBuffer; + HBufC* iAppNameText; + HBufC* iContextSeparator; + RFs iFs; + TPtrC iTruncatedTextPointer; + }; + +#endif + +// End of File