include/lttng/trigger/trigger.h

   1 /*
   2  * Copyright (C) 2017 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * This library is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU Lesser General Public License, version 2.1 only,
   6  * as published by the Free Software Foundation.
   7  *
   8  * This library is distributed in the hope that it will be useful, but WITHOUT
   9  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
  11  * for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public License
  14  * along with this library; if not, write to the Free Software Foundation,
  15  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  16  */
  17
  18 #ifndef LTTNG_TRIGGER_H
  19 #define LTTNG_TRIGGER_H
  20
  21 struct lttng_action;
  22 struct lttng_condition;
  23 struct lttng_trigger;
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 enum lttng_register_trigger_status {
  30         LTTNG_REGISTER_TRIGGER_STATUS_OK = 0,
  31         LTTNG_REGISTER_TRIGGER_STATUS_INVALID = -1,
  32 };
  33
  34 /*
  35  * Create a trigger object associating a condition and an action.
  36  *
  37  * A trigger associates a condition and an action to take whenever the
  38  * condition evaluates to true. Such actions can, for example, consist
  39  * in the emission of a notification to clients listening through
  40  * notification channels.
  41  *
  42  * The caller retains the ownership of both the condition and action
  43  * and both must be kept alive for the lifetime of the trigger object.
  44  *
  45  * A trigger must be registered in order to become activate and can
  46  * be destroyed after its registration.
  47  *
  48  * Returns a trigger object on success, NULL on error.
  49  * Trigger objects must be destroyed using the lttng_trigger_destroy()
  50  * function.
  51  */
  52 extern struct lttng_trigger *lttng_trigger_create(
  53                 struct lttng_condition *condition, struct lttng_action *action);
  54
  55 /*
  56  * Get the condition of a trigger.
  57  *
  58  * The caller acquires no ownership of the returned condition.
  59  *
  60  * Returns a condition on success, NULL on error.
  61  */
  62 extern struct lttng_condition *lttng_trigger_get_condition(
  63                 struct lttng_trigger *trigger);
  64
  65 /*
  66  * Get the action of a trigger.
  67  *
  68  * The caller acquires no ownership of the returned action.
  69  *
  70  * Returns an action on success, NULL on error.
  71  */
  72 extern struct lttng_action *lttng_trigger_get_action(
  73                 struct lttng_trigger *trigger);
  74
  75 /*
  76  * Destroy (frees) a trigger object.
  77  */
  78 extern void lttng_trigger_destroy(struct lttng_trigger *trigger);
  79
  80 /*
  81  * Register a trigger to the session daemon.
  82  *
  83  * The trigger can be destroyed after this call.
  84  *
  85  * Return 0 on success, a negative LTTng error code on error.
  86  */
  87 extern int lttng_register_trigger(struct lttng_trigger *trigger);
  88
  89 /*
  90  * Unregister a trigger from the session daemon.
  91  *
  92  * The trigger can be destroyed after this call.
  93  *
  94  * Return 0 on success, a negative LTTng error code on error.
  95  */
  96 extern int lttng_unregister_trigger(struct lttng_trigger *trigger);
  97
  98 #ifdef __cplusplus
  99 }
 100 #endif
 101
 102 #endif /* LTTNG_TRIGGER_H */