--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/genericservices/s60compatibilityheaders/commonengine/inc/textresolver.h Fri Jun 04 16:20:51 2010 +0100
@@ -0,0 +1,199 @@
+/*
+* Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description:
+*
+*/
+
+
+
+
+#ifndef TEXT_RESOLVER_H
+#define TEXT_RESOLVER_H
+
+#include <coemain.h> // CCoeEnv
+#include <textresolver.hrh> // Resource flags
+#include <eikenv.h> // CEikonEnv
+
+// 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:
+ IMPORT_C static CTextResolver* NewL(CCoeEnv& aEnv);
+ IMPORT_C static CTextResolver* NewLC(CCoeEnv& aEnv);
+ IMPORT_C static CTextResolver* NewL();
+ IMPORT_C static CTextResolver* NewLC();
+ IMPORT_C ~CTextResolver();
+ IMPORT_C const TDesC& ResolveErrorString(TInt aError, TInt& aTextId, TUint& aFlags,TErrorContext aContext = ECtxAutomatic);
+ IMPORT_C const TDesC& ResolveErrorString(TInt aError, TErrorContext aContext = ECtxAutomatic);
+private: // Construction
+ virtual TInt ResourceForError(TInt aError);
+ virtual void LoadResourceFilesL() { ASSERT(0); } // deprecated
+ CTextResolver(CCoeEnv& aEnv);
+ CTextResolver();
+ void ConstructL();
+
+ // Utility
+ void DoRawReadOfSystemErrorResourcesToArraysL(TInt& aError, TInt& aTextId);
+ void Reset();
+ void ReadLocalizedSeparatorCharacterFromResourceL(CCoeEnv& aCoeEnv);
+ void ReadLocalizedSeparatorCharacterFromResourceAndPrepareResourceReaderLC(TResourceReader& aResReader);
+
+ // returns NULL if fails
+ static HBufC* AllocReadUnicodeString(RResourceFile& aResFile, 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);
+ void AllocBuffersL();
+ void DoResolveErrorStringL(TInt aError, TInt& aTextId, TUint& aFlags);
+private:
+ CCoeEnv* iCoe;
+ RResourceFile iResFile;
+ TInt iRDSupport;
+ TInt iBaseResourceFileOffset;
+ CArrayFix<TInt>* iStartError;
+ CArrayFix<TInt>* iAppTexts;
+ CArrayPtr<CErrorResourceIdArray>* iErrorTexts; // Array of arrays of ints
+ CArrayPtr<CErrorResourceFlagArray>* iFlags; // Array of arrays of ints
+ HBufC* iTextBuffer;
+ HBufC* iTitleText;
+ HBufC* iContextSeparator;
+ RFs iFs;
+ TPtrC iTruncatedTextPointer;
+ };
+
+#endif
+