CTextResolver Class Reference

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();
Dll commonengine.lib
Since:
S60 2.0

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-2007
Back to top