2 * Copyright (C) 2017 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
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.
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
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
18 #ifndef LTTNG_NOTIFICATION_CHANNEL_H
19 #define LTTNG_NOTIFICATION_CHANNEL_H
27 struct lttng_endpoint
;
28 struct lttng_condition
;
29 struct lttng_notification
;
30 struct lttng_notification_channel
;
32 enum lttng_notification_channel_status
{
33 LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED
= 1,
34 LTTNG_NOTIFICATION_CHANNEL_STATUS_INTERRUPTED
= 2,
35 LTTNG_NOTIFICATION_CHANNEL_STATUS_OK
= 0,
36 LTTNG_NOTIFICATION_CHANNEL_STATUS_ERROR
= -1,
37 LTTNG_NOTIFICATION_CHANNEL_STATUS_CLOSED
= -2,
38 LTTNG_NOTIFICATION_CHANNEL_STATUS_ALREADY_SUBSCRIBED
= -3,
39 /* Condition unknown. */
40 LTTNG_NOTIFICATION_CHANNEL_STATUS_UNKNOWN_CONDITION
= -4,
41 LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID
= -5,
42 LTTNG_NOTIFICATION_CHANNEL_STATUS_UNSUPPORTED_VERSION
= -6,
46 * A notification channel is used to receive notifications from various
49 * Notification channels connect a client to an LTTng endpoint
50 * (see lttng/endpoint.h) and allows client to subscribe and unsubscribe
51 * to various types of notifications which are associated to conditions.
53 * In order to emit a notification, a condition must be associated to a
54 * notify action within a trigger. A client wishing to consume such
55 * conditions must explicitly subscribe to them by using an equivalent
60 * Create a notification channel connected to a given endpoint.
62 * The only supported endpoint, at the moment, is the
63 * lttng_session_daemon_notification_endpoint, which is a singleton
64 * declared in the lttng/endpoint.h header.
66 * Returns an lttng_notification_channel on success, NULL on failure.
67 * The returned lttng_notification_channel must be destroyed using
68 * the lttng_notification_channel_destroy() function.
70 extern struct lttng_notification_channel
*lttng_notification_channel_create(
71 struct lttng_endpoint
*endpoint
);
74 * Get the next notification received on a notification channel.
76 * This call will block until a notification is received on the notification
77 * channel or until the endpoint closes the connection.
79 * The returned notification's ownership is transferred to the caller and
80 * it must be destroyed using lttng_notification_destroy().
82 * Notifications can be dropped if a client consumes the notifications sent
83 * through the notification channel too slowly.
86 * - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK and a notification on success,
87 * - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was
89 * - LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED if notifications
91 * - LTTNG_NOTIFICATION_CHANNEL_STATUS_INTERRUPTED if a signal was received
92 * that caused the reception to fail.
94 extern enum lttng_notification_channel_status
95 lttng_notification_channel_get_next_notification(
96 struct lttng_notification_channel
*channel
,
97 struct lttng_notification
**notification
);
100 * Check whether a notification is pending on a notification channel.
102 * This call allows the user to check whether a notification is pending on
103 * the notification channel.
105 * If pending is set to true and the return value is
106 * LTTNG_NOTIFICATION_CHANNEL_STATUS_OK,
107 * lttng_notification_channel_get_next_notification() can be called and
108 * is guaranteed to not block.
111 * - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success,
112 * - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was
115 extern enum lttng_notification_channel_status
116 lttng_notification_channel_has_pending_notification(
117 struct lttng_notification_channel
*channel
,
118 bool *notification_pending
);
121 * Subscribe to notifications of a condition through a notification channel.
123 * The caller retains the ownership of the condition passed through this call
124 * and it can be disposed-of at any moment after this call.
126 * An error will be reported if the client tries to subscribe to the same
127 * condition multiple times without unsubscribing.
130 * - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success,
131 * - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was
132 * provided, or LTTNG_NOTIFICATION_CHANNEL_STATUS_ALREADY_SUBSCRIBED if the
133 * client was already subscribed to the condition through this channel.
135 extern enum lttng_notification_channel_status
136 lttng_notification_channel_subscribe(
137 struct lttng_notification_channel
*channel
,
138 const struct lttng_condition
*condition
);
141 * Unsubscribe to notifications of a condition through a notification channel.
143 * The caller retains the ownership of the condition passed through this call
144 * and it can be disposed-of at any moment after this call.
146 * An error will be reported if the client tries to unsubscribe to from a
147 * conditions' notifications to which it was not previously subscribed.
150 * - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success,
151 * - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was
152 * provided, or LTTNG_NOTIFICATION_CHANNEL_STATUS_UNKNOWN_CONDITION if the
153 * client was not already subscribed to the condition through this channel.
155 extern enum lttng_notification_channel_status
156 lttng_notification_channel_unsubscribe(
157 struct lttng_notification_channel
*channel
,
158 const struct lttng_condition
*condition
);
161 * Closes and destroys (frees) a notification channel.
163 extern void lttng_notification_channel_destroy(
164 struct lttng_notification_channel
*channel
);
170 #endif /* LTTNG_NOTIFICATION_CHANNEL_H */