# Event Hooks

struct WpEventHook

  The event hook is a structure that describes some executable action that an event dispatcher will run when a matching event has been received.

struct _WpEventHookClass

  Public Members

  GObjectClass parent_class
  gboolean(*) runs_for_event (WpEventHook *self, WpEvent *event)
  void(*) run (WpEventHook *self, WpEvent *event, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer callback_data)
  gboolean(*) finish (WpEventHook *self, GAsyncResult *res, GError **error)
  GPtrArray *(*) get_matching_event_types (WpEventHook *self)

struct WpInterestEventHook

  An event hook that declares interest in specific events. This subclass implements the WpEventHook.runs_for_event() vmethod and returns TRUE from that method if the given event has properties that match one of the declared interests.

struct _WpInterestEventHookClass

  Public Members

  WpEventHookClass parent_class

struct WpSimpleEventHook

  An event hook that runs a GClosure, synchronously.

struct WpAsyncEventHook

  An event hook that runs a WpTransition, implemented with closures.

const gchar *wp_event_hook_get_name(WpEventHook *self)

  Returns the name of the hook.

  Parameters:

    - self -- the event hook

  Returns:

    the event hook name

const gchar *const *wp_event_hook_get_runs_before_hooks(WpEventHook *self)

  Returns the names of the hooks that should run after this hook, or in other words, this hook should run before them.

  Parameters:

    - self -- the event hook

  Returns:

    (array zero-terminated=1)(element-type utf8)(transfer none): a NULL-terminated array of hook names

const gchar *const *wp_event_hook_get_runs_after_hooks(WpEventHook *self)

  Returns the names of the hooks that should run before this hook, or in other words, this hook should run after them.

  Parameters:

    - self -- the event hook

  Returns:

    (array zero-terminated=1)(element-type utf8)(transfer none): a NULL-terminated array of hook names

gboolean wp_event_hook_runs_for_event(WpEventHook *self, WpEvent *event)

  Checks if the hook should be executed for a given event.

  Parameters:

    - self -- the event hook

    - event -- the event

  Returns:

    TRUE if the hook should be executed for the given event, FALSE otherwise

void wp_event_hook_run(WpEventHook *self, WpEvent *event, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer callback_data)

  Runs the hook on the given event.

  Parameters:

    - self -- the event hook

    - event -- the event that triggered the hook

    - cancellable -- (nullable): a GCancellable to cancel the async operation

    - callback -- (scope async)(closure callback_data): a callback to fire after execution of the hook has completed

    - callback_data -- data for the callback

GPtrArray *wp_event_hook_get_matching_event_types(WpEventHook *self)

  Gets all the matching event types for this hook if any.

  Since

    0.5.13

  Parameters:

    - self -- the event hook

  Returns:

    (element-type gchar*) (transfer full) (nullable): the matching event types for this hook if any.

gboolean wp_event_hook_finish(WpEventHook *self, GAsyncResult *res, GError **error)

  Finishes the async operation that was started by wp_event_hook_run().

  Parameters:

    - self -- the event hook

    - res -- the async operation result

    - error -- (out) (optional): the error of the operation, if any

  Returns:

    FALSE if there was an error, TRUE otherwise

void wp_interest_event_hook_add_interest(WpInterestEventHook *self, ...)

  Equivalent to:

      WpObjectInterest *i = wp_object_interest_new (WP_TYPE_EVENT, ...);
      wp_interest_event_hook_add_interest_full (self, i);

  The constraints specified in the variable arguments must follow the rules documented in wp_object_interest_new().

  Parameters:

    - self -- the event hook

    - ... -- a list of constraints, terminated by NULL

void wp_interest_event_hook_add_interest_full(WpInterestEventHook *self, WpObjectInterest *interest)

  Declares interest on events. The interest must be constructed to match WP_TYPE_EVENT objects and it is going to be matched against the WpEvent's properties.

  Parameters:

    - self -- the event hook

    - interest -- (transfer full): the event interest

WpEventHook *wp_simple_event_hook_new(const gchar *name, const gchar *before[], const gchar *after[], GClosure *closure)

  Constructs a new simple event hook.

  Parameters:

    - name -- the name of the hook

    - before -- (array zero-terminated=1)(element-type utf8)(transfer none)(nullable): an array of hook names that should run after this hook

    - after -- (array zero-terminated=1)(element-type utf8)(transfer none)(nullable): an array of hook names that should run before this hook

    - closure -- the closure to invoke when the hook is executed; the closure should accept two parameters: the event dispatcher and the event, returning nothing

  Returns:

    a new simple event hook

WpEventHook *wp_async_event_hook_new(const gchar *name, const gchar *before[], const gchar *after[], GClosure *get_next_step, GClosure *execute_step)

  Constructs a new async event hook.

  Parameters:

    - name -- the name of the hook

    - before -- (array zero-terminated=1)(element-type utf8)(transfer none)(nullable): an array of hook names that should run after this hook

    - after -- (array zero-terminated=1)(element-type utf8)(transfer none)(nullable): an array of hook names that should run before this hook

    - get_next_step -- the closure to invoke to get the next step

    - execute_step -- the closure to invoke to execute the step

  Returns:

    a new async event hook

WP_TYPE_INTEREST_EVENT_HOOK (wp_interest_event_hook_get_type ())

  The WpInterestEventHook GType.

WP_TYPE_SIMPLE_EVENT_HOOK (wp_simple_event_hook_get_type ())

  The WpSimpleEventHook GType.

WP_TYPE_ASYNC_EVENT_HOOK (wp_async_event_hook_get_type ())

  The WpAsyncEventHook GType.