Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

Exceptions and Messages


Detailed Description

The functions in this module provide support for exceptions and messages based on simple objects.

This module is typically used with exception/message code generated through the sobjxc tool (see Exception Compiler). The API of this module is provided through the <sobject/exc.h> include file.


Files

file  exc.h
 Public include file of the exceptions and messages module.

Exception Stripping Flags

The following flag constants may be passed as the flags argument of sobj_exc_strip().

See sobj_exc_strip() for the documentation of these flags.

#define SOBJ_EXC_STRIP_SOURCE   (1)
#define SOBJ_EXC_STRIP_ARGS   (2)
#define SOBJ_EXC_STRIP_MODULE   (4)
#define SOBJ_EXC_STRIP_CLASS   (8)
#define SOBJ_EXC_STRIP_I18N   (16)
#define SOBJ_EXC_STRIP_CN   (32)
#define SOBJ_EXC_STRIP_ID   (64)
#define SOBJ_EXC_STRIP_LEVEL   (128)
#define SOBJ_EXC_STRIP_TYPE   (256)

Defines

#define sobj_exc_args_size(exc, arg_n)
 Macro for computing the buffer sizes required for calling sobj_exc_args().
#define sobj_exc_sourceref_size(exc)
 Macro for computing the buffer size required for calling sobj_exc_sourceref().
#define sobj_exc_info_size(exc, xcls_n, arg_n)
 Macro for computing the buffer size required for calling sobj_exc_info().

Functions

size_t sobj_exc_args (struct sobj *exc, int *arg_n, const char **key, struct sobj **value, char *buffer, size_t buffer_size)
 Get the argument keys and values from an exception or message object.
size_t sobj_exc_sourceref_to_string (struct sobj *exc, bool show_module, char *buffer, size_t buffer_size)
 Convert a source reference from an exception or message object to a string.
size_t sobj_exc_to_string (struct sobj *exc, bool compact, char *buffer, size_t buffer_size)
 Create a string representation of an exception object.
size_t sobj_msg_to_string (struct sobj *msg, bool compact, char *buffer, size_t buffer_size)
 Create a string representation of a message object.
bool sobj_exc_xcls_match (const char *exc_class, const char *xcls)
 Check if the specfied exception class matches the specfied class.
bool sobj_exc_match (struct sobj *exc, const char *xcls)
 Check if an exception object matches the specfied exception class.
bool sobj_exc_match_exact (struct sobj *exc, const char *xcls)
 Check if an exception object matches the specfied exception class.
bool sobj_exc_match_id (struct sobj *exc, const char *id, const char *module)
 Check if the specfied exception or message object matches the specfied exception/message ID.
size_t sobj_exc_sourceref (struct sobj *exc, const char **module, const char **file, int *line, const char **func, char *buffer, size_t buffer_size)
 Get the source reference from the specfied exception or message object.
size_t sobj_exc_info (struct sobj *exc, int *xcls_n, const char **xcls, const char **id, int *arg_n, const char **key, struct sobj **value, char *buffer, size_t buffer_size)
 Extract the class, ID, and argument information from an exception object.
sobjsobj_exc_strip (struct sobj *exc, unsigned flags)
 Strip information from an exception or message object.
void sobj_exc_dump (struct sobj *exc)
 Dump a string representation of an exception object to the standard error stream.


Define Documentation

#define sobj_exc_args_size exc,
arg_n   ) 
 

Value:

(\
    sobj_exc_args((exc), (arg_n), 0, 0, 0, 0))
Macro for computing the buffer sizes required for calling sobj_exc_args().

Parameters:
exc The exception or message object.
arg_n Pointer to a variable receiving the number of message/exception arguments. This may be a null-pointer.
Returns:
The size required for the key buffer as specfied in the buffer parameter of the sobj_exc_args() function.
See also:
sobj_exc_args().

#define sobj_exc_info_size exc,
xcls_n,
arg_n   ) 
 

Value:

(\
    sobj_exc_info((exc), (xcls_n), 0, 0, (arg_n), 0, 0, 0, 0))
Macro for computing the buffer size required for calling sobj_exc_info().

Parameters:
exc The exception object.
xcls_n Pointer to a variable receiving the number of exception classes. This may be a null-pointer.
arg_n Pointer to a variable receiving the number of exception arguments. This may be a null-pointer.
Returns:
The size required for the buffer as specfied in the buffer parameter of the sobj_exc_info() function.
See also:
sobj_exc_info().

#define sobj_exc_sourceref_size exc   ) 
 

Value:

(\
    sobj_exc_sourceref((exc), 0, 0, 0, 0, 0, 0))
Macro for computing the buffer size required for calling sobj_exc_sourceref().

Parameters:
exc The exception or message object.
Returns:
The size required for the buffer as specfied in the buffer parameter of the sobj_exc_sourceref() function.
See also:
sobj_exc_sourceref().


Function Documentation

size_t sobj_exc_args struct sobj exc,
int *  arg_n,
const char **  key,
struct sobj **  value,
char *  buffer,
size_t  buffer_size
 

