include/lttng/trigger/trigger.h

   1 /*
   2  * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_TRIGGER_H
   9 #define LTTNG_TRIGGER_H
  10
  11 struct lttng_action;
  12 struct lttng_condition;
  13 struct lttng_trigger;
  14
  15 #ifdef __cplusplus
  16 extern "C" {
  17 #endif
  18
  19 enum lttng_register_trigger_status {
  20         LTTNG_REGISTER_TRIGGER_STATUS_OK = 0,
  21         LTTNG_REGISTER_TRIGGER_STATUS_INVALID = -1,
  22 };
  23
  24 /*
  25  * Create a trigger object associating a condition and an action.
  26  *
  27  * A trigger associates a condition and an action to take whenever the
  28  * condition evaluates to true. Such actions can, for example, consist
  29  * in the emission of a notification to clients listening through
  30  * notification channels.
  31  *
  32  * The caller retains the ownership of both the condition and action
  33  * and both must be kept alive for the lifetime of the trigger object.
  34  *
  35  * A trigger must be registered in order to become activate and can
  36  * be destroyed after its registration.
  37  *
  38  * Returns a trigger object on success, NULL on error.
  39  * Trigger objects must be destroyed using the lttng_trigger_destroy()
  40  * function.
  41  */
  42 extern struct lttng_trigger *lttng_trigger_create(
  43                 struct lttng_condition *condition, struct lttng_action *action);
  44
  45 /*
  46  * Get the condition of a trigger.
  47  *
  48  * The caller acquires no ownership of the returned condition.
  49  *
  50  * Returns a condition on success, NULL on error.
  51  */
  52 extern struct lttng_condition *lttng_trigger_get_condition(
  53                 struct lttng_trigger *trigger);
  54
  55 /*
  56  * Get the action of a trigger.
  57  *
  58  * The caller acquires no ownership of the returned action.
  59  *
  60  * Returns an action on success, NULL on error.
  61  */
  62 extern struct lttng_action *lttng_trigger_get_action(
  63                 struct lttng_trigger *trigger);
  64
  65 /*
  66  * Destroy (frees) a trigger object.
  67  */
  68 extern void lttng_trigger_destroy(struct lttng_trigger *trigger);
  69
  70 /*
  71  * Register a trigger to the session daemon.
  72  *
  73  * The trigger can be destroyed after this call.
  74  *
  75  * Return 0 on success, a negative LTTng error code on error.
  76  */
  77 extern int lttng_register_trigger(struct lttng_trigger *trigger);
  78
  79 /*
  80  * Unregister a trigger from the session daemon.
  81  *
  82  * The trigger can be destroyed after this call.
  83  *
  84  * Return 0 on success, a negative LTTng error code on error.
  85  */
  86 extern int lttng_unregister_trigger(struct lttng_trigger *trigger);
  87
  88 #ifdef __cplusplus
  89 }
  90 #endif
  91
  92 #endif /* LTTNG_TRIGGER_H */