williamr@2: /*
williamr@4: * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@4: * Description:
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@4: 
williamr@4: #ifndef TEXT_RESOLVER_H
williamr@2: #define TEXT_RESOLVER_H
williamr@2: 
williamr@2: #include <coemain.h>    //  CCoeEnv
williamr@4: #include <textresolver.hrh> // Resource flags 
williamr@4: #include <eikenv.h>    //  CEikonEnv
williamr@2: 
williamr@2: // DEFINES
williamr@2: typedef CArrayFixFlat<TInt> CErrorResourceIdArray;
williamr@2: typedef CArrayFixFlat<TInt> CErrorResourceFlagArray;
williamr@2: 
williamr@2: /**
williamr@2: * Class offers functionality for resolving corresponding error texts for 
williamr@2: * error codes. Text Resolver API provides operations with which a specific 
williamr@2: * error code can be resolved to a human readable text. Descriptions for the
williamr@2: * different error codes must be defined in the resource files of this 
williamr@2: * component. 
williamr@2: *
williamr@2: * Text Resolver uses the CCoeEnv environment class to access the resource
williamr@2: * files if the CCoeEnv environment is available. If the CCoeEnv environment
williamr@2: * is not available, the files are accessed through the RResourceFile API.
williamr@2: *
williamr@2: * The API consist of the CTextResolver class which is used together with 
williamr@2: * Text Resolver flags defined in textresolver.hrh file. The flags are used
williamr@2: * to tell the priority of the error to the client:
williamr@2: *
williamr@2: * - EErrorResBlankErrorFlag is used to tell that error has no proper explanation.
williamr@2: * - EErrorResUnknownErrorFlag indicates that Text Resolver does not support the error. 
williamr@2: * - EErrorResOOMFlag Flag is returned while processing KErrNoMemory error code. 
williamr@2: *
williamr@2: *
williamr@2: * Usage:
williamr@2: *
williamr@2: * @code
williamr@2: *  #include <textresolver.h>
williamr@2: *
williamr@2: *  // Typically used as an instance variable.
williamr@2: *  
williamr@2: *  // Call the factory method NewLC() to create a new instance of CTextResolver.
williamr@2: *  // NewLC() method leaves the instance of the object on the cleanup stack.	
williamr@2: *  // The passed CCoeEnv instance is needed to access the resource files.
williamr@2: *  CTextResolver* iTextResolver = CTextResolver::NewLC(*iCoeEnv); 
williamr@2: *
williamr@2: *  // // Error Resolving, simple:
williamr@2: *
williamr@2: *  // Get error code to be resolved.
williamr@2: *  // TInt err1 = MyMethod(KInvalidValue);
williamr@2: *  TInt err1 = KErrNoMemory;
williamr@2: *    
williamr@2: *  TPtrC buf1;  // For returned error text
williamr@2: *    
williamr@2: *  if (err1 != KErrNone)
williamr@2: *      {
williamr@2: *      // Resolve the given error code. 
williamr@2: *      // The operation returns the error text for the resolved error.
williamr@2: *      // There's no limit how long the resolved string can be.
williamr@2: *      // Add context to 2nd param if needed.
williamr@2: *      buf1.Set(iTextResolver->ResolveErrorString(err)); 
williamr@2: *      }
williamr@2: *  else
williamr@2: *      {
williamr@2: *      // Do something.
williamr@2: *      }
williamr@2: *        
williamr@2: *  // Note that buf1 will only be valid as long as CTextResolver 
williamr@2: *  // instance is alive and no new error is resolved by the same instance.
williamr@2: *  // If for some reason you need to store the resolved error
williamr@2: *  // beyond immediate use, make a copy of it.
williamr@2: *
williamr@2: *  // Error Resolving, advanced:
williamr@2: * 
williamr@2: *  // Get error code to be resolved.
williamr@2: *  // TInt err2 = MyMethod(KInvalidValue);
williamr@2: *  TInt err2 = KErrNotSupported;
williamr@2: *        
williamr@2: *  TInt textId(0);    // ID of the returned text
williamr@2: *  TUint flags(0);    // Priority of the returned error 
williamr@2: *  TPtrC buf2;      // For returned error text
williamr@2: *   
williamr@2: *  if (err2 != KErrNone)
williamr@2: *      {
williamr@2: *      // Resolve the given error code.
williamr@2: *      // The operation returns the error text for the resolved error.
williamr@2: *      // There's no limit on how long the resolved string can be.
williamr@2: *      // Add Context to 4th param if needed.
williamr@2: *      buf2.Set(iTextResolver->ResolveErrorString(err, textId, flags)); 
williamr@2: *
williamr@2: *      if (flags & EErrorResUnknownErrorFlag)
williamr@2: *          {
williamr@2: *          // The flag indicates that Text Resolver does not support
williamr@2: *          // the error code. 
williamr@2: *          // Do something.
williamr@2: *          }
williamr@2: *      }
williamr@2: *  else
williamr@2: *      {
williamr@2: *      // Do something.
williamr@2: *      }
williamr@2: *    
williamr@2: *  // Note that buf2 will only be valid as long as CTextResolver 
williamr@2: *  // instance is alive and no new error is resolved by the same instance.
williamr@2: *  // If for some reason you need to store the resolved error
williamr@2: *  // beyond immediate use, make a copy of it.
williamr@2: *
williamr@2: *  // iTextResolver, Free loaded resources
williamr@2: *  CleanupStack::PopAndDestroy(); 
williamr@2: * @endcode
williamr@2: *
williamr@2: * @lib commonengine.lib
williamr@2: * @since S60 2.0
williamr@2: */
williamr@2: class CTextResolver : public CBase
williamr@2:     {
williamr@4: public:
williamr@4:     /**
williamr@4:     * Defines used error contexts. 
williamr@4:     * Optional error contexes for aiding the mapping of error codes to 
williamr@4:     * texts in a unique way. If no context is given the assumption is 
williamr@4:     * that error codes are unique.
williamr@4:     */
williamr@4:     enum TErrorContext
williamr@4:         {
williamr@4:         /** Context is defined automatically from error code value.
williamr@4:         * Here it is assumed that each error code is unique and in
williamr@4:         * own range. This is a default value when resolving errors. */
williamr@4:         ECtxAutomatic = 0,
williamr@4:         /** Context text is not added to the beginning of the resolved error text,
williamr@4:         * just context separator ':' and newline are added. */
williamr@4:         ECtxNoCtx = 1,
williamr@4:         /** No context text, context separator ':' or newline added to the 
williamr@4:         * beginning of the resolved error text. */
williamr@4:         ECtxNoCtxNoSeparator = 2
williamr@4:         };
williamr@4: public:
williamr@4:     IMPORT_C static CTextResolver* NewL(CCoeEnv& aEnv);
williamr@4:     IMPORT_C static CTextResolver* NewLC(CCoeEnv& aEnv);
williamr@4:     IMPORT_C static CTextResolver* NewL();
williamr@4: 	IMPORT_C static CTextResolver* NewLC();
williamr@4:     IMPORT_C ~CTextResolver();
williamr@4: 	IMPORT_C const TDesC& ResolveErrorString(TInt aError, TInt& aTextId, TUint& aFlags,TErrorContext aContext = ECtxAutomatic);
williamr@4:     IMPORT_C const TDesC& ResolveErrorString(TInt aError, TErrorContext aContext = ECtxAutomatic);
williamr@4: private: // Construction
williamr@4:     virtual TInt ResourceForError(TInt aError);
williamr@4:     virtual void LoadResourceFilesL() { ASSERT(0); }	// deprecated
williamr@4:     CTextResolver(CCoeEnv& aEnv);
williamr@4:     CTextResolver();
williamr@4:     void ConstructL();
williamr@4:     
williamr@4:     // Utility
williamr@4:     void DoRawReadOfSystemErrorResourcesToArraysL(TInt& aError, TInt& aTextId);
williamr@4:     void Reset();
williamr@4:     void ReadLocalizedSeparatorCharacterFromResourceL(CCoeEnv& aCoeEnv);
williamr@4:     void ReadLocalizedSeparatorCharacterFromResourceAndPrepareResourceReaderLC(TResourceReader& aResReader);
williamr@2: 
williamr@4:     // returns NULL if fails
williamr@4:     static HBufC* AllocReadUnicodeString(RResourceFile& aResFile, TInt aTextId);
williamr@4:     /** Returns false if any memory allocation fails or initial values 
williamr@4: 	of necessary pointers are NULL, indicating alloc failure earlier.*/
williamr@4:     TBool AddContextAndSeparator(TErrorContext aContext);
williamr@4:     void AllocBuffersL();
williamr@4:     void DoResolveErrorStringL(TInt aError, TInt& aTextId, TUint& aFlags);
williamr@4: private:
williamr@4:     CCoeEnv* iCoe;
williamr@4:     RResourceFile iResFile;
williamr@4:     TInt iRDSupport;
williamr@4:     TInt iBaseResourceFileOffset;
williamr@4:     CArrayFix<TInt>* iStartError;
williamr@4:     CArrayFix<TInt>* iAppTexts;
williamr@4:     CArrayPtr<CErrorResourceIdArray>*   iErrorTexts;	// Array of arrays of ints
williamr@4:     CArrayPtr<CErrorResourceFlagArray>* iFlags;			// Array of arrays of ints
williamr@4:     HBufC* iTextBuffer;
williamr@4:     HBufC* iTitleText;
williamr@4:     HBufC* iContextSeparator;
williamr@4:     RFs iFs;
williamr@4:     TPtrC  iTruncatedTextPointer;
williamr@4: 	};
williamr@2: 
williamr@2: #endif
williamr@2: