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