Docs: document the trigger API
[lttng-tools.git] / include / lttng / trigger / trigger.h
CommitLineData
a58c490f
JG
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
21struct lttng_action;
22struct lttng_condition;
23struct lttng_trigger;
24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
29enum lttng_register_trigger_status {
30 LTTNG_REGISTER_TRIGGER_STATUS_OK = 0,
31 LTTNG_REGISTER_TRIGGER_STATUS_INVALID = -1,
32};
33
75984389
JG
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 */
a58c490f
JG
52extern struct lttng_trigger *lttng_trigger_create(
53 struct lttng_condition *condition, struct lttng_action *action);
54
75984389
JG
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 */
a58c490f
JG
62extern struct lttng_condition *lttng_trigger_get_condition(
63 struct lttng_trigger *trigger);
64
75984389
JG
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 */
a58c490f
JG
72extern struct lttng_action *lttng_trigger_get_action(
73 struct lttng_trigger *trigger);
74
75984389
JG
75/*
76 * Destroy (frees) a trigger object.
77 */
a58c490f
JG
78extern void lttng_trigger_destroy(struct lttng_trigger *trigger);
79
75984389
JG
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 */
a58c490f
JG
87extern int lttng_register_trigger(struct lttng_trigger *trigger);
88
75984389
JG
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 */
a58c490f
JG
96extern 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.037326 seconds and 4 git commands to generate.