Event: QOF event handlers.
[Query Object Framework]


Files

file  qofevent.h
 QOF event handling interface.

Defines

#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 )(QofEntity *ent, QofEventId event_type, gpointer handler_data, gpointer event_data)
 Handler invoked when an event is generated.

Functions

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 (QofEntity *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 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  )     (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 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 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 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 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 287 of file qofevent.c.

00288 {
00289   if (!entity)
00290     return;
00291 
00292   if (suspend_counter)
00293     return;
00294 
00295   qof_event_generate_internal (entity, event_id, event_data);
00296 }

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 106 of file qofevent.c.

00107 {
00108   HandlerInfo *hi;
00109   gint handler_id;
00110 
00111   ENTER ("(handler=%p, data=%p)", handler, user_data);
00112 
00113   /* sanity check */
00114   if (!handler)
00115   {
00116     PERR ("no handler specified");
00117     return 0;
00118   }
00119 
00120   /* look for a free handler id */
00121   handler_id = find_next_handler_id();
00122 
00123   /* Found one, add the handler */
00124   hi = g_new0 (HandlerInfo, 1);
00125 
00126   hi->handler = handler;
00127   hi->user_data = user_data;
00128   hi->handler_id = handler_id;
00129 
00130   handlers = g_list_prepend (handlers, hi);
00131   LEAVE ("(handler=%p, data=%p) handler_id=%d", handler, user_data, handler_id);
00132   return handler_id;
00133 }

void qof_event_resume void   ) 
 

Resume engine event generation.

Definition at line 194 of file qofevent.c.

00195 {
00196   if (suspend_counter == 0)
00197   {
00198     PERR ("suspend counter underflow");
00199     return;
00200   }
00201 
00202   suspend_counter--;
00203 }

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 gnc_engine_resume_events must be made.

Definition at line 183 of file qofevent.c.

00184 {
00185   suspend_counter++;
00186 
00187   if (suspend_counter == 0)
00188   {
00189     PERR ("suspend counter overflow");
00190   }
00191 }

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 136 of file qofevent.c.

00137 {
00138   GList *node;
00139 
00140   ENTER ("(handler_id=%d)", handler_id);
00141   for (node = handlers; node; node = node->next)
00142   {
00143     HandlerInfo *hi = node->data;
00144 
00145     if (hi->handler_id != handler_id)
00146       continue;
00147 
00148     /* Normally, we could actually remove the handler's node from the
00149        list, but we may be unregistering the event handler as a result
00150        of a generated event, such as GNC_EVENT_DESTROY.  In that case,
00151        we're in the middle of walking the GList and it is wrong to
00152        modify the list. So, instead, we just NULL the handler. */ 
00153     if(hi->handler) 
00154     LEAVE ("(handler_id=%d) handler=%p data=%p", handler_id,
00155            hi->handler, hi->user_data);
00156 #ifndef QOF_DISABLE_DEPRECATED
00157     if(hi->old_handler) 
00158         LEAVE ("(handler_id=%d) handler=%p data=%p", handler_id,
00159            hi->old_handler, hi->user_data);
00160 #endif
00161 
00162     /* safety -- clear the handler in case we're running events now */
00163     hi->handler = NULL;
00164 #ifndef QOF_DISABLE_DEPRECATED
00165     hi->old_handler = NULL;
00166 #endif
00167 
00168     if (handler_run_level == 0) {
00169       handlers = g_list_remove_link (handlers, node);
00170       g_list_free_1 (node);
00171       g_free (hi);
00172     } else {
00173       pending_deletes++;
00174     }
00175 
00176     return;
00177   }
00178 
00179   PERR ("no such handler: %d", handler_id);
00180 }


Generated on Fri May 12 17:57:22 2006 for QOF by  doxygen 1.4.4