CTextResolver Class Reference

API published in: S60 2nd Ed

Link against: commonengine.lib

Capability Information

Required Capabilities

None

#include <textresolver.h>

Detailed Description

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:

Usage: 

  #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();

Public Types
enum   TErrorContext { ECtxAutomatic = 0, ECtxNoCtx = 1, ECtxNoCtxNoSeparator = 2 }
  Defines used error contexts. More...

Public Member Functions
IMPORT_C  ~CTextResolver ()
  Destructor.
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.
IMPORT_C const TDesC &  ResolveErrorString (TInt aError, TErrorContext aContext=ECtxAutomatic)
  Resolves the given error code and returns the error text for the resolved error.

Static Public Member Functions
static IMPORT_C CTextResolver *  NewL (CCoeEnv &aEnv)
  Two-phase constructor method that is used to create a new instance of the CTextResolver class.
static IMPORT_C CTextResolver *  NewLC (CCoeEnv &aEnv)
  Constructor creates a new instance of CTextResolver.
static IMPORT_C CTextResolver *  NewL ()
  Constructor creates a new instance of CTextResolver.
static IMPORT_C CTextResolver *  NewLC ()
  Constructor creates a new instance of CTextResolver.Resource files are accessed through the RResourceFile API.

Member Enumeration Documentation

enum CTextResolver::TErrorContext
 

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.

Enumerator:
ECtxAutomatic  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.

ECtxNoCtx  Context text is not added to the beginning of the resolved error text, just context separator ':' and newline are added.
ECtxNoCtxNoSeparator  No context text, context separator ':' or newline added to the beginning of the resolved error text.

Constructor & Destructor Documentation

IMPORT_C CTextResolver::~CTextResolver (   ) 
 

Destructor.

Member Function Documentation

static IMPORT_C CTextResolver* CTextResolver::NewL (   )  [static]
 

Constructor creates a new instance of CTextResolver.

Resource files are accessed through the RResourceFile API.

Returns:
a pointer to a new instance of the CTextResolver class.
static IMPORT_C CTextResolver* CTextResolver::NewL (  CCoeEnv &  aEnv  )  [static]
 

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.

Parameters:
aEnv  the CCoeEnv instance to be used to access the resource files.
Returns:
a pointer to a new instance of the CTextResolver class.
static IMPORT_C CTextResolver* CTextResolver::NewLC (   )  [static]
 

Constructor creates a new instance of CTextResolver.Resource files are accessed through the RResourceFile API.

Leaves the object on the cleanup stack.

Returns:
a pointer to a new instance of the CTextResolver class.
static IMPORT_C CTextResolver* CTextResolver::NewLC (  CCoeEnv &  aEnv  )  [static]
 

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.

Parameters:
aEnv  the CCoeEnv instance to be used to access the resource files.
Returns:
a pointer to a new instance of the CTextResolver class.
IMPORT_C const TDesC& CTextResolver::ResolveErrorString (  TInt  aError,
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.

Parameters:
aError  The error code to be resolved.
aContext  Optional context for error numbers. If the aContext parameter is not passed to the function, it uses the default value ECtxAutomatic.
Returns:
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& CTextResolver::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 advanced use

Parameters:
aError  The error code to be resolved.
aTextId  ID of the returned text.
aFlags  The priority of the returned error. The priority is defined by the this module! Flags are defined in textresolver.hrh.
aContext  Optional context for error numbers. If the aContext parameter is not passed to the function, it uses the default value ECtxAutomatic.
Returns:
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.
The documentation for this class was generated from the following file:
Copyright © Nokia Corporation 2001-2008
Back to top