QOF  0.7.5
Event: QOF event handlers.

Files

file  qofevent.h
 QOF event handling interface.
 

Macros

#define QOF_MAKE_EVENT(x)   (1<<(x))
 Allow application-specific events to be created. More...
 
#define QOF_EVENT_BASE   8
 

Typedefs

typedef gint QofEventId
 
typedef void(* QofEventHandler )(QofEntity *ent, QofEventId event_type, gpointer handler_data, gpointer event_data)
 Handler invoked when an event is generated. More...
 

Functions

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 (QofEntity *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)
 

Default events for backwards compatibility.

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

Note
events 6, and 7 are "undefined" as of v0.6.3 for future libqof1 or libqof2 usage.
#define QOF_EVENT_NONE   (0)
 
#define QOF_EVENT_CREATE   QOF_MAKE_EVENT(0)
 
#define QOF_EVENT_MODIFY   QOF_MAKE_EVENT(1)
 an entity is about to be modified. More...
 
#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_COMMIT   QOF_MAKE_EVENT(5)
 an entity has been modified. More...
 
#define QOF_EVENT__LAST   QOF_MAKE_EVENT(QOF_EVENT_BASE-1)
 
#define QOF_EVENT_ALL   (0xff)
 

Detailed Description

Macro Definition Documentation

#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_COMMIT   QOF_MAKE_EVENT(5)

an entity has been modified.

Added for QofUndo so that the altered state of an entity can be stored to allow the change to be undone and then redone.

Since
0.7.0

Definition at line 92 of file qofevent.h.

#define QOF_EVENT_CREATE   QOF_MAKE_EVENT(0)

an entity has been created.

Definition at line 71 of file qofevent.h.

#define QOF_EVENT_DESTROY   QOF_MAKE_EVENT(2)

an entity is about to be destroyed.

Definition at line 81 of file qofevent.h.

#define QOF_EVENT_MODIFY   QOF_MAKE_EVENT(1)

an entity is about to be modified.

In addition to previous usage, can used for ::QofUndo so that the original state of an entity can be stored before modification to allow the change to be undone and then redone.

Definition at line 79 of file qofevent.h.

#define QOF_EVENT_NONE   (0)

init value - invalid.

Definition at line 69 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)(QofEntity *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 104 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 ( QofEntity 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 book.
  • 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 book.

    Any other events are entirely the concern of the application.

Note
QofEventHandler routines do NOT support generating events from a GUID and QofIdType - you must specify a genuine QofEntity.
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 292 of file qofevent.c.

293 {
294  if (!entity)
295  return;
296 
297  if (suspend_counter)
298  return;
299 
300  qof_event_generate_internal (entity, event_id, event_data);
301 }
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 108 of file qofevent.c.

109 {
110  HandlerInfo *hi;
111  gint handler_id;
112 
113  ENTER ("(handler=%p, data=%p)", handler, user_data);
114 
115  /* sanity check */
116  if (!handler)
117  {
118  PERR ("no handler specified");
119  return 0;
120  }
121 
122  /* look for a free handler id */
123  handler_id = find_next_handler_id ();
124 
125  /* Found one, add the handler */
126  hi = g_new0 (HandlerInfo, 1);
127 
128  hi->handler = handler;
129  hi->user_data = user_data;
130  hi->handler_id = handler_id;
131 
132  handlers = g_list_prepend (handlers, hi);
133  LEAVE ("(handler=%p, data=%p) handler_id=%d", handler, user_data,
134  handler_id);
135  return handler_id;
136 }
void qof_event_resume ( void  )

Resume engine event generation.

Definition at line 200 of file qofevent.c.

201 {
202  if (suspend_counter == 0)
203  {
204  PERR ("suspend counter underflow");
205  return;
206  }
207 
208  suspend_counter--;
209 }
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 189 of file qofevent.c.

190 {
191  suspend_counter++;
192 
193  if (suspend_counter == 0)
194  {
195  PERR ("suspend counter overflow");
196  }
197 }
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 139 of file qofevent.c.

140 {
141  GList *node;
142 
143  ENTER ("(handler_id=%d)", handler_id);
144  for (node = handlers; node; node = node->next)
145  {
146  HandlerInfo *hi = node->data;
147 
148  if (hi->handler_id != handler_id)
149  continue;
150 
151  /* Normally, we could actually remove the handler's node from the
152  list, but we may be unregistering the event handler as a result
153  of a generated event, such as GNC_EVENT_DESTROY. In that case,
154  we're in the middle of walking the GList and it is wrong to
155  modify the list. So, instead, we just NULL the handler. */
156  if (hi->handler)
157  LEAVE ("(handler_id=%d) handler=%p data=%p", handler_id,
158  hi->handler, hi->user_data);
159 #ifndef QOF_DISABLE_DEPRECATED
160  if (hi->old_handler)
161  LEAVE ("(handler_id=%d) handler=%p data=%p", handler_id,
162  hi->old_handler, hi->user_data);
163 #endif
164 
165  /* safety -- clear the handler in case we're running events now */
166  hi->handler = NULL;
167 #ifndef QOF_DISABLE_DEPRECATED
168  hi->old_handler = NULL;
169 #endif
170 
171  if (handler_run_level == 0)
172  {
173  handlers = g_list_remove_link (handlers, node);
174  g_list_free_1 (node);
175  g_free (hi);
176  }
177  else
178  {
179  pending_deletes++;
180  }
181 
182  return;
183  }
184 
185  PERR ("no such handler: %d", handler_id);
186 }