EDT PDV SDK Documentation 6.1.0
EDT Message Handler Library

Data Structures

struct  edt_msg_handler_s
 

Macros

#define EDTAPP_MSG_FATAL   0x1
 
#define EDTAPP_MSG_WARNING   0x2
 
#define EDTAPP_MSG_INFO_1   0x4
 
#define EDTAPP_MSG_INFO_2   0x8
 
#define EDTLIB_MSG_FATAL   0x10
 
#define EDTLIB_MSG_WARNING   0x20
 
#define EDTLIB_MSG_INFO_1   0x40
 
#define EDTLIB_MSG_INFO_2   0x80
 
#define PDVLIB_MSG_FATAL   0x100
 
#define PDVLIB_MSG_WARNING   0x200
 
#define PDVLIB_MSG_INFO_1   0x400
 
#define PDVLIB_MSG_INFO_2   0x800
 

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. More...
 
typedef struct edt_msg_handler_s EdtMsgHandler
 

Functions

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. More...
 
void edt_msg_init_file (EdtMsgHandler *msg_p, FILE *file, int level)
 Initializes a message handler to use the specified file and level. This takes a pointer to a FILE which has been opened by the caller. More...
 
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_file or edt_msg_set_file, then the user is responsible for closing that file after calling this function. More...
 
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. More...
 
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. More...
 
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). More...
 
void edt_msg_set_file (EdtMsgHandler *msg_p, FILE *f)
 Sets the output file pointer for the message handler. More...
 
void edt_msg_set_target (EdtMsgHandler *msg_p, void *t)
 Sets the target in the message handler. More...
 
void edt_msg_set_name (EdtMsgHandler *msg_p, const char *name)
 Sets the output file to the named file. More...
 
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. More...
 
int edt_msg_output (EdtMsgHandler *msg_p, int level, const char *format,...)
 
int edt_msg_perror (int level, const char *msg)
 Conditionally outputs a system perror using the default message handler. More...
 
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. More...
 
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. More...
 
EdtMsgHandleredt_msg_default_handle (void)
 Gets the default message handler. More...
 
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. More...
 
char * edt_msg_last_error (void)
 Returns pointer to most recent msg string. More...
 
void edt_set_verbosity (int verbose)
 Simple verbose level setting output message simplified - levels 0 - 3. More...
 
int edt_get_verbosity (void)
 Return simple verbose level setting.
 

Detailed Description

Provides generalized error- and message-handling for the edt and pdv libraries.

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.

Files

The EdtMsgHandler structure is defined in edt_error.h. For compatibility with possible future changes, do not access structure elements directly; instead always use the error subroutines.

Macro Definition Documentation

◆ EDTAPP_MSG_FATAL

#define EDTAPP_MSG_FATAL   0x1

Predefined message flags. EDTAPP_MSG are for general purpose application use EDTLIB_MSG are for libedt messages. PDVLIB are for libpdv messages. Application programmers can define other flags in the 0x1000 to 0x1000000 range. Fatal-error messages in applications.

◆ EDTAPP_MSG_WARNING

#define EDTAPP_MSG_WARNING   0x2

Warning messages in applications

◆ EDTAPP_MSG_INFO_1

#define EDTAPP_MSG_INFO_1   0x4

First level info messages in applications.

◆ EDTAPP_MSG_INFO_2

#define EDTAPP_MSG_INFO_2   0x8

Second level info messages in applications.

◆ EDTLIB_MSG_FATAL

#define EDTLIB_MSG_FATAL   0x10

Fatal-error messages in libedt.

◆ EDTLIB_MSG_WARNING

#define EDTLIB_MSG_WARNING   0x20

Warning messages in libedt.

◆ EDTLIB_MSG_INFO_1

#define EDTLIB_MSG_INFO_1   0x40

Informative messages in libedt.

◆ EDTLIB_MSG_INFO_2

#define EDTLIB_MSG_INFO_2   0x80

Debugging messages in libedt.

◆ PDVLIB_MSG_FATAL

#define PDVLIB_MSG_FATAL   0x100

Fatal-error messages in libpdv.

◆ PDVLIB_MSG_WARNING

#define PDVLIB_MSG_WARNING   0x200

Warning messages in libpdv.

◆ PDVLIB_MSG_INFO_1