Get the argument keys and values from an exception or message object.

The function scans the specfied array object for keys which are simple strings (i.e. strings with no class and/or embedded variable references) that do not start with a double underscore. These keys and values are extracted from the specfied object. If the specfied exception object is not an array (or an empty array), then the function returns 0 and sets *arg_n to 0.

This function is typically called twice: a first time to comute the size of the buffers required for the key, value, and buffer arguments and a second time to extact the argument keys and values.

Parameters:
exc The exception (or message) object.
arg_n Pointer to a variable receiving the number of argument keys found in the object. This may be a null-pointer.
key Pointer to a vector of character pointers to be initialized to point to the argument keys found in the object. This may be a null-pointer.
value Pointer to a vector receiving borrowed references to the argument values. This may be a null-pointer.
buffer Pointer to a buffer receiving all argument keys, separated by null-characters. The key[i] pointers will point into this buffer if both key and buffer are non-null. This argument may be a null-pointer.
buffer_size The size of the specfied buffer.
Returns:
The size required for the key buffer as specfied in the buffer parameter.

void sobj_exc_dump struct sobj exc  ) 
 

Dump a string representation of an exception object to the standard error stream.

Parameters:
exc The exception object. If this is a null-pointer, then the function has no effect.

size_t sobj_exc_info struct sobj exc,
int *  xcls_n,
const char **  xcls,
const char **  id,
int *  arg_n,
const char **  key,
struct sobj **  value,
char *  buffer,
size_t  buffer_size
 

Extract the class, ID, and argument information from an exception object.

This function is typically called twice: a first time with all arguments null (except for exc and arg_n) to compute the size of the buffer argument vectors and a second time to extact the requested information. Example:

        const char *id = 0;
        int arg_n = 0, xcls_n = 0;
        char buffer[sobj_exc_info(exc, 0, &xcls_n, 0, &arg_n, 0, 0, 0, 0)];
        const char *arg_key[arg_n ? arg_n : 1];
        struct sobj *arg_value[arg_n ? arg_n : 1];
        const char *xcls[xcls_n ? xcls_n : 1];
        sobj_exc_info(exc, 0, xcls, &id, 0, arg_key, arg_value,
            buffer, sizeof buffer);

Parameters:
exc The exception object.
xcls_n Pointer to a variables receiving the number of exception classes listed in the exception object. This may be a null-pointer.
xcls Pointer to the vectors receiving the references to the exception classes. This may be a null-pointer.
id Pointer to the variable receiving the reference to the exception ID. This may be a null-pointer. If this is not null and no exception ID is specfied if the exception object, then *id is set to a null-pointer.
arg_n Pointer to a variable receiving the number of argument keys found in the exception object. This may be a null-pointer.
key Pointer to a vector of character pointers to be initialized to point to the argument keys found in the exception object. This may be a null-pointer.
value Pointer to a vector receiving borrowed references to the argument values. This may be a null-pointer.
buffer Pointer to a caller supplied buffer for storing the exception class, ID, and argument keys. If this is not null, then the exception class, ID, and argument keys are stored to this buffer (separated by null-characters) and the variables referenced by xcls, id, and/or key[] are set to point into this buffer.
buffer_size The size of the specfied buffer. This argument is ignored if no buffer is specfied.
Returns:
The size required for the buffer specfied in the buffer argument.

bool sobj_exc_match struct sobj exc,
const char *  xcls
 

Check if an exception object matches the specfied exception class.

The class is either specfied directly or using the MODULE/CLASS syntax. If the specfied classname contains a slash character, then the string preceeding the slash is interpreted as a module name.

It is safe to call this function with an arbitrary simple object. If the specfied object does not define the relevant exception fields, then the function returns false.

Parameters:
exc The exception object.
xcls The exception class or module/class tuple.
Return values:
true The specfied exception object matches the specfied exception class.
false The specfied exception object does not matches the specfied exception class or does not define the relevant exception object fields.
See also:
sobj_exc_match_exact().

bool sobj_exc_match_exact struct sobj exc,
const char *  xcls
 

Check if an exception object matches the specfied exception class.

This is a variant of sobj_exc_match() performing an exact comparison of the class names.

Parameters:
exc The exception object.
xcls The exception class or module/class tuple.
Return values:
true The specfied exception object exactly matches the specfied exception class.
false The specfied exception object does not matches the specfied exception class or does not define the relevant exception object fields.
See also:
sobj_exc_match().

bool sobj_exc_match_id struct sobj exc,
const char *  id,
const char *  module
 

Check if the specfied exception or message object matches the specfied exception/message ID.

Parameters:
exc The exception or message object.
id The message/exception ID to be checked against.
module The module name. If this is not a null-pointer, then the function also checks if the specfied module name matches the module name of the specfied exception/message object.
Return values:
true The specfied exception/message object matches the specfied exception/message ID and (if specfied) module name.
false The specfied exception/message object does not match the specfied exception/message ID or (if specfied) module name.

size_t sobj_exc_sourceref struct sobj exc,
const char **  module,
const char **  file,
int *  line,
const char **  func,
char *  buffer,
size_t  buffer_size
 

