Audit Emitter Interface Overview

Each emitter configured for use by the Audit Manager, whether well-known or dynamically loaded, will conform to the interface outlined in this section.

A dynamically loaded emitter is loaded by the Audit Manager using the program name specified by an mfaudit.emitter configuration file entry (see mfaudit.emitter.emitter-name).

Once loaded, the GET_AUDIT_EMITTER_FUNCS entry point of the loaded program is invoked to retrieve the address of a function pointer table (see Structures and Typedefs for AUDIT_EMITTER_FUNCS). This table contains pointers for a set of functions responsible for initialising the emitter, deinitialising the emitter, outputting an audit event, and handling notifications of emitter property changes. The example below shows how the main entry point for an emitter would typically be coded to return an AUDIT_EMITTER_FUNCS structure:

....
#include "mfaudit.h"
....
static int audit_emitter_deinit(cobuns32_t flags,
                                void       *emitter_data);

static int audit_emitter_init(cobuns32_t          flags,
                              const cobuns8_t     *emitter_name,
                              AUDIT_EMITTER_EVENT *audit_event,
                              void                **emitter_data);

static void audit_emitter_notify(cobuns32_t notif_type,
                                 void       *notif_buf,
                                 void       *emitter_data);

static int audit_emitter_output(cobuns32_t          flags,
                                AUDIT_EMITTER_EVENT *audit_event,
                                Void                *emitter_data);

static AUDIT_EMITTER_FUNCS audit_emitter_funcs = 
{
    0,                         /* Version of structure format      */
    0,                         /* Reserved for future use          */
    audit_emitter_init,        /* Function to initialise the       */
                               /* emitter                          */
    audit_emitter_deinit,      /* Function to deinitialise the     */
                               /* emitter                          */
    audit_emitter_output,      /* Function to output a trace event */
    audit_emitter_notify,      /* Function to handle notifications */
                               /* of emitter config changes        */
};
....

AUDIT_EMITTER_FUNCS *
GET_AUDIT_EMITTER_FUNCS()
{
    return &audit_emitter_funcs;
}
....

Emitter initialisation (the invocation of the fn_init AUDIT_EMITTER_FUNCS function) is deferred by the Audit Manager until just prior to the first audit event needing to be output. During emitter initialisation the emitter would typically invoke the CBL_AUDIT_EMITTER_PROPERTY_GET API to pick up the value associated with each of its known properties.

Emitter de-initialisation (the invocation of the fn_deinit AUDIT_EMITTER_FUNCS function) occurs during Audit Manager de-initialisation. During emitter de-initialisation the emitter would release any resources it had acquired during any previous invocations.

The outputting of an audit event (the invocation of the fn_output AUDIT_EMITTER_FUNCS function) occurs when a component invokes the CBL_AUDIT_EVENT API (see CBL_AUDIT_EVENT() - Output an Audit Event).

The emitter is notified (the invocation of the fn_notify AUDIT_EMITTER_FUNCS function) of each configuration change (e.g. property value change) that occurs for it after it has been initialised.