#define PDVLIB_MSG_INFO_1   0x400

Informative messages in libpdv.

◆ PDVLIB_MSG_INFO_2

#define PDVLIB_MSG_INFO_2   0x800

Debugging messages in libpdv.

Typedef Documentation

◆ EdtMsgFunction

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
targetThis 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.
levelThe message level associated with with the message.
messageThe message which can be output by the function.

◆ EdtMsgHandler

Structure used by the Message Handler Library to control the output of messages.

Function Documentation

◆ edt_msg_init()

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_pPointer to message handler structure to initialize.
See also
edt_msg_output

\Example

EdtMsgHandler msgLogger;
edt_msg_init(&msgLogger);
Here is the caller graph for this function:

◆ edt_msg_init_file()

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

Initializes a message handler to use the specified file and level. This takes a pointer to a FILE which has been opened by the caller.

Parameters
msg_pPointer to message handler structure to initialize.
fileFILE pointer returned by e.g. fopen().
levelThe level that future messages must match against if they are to be handled by the msg_p handler.
Here is the call graph for this function:

◆ edt_msg_close()

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_file or edt_msg_set_file, then the user is responsible for closing that file after calling this function.

Parameters
msg_pPointer to message handler to close, which was initialized by edt_msg_init
Returns
0 on success, -1 on failure.

◆ edt_msg_set_level()

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_pPointer to message handler.
newlevelThe new level to set in the message handler.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_msg_get_level()

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_pPointer to message handler.

◆ edt_msg_set_function()

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_pPointer to message handler.
fThe function to call when a message event occurs.
See also
edt_msg_set_level, edt_msg
Here is the call graph for this function:

◆ edt_msg_set_file()

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_pPointer to message handler.
fFILE pointer to an opened file, to which the messages should be output.

\Example

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);
Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_msg_set_target()

void edt_msg_set_target ( EdtMsgHandler msg_p,
void *  t 
)

Sets the target in the message handler.

Parameters
msg_pPointer to message handler.
tStores 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. 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
Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_msg_set_name()

void edt_msg_set_name ( EdtMsgHandler msg_p,
const char *  name 
)

Sets the output file to the named file.

Parameters
msg_pPointer to message handler.
nameThe name of a file to open. Future messages will be written to that file.
Here is the call graph for this function:

◆ edt_msg()

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
levelAn integer variable that contains flag bits indicating what 'level' message it is. Flag bits are described in the overview.
formatA 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.
Returns
0 on success, -1 on failure.

\Example

edt_msg(EDTAPP_MSG_WARNING, "file '%s' not found", fname);
Here is the call graph for this function:

◆ edt_msg_output()

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_ppointer to message handler, initiailzed by edt_msg_init
levelan integer variable that contains flag bits indicating what 'level' message it is. Flag bits are described in the overview.
formata 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_function(msgLogger, (EdtMsgFunction *)my_error_popup);
edt_msg_set_level(msgLogger, EDT_MSG_FATAL | EDT_MSG_WARNING);
Returns
0 on success, -1 on failure.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_msg_perror()

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
levelMessage level for the current message, as described in the overview.
msgMessage to concatenate to the system error message.
Returns
0 on success, -1 on failure.
See also
edt_perror, edt_msg_output_perror

\Example

if ((fp = fopen ("file.txt", "r")) == NULL)
edt_msg_perror(EDT_FATAL, "couldn't open file.txt for reading");
Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_msg_output_perror()

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.

To output to the default message handler, use edt_msg_perror.

Parameters
msg_pPointer to message handler, initialized by edt_msg_init.
levelMessage level for the current message, as described in the overview.
msgMessage to concatenate to the system error message.
See also
edt_perror
Here is the call graph for this function:

◆ edt_msg_output_printf_perror()

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.

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

◆ edt_msg_default_handle()

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.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_msg_default_level()

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.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_msg_last_error()

char * edt_msg_last_error ( void  )

Returns pointer to most recent msg string.

Gets the message last sent to the output by the edt message handling system.

◆ edt_set_verbosity()

void edt_set_verbosity ( int  verbose)

Simple verbose level setting output message simplified - levels 0 - 3.

Parameters
verboseLevel setting. One of: level 0 - fatal only level 1 - warnings level 2 - info level 1 level 3 - info level 2
Here is the call graph for this function: