Reporters
[COMMON]

Reporting mechanism. More...

Data Structures

struct  oscap_reporter_message
 Represents a message to be reported. More...
struct  oscap_reporter_type
 Reporter type. More...
struct  oscap_reporter
 Reporter instance. More...

Defines

#define OSCAP_REPORTER_ALL   0, OSCAP_REPORTER_CODE_MAX
 Macro to match whole code range.
#define XREPORTER(r)   ((struct oscap_reporter*) r)
 Reporter cast.

Typedefs

typedef enum oscap_reporter_family oscap_reporter_family_t
 Reporter message family.
typedef unsigned int oscap_reporter_code_t
 Reporter message code type.
typedef bool(* oscap_reporter_init_func )(void **user)
 Function porototype for reporter initialisation.
typedef void(* oscap_reporter_report_func )(const struct oscap_reporter_message *msg, void *user)
 Function porototype for reporting a message.
typedef void(* oscap_reporter_destroy_func )(void *user)
 Function porototype for destroying a reporter.

Enumerations

enum  oscap_reporter_family { OSCAP_REPORTER_FAMILY_XML = 1, OSCAP_REPORTER_FAMILY_USER_START = 1024 }
 

Reporter message family.


Functions

struct oscap_reporter_messageoscap_reporter_message::oscap_reporter_message_new (void)
struct oscap_reporter_messageoscap_reporter_message::oscap_reporter_message_new_fill (oscap_reporter_family_t family, oscap_reporter_code_t code, const char *string)
struct oscap_reporter_messageoscap_reporter_message::oscap_reporter_message_new_arg (oscap_reporter_family_t family, oscap_reporter_code_t code, const char *fmt, va_list ap)
struct oscap_reporter_messageoscap_reporter_message::oscap_reporter_message_new_fmt (oscap_reporter_family_t family, oscap_reporter_code_t code, const char *fmt,...)
struct oscap_reporter_messageoscap_reporter_message::oscap_reporter_message_clone (const struct oscap_reporter_message *msg)
oscap_reporter_family_t oscap_reporter_message::oscap_reporter_message_get_family (const struct oscap_reporter_message *item)
oscap_reporter_code_t oscap_reporter_message::oscap_reporter_message_get_code (const struct oscap_reporter_message *item)
const char * oscap_reporter_message::oscap_reporter_message_get_string (const struct oscap_reporter_message *item)
const char * oscap_reporter_message::oscap_reporter_message_get_user1str (const struct oscap_reporter_message *msg)
int oscap_reporter_message::oscap_reporter_message_get_user1num (const struct oscap_reporter_message *msg)
void * oscap_reporter_message::oscap_reporter_message_get_user1ptr (const struct oscap_reporter_message *msg)
const char * oscap_reporter_message::oscap_reporter_message_get_user2str (const struct oscap_reporter_message *msg)
int oscap_reporter_message::oscap_reporter_message_get_user2num (const struct oscap_reporter_message *msg)
void * oscap_reporter_message::oscap_reporter_message_get_user2ptr (const struct oscap_reporter_message *msg)
const char * oscap_reporter_message::oscap_reporter_message_get_user3str (const struct oscap_reporter_message *msg)
int oscap_reporter_message::oscap_reporter_message_get_user3num (const struct oscap_reporter_message *msg)
void * oscap_reporter_message::oscap_reporter_message_get_user3ptr (const struct oscap_reporter_message *msg)
struct oscap_reporter_typeoscap_reporter_type::oscap_reporter_type_new (oscap_reporter_init_func init, oscap_reporter_report_func report, oscap_reporter_destroy_func destroy)
 Create a new reporter type.
void oscap_reporter_type::oscap_reporter_type_free (struct oscap_reporter_type *reptype)
struct oscap_reporteroscap_reporter::oscap_reporter_new (const struct oscap_reporter_type *type, void *user)
 Create a new reporter of given type.
void oscap_reporter::oscap_reporter_free (struct oscap_reporter *reporter)
void oscap_reporter::oscap_reporter_dispatch (struct oscap_reporter *reporter, const struct oscap_reporter_message *msg)
 Forward a message to a reporter.
void oscap_reporter::oscap_reporter_report (struct oscap_reporter *reporter, struct oscap_reporter_message *msg)
 Do report.
void oscap_reporter::oscap_reporter_report_fmt (struct oscap_reporter *reporter, oscap_reporter_family_t family, oscap_reporter_code_t code, const char *fmt,...)
const char * oscap_reporter::oscap_reporter_get_userdata (const struct oscap_reporter *item)
bool oscap_reporter::oscap_reporter_set_userdata (struct oscap_reporter *obj, const char *newval)
void oscap_reporter_message::oscap_reporter_message_free (struct oscap_reporter_message *msg)
bool oscap_reporter_message::oscap_reporter_message_set_family (struct oscap_reporter_message *obj, oscap_reporter_family_t newval)
bool oscap_reporter_message::oscap_reporter_message_set_code (struct oscap_reporter_message *obj, oscap_reporter_code_t newval)
bool oscap_reporter_message::oscap_reporter_message_set_string (struct oscap_reporter_message *obj, const char *newval)
bool oscap_reporter_message::oscap_reporter_message_set_user1str (struct oscap_reporter_message *msg, const char *newval)
bool oscap_reporter_message::oscap_reporter_message_set_user1num (struct oscap_reporter_message *msg, int newval)
bool oscap_reporter_message::oscap_reporter_message_set_user1ptr (struct oscap_reporter_message *msg, void *newval)
bool oscap_reporter_message::oscap_reporter_message_set_user2str (struct oscap_reporter_message *msg, const char *newval)
bool oscap_reporter_message::oscap_reporter_message_set_user2num (struct oscap_reporter_message *msg, int newval)
bool oscap_reporter_message::oscap_reporter_message_set_user2ptr (struct oscap_reporter_message *msg, void *newval)
bool oscap_reporter_message::oscap_reporter_message_set_user3str (struct oscap_reporter_message *msg, const char *newval)
bool oscap_reporter_message::oscap_reporter_message_set_user3num (struct oscap_reporter_message *msg, int newval)
bool oscap_reporter_message::oscap_reporter_message_set_user3ptr (struct oscap_reporter_message *msg, void *newval)
void oscap_reporter::oscap_reporter_report_xml (struct oscap_reporter *reporter, xmlErrorPtr error)
 Feed a XML error to the reporter.
void oscap_reporter::oscap_reporter_report_libc (struct oscap_reporter *reporter)
 Report standard C error (errno based) to a reporter.

Variables

const oscap_reporter_code_t OSCAP_REPORTER_CODE_MAX
 Maximum code.

Standard reporters



struct oscap_reporter_type oscap_reporter::OSCAP_REPORTER_STDOUT
 Standard output reporter.
struct oscap_reporter_type oscap_reporter::OSCAP_REPORTER_MULTI
 Reporter to multiple other reporters.
void oscap_reporter::oscap_reporter_multi_add_reporter (struct oscap_reporter *multi, struct oscap_reporter *reporter)
 Add a subreporter to given multireporter.
struct oscap_reporteroscap_reporter::oscap_reporter_new_filter (struct oscap_reporter *pos_child, struct oscap_reporter *neg_child, oscap_reporter_family_t family, oscap_reporter_code_t min_code, oscap_reporter_code_t max_code)
 Create a new filtering reporter.

Detailed Description

Reporting mechanism.

Can be used for e.g. returning individual errors during a SCAP document validation, reporting progress of some processing etc.

Aim of reporters is to separate message content from their final representation and provide reasonable modularity. You can have reporters that print messages, log messages to a file, update a GUI and more.

Reporter types

Reporter types are represented by oscap_reporter_type structure.

Simple printing messages to the standard is provided by the library. There are also special reporters that forward messaged to more than one other reporter (OSCAP_REPORTER_MULTI) or filter messages based on message code and family and forward them to one or other reporter (see oscap_reporter_new_filter()).

oscap_reporter_type_new() can be used to define your own reporter type. It consists of three callbacks: init, report, and destroy.

Handling messages

Messages (oscap_reporter_message) are organized in families to avoid code clashes. Message code distiguishes different types of messages. In addition to that, messages cointain human-readable string description of the event.

It is also possible to attach up to three machine-readable items to the message. These are domain-specific for given family or even code and shall be well-documented so they can be handeled properly.

One function that makes use of reporters is oscap_validate_xml(). It takes XML file name, schema file name and a reporter as a last parameter. To print encountered defects to standard output, you would use it as follows:

 struct oscap_reporter *reporter = oscap_reporter_new(&OSCAP_REPORTER_STDOUT, NULL);
 oscap_validate_xml(xmlfilename, schemafilename, reporter);
 oscap_reporter_free(reporter);

With special reporters you can for example write all the messages to a file, validation-related messages to standard output and other messages (e.g. xinclude substitution failure, schema errors) to standard error, creating a hierarchy of reporters. Note you release only the top-level reporter. It is assumed that my_*_reporter_type are previously created by the user.

 struct oscap_reporter *reporter = oscap_reporter_new(&OSCAP_REPORTER_MULTI, NULL);
 oscap_reporter_multi_add_reporter(reporter, oscap_reporter_new(my_file_reporter_type, "validation.log"));
 oscap_reporter_multi_add_reporter(reporter,
     oscap_reporter_new_filter(
         oscap_reporter_new(&OSCAP_REPORTER_STDOUT, NULL),
         oscap_reporter_new(my_stderr_reporter_type, NULL),
         OSCAP_REPORTER_FAMILY_XML, XML_SCHEMAV_NOROOT, XML_SCHEMAV_MISC
     )
 );
 oscap_validate_xml(xmlfilename, schemafilename, reporter);
 oscap_reporter_free(reporter);
inline_dotgraph_1.dot
Sending messages

In order to send a message from a function, you have to create the message (oscap_reporter_message) and send it. To send a message use oscap_reporter_report(). To forward a message from one reporter to another (used in the special reporters) use oscap_reporter_dispatch().

There are also shortcut functions, like oscap_reporter_report_fmt(), that allows you to create and sen a message in one step.


Typedef Documentation

typedef void(* oscap_reporter_destroy_func)(void *user)

Function porototype for destroying a reporter.

It is intended to be used to release allocated resources and do necessary cleanup.

Parameters:
user User supplied data.
typedef bool(* oscap_reporter_init_func)(void **user)

Function porototype for reporter initialisation.

The user argument is a pointer to the pointer user passed to the oscap_reporter_new() call. You can modify it, if you want/need to.

The function is upposed to return true on success and false on failure. In case of failure oscap_reporter_new() will return NULL.

Parameters:
user pointer to user-supplied data
Returns:
false on failure, true on success
typedef void(* oscap_reporter_report_func)(const struct oscap_reporter_message *msg, void *user)

Function porototype for reporting a message.

This callback gets called for every reported message.

Parameters:
msg Message to be processed by the reporter.
user User supplied data.

Function Documentation

void oscap_reporter_dispatch ( struct oscap_reporter reporter,
const struct oscap_reporter_message msg 
) [inherited]

Forward a message to a reporter.

Parameters:
msg message to be sent / forwarded
void oscap_reporter_free ( struct oscap_reporter reporter  )  [inherited]
const char * oscap_reporter_get_userdata ( const struct oscap_reporter item  )  [inherited]
struct oscap_reporter_message * oscap_reporter_message_clone ( const struct oscap_reporter_message msg  )  [read, inherited]
void oscap_reporter_message_free ( struct oscap_reporter_message msg  )  [inherited]
oscap_reporter_code_t oscap_reporter_message_get_code ( const struct oscap_reporter_message item  )  [inherited]
oscap_reporter_family_t oscap_reporter_message_get_family ( const struct oscap_reporter_message item  )  [inherited]
const char * oscap_reporter_message_get_string ( const struct oscap_reporter_message item  )  [inherited]
int oscap_reporter_message_get_user1num ( const struct oscap_reporter_message msg  )  [inherited]
void * oscap_reporter_message_get_user1ptr ( const struct oscap_reporter_message msg  )  [inherited]
const char * oscap_reporter_message_get_user1str ( const struct oscap_reporter_message msg  )  [inherited]
int oscap_reporter_message_get_user2num ( const struct oscap_reporter_message msg  )  [inherited]
void * oscap_reporter_message_get_user2ptr ( const struct oscap_reporter_message msg  )  [inherited]
const char * oscap_reporter_message_get_user2str ( const struct oscap_reporter_message msg  )  [inherited]
int oscap_reporter_message_get_user3num ( const struct oscap_reporter_message msg  )  [inherited]
void * oscap_reporter_message_get_user3ptr ( const struct oscap_reporter_message msg  )  [inherited]
const char * oscap_reporter_message_get_user3str ( const struct oscap_reporter_message msg  )  [inherited]
struct oscap_reporter_message * oscap_reporter_message_new ( void   )  [read, inherited]
struct oscap_reporter_message * oscap_reporter_message_new_arg ( oscap_reporter_family_t  family,
oscap_reporter_code_t  code,
const char *  fmt,
va_list  ap 
) [read, inherited]
struct oscap_reporter_message * oscap_reporter_message_new_fill ( oscap_reporter_family_t  family,
oscap_reporter_code_t  code,
const char *  string 
) [read, inherited]
struct oscap_reporter_message * oscap_reporter_message_new_fmt ( oscap_reporter_family_t  family,
oscap_reporter_code_t  code,
const char *  fmt,
  ... 
) [read, inherited]
bool oscap_reporter_message_set_code ( struct oscap_reporter_message obj,
oscap_reporter_code_t  newval 
) [inherited]
bool oscap_reporter_message_set_family ( struct oscap_reporter_message obj,
oscap_reporter_family_t  newval 
) [inherited]
bool oscap_reporter_message_set_string ( struct oscap_reporter_message obj,
const char *  newval 
) [inherited]
bool oscap_reporter_message_set_user1num ( struct oscap_reporter_message msg,
int  newval 
) [inherited]
bool oscap_reporter_message_set_user1ptr ( struct oscap_reporter_message msg,
void *  newval 
) [inherited]
bool oscap_reporter_message_set_user1str ( struct oscap_reporter_message msg,
const char *  newval 
) [inherited]
bool oscap_reporter_message_set_user2num ( struct oscap_reporter_message msg,
int  newval 
) [inherited]
bool oscap_reporter_message_set_user2ptr ( struct oscap_reporter_message msg,
void *  newval 
) [inherited]
bool oscap_reporter_message_set_user2str ( struct oscap_reporter_message msg,
const char *  newval 
) [inherited]
bool oscap_reporter_message_set_user3num ( struct oscap_reporter_message msg,
int  newval 
) [inherited]
bool oscap_reporter_message_set_user3ptr ( struct oscap_reporter_message msg,
void *  newval 
) [inherited]
bool oscap_reporter_message_set_user3str ( struct oscap_reporter_message msg,
const char *  newval 
) [inherited]
void oscap_reporter_multi_add_reporter ( struct oscap_reporter multi,
struct oscap_reporter reporter 
) [related, inherited]

