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_message * | oscap_reporter_message::oscap_reporter_message_new (void) |
struct oscap_reporter_message * | oscap_reporter_message::oscap_reporter_message_new_fill (oscap_reporter_family_t family, oscap_reporter_code_t code, const char *string) |
struct oscap_reporter_message * | oscap_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_message * | oscap_reporter_message::oscap_reporter_message_new_fmt (oscap_reporter_family_t family, oscap_reporter_code_t code, const char *fmt,...) |
struct oscap_reporter_message * | oscap_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_type * | oscap_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_reporter * | oscap_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_reporter * | 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) |
| 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:
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);
- 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
Function porototype for destroying a reporter.
It is intended to be used to release allocated resources and do necessary cleanup.
- Parameters:
-
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
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
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] |
bool oscap_reporter_message_set_string |
( |
struct oscap_reporter_message * |
obj, |
|
|
const char * |
newval | |
|
) |
| | [inherited] |
bool oscap_reporter_message_set_user1str |
( |
struct oscap_reporter_message * |
msg, |
|
|
const char * |
newval | |
|
) |
| | [inherited] |
bool oscap_reporter_message_set_user2str |
( |
struct oscap_reporter_message * |
msg, |
|
|
const char * |
newval | |
|
) |
| | [inherited] |
bool oscap_reporter_message_set_user3str |
( |
struct oscap_reporter_message * |
msg, |
|
|
const char * |
newval | |
|
) |
| | [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
Create a new reporter of given type.
- Parameters:
-
| type | reporter handler set |
| user | reporter-specific user-supplied data |
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). |
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. |
bool oscap_reporter_set_userdata |
( |
struct oscap_reporter * |
obj, |
|
|
const char * |
newval | |
|
) |
| | [inherited] |
Variable Documentation
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.