Get the source reference from the specfied exception or message object.

This function is typically called twice: a first time with all arguments null (except for exc) to compute the size of the buffer and a second time to extact the requested source reference fields. For example:

        const char *module = 0, *file = 0, *func = 0;
        int line = 0;
        char buffer[sobj_exc_sourceref(exc, 0, 0, 0, 0, 0, 0)];
        sobj_exc_sourceref(exc, &module, &file, &line, &func,
            buffer, sizeof buffer);

Parameters:
exc The exception or message object.
module Pointer to the variable receiving the reference to the module name. This may be a null-pointer. If this is not null and no module name is specfied if the exception/message object, then *module is set to a null-pointer.
file Pointer to the variable receiving the reference to the source file name. This may be a null-pointer. If this is not null and no source file name is specfied if the exception/message object, then *file is set to a null-pointer.
line Pointer to the variable receiving the reference to the source line number. This may be a null-pointer. If this is not null and no source line number is specfied if the exception/message object, then *line is set to zero.
func Pointer to the variable receiving the reference to the function name. This may be a null-pointer. If this is not null and no function name is specfied if the exception/message object, then *func is set to a null-pointer.
buffer Pointer to a caller supplied buffer for storing the module, file, and function name(s). If this is not null, then the module, file, and function name(s) are stored to this buffer (separated by null-characters) and the variables referenced by module, file, and/or func are set to point into this buffer.
buffer_size The size of the specfied buffer. This argument is ignored if no buffer is specfied.
Returns:
The size required for the buffer specfied in the buffer argument.

size_t sobj_exc_sourceref_to_string struct sobj exc,
bool  show_module,
char *  buffer,
size_t  buffer_size
 

Convert a source reference from an exception or message object to a string.

Note that the resulting string is not internationalized or internationalizable.

Parameters:
exc The exception or message object containing the source reference.
show_module Flag indicating if the module name should be included in the resulting string.
buffer Buffer receiving the string representation of the source reference. This may be a null-pointer.
buffer_size The size of the specfied buffer.
Returns:
The function returns the length of the string representation, not counting the terminating null-character.

struct sobj* sobj_exc_strip struct sobj exc,
unsigned  flags
 

Strip information from an exception or message object.

The function will either return the specfied exception/message object unchanged, or drop the specfied object and return a flat reference to a new object. Due to this behavior, it is safe to strip message/exception objects ``on the fly''.

It is safe to call this function on an arbitrary object.

Parameters:
exc The message or exception object.
flags A combination of the following flags:
  • #SOBJ_EXC_STRIP_SOURCE
    Strip the source code information from the object.
  • #SOBJ_EXC_STRIP_ARGS
    Strip all message/exception arguments from the object.
  • #SOBJ_EXC_STRIP_MODULE
    Strip the __module field from the object.
  • #SOBJ_EXC_STRIP_CLASS
    Strip the __class field from the object.
  • #SOBJ_EXC_STRIP_I18N
    Strip the __i18n field from the object.
  • #SOBJ_EXC_STRIP_CN
    Strip the object class name from the object.
  • #SOBJ_EXC_STRIP_ID
    Strip the message/exception ID from the object.
  • #SOBJ_EXC_STRIP_LEVEL
    Strip the message level from the object (for message objects).
  • #SOBJ_EXC_STRIP_TYPE
    Strip the message type from the object (for message objects).
Returns:
A flat reference to the stripped object. If nothing was stripped from the specfied object, then the object is returned as is.

size_t sobj_exc_to_string struct sobj exc,
bool  compact,
char *  buffer,
size_t  buffer_size
 

Create a string representation of an exception object.

It is safe to call this function with an arbitrary object. However, the resulting string may be unusable if the specfied object is not an exception object.

Parameters:
exc The exception object.
compact Flag indicating if a compact text representation should be created.
buffer The buffer receiving the text representation of the exception object. This may be a null-pointer.
buffer_size The size of the supplied buffer.
Returns:
The function returns the length of the string representation (without the terminating null-character).

bool sobj_exc_xcls_match const char *  exc_class,
const char *  xcls
 

Check if the specfied exception class matches the specfied class.

If any of the specfied class string has a module prefix, then the module prefix is ignored.

Parameters:
exc_class The exception class of an exception.
xcls The class to match against.
Return values:
true The exception class exc_class is a equal or a subclass of xcls.
false The exc_class class exc_class is not equal or a subclass of xcls.

size_t sobj_msg_to_string struct sobj msg,
bool  compact,
char *  buffer,
size_t  buffer_size
 

Create a string representation of a message object.

It is safe to call this function with an arbitrary object. However, the resulting string may be unusable if the specfied object is not a message object.

Parameters:
msg The message object.
compact Flag indicating if a compact text representation should be created.
buffer The buffer receiving the text representation of the message object. This may be a null-pointer.
buffer_size The size of the supplied buffer.
Returns:
The function returns the length of the string representation (without the terminating null-character).


Generated on Sat Jul 23 16:07:33 2005 for sobject by  doxygen 1.3.9.1