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