S60 3rd Edition API Reference: CTextResolver Class Reference

Detailed Description

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.

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

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:


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.

CTextResolver Class Reference

Capability Information

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation