EDT Message Handler Library

These routines provide a way for application programs to intercept and handle edtlib and pdvlib error, warning, and debug messages, but you can also use them for application messages.

By default, output goes to the console (stdout), but you can substitute user-defined functions -- for example, a function that pops up a window to display text. You can set different message levels for different output, and multiple message handles can exist within an application, with different message handlers associated with them.

Predefined message flags are described in the "Defines" section of this document. Those starting with EDTAPP_MSG_ are for general application use, those starting with EDTLIB_MSG_ are for libedt messages, and those beginning with PDVLIB_MSG_ are for libpdv messages. Application programmers can define other flags in the 0x1000 to 0x1000000 range.

Message levels are defined by flag bits, and each bit can be set or cleared individually. So, for example, to have a message-handler called only for fatal and warning application messages, specify EDTAPP_MSG_FATAL | EDTAPP_MSG_WARNING .

As you can see, the edt and pci dv libraries have their own message flags. These can be turned on and off from within an application, and also by setting the environment variables EDTDEBUG and PDVDEBUG, respectively, to values greater than zero.

Application programs ordinarily specify combinations of either the EDTAPP_MSG_ or EDT_MSG_ flags for their messages.


Data Structures
struct	_edt_msg_handler
	Structure used by the Message Handler Library to control the output of messages. More...
Defines
#define	edt_msg_add_default_level(addlevel) edt_msg_set_level(edt_msg_default_handle(), edt_msg_default_level() \| addlevel)
#define	EDT_MSG_ALWAYS 0x80000000
#define	EDT_MSG_FATAL EDTAPP_MSG_FATAL \| EDTLIB_MSG_FATAL \| PDVLIB_MSG_FATAL
#define	EDT_MSG_INFO_1 EDTAPP_MSG_INFO_1 \| EDTLIB_MSG_INFO_1 \| PDVLIB_MSG_INFO_1
#define	EDT_MSG_INFO_2 EDTAPP_MSG_INFO_2 \| EDTLIB_MSG_INFO_2 \| PDVLIB_MSG_INFO_2
#define	EDT_MSG_WARNING EDTAPP_MSG_WARNING \| EDTLIB_MSG_WARNING \| PDVLIB_MSG_WARNING
#define	EDTAPP_MSG_FATAL 0x1
	Fatal-error messages in applications.
#define	EDTAPP_MSG_INFO_1 0x4
	First level info messages in applications.
#define	EDTAPP_MSG_INFO_2 0x8
	Second level info messages in applications.
#define	EDTAPP_MSG_WARNING 0x2
	Warning messages in applications.
#define	EDTLIB_MSG_FATAL 0x10
	Fatal-error messages in libedt.
#define	EDTLIB_MSG_INFO_1 0x40
	Informative messages in libedt.
#define	EDTLIB_MSG_INFO_2 0x80
	Debugging messages in libedt.
#define	EDTLIB_MSG_WARNING 0x20
	Warning messages in libedt.
#define	PDVLIB_MSG_FATAL 0x100
	Fatal-error messages in libpdv.
#define	PDVLIB_MSG_INFO_1 0x400
	Informative messages in libpdv.
#define	PDVLIB_MSG_INFO_2 0x800
	Debugging messages in libpdv.
#define	PDVLIB_MSG_WARNING 0x200
	Warning messages in libpdv.
Typedefs
typedef int(*)	EdtMsgFunction (void target, int level, const char message)
	An EdtMsgFunction is a function which outputs a message if that message's level is high enough.
typedef _edt_msg_handler	EdtMsgHandler
	Structure used by the Message Handler Library to control the output of messages.
Functions
int	edt_get_verbosity (void)
int	edt_msg (int level, const char *format,...)
	Submits a message to the default message handler, which will conditionally (based on the flag bits) send the message to the default message handler function.
void	edt_msg_add_level (EdtMsgHandler *msg_p, int level)
	Sets the message level to the combination of the specified level with the message handler's previous level.
void	edt_msg_close (EdtMsgHandler *msg_p)
	Closes and frees up memory associated with a message handler.
EdtMsgHandler *	edt_msg_default_handle (void)
	Gets the default message handler.
int	edt_msg_default_level (void)
	Gets the message level that messages must match in order to be handled by the default message handler.
int	edt_msg_get_level (EdtMsgHandler *msg_p)
	Gets the message level that messages must match in order to be handled by the message handler msg_p.
void	edt_msg_init (EdtMsgHandler *msg_p)
	Initializes a message handler with default values.
void	edt_msg_init_files (EdtMsgHandler msg_p, FILE file, int level)
	Initializes a message handler to use the specified file and level.
void	edt_msg_init_names (EdtMsgHandler msg_p, char file, int level)
	Initializes a message handler to use the named file and specified level.
char *	edt_msg_last_error (void)
	Gets the message last sent to the output by the edt message handling system.
int	edt_msg_output (EdtMsgHandler msg_p, int level, const char format,...)
	Submits a message using the msg_p message handler, which will conditionally (based on the flag bits) send the message to the handler's function.
int	edt_msg_output_perror (EdtMsgHandler msg_p, int level, const char message)
	Conditionally (based on the flag bits) outputs `message`, followed by the last system error message, to `msg_p`.
int	edt_msg_output_printf_perror (EdtMsgHandler msg_p, int level, const char format,...)
	Writes to the specified EdtMsgHandler a caller-specified message (in the printf-style format) followed by the last system error message.
int	edt_msg_perror (int level, const char *msg)
	Conditionally outputs a system perror using the default message handler.
int	edt_msg_printf_perror (int level, const char *format,...)
	Outputs a caller-specified message to the output, followed by the last system error message.
void	edt_msg_set_file (EdtMsgHandler msg_p, FILE f)
	Sets the output file pointer for the message handler.
void	edt_msg_set_function (EdtMsgHandler *msg_p, EdtMsgFunction f)
	Sets the function to call when a message event occurs.
void	edt_msg_set_level (EdtMsgHandler *msg_p, int newlevel)
	Sets the "message level" flag bits that determine whether to call the message handler for a given message.
void	edt_msg_set_name (EdtMsgHandler msg_p, const char f)
	Sets the output file to the named file.
void	edt_msg_set_target (EdtMsgHandler msg_p, void t)
	Sets the target in the message handler.
void	edt_set_verbosity (int verbose)
int	lvl_printf (int delta, char *format,...)

Typedef Documentation

typedef int(*) EdtMsgFunction(void *target, int level, const char *message)

An EdtMsgFunction is a function which outputs a message if that message's level is high enough.

Parameters:

	target	this stores extra info useful to the specific function defined. In the default message handler setup by edt_msg_init, the function used expects target to be a FILE pointer.
	level	The message level associated with with the message.
	message	The message which can be output by the function.

Definition at line 83 of file edt_error.h.

Function Documentation

int edt_msg	(	int	level,
		const char *	format,
			...
	)

Submits a message to the default message handler, which will conditionally (based on the flag bits) send the message to the default message handler function.

This function uses the default message handler, and is equivalent to calling edt_msg_output(edt_msg_default_handle(), ...). To submit a message for handling by other than the default message handle, use edt_msg_output.

Parameters:

	level	an integer variable that contains flag bits indicating what 'level' message it is. Flag bits are described in the overview.
	format	a string and arguments describing the format. Uses vsprintf to print formatted text to a string, and sends the result to the handler subroutine. Refer to the `printf` manual page for formatting flags and options.

Example

 edt_msg(EDTAPP_MSG_WARNING, "file '%s' not found", fname);

Returns:: 0 on success, -1 on failure.

Definition at line 279 of file edt_error.c.

void edt_msg_add_level	(	EdtMsgHandler *	msg_p,
		int	level
	)

Sets the message level to the combination of the specified level with the message handler's previous level.

Parameters:

	msg_p	pointer to message handler, initiailzed by edt_msg_init
	level	a message level flag, as defined in the overview.

Definition at line 421 of file edt_error.c.

void edt_msg_close ( EdtMsgHandler * msg_p )

Closes and frees up memory associated with a message handler.

Use only on message handlers that have been explicitly initialized by edt_msg_init. Do not try to close the default message handler. If the message handler has been configured to use a file which the user opened, through functions such as edt_msg_init_files or edt_msg_set_file, then the user is responsible for closing that file after calling this function.

Parameters:

msg_p

pointer to message handler to close, which was initiailzed by edt_msg_init

Returns:: 0 on success, -1 on failure.

Definition at line 246 of file edt_error.c.

EdtMsgHandler* edt_msg_default_handle ( void )

Gets the default message handler.

This is useful if you want to modify the default handler's behaviour, with functions such as edt_msg_set_level, edt_msg_set_function, edt_msg_set_file, edt_msg_set_name, or edt_msg_set_target.

Definition at line 716 of file edt_error.c.

int edt_msg_default_level ( void )

Gets the message level that messages must match in order to be handled by the default message handler.

The level is a combination of flags OR'ed together as described in the overview.

The equivalent function for a user defined message handler is edt_msg_get_level.

Definition at line 733 of file edt_error.c.

int edt_msg_get_level ( EdtMsgHandler * msg_p )

Gets the message level that messages must match in order to be handled by the message handler msg_p.

The level is a combination of flags OR'ed together as described in the overview.

Parameters:

msg_p

pointer to message handler

Definition at line 407 of file edt_error.c.

void edt_msg_init ( EdtMsgHandler * msg_p )

Initializes a message handler with default values.

The message file is initialized to stderr. The output subroutine pointer is set to fprintf (to write output to the console). The message level is set to EDT_MSG_WARNING | EDT_MSG_FATAL.

Parameters:

msg_p

pointer to message handler structure to initialize

Example

 EdtMsgHandler msgLogger;
 edt_msg_init(&msgLogger);

See also:: edt_msg_output

Definition at line 174 of file edt_error.c.

void edt_msg_init_files	(	EdtMsgHandler *	msg_p,
		FILE *	file,
		int	level
	)

Initializes a message handler to use the specified file and level.

Similar to edt_msg_init_names but rather than opening a named file, this takes a pointer to a FILE which has been opened by the caller.

Parameters:

	msg_p	pointer to message handler structure to initialize
	file	FILE pointer returned by e.g. fopen().
	level	the level that future messages must match against if they are to be handled by the msg_p handler.

Definition at line 221 of file edt_error.c.

void edt_msg_init_names	(	EdtMsgHandler *	msg_p,
		char *	file,
		int	level
	)

Initializes a message handler to use the named file and specified level.

Parameters:

	msg_p	pointer to message handler structure to initialize
	file	the name of a file to open and write messages to.
	level	the level that future messages must match against if they are to be handled by the msg_p handler.

Definition at line 201 of file edt_error.c.

int edt_msg_output	(	EdtMsgHandler *	msg_p,
		int	level,
		const char *	format,
			...
	)

Submits a message using the msg_p message handler, which will conditionally (based on the flag bits) send the message to the handler's function.

To submit a message to the default message handler, use edt_msg.

Parameters:

	msg_p	pointer to message handler, initiailzed by edt_msg_init
	level	an integer variable that contains flag bits indicating what 'level' message it is. Flag bits are described in the overview.
	format	a string and arguments describing the format. Uses `vsprintf` to print formatted text to a string, and sends the result to the handler subroutine. Refer to the `printf` manual page for formatting flags and options.

Example

 int my_error_popup(void *target, int level, char *message) {
     GtkWindow * parentWindow = (GtkWindow *)target;
     GtkWidget * dialog = gtk_message_dialog_new(parentWindow, 0,
     GTK_MESSAGE_WARNING, GTK_BUTTONS_NONE, message);
 }

 if (edt_access(fname, 0) != 0)
      edt_msg_output(msgLogger, EDTAPP_MSG_WARNING, "file '%s' not
      found", fname);

 GtkWindow *window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
 gtk_widget_show(window);

 EdtMsgHandler msgLogger;
 edt_msg_init(&msgLogger);
 edt_msg_set_target(window);
 edt_msg_set_function(msgLogger, (EdtMsgFunction *)my_error_popup);
 edt_msg_set_level(msgLogger, EDT_MSG_FATAL | EDT_MSG_WARNING);

Returns:: 0 on success, -1 on failure.

Definition at line 344 of file edt_error.c.

int edt_msg_output_perror	(	EdtMsgHandler *	msg_p,
		int	level,
		const char *	msg
	)

Conditionally (based on the flag bits) outputs message, followed by the last system error message, to msg_p.

To output to the default message handler, use edt_msg_perror.

Parameters:

	msg_p	pointer to message handler, initiailzed by edt_msg_init
	level	message level for the current message, as described in the overview
	msg	message to concatenate to the system error message

See also:: edt_perror

Definition at line 606 of file edt_error.c.

int edt_msg_output_printf_perror	(	EdtMsgHandler *	msg_p,
		int	level,
		const char *	format,
			...
	)

Writes to the specified EdtMsgHandler a caller-specified message (in the printf-style format) followed by the last system error message.

If you want to just use the default handler (to just print to the console), use edt_msg_printf_perror instead.

Parameters:

	msg_p	pointer to message handler, initiailzed by edt_msg_init
	level	the EDT Message level. This function will only output the message if level is greater than or equal to that set by edt_msg_init, edt_msg_set_level, edt_msg_add_level, or edt_msg_add_default_level.
	format	a printf() style format string. Like printf(), it should be followed by arguments to match the format.

See also:: edt_msg_printf_perror for an example

Definition at line 699 of file edt_error.c.

int edt_msg_perror	(	int	level,
		const char *	msg
	)

Conditionally outputs a system perror using the default message handler.

This function is equivalent to calling edt_msg_output_perror(edt_msg_default_handle(), level, msg);

Parameters:

	level	message level for the current message, as described in the overview
	msg	message to concatenate to the system error message

Example

 if ((fp = fopen ("file.txt", "r")) == NULL)
     edt_msg_perror(EDT_FATAL, "couldn't open file.txt for reading");

Returns:: 0 on success, -1 on failure.

See also:: edt_perror, edt_msg_output_perror

Definition at line 554 of file edt_error.c.

int edt_msg_printf_perror	(	int	level,
		const char *	format,
			...
	)

Outputs a caller-specified message to the output, followed by the last system error message.

This is useful when an error occurs, and you want your error message to be followed by the system's error message.

Example:

 char *file_name = "/aFileThatDoesNotExist";
 FILE *file_ptr = fopen(file_name, "r");
 if (file_ptr == NULL) {
     edt_msg_printf_perror(
           EDTAPP_MSG_FATAL, 
           "Couldn't open file '%s'",
           file_name);
     exit(1);
 }

Which will print something like "Couldn't open file '/aFileThatDoesNotExist': No such file or directory"

Parameters:

	level	the EDT Message level. This function will only output the message if level is greater than or equal to that set by edt_msg_init, edt_msg_set_level, edt_msg_add_level, or edt_msg_add_default_level.
	format	a printf() style format string. Like printf(), it should be followed by arguments to match the format.

Returns:: 0 on success, -1 on failure.

Definition at line 673 of file edt_error.c.

void edt_msg_set_file	(	EdtMsgHandler *	msg_p,
		FILE *	fp
	)

Sets the output file pointer for the message handler.

The user still owns the file, so they are responsible for closing it after this message handler is done with it, such as after this function is called again, or after edt_msg_close is called.

Parameters:

	msg_p	pointer to message handler
	fp	FILE pointer to an opened file, to which the messages should be output.

Example

 EdtMsgHandler msg;
 EdtMsgHandler *msg_p = &msg;
 FILE *fp = fopen("messages.out", "w");
 edt_msg_init(msg_p);
 edt_msg_set_file(msg_p, fp);

 ... some time later ...

 edt_msg_close(msg_p);
 fclose(fp);

Definition at line 477 of file edt_error.c.

void edt_msg_set_function	(	EdtMsgHandler *	msg_p,
		EdtMsgFunction	f
	)

Sets the function to call when a message event occurs.

The default message function is fprintf() (which outputs to stderr); this routine allows programmers to substitute any type of message handler (pop-up callback, file write, etc).

For an example of how this could be used, see edt_msg.

Parameters:

	msg_p	pointer to message handler
	f	The funtion to call when a message event occurs.

See also:: edt_msg_set_level, edt_msg

Definition at line 441 of file edt_error.c.

void edt_msg_set_level	(	EdtMsgHandler *	msg_p,
		int	newlevel
	)

Sets the "message level" flag bits that determine whether to call the message handler for a given message.

The flags set by this function are ANDed with the flags set in each edt_msg call, to determine whether the call goes to the message function and actually results in any output.

Parameters:

	msg_p	pointer to message handler
	newlevel	The new level to set in the message handler.

Example

 edt_msg_set_level(edt_msg_default_handle(), 
                   EDT_MSG_FATAL|EDT_MSG_WARNING);

Definition at line 389 of file edt_error.c.

void edt_msg_set_name	(	EdtMsgHandler *	msg_p,
		const char *	name
	)

Sets the output file to the named file.

Parameters:

	msg_p	pointer to message handler
	name	the name of a file to open. Future messages will be written to that file.

Definition at line 499 of file edt_error.c.

void edt_msg_set_target	(	EdtMsgHandler *	msg_p,
		void *	target
	)

Sets the target in the message handler.

The target would usually be an object that messages are sent to, such as a window, but exactly what it will be depends on what the message handler's function expects.

See also:: edt_msg_set_function, EdtMsgFunction

Definition at line 524 of file edt_error.c.

EDT Message Handler Library

Detailed Description

Data Structures

Defines

Typedefs

Functions

Typedef Documentation

Function Documentation