QSDK 1.1 Documentation

QUtils

Files
file	utils.h
Modules
Collection classes
Reference counting
Abstract Data Types
Thread Synchronisation
Memory Management
Logging
Version
Compounds
struct	Problem
struct	ResultListener
struct	ResultString
struct	UID
Defines
#define	ERROR_CODE(__subsys, __code)   (0x80040000 + (__subsys << 8) + __code)
#define	WARNING_CODE(__subsys, __code)   (0x00040000 + (__subsys << 8) + __code)
Typedefs
typedef unsigned int	Result
Enumerations
enum	StdResult {   Success = 0,   False = 1,   Failure = 0x80000000,   NotImplemented = 0x80000001,   OutOfMemory = 0x80000002,   InvalidArgument = 0x80000003,   NoInterface = 0x80000004,   FileNotFound = (0x80040000 + ( 0 << 8) + 1 ),   FileReadError = (0x80040000 + ( 0 << 8) + 2 ),   FileWriteError = (0x80040000 + ( 0 << 8) + 3 ),   FileCorrupt = (0x80040000 + ( 0 << 8) + 4 ) }
Functions
bool	succeeded (Result res)
bool	failed (Result res)
Result	raiseError (Result res)
Result	lastError ()
void	clearError ()
void	setErrorSuppressed (Result res)
void	clearErrorSuppressed (Result res)
const char *	resultToString (Result res)
void	addResultListener (const ResultListener *)
void	removeResultListener (const ResultListener *)

---

Detailed Description

This subsystem depends on QSys. Most other subsystems use QUtils to provide various useful collection class templates and other utilities.

---

Define Documentation

#define ERROR_CODE (  __subsys, __code   )     (0x80040000 + (__subsys << 8) + __code)

Construct a Utils::Result representing an error given a subsystem code and a unique error code within that subsystem. See also: StdResult, Result, WARNING_CODE, failed()

#define WARNING_CODE (  __subsys, __code   )     (0x00040000 + (__subsys << 8) + __code)

Construct a Utils::Result representing a warning given a subsystem code and a unique warning code within that subsystem. See also: StdResult, Result, ERROR_CODE, failed()

---

Typedef Documentation

typedef unsigned int Utils::Result

Many function methods return a status code that can be used to determine success or failure. Result codes are all represented by a 32-bit (Microsoft COM-compatible) unsigned integer, which is divided into a number of fields: bits 00-15: code bits 16-27: facility bit 28: reserved (should be zero) bit 29: customer code flag (should be zero) bits 30-31: severity (00 = success, 01 = informational, 10 = warning, 11 = error). Ideally, each area of the system should be assigned a different Facility code, ensuring that the status codes from different system areas do not clash. Microsoft allocates these facility codes and various values are reserved for the use of different components of the Windows operating system. One particular facility code (with value 4) is defined to be 'interface specific'. We use this facility code to define Q-specific status codes. For software developed at Qube we subdivide the code field into two eight bit fields with the high eight bits of the code representing the Qube subsystem and the low eight bits the error code within that subsystem. For convenience, the macros ERROR_CODE(subsys, code) and WARNING_CODE(subsys, code) are provided for constructing error codes in this format. See also: ERROR_CODE, WARNING_CODE, succeeded(), failed(), StdResult

---

Enumeration Type Documentation

enum Utils::StdResult

Standard codes returned in a Result. See also: ERROR_CODE, WARNING_CODE, succeeded(), failed(), Com::StdComResult Enumeration values: Success  standard success code False  standard success code Failure  generic failure code NotImplemented  not implemented OutOfMemory  memory allocation failure InvalidArgument  invalid argument passed to a method NoInterface  the object does not support a required interface FileNotFound  file not found FileReadError  file read error FileWriteError  file write error FileCorrupt  file is corrupt

---

Function Documentation

void addResultListener (  const ResultListener *   )

Add a listener to the list of object called when a runtime error is detected.

void clearError (   )

Clear the last value recorded with raiseError(). This simply sets the value to Success. See also: raiseError(), lastError().

void clearErrorSuppressed (  Result  res  )

Indicate that errors of this type should no longer be suppressed. Error message and Utils::ResultListener will now be active for errors of this type.

bool failed (  Result  res  )  [inline, static]

Return false if a value represents a failed result or true otherwise. See also: succeeded()

Result lastError (   )

Return the last value recorded with raiseError(). See also: raiseError(), clearError()

Result raiseError (  Result  res  )

Record a result value. This value can be retrieved later if for some reason the value was not available. See also: lastError(), clearError()

void removeResultListener (  const ResultListener *   )

Remove a listener from the list of object called when a runtime error is detected.

const char* resultToString (  Result  res  )

Return a printable string describing a result value. See also: ResultString

void setErrorSuppressed (  Result  res  )

Indicate that errors of this type should not be reported.

bool succeeded (  Result  res  )  [inline, static]

Return true if a value represents a successful result or false otherwise. See also: failed()

		Qube Software Limited © 2000-2004