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