Data Structures
struct	GncEventData
Files
file	gnc-event.h
	Additional event handling code.
file	qofevent.h
	QOF event handling interface.
Defines
#define	GNC_EVENT_ITEM_ADDED QOF_MAKE_EVENT(QOF_EVENT_BASE+0)
#define	GNC_EVENT_ITEM_REMOVED QOF_MAKE_EVENT(QOF_EVENT_BASE+1)
#define	GNC_EVENT_ITEM_CHANGED QOF_MAKE_EVENT(QOF_EVENT_BASE+2)
#define	QOF_MAKE_EVENT(x) (1<<(x))
	Allow application-specific events to be created.
#define	QOF_EVENT_BASE 8
#define	QOF_EVENT_NONE (0)
	Default events for backwards compatibility.
#define	QOF_EVENT_CREATE QOF_MAKE_EVENT(0)
#define	QOF_EVENT_MODIFY QOF_MAKE_EVENT(1)
#define	QOF_EVENT_DESTROY QOF_MAKE_EVENT(2)
#define	QOF_EVENT_ADD QOF_MAKE_EVENT(3)
#define	QOF_EVENT_REMOVE QOF_MAKE_EVENT(4)
#define	QOF_EVENT__LAST QOF_MAKE_EVENT(QOF_EVENT_BASE-1)
#define	QOF_EVENT_ALL (0xff)
Typedefs
typedef gint	QofEventId
typedef void(*	QofEventHandler )(QofInstance *ent, QofEventId event_type, gpointer handler_data, gpointer event_data)
	Handler invoked when an event is generated.
Functions
const char *	qofeventid_to_string (QofEventId id)
gint	qof_event_register_handler (QofEventHandler handler, gpointer handler_data)
	Register a handler for events.
void	qof_event_unregister_handler (gint handler_id)
	Unregister an event handler.
void	qof_event_gen (QofInstance *entity, QofEventId event_type, gpointer event_data)
	Invoke all registered event handlers using the given arguments.
void	qof_event_suspend (void)
	Suspend all engine events.
void	qof_event_resume (void)

Define Documentation

#define GNC_EVENT_ITEM_ADDED QOF_MAKE_EVENT(QOF_EVENT_BASE+0)

These events are used when a split is added to an account. The event subject is the Account, the Object is the Split.

Definition at line 45 of file gnc-event.h.

#define QOF_EVENT_BASE 8

Allow scope for more defaults in future. Additional event identifiers must be based on this when using QOF_MAKE_EVENT().

Definition at line 57 of file qofevent.h.

#define QOF_EVENT_NONE (0)

Default events for backwards compatibility.

These defaults merely replicate previous behaviour, any process can define their own events.

Note:: events 5, 6, and 7 are "undefined" as of v0.6.3 for future libqof1 or libqof2 usage.

Definition at line 67 of file qofevent.h.

#define QOF_MAKE_EVENT ( x ) (1<<(x))

Allow application-specific events to be created.

Used together with QOF_EVENT_BASE to simplify creation of application events without interfering with any new events added within QOF.

#define APP_EVENT_A QOF_MAKE_EVENT(QOF_EVENT_BASE+0)
#define APP_EVENT_B QOF_MAKE_EVENT(QOF_EVENT_BASE+1)

Definition at line 53 of file qofevent.h.

Typedef Documentation

typedef void(* QofEventHandler)(QofInstance *ent, QofEventId event_type, gpointer handler_data, gpointer event_data)

Handler invoked when an event is generated.

Parameters:

ent,:	Entity generating the event
event_type,:	The id of the event, including additional identifiers and the older defaults.
handler_data,:	data supplied when handler was registered.
event_data,:	data to be supplied when handler is invoked.

Definition at line 84 of file qofevent.h.

typedef gint QofEventId

Define the type of events allowed.

Definition at line 40 of file qofevent.h.

Function Documentation

void qof_event_gen	(	QofInstance *	entity,
		QofEventId	event_type,
		gpointer	event_data
	)

Invoke all registered event handlers using the given arguments.

Certain default events are used by QOF:

QOF_EVENT_DEFAULT_CREATE events should be generated after the object has been created and registered in the engine entity table.
QOF_EVENT_DEFAULT_MODIFY events should be generated whenever any data member or submember (i.e., splits) is changed.
QOF_EVENT_DEFAULT_DESTROY events should be called before the object has been destroyed or removed from the entity table.

Any other events are entirely the concern of the application.

Note:: QofEventHandler routines do NOT support generating events from a GncGUID and QofIdType - you must specify a genuine QofInstance.

Parameters:

entity,:	the entity generating the event
event_type,:	the name of the event.
event_data,:	Data to be passed to the event handler just for this one event. Can be NULL.

Definition at line 236 of file qofevent.c.

{
    if (!entity)
        return;

    if (suspend_counter)
        return;

    qof_event_generate_internal (entity, event_id, event_data);
}

gint qof_event_register_handler	(	QofEventHandler	handler,
		gpointer	handler_data
	)

Register a handler for events.

Parameters:

handler,:	handler to register
handler_data,:	data provided when handler is invoked

Returns:: id identifying handler

Definition at line 72 of file qofevent.c.

{
    HandlerInfo *hi;
    gint handler_id;

    ENTER ("(handler=%p, data=%p)", handler, user_data);

    /* sanity check */
    if (!handler)
    {
        PERR ("no handler specified");
        return 0;
    }

    /* look for a free handler id */
    handler_id = find_next_handler_id();

    /* Found one, add the handler */
    hi = g_new0 (HandlerInfo, 1);

    hi->handler = handler;
    hi->user_data = user_data;
    hi->handler_id = handler_id;

    handlers = g_list_prepend (handlers, hi);
    LEAVE ("(handler=%p, data=%p) handler_id=%d", handler, user_data, handler_id);
    return handler_id;
}

void qof_event_resume ( void )

Resume engine event generation.

Definition at line 155 of file qofevent.c.

{
    if (suspend_counter == 0)
    {
        PERR ("suspend counter underflow");
        return;
    }

    suspend_counter--;
}

void qof_event_suspend ( void )

Suspend all engine events.

This function may be called multiple times. To resume event generation, an equal number of calls to qof_event_resume must be made.

Definition at line 144 of file qofevent.c.

{
    suspend_counter++;

    if (suspend_counter == 0)
    {
        PERR ("suspend counter overflow");
    }
}

void qof_event_unregister_handler ( gint handler_id )

Unregister an event handler.

Parameters:

handler_id,: the id of the handler to unregister

Definition at line 102 of file qofevent.c.

{
    GList *node;

    ENTER ("(handler_id=%d)", handler_id);
    for (node = handlers; node; node = node->next)
    {
        HandlerInfo *hi = node->data;

        if (hi->handler_id != handler_id)
            continue;

        /* Normally, we could actually remove the handler's node from the
           list, but we may be unregistering the event handler as a result
           of a generated event, such as QOF_EVENT_DESTROY.  In that case,
           we're in the middle of walking the GList and it is wrong to
           modify the list. So, instead, we just NULL the handler. */
        if (hi->handler)
            LEAVE ("(handler_id=%d) handler=%p data=%p", handler_id,
                   hi->handler, hi->user_data);

        /* safety -- clear the handler in case we're running events now */
        hi->handler = NULL;

        if (handler_run_level == 0)
        {
            handlers = g_list_remove_link (handlers, node);
            g_list_free_1 (node);
            g_free (hi);
        }
        else
        {
            pending_deletes++;
        }

        return;
    }

    PERR ("no such handler: %d", handler_id);
}

const char* qofeventid_to_string ( QofEventId id )

Convert the given QofEventId (an integer number) to a string that is usable in debugging output.

Definition at line 4 of file gnc-event.c.

{
    switch (id)
    {
    case 0:
        return "NONE";
    case QOF_EVENT_CREATE:
        return "CREATE";
    case QOF_EVENT_MODIFY:
        return "MODIFY";
    case QOF_EVENT_DESTROY:
        return "DESTROY";
    case QOF_EVENT_ADD:
        return "ADD";
    case QOF_EVENT_REMOVE:
        return "REMOVE";

    case GNC_EVENT_ITEM_ADDED:
        return "ITEM_ADDED";
    case GNC_EVENT_ITEM_REMOVED:
        return "ITEM_REMOVED";
    case GNC_EVENT_ITEM_CHANGED:
        return "ITEM_CHANGED";

    default:
        return "<unknown, maybe multiple>";
    }
}

Data Structures

Files

Defines

Typedefs

Functions

Define Documentation

Typedef Documentation

Function Documentation