Docs: document the trigger API
[lttng-tools.git] / 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 */
This page took 0.044516 seconds and 4 git commands to generate.