GnuCash  5.6-150-g038405b370+
Files | Data Structures | Macros | Typedefs | Functions
Event: QOF event handlers.

Files

file  gnc-event.h
 Additional event handling code.
 
file  qofevent.h
 QOF event handling interface.
 

Data Structures

struct  GncEventData
 

Macros

#define GNC_EVENT_ITEM_ADDED   QOF_MAKE_EVENT(QOF_EVENT_BASE+0)
 These events are used when a split is added to an account. More...
 
#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. More...
 
#define QOF_EVENT_BASE   8
 Allow scope for more defaults in future. More...
 
#define QOF_EVENT_NONE   (0)
 Default events for backwards compatibility. More...
 
#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
 Define the type of events allowed. More...
 
typedef void(* QofEventHandler) (QofInstance *ent, QofEventId event_type, gpointer handler_data, gpointer event_data)
 Handler invoked when an event is generated. More...
 

Functions

const char * qofeventid_to_string (QofEventId id)
 Convert the given QofEventId (an integer number) to a string that is usable in debugging output. More...
 
gint qof_event_register_handler (QofEventHandler handler, gpointer handler_data)
 Register a handler for events. More...
 
void qof_event_unregister_handler (gint handler_id)
 Unregister an event handler. More...
 
void qof_event_gen (QofInstance *entity, QofEventId event_type, gpointer event_data)
 Invoke all registered event handlers using the given arguments. More...
 
void qof_event_suspend (void)
 Suspend all engine events. More...
 
void qof_event_resume (void)
 Resume engine event generation. More...
 

Detailed Description

Macro Definition Documentation

◆ GNC_EVENT_ITEM_ADDED

#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.

◆ QOF_EVENT_BASE

#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 62 of file qofevent.h.

◆ QOF_EVENT_NONE

#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 72 of file qofevent.h.

◆ QOF_MAKE_EVENT

#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 58 of file qofevent.h.

Typedef Documentation

◆ QofEventHandler

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

Handler invoked when an event is generated.

Parameters
entEntity generating the event
event_typeThe id of the event, including additional identifiers and the older defaults.
handler_datadata supplied when handler was registered.
event_datadata to be supplied when handler is invoked.

Definition at line 89 of file qofevent.h.

◆ QofEventId

typedef gint QofEventId

Define the type of events allowed.

Definition at line 45 of file qofevent.h.

Function Documentation

◆ qof_event_gen()

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
    entitythe entity generating the event
    event_typethe name of the event.
    event_dataData to be passed to the event handler just for this one event. Can be NULL.

Definition at line 231 of file qofevent.cpp.

232 {
233  if (!entity)
234  return;
235 
236  if (suspend_counter)
237  return;
238 
239  qof_event_generate_internal (entity, event_id, event_data);
240 }

◆ qof_event_register_handler()

gint qof_event_register_handler ( QofEventHandler  handler,
gpointer  handler_data 
)

Register a handler for events.

Parameters
handlerhandler to register
handler_datadata provided when handler is invoked
Returns
id identifying handler

Definition at line 73 of file qofevent.cpp.

74 {
75  HandlerInfo *hi;
76  gint handler_id;
77 
78  ENTER ("(handler=%p, data=%p)", handler, user_data);
79 
80  /* sanity check */
81  if (!handler)
82  {
83  PERR ("no handler specified");
84  return 0;
85  }
86 
87  /* look for a free handler id */
88  handler_id = find_next_handler_id();
89 
90  /* Found one, add the handler */
91  hi = g_new0 (HandlerInfo, 1);
92 
93  hi->handler = handler;
94  hi->user_data = user_data;
95  hi->handler_id = handler_id;
96 
97  handlers = g_list_prepend (handlers, hi);
98  LEAVE ("(handler=%p, data=%p) handler_id=%d", handler, user_data, handler_id);
99  return handler_id;
100 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:282

◆ qof_event_resume()

void qof_event_resume ( void  )

Resume engine event generation.

Definition at line 156 of file qofevent.cpp.

157 {
158  if (suspend_counter == 0)
159  {
160  PERR ("suspend counter underflow");
161  return;
162  }
163 
164  suspend_counter--;
165 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244

◆ qof_event_suspend()

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 145 of file qofevent.cpp.

146 {
147  suspend_counter++;
148 
149  if (suspend_counter == 0)
150  {
151  PERR ("suspend counter overflow");
152  }
153 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244

◆ qof_event_unregister_handler()

void qof_event_unregister_handler ( gint  handler_id)

Unregister an event handler.

Parameters
handler_idthe id of the handler to unregister

Definition at line 103 of file qofevent.cpp.

104 {
105  GList *node;
106 
107  ENTER ("(handler_id=%d)", handler_id);
108  for (node = handlers; node; node = node->next)
109  {
110  HandlerInfo *hi = static_cast<HandlerInfo*>(node->data);
111 
112  if (hi->handler_id != handler_id)
113  continue;
114 
115  /* Normally, we could actually remove the handler's node from the
116  list, but we may be unregistering the event handler as a result
117  of a generated event, such as QOF_EVENT_DESTROY. In that case,
118  we're in the middle of walking the GList and it is wrong to
119  modify the list. So, instead, we just NULL the handler. */
120  if (hi->handler)
121  LEAVE ("(handler_id=%d) handler=%p data=%p", handler_id,
122  hi->handler, hi->user_data);
123 
124  /* safety -- clear the handler in case we're running events now */
125  hi->handler = NULL;
126 
127  if (handler_run_level == 0)
128  {
129  handlers = g_list_remove_link (handlers, node);
130  g_list_free_1 (node);
131  g_free (hi);
132  }
133  else
134  {
135  pending_deletes++;
136  }
137 
138  return;
139  }
140 
141  PERR ("no such handler: %d", handler_id);
142 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:282

◆ qofeventid_to_string()

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 24 of file gnc-event.c.

25 {
26  switch (id)
27  {
28  case 0:
29  return "NONE";
30  case QOF_EVENT_CREATE:
31  return "CREATE";
32  case QOF_EVENT_MODIFY:
33  return "MODIFY";
34  case QOF_EVENT_DESTROY:
35  return "DESTROY";
36  case QOF_EVENT_ADD:
37  return "ADD";
38  case QOF_EVENT_REMOVE:
39  return "REMOVE";
40 
42  return "ITEM_ADDED";
43  case GNC_EVENT_ITEM_REMOVED:
44  return "ITEM_REMOVED";
45  case GNC_EVENT_ITEM_CHANGED:
46  return "ITEM_CHANGED";
47 
48  default:
49  return "<unknown, maybe multiple>";
50  }
51 }
#define GNC_EVENT_ITEM_ADDED
These events are used when a split is added to an account.
Definition: gnc-event.h:45