Add a subreporter to given multireporter.

It is users responsibility to ensure that reporter type of the first param is OSCAP_REPORTER_MULTI.

See also:
OSCAP_REPORTER_MULTI
struct oscap_reporter * oscap_reporter_new ( const struct oscap_reporter_type type,
void *  user 
) [read, inherited]

Create a new reporter of given type.

Parameters:
type reporter handler set
user reporter-specific user-supplied data
struct oscap_reporter * oscap_reporter_new_filter ( struct oscap_reporter pos_child,
struct oscap_reporter neg_child,
oscap_reporter_family_t  family,
oscap_reporter_code_t  min_code,
oscap_reporter_code_t  max_code 
) [related, inherited]

Create a new filtering reporter.

Messages will be forwarded to the pos_child reporter if they match given family and code range and to neg_child if they do not. Either of these reporters can be NULL. The child reporters will be freed with filter. If you want to match all error codes, you can use OSCAP_REPORTER_ALL instead of two last params.

Parameters:
pos_child Reporter to forward messages that pass filter criteria.
neg_child Reporter to forward messages that do NOT pass filter criteria.
family Error family to let pass through the filter.
min_code Minimum error code number to match (inclusive).
max_code Maximum error code number to match (inclusive).
void oscap_reporter_report ( struct oscap_reporter reporter,
struct oscap_reporter_message msg 
) [inherited]

Do report.

This function does nothing if reporter is null. The message gets freed afterwards.

Parameters:
reporter Reporter to use.
msg Message to send. Will be freed after processing by the reporter.
void oscap_reporter_report_fmt ( struct oscap_reporter reporter,
oscap_reporter_family_t  family,
oscap_reporter_code_t  code,
const char *  fmt,
  ... 
) [inherited]
bool oscap_reporter_set_userdata ( struct oscap_reporter obj,
const char *  newval 
) [inherited]
void oscap_reporter_type_free ( struct oscap_reporter_type reptype  )  [inherited]
struct oscap_reporter_type * oscap_reporter_type_new ( oscap_reporter_init_func  init,
oscap_reporter_report_func  report,
oscap_reporter_destroy_func  destroy 
) [read, inherited]

Create a new reporter type.

Parameters:
init function called upon initialisation with a pointer to user supplied data
report reporting function, that is called for each reported message
destroy reporter cleanup function
See also:
oscap_reporter_init_func oscap_reporter_report_func oscap_reporter_destroy_func

Variable Documentation

struct oscap_reporter_type OSCAP_REPORTER_MULTI [related, inherited]

Reporter to multiple other reporters.

Use oscap_reporter_multi_add_reporter() to register reporters. Any message handled by this reporter will be forwarded to all the registered subreporters. The subreporters will be destroyed with the multireporter. No user data allowed.

See also:
oscap_reporter_multi_add_reporter
struct oscap_reporter_type OSCAP_REPORTER_STDOUT [related, inherited]

Standard output reporter.

This reporter simply prints messages to the standard output. If user data is supplied, it shall be a string that will be printed as a message prefix.


Generated on 30 Jun 2010 for Open SCAP Library by  doxygen 1.6.1