x3dio::ErrorCallback Class Reference

An interface to send error messages to the caller of readers and writers. More...

#include <io.h>

List of all members.

Public Types

enum errcode_t {
  ERR_NONE, ERR_BAD_ATTRIBUTE, ERR_BAD_COMMENT, ERR_BAD_FORMAT,
  ERR_BAD_TAG, ERR_MISSING_CONTAINER_FIELD, ERR_NO_HEADER, ERR_UNEXPECTED_CDATA,
  ERR_UNKNOWN_CONTAINER_FIELD, ERR_UNKNOWN_TYPE, ERR_IO, ERR_max
}

Public Member Functions

virtual void Error (errcode_t errcode, const char *message)=0

The Error() function is called each time an I/O error occurs.

void ErrorMsg (errcode_t errcode, const char *format,...)

Generates a string with the error and arguments and pass it to Error().

void ErrorVMsg (errcode_t errcode, const char *format, va_list ap)

Generates a string with the error and array of arguments and pass it to Error().

virtual ~ErrorCallback ()

The error callback destructor needs to be defined since it is virtual.

Detailed Description

An interface to send error messages to the caller of readers and writers.

Implement this interface if you are interested in the error messages while reading from or writing to a stream.

The only function you need to implement is the Error() function. The others are just helper functions so you do not have to reimplement them (and they are not virtual anyway.)

This is very useful to implement either a console application where the Error() can just be something like this:

 MyClass::Error(errcode_t errcode, const char *message)
 {
        fprintf(stderr, "error %d: %s", errcode, message);
 }

And an application with a GUI can open some sort of message box:

 MyClass::Error(errcode_t errcode, const char *message)
 {
        MessageBox(NULL, message, "X3D Loading Error", MB_OK | MB_ICONERROR);
 }

At this time, the Reader and Writer interfaces make use of this error callback mechanism.

See also:: Reader
Writer

Member Enumeration Documentation

enum x3dio::ErrorCallback::errcode_t

Enumerator:

ERR_NONE not an error

ERR_BAD_ATTRIBUTE name too long, bad string

ERR_BAD_COMMENT usually unterminated comment

ERR_BAD_FORMAT DOCTYPE which is NOT named X3D.

ERR_BAD_TAG most likely unterminated

ERR_MISSING_CONTAINER_FIELD no containerField name...

ERR_NO_HEADER cannot find <?xml ... ?>

ERR_UNEXPECTED_CDATA only scripts accept a <![CDATA[...]]>

ERR_UNKNOWN_CONTAINER_FIELD containerField name not recognized...

ERR_UNKNOWN_TYPE do not know how to create this node

ERR_IO some error happened while reading/writing the stream

ERR_max end of list

Constructor & Destructor Documentation

x3dio::ErrorCallback::~ErrorCallback ( ) [virtual]

The error callback destructor needs to be defined since it is virtual.
Cleans up the error callback class. Since this object has no member it just does nothing.

Member Function Documentation

void x3dio::ErrorCallback::Error ( errcode_t errcode,

const char * message

) [pure virtual]

The Error() function is called each time an I/O error occurs.
The x3dio::Reader and x3dio::Writer classes have functions which accept an ErrorCallback pointer. When provided, the Error() function is automatically called each time an error occurs.
You can test the errcode to know whether you should fail or not. Note that many errors mean that an x3dio::Reader will fail anyway.
You are welcome to print out the message.

Todo:
I will need to make the FileStream proper in order to internationalize the messages since these could be used in a graphical interface some day.

Todo:
Should the function return bool so the x3dio::Reader or x3dio::Writer knows whether to fail at once or try to continue?

void x3dio::ErrorCallback::ErrorMsg ( errcode_t errcode,

const char * format,

...

)

Generates a string with the error and arguments and pass it to Error().
This function is a helper function which takes a fprintf(3C) like format and a variable list of arguments to generate a message in a string before to call the Error() function.
It is used by the different libraries to generate errors.

void x3dio::ErrorCallback::ErrorVMsg ( errcode_t errcode,

const char * format,

va_list ap

)

Generates a string with the error and array of arguments and pass it to Error().
This function is a helper function which takes a vfprintf(3C) like format and an array of arguments (va_list) to generate a message in a string before to call the Error() function.
It is used by functions which accept a variable number of parameters (such as ErrorMsg() in this class) and need to send an Error() message.

Todo:
At this time, the message is limited to 1Kb. Should we allocate memory if that's too small?!

The documentation for this class was generated from the following files: