| 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_NOTIFICATION_CHANNEL_H |
| 9 | #define LTTNG_NOTIFICATION_CHANNEL_H |
| 10 | |
| 11 | #include <lttng/lttng-export.h> |
| 12 | #include <stdbool.h> |
| 13 | |
| 14 | #ifdef __cplusplus |
| 15 | extern "C" { |
| 16 | #endif |
| 17 | |
| 18 | struct lttng_endpoint; |
| 19 | struct lttng_condition; |
| 20 | struct lttng_notification; |
| 21 | struct lttng_notification_channel; |
| 22 | |
| 23 | enum lttng_notification_channel_status { |
| 24 | LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED = 1, |
| 25 | LTTNG_NOTIFICATION_CHANNEL_STATUS_INTERRUPTED = 2, |
| 26 | LTTNG_NOTIFICATION_CHANNEL_STATUS_OK = 0, |
| 27 | LTTNG_NOTIFICATION_CHANNEL_STATUS_ERROR = -1, |
| 28 | LTTNG_NOTIFICATION_CHANNEL_STATUS_CLOSED = -2, |
| 29 | LTTNG_NOTIFICATION_CHANNEL_STATUS_ALREADY_SUBSCRIBED = -3, |
| 30 | /* Condition unknown. */ |
| 31 | LTTNG_NOTIFICATION_CHANNEL_STATUS_UNKNOWN_CONDITION = -4, |
| 32 | LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID = -5, |
| 33 | LTTNG_NOTIFICATION_CHANNEL_STATUS_UNSUPPORTED_VERSION = -6, |
| 34 | }; |
| 35 | |
| 36 | /** |
| 37 | * A notification channel is used to receive notifications from various |
| 38 | * LTTng components. |
| 39 | * |
| 40 | * Notification channels connect a client to an LTTng endpoint |
| 41 | * (see lttng/endpoint.h) and allows client to subscribe and unsubscribe |
| 42 | * to various types of notifications which are associated to conditions. |
| 43 | * |
| 44 | * In order to emit a notification, a condition must be associated to a |
| 45 | * notify action within a trigger. A client wishing to consume such |
| 46 | * conditions must explicitly subscribe to them by using an equivalent |
| 47 | * condition. |
| 48 | */ |
| 49 | |
| 50 | /* |
| 51 | * Create a notification channel connected to a given endpoint. |
| 52 | * |
| 53 | * The only supported endpoint, at the moment, is the |
| 54 | * lttng_session_daemon_notification_endpoint, which is a singleton |
| 55 | * declared in the lttng/endpoint.h header. |
| 56 | * |
| 57 | * Returns an lttng_notification_channel on success, NULL on failure. |
| 58 | * The returned lttng_notification_channel must be destroyed using |
| 59 | * the lttng_notification_channel_destroy() function. |
| 60 | */ |
| 61 | LTTNG_EXPORT extern struct lttng_notification_channel *lttng_notification_channel_create( |
| 62 | struct lttng_endpoint *endpoint); |
| 63 | |
| 64 | /* |
| 65 | * Get the next notification received on a notification channel. |
| 66 | * |
| 67 | * This call will block until a notification is received on the notification |
| 68 | * channel or until the endpoint closes the connection. |
| 69 | * |
| 70 | * The returned notification's ownership is transferred to the caller and |
| 71 | * it must be destroyed using lttng_notification_destroy(). |
| 72 | * |
| 73 | * Notifications can be dropped if a client consumes the notifications sent |
| 74 | * through the notification channel too slowly. |
| 75 | * |
| 76 | * Returns |
| 77 | * - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK and a notification on success, |
| 78 | * - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was |
| 79 | * provided, |
| 80 | * - LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED if notifications |
| 81 | * were dropped, |
| 82 | * - LTTNG_NOTIFICATION_CHANNEL_STATUS_INTERRUPTED if a signal was received |
| 83 | * that caused the reception to fail. |
| 84 | */ |
| 85 | LTTNG_EXPORT extern enum lttng_notification_channel_status |
| 86 | lttng_notification_channel_get_next_notification( |
| 87 | struct lttng_notification_channel *channel, |
| 88 | struct lttng_notification **notification); |
| 89 | |
| 90 | /* |
| 91 | * Check whether a notification is pending on a notification channel. |
| 92 | * |
| 93 | * This call allows the user to check whether a notification is pending on |
| 94 | * the notification channel. |
| 95 | * |
| 96 | * If pending is set to true and the return value is |
| 97 | * LTTNG_NOTIFICATION_CHANNEL_STATUS_OK, |
| 98 | * lttng_notification_channel_get_next_notification() can be called and |
| 99 | * is guaranteed to not block. |
| 100 | * |
| 101 | * Returns |
| 102 | * - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success, |
| 103 | * - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was |
| 104 | * provided. |
| 105 | */ |
| 106 | LTTNG_EXPORT extern enum lttng_notification_channel_status |
| 107 | lttng_notification_channel_has_pending_notification( |
| 108 | struct lttng_notification_channel *channel, |
| 109 | bool *notification_pending); |
| 110 | |
| 111 | /* |
| 112 | * Subscribe to notifications of a condition through a notification channel. |
| 113 | * |
| 114 | * The caller retains the ownership of the condition passed through this call |
| 115 | * and it can be disposed-of at any moment after this call. |
| 116 | * |
| 117 | * An error will be reported if the client tries to subscribe to the same |
| 118 | * condition multiple times without unsubscribing. |
| 119 | * |
| 120 | * Returns |
| 121 | * - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success, |
| 122 | * - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was |
| 123 | * provided, or LTTNG_NOTIFICATION_CHANNEL_STATUS_ALREADY_SUBSCRIBED if the |
| 124 | * client was already subscribed to the condition through this channel. |
| 125 | */ |
| 126 | LTTNG_EXPORT extern enum lttng_notification_channel_status |
| 127 | lttng_notification_channel_subscribe( |
| 128 | struct lttng_notification_channel *channel, |
| 129 | const struct lttng_condition *condition); |
| 130 | |
| 131 | /* |
| 132 | * Unsubscribe to notifications of a condition through a notification channel. |
| 133 | * |
| 134 | * The caller retains the ownership of the condition passed through this call |
| 135 | * and it can be disposed-of at any moment after this call. |
| 136 | * |
| 137 | * An error will be reported if the client tries to unsubscribe to from a |
| 138 | * conditions' notifications to which it was not previously subscribed. |
| 139 | * |
| 140 | * Returns |
| 141 | * - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success, |
| 142 | * - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was |
| 143 | * provided, or LTTNG_NOTIFICATION_CHANNEL_STATUS_UNKNOWN_CONDITION if the |
| 144 | * client was not already subscribed to the condition through this channel. |
| 145 | */ |
| 146 | LTTNG_EXPORT extern enum lttng_notification_channel_status |
| 147 | lttng_notification_channel_unsubscribe( |
| 148 | struct lttng_notification_channel *channel, |
| 149 | const struct lttng_condition *condition); |
| 150 | |
| 151 | /* |
| 152 | * Closes and destroys (frees) a notification channel. |
| 153 | */ |
| 154 | LTTNG_EXPORT extern void lttng_notification_channel_destroy( |
| 155 | struct lttng_notification_channel *channel); |
| 156 | |
| 157 | #ifdef __cplusplus |
| 158 | } |
| 159 | #endif |
| 160 | |
| 161 | #endif /* LTTNG_NOTIFICATION_CHANNEL_H */ |