NAME

SinisterSdpError - SinisterSdp error handling.

SYNOPSIS

 #include <stdarg.h>
 #include <stdio.h>
 #include <SDP/SDP_Parser.h>
 
 /* Function to quit: */
 int quit(const char *format, ...)
 {
 	va_list arg;
 
 	va_start(format, arg);
 	vfprintf(stderr, format, arg);
 	va_end(arg);
 
 	exit(0);
 }
 
 /* Error handlers that can be registered: */
 void fatal_error_handler(SDP_Error error_code, const char *error_string)
 {
 	quit("An error has occurred: %s", error_string);
 }
 int non_fatal_error_handler(SDP_Error error_code, const char *error_string)
 {
 	fprintf(stderr, "WARNING: %s", error_string);
	return 1; /* Keep going... */
 }
 
 int main(void)
 {
 	SDP_Parser *parser;
 	SDP_Description *description;
 
 	parser = SDP_NewParser();
 	if (parser == NULL)
		quit("Error: %s\n", SDP_GetLastErrorString());
 
 	description = SDP_ParseFile(parser, './sessions/description.sdp');
 	if (description == NULL)
 		quit("Couldn't parse: %s\n", SDP_GetLastErrorString());
 
 	...
 
 	/* Or, instead, register the error handlers: */
 	SDP_SetFatalErrorHandler(fatal_error_handler);
 	SDP_SetNonFatalErrorHandler(fatal_error_handler);
 
 	/* Now you can just ignore all return codes: */
 	parser = SDP_NewParser();
 	description = SDP_ParseFile(parser, './sessions/description.sdp');

	...
 }

DESCRIPTION

SinisterSdp employs a standard error code system for handling errors. Functions return either false values or NULL pointers to indicate failure, and error codes and strings can be retrieved using SDP_GetLastError() and SDP_GetLastErrorString().

In addition, you can register error handlers to catch and process errors as they occur.

The error code variable, error string variable, and the variables that hold the function pointers to the error handlers are the only real global variables in SinisterSdp, and they are not reentrant and they are not thread-safe. This was done to keep portability at a maximum and refrain from having to introduce any platform-specific code into what is otherwise a relatively straightforward text manipulating library.

If you need thread safety, go edit SDP_Error.c and put the variables in thread local storage.

FUNCTIONS

The following functions are available:

SDP_GetLastError()

 SDP_Error SDP_GetLastError(void);

This function retrieves the error code of the last error that occurred. If some function call fails, call this to find out why.

SDP_GetLastErrorString()

 const char *SDP_GetLastErrorString(void);

In addition to error codes, SinisterSdp functions produce printable error messages when they fail. these messages are generated on the fly and stored in the global error string variable.

SDP_ErrorRaised()

 int SDP_ErrorRaised(void);

Can be used to tell whether or not any error has occurred yet.

SDP_SetFatalErrorHandler(handler)

 void SDP_SetFatalErrorHandler(SDP_FatalErrorHandler handler);

This function allows you to register a handler to be invoked when any "fatal" error occurs. A fatal error being one that the routine you called cannot continue after and must return prematurely.

Afterwards, any time a fatal error occurs, your handler will be invoked with the error code as the first argument and the error string as the second.

Here's the prototype of a sample handler:

 void sample_fatal_error_handler(
 	SDP_Error      error_code,
 	const char *   error_string
 );

SDP_SetNonFatalErrorHandler(handler)

 void SDP_SetNonFatalErrorHandler(SDP_NonFatalErrorHandler handler);

This function allows you to register a non-fatal error handler to be invoked for all non-fatal errors. Non-fatal errors being errors that the function you called *can* continue safely after, but probably shouldn't. The return value of your handler is used by the function you called to tell whether or not it should keep going anyway. A true return value means it should, a false value means it shouldn't.

Here's the prototype of a sample handler:

 int sample_non_fatal_error_handler(
 	SDP_Error      error_code,
 	const char *   error_string
 );

SDP_UseHandlersForErrors(use_handlers)

 void SDP_UseHandlersForErrors(int use_handlers);

This function allows you to turn on or turn off the error handlers by specifying a true or false value respectively. When off, neither of the two handlers will be invoked when errors occur.

BUGS

Bugs in this package can be reported and monitored using sourceforge.net: http://sourceforge.net/tracker/?atid=644250&group_id=106387&func=browse

You can also email me directly: <william_g_davis at users dot sourceforge dot net>.

COPYRIGHT

Copyright 2004 by William G. Davis.

This library is free software released under the terms of the GNU Lesser General Public License (LGPL), the full terms of which can be found in the "COPYING" file that comes with the distribution.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.