Error Handlers

Contents, Programmers Guide, Applying the SDK, Miscellaneous API Issues, Error Handlers

Error Handlers

To obtain an interface to pathengine you will need to specify a handler for pathengine to call in the case of an error.
(Unless you are using the testbed in which case the testbed supplies a handler.)

The handler must derive from Interface iErrorHandler.

#ifndef I_ERRORHANDLER_HAS_BEEN_INCLUDED
#define I_ERRORHANDLER_HAS_BEEN_INCLUDED
class iErrorHandler
{
public:
	virtual ~iErrorHandler() {};
	enum eAction
	{
		CONTINUE,
		ABORT,
		BREAK,
		CONTINUE_IGNORE_IN_FUTURE,
	};
	virtual eAction handle(const char *type, const char *description, const char *const* attributes)=0;
};
#endif

If an error occurs, the handler's handle() function will be called with details about the error.

'error_type' and 'error_string' are C strings.
'attributes' points to a set of attributes relating to the error.
See Handling Attributes for an explanation about how to parse these attributes.
The memory associated with all of these arguments is managed internally by pathengine and should not be deleted.

'error_string' is a descriptive string explaining the error.

'error_type' indicates the severity of the error.
Some values to expect are:

Value	Meaning
"Fatal"	Execution cannot continue following this error. After the handler returns, pathengine will abort execution.
"NonFatal"	An error has occurred but execution can continue after the handler returns. An error will be returned by the code that detected the error to calling code. The calling code will then decide what to do. The calling code may retry the operation, or trigger a "Fatal" error. Interface functions that return pointers may return 0 following a "NonFatal" error to indicate failure.
"Warning"	This error is for information only, and execution can continue after the handler returns.
"Assertion"	A runtime assertion. The action taken after the handler returns depends on the eAction value returned by the handler.

The eAction value returned by this function indicates a requested action.
The actual action taken depends on the exact nature of the error.
(In fact the requested action is currently ignored except in the case of assertions.)

An example handler

Here is an example of how the handler might be implemented (taken from the tesbed):

#include "testbederror.h"
#include <windows.h>
#include <stdio.h>
#include <string>
#include "i_errorhandler.h"

class cTestBedError : public iErrorHandler
{
	cTestBedError() {}
public:
	eAction handle(const char* error_type, const char* error_string, const char **attributes)
	{
		char title[1000];
		sprintf(title,"Error, type: %s",error_type);
		MessageBox(0,error_string,title,MB_OK);
		std::string attributes_string;
		if(attributes==0 || *attributes==0)
			return CONTINUE;
		while(*attributes)
		{
			attributes_string+="attribute \"";
			attributes_string+=*attributes;
			attributes_string+="\"=\"";
			attributes++;
			attributes_string+=*attributes;
			attributes_string+="\"\n";
			attributes++;
		}
		MessageBox(0,attributes_string.c_str(),"Error attributes",MB_OK);
		return CONTINUE;
	}
	static cTestBedError &refInstance()
	{
		static cTestBedError the_instance;
		return the_instance;
	}
};
iErrorHandler* getTestBedErrorHandler()
{
	return &cTestBedError::refInstance();
}

next: Handling Attributes