1.1 --- a/epoc32/include/textresolver.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/textresolver.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,292 @@
1.4 -textresolver.h
1.5 +/*
1.6 +* Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: Offers functionality for resolving corresponding error texts
1.19 +* for error codes.
1.20 +*
1.21 +*/
1.22 +
1.23 +
1.24 +
1.25 +#if !defined TEXT_RESOLVER_H
1.26 +#define TEXT_RESOLVER_H
1.27 +
1.28 +#include <coemain.h> // CCoeEnv
1.29 +#include <TextResolver.hrh> // Resource flags
1.30 +
1.31 +// DEFINES
1.32 +typedef CArrayFixFlat<TInt> CErrorResourceIdArray;
1.33 +typedef CArrayFixFlat<TInt> CErrorResourceFlagArray;
1.34 +
1.35 +/**
1.36 +* Class offers functionality for resolving corresponding error texts for
1.37 +* error codes. Text Resolver API provides operations with which a specific
1.38 +* error code can be resolved to a human readable text. Descriptions for the
1.39 +* different error codes must be defined in the resource files of this
1.40 +* component.
1.41 +*
1.42 +* Text Resolver uses the CCoeEnv environment class to access the resource
1.43 +* files if the CCoeEnv environment is available. If the CCoeEnv environment
1.44 +* is not available, the files are accessed through the RResourceFile API.
1.45 +*
1.46 +* The API consist of the CTextResolver class which is used together with
1.47 +* Text Resolver flags defined in textresolver.hrh file. The flags are used
1.48 +* to tell the priority of the error to the client:
1.49 +*
1.50 +* - EErrorResBlankErrorFlag is used to tell that error has no proper explanation.
1.51 +* - EErrorResUnknownErrorFlag indicates that Text Resolver does not support the error.
1.52 +* - EErrorResOOMFlag Flag is returned while processing KErrNoMemory error code.
1.53 +*
1.54 +*
1.55 +* Usage:
1.56 +*
1.57 +* @code
1.58 +* #include <textresolver.h>
1.59 +*
1.60 +* // Typically used as an instance variable.
1.61 +*
1.62 +* // Call the factory method NewLC() to create a new instance of CTextResolver.
1.63 +* // NewLC() method leaves the instance of the object on the cleanup stack.
1.64 +* // The passed CCoeEnv instance is needed to access the resource files.
1.65 +* CTextResolver* iTextResolver = CTextResolver::NewLC(*iCoeEnv);
1.66 +*
1.67 +* // // Error Resolving, simple:
1.68 +*
1.69 +* // Get error code to be resolved.
1.70 +* // TInt err1 = MyMethod(KInvalidValue);
1.71 +* TInt err1 = KErrNoMemory;
1.72 +*
1.73 +* TPtrC buf1; // For returned error text
1.74 +*
1.75 +* if (err1 != KErrNone)
1.76 +* {
1.77 +* // Resolve the given error code.
1.78 +* // The operation returns the error text for the resolved error.
1.79 +* // There's no limit how long the resolved string can be.
1.80 +* // Add context to 2nd param if needed.
1.81 +* buf1.Set(iTextResolver->ResolveErrorString(err));
1.82 +* }
1.83 +* else
1.84 +* {
1.85 +* // Do something.
1.86 +* }
1.87 +*
1.88 +* // Note that buf1 will only be valid as long as CTextResolver
1.89 +* // instance is alive and no new error is resolved by the same instance.
1.90 +* // If for some reason you need to store the resolved error
1.91 +* // beyond immediate use, make a copy of it.
1.92 +*
1.93 +* // Error Resolving, advanced:
1.94 +*
1.95 +* // Get error code to be resolved.
1.96 +* // TInt err2 = MyMethod(KInvalidValue);
1.97 +* TInt err2 = KErrNotSupported;
1.98 +*
1.99 +* TInt textId(0); // ID of the returned text
1.100 +* TUint flags(0); // Priority of the returned error
1.101 +* TPtrC buf2; // For returned error text
1.102 +*
1.103 +* if (err2 != KErrNone)
1.104 +* {
1.105 +* // Resolve the given error code.
1.106 +* // The operation returns the error text for the resolved error.
1.107 +* // There's no limit on how long the resolved string can be.
1.108 +* // Add Context to 4th param if needed.
1.109 +* buf2.Set(iTextResolver->ResolveErrorString(err, textId, flags));
1.110 +*
1.111 +* if (flags & EErrorResUnknownErrorFlag)
1.112 +* {
1.113 +* // The flag indicates that Text Resolver does not support
1.114 +* // the error code.
1.115 +* // Do something.
1.116 +* }
1.117 +* }
1.118 +* else
1.119 +* {
1.120 +* // Do something.
1.121 +* }
1.122 +*
1.123 +* // Note that buf2 will only be valid as long as CTextResolver
1.124 +* // instance is alive and no new error is resolved by the same instance.
1.125 +* // If for some reason you need to store the resolved error
1.126 +* // beyond immediate use, make a copy of it.
1.127 +*
1.128 +* // iTextResolver, Free loaded resources
1.129 +* CleanupStack::PopAndDestroy();
1.130 +* @endcode
1.131 +*
1.132 +* @lib commonengine.lib
1.133 +* @since S60 2.0
1.134 +*/
1.135 +
1.136 +class CTextResolver : public CBase
1.137 + {
1.138 +
1.139 + public:
1.140 +
1.141 + /**
1.142 + * Defines used error contexts.
1.143 + * Optional error contexes for aiding the mapping of error codes to
1.144 + * texts in a unique way. If no context is given the assumption is
1.145 + * that error codes are unique.
1.146 + */
1.147 + enum TErrorContext
1.148 + {
1.149 + /** Context is defined automatically from error code value.
1.150 + * Here it is assumed that each error code is unique and in
1.151 + * own range. This is a default value when resolving errors.
1.152 + */
1.153 + ECtxAutomatic = 0,
1.154 + /** Context text is not added to the beginning of the resolved error text,
1.155 + * just context separator ':' and newline are added.
1.156 + */
1.157 + ECtxNoCtx = 1,
1.158 + /** No context text, context separator ':' or newline added to the
1.159 + * beginning of the resolved error text.
1.160 + */
1.161 + ECtxNoCtxNoSeparator = 2
1.162 + };
1.163 + public:
1.164 + /**
1.165 + * Two-phase constructor method that is used to create a new instance
1.166 + * of the CTextResolver class. The implementation uses the passed
1.167 + * CCoeEnv instance to access the resource files.
1.168 + *
1.169 + * @param aEnv the CCoeEnv instance to be used to access the resource
1.170 + * files.
1.171 + * @return a pointer to a new instance of the CTextResolver class.
1.172 + */
1.173 + IMPORT_C static CTextResolver* NewL(CCoeEnv& aEnv);
1.174 +
1.175 + /**
1.176 + * Constructor creates a new instance of CTextResolver. The
1.177 + * implementation uses the passed CCoeEnv instance to access the
1.178 + * resource files. Leaves the object on the cleanup stack.
1.179 + *
1.180 + * @param aEnv the CCoeEnv instance to be used to access the resource
1.181 + * files.
1.182 + * @return a pointer to a new instance of the CTextResolver class.
1.183 + */
1.184 + IMPORT_C static CTextResolver* NewLC(CCoeEnv& aEnv);
1.185 +
1.186 + /**
1.187 + * Constructor creates a new instance of CTextResolver. Resource files
1.188 + * are accessed through the RResourceFile API.
1.189 + *
1.190 + * @return a pointer to a new instance of the CTextResolver class.
1.191 + */
1.192 + IMPORT_C static CTextResolver* NewL();
1.193 +
1.194 + /**
1.195 + * Constructor creates a new instance of CTextResolver.Resource files
1.196 + * are accessed through the RResourceFile API. Leaves the object on
1.197 + * the cleanup stack.
1.198 + *
1.199 + * @return a pointer to a new instance of the CTextResolver class.
1.200 + */
1.201 + IMPORT_C static CTextResolver* NewLC();
1.202 +
1.203 +
1.204 + /**
1.205 + * Destructor
1.206 + */
1.207 + IMPORT_C ~CTextResolver();
1.208 +
1.209 + /**
1.210 + * Resolves the given error code and returns the error text for the
1.211 + * resolved error. Resolved text can be of any length. This version
1.212 + * is for advanced use
1.213 + *
1.214 + * @param aError The error code to be resolved.
1.215 + * @param aTextId ID of the returned text.
1.216 + * @param aFlags The priority of the returned error. The priority is
1.217 + * defined by the this module! Flags are defined in textresolver.hrh.
1.218 + * @param aContext Optional context for error numbers. If the aContext
1.219 + * parameter is not passed to the function, it uses the default value
1.220 + * ECtxAutomatic.
1.221 + * @return the error text for the resolved error. "System error" (in
1.222 + * English localisation) is returned when error code is not known. For
1.223 + * unknown errors blank error flag (flags are defined in
1.224 + * textresolver.hrh) is also set to hide errors without proper
1.225 + * explanation. There is no limit on how long the resolved string
1.226 + * can be.
1.227 + */
1.228 + IMPORT_C const TDesC& ResolveErrorString(
1.229 + TInt aError,
1.230 + TInt& aTextId,
1.231 + TUint& aFlags,
1.232 + TErrorContext aContext = ECtxAutomatic);
1.233 +
1.234 + /**
1.235 + * Resolves the given error code and returns the error text for the
1.236 + * resolved error. Resolved text can be of any length. This version
1.237 + * is for "normal" use.
1.238 + *
1.239 + * @param aError The error code to be resolved.
1.240 + * @param aContext Optional context for error numbers. If the aContext
1.241 + * parameter is not passed to the function, it uses the default value
1.242 + * ECtxAutomatic.
1.243 + * @return the error text for the resolved error. "System error" (in
1.244 + * English localisation) is returned when error code is not known. For
1.245 + * unknown errors blank error flag (flags are defined in
1.246 + * textresolver.hrh) is also set to hide errors without proper
1.247 + * explanation. There is no limit on how long the resolved string
1.248 + * can be.
1.249 + */
1.250 + IMPORT_C const TDesC& ResolveErrorString(
1.251 + TInt aError,
1.252 + TErrorContext aContext = ECtxAutomatic);
1.253 +
1.254 + private:
1.255 +
1.256 + virtual TInt ResourceForError(TInt aError);
1.257 + virtual void LoadResourceFilesL();
1.258 +
1.259 + // Construction
1.260 + CTextResolver(CCoeEnv& aEnv);
1.261 + CTextResolver();
1.262 + void ConstructL();
1.263 +
1.264 + // Utility
1.265 + void FindFullPathOfResourceFile(TFileName& aResFile) const;
1.266 + void ReadResourcesToArraysL(TInt& aError, TInt& aTextId);
1.267 + void Reset();
1.268 + void PrepareReaderLC(TResourceReader& reader);
1.269 +
1.270 + // returns NULL if fails
1.271 + HBufC* ReadUnicodeString(const TInt& aTextId);
1.272 +
1.273 + // returns false if any memory allocation fails or initial values
1.274 + // of necessary pointers are NULL, indicating alloc failure earlier.
1.275 + TBool AddContextAndSeparator(TErrorContext aContext);
1.276 +
1.277 + private:
1.278 +
1.279 + CCoeEnv* iCoe;
1.280 + RResourceFile iRFile;
1.281 + TInt iRDSupport;
1.282 + TInt iBaseResourceFileOffset;
1.283 + CArrayFix<TInt>* iStartError;
1.284 + CArrayFix<TInt>* iAppTexts;
1.285 + CArrayPtr<CErrorResourceIdArray>* iErrorTexts;
1.286 + CArrayPtr<CErrorResourceFlagArray>* iFlags;
1.287 + HBufC* iTextBuffer;
1.288 + HBufC* iAppNameText;
1.289 + HBufC* iContextSeparator;
1.290 + RFs iFs;
1.291 + TPtrC iTruncatedTextPointer;
1.292 + };
1.293 +
1.294 +#endif
1.295 +
1.296 +// End of File