include/lttng/condition/event-rule-matches.h

   1 /*
   2  * Copyright (C) 2019 Jonathan Rajotte <jonathan.rajotte-julien@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_CONDITION_EVENT_RULE_MATCHES_H
   9 #define LTTNG_CONDITION_EVENT_RULE_MATCHES_H
  10
  11 #include <lttng/event-rule/event-rule.h>
  12 #include <lttng/condition/condition.h>
  13 #include <lttng/condition/evaluation.h>
  14 #include <lttng/lttng-export.h>
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif
  19
  20 struct lttng_event_expr;
  21 struct lttng_event_field_value;
  22
  23 enum lttng_evaluation_event_rule_matches_status {
  24         LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_NONE = 1,
  25         LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_OK = 0,
  26         LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_INVALID = -1,
  27 };
  28
  29 /**
  30  * Event Rule Matches conditions allows an action to be taken whenever an event
  31  * matching the Event Rule Matches is hit by the tracers.
  32  *
  33  * An Event Rule Matches condition can also specify a payload to be captured at
  34  * runtime. This is done via the capture descriptor.
  35  *
  36  * Note: the dynamic runtime capture of payload is only available for the
  37  *       trigger notification subsystem.
  38  */
  39
  40 /*
  41  * Create a newly allocated Event Rule Matches condition.
  42  *
  43  * Returns a new condition on success, NULL on failure. This condition must be
  44  * destroyed using lttng_condition_destroy().
  45  */
  46 LTTNG_EXPORT extern struct lttng_condition *lttng_condition_event_rule_matches_create(
  47                 struct lttng_event_rule *rule);
  48
  49 /*
  50  * Get the rule property of an Event Rule Matches condition.
  51  *
  52  * The caller does not assume the ownership of the returned rule. The
  53  * rule shall only be used for the duration of the condition's
  54  * lifetime.
  55  *
  56  * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's rule
  57  * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
  58  * parameter is passed. */
  59 LTTNG_EXPORT extern enum lttng_condition_status lttng_condition_event_rule_matches_get_rule(
  60                 const struct lttng_condition *condition,
  61                 const struct lttng_event_rule **rule);
  62
  63 /**
  64  * lttng_evaluation_event_rule_matches_hit are specialised lttng_evaluations
  65  * which allow users to query a number of properties resulting from the
  66  * evaluation of a condition which evaluated to true.
  67  *
  68  * The evaluation of an Event Rule Matches condition contains the captured event
  69  * payload fields that were specified by the condition.
  70  */
  71
  72 /*
  73  * Sets `*field_val` to the array event field value of the Event Rule Matches
  74  * condition evaluation `evaluation` which contains its captured values.
  75  *
  76  * Returns:
  77  *
  78  * `LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_OK`:
  79  *     Success.
  80  *
  81  *     `*field_val` is an array event field value with a length of at
  82  *     least one.
  83  *
  84  * `LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_INVALID`:
  85  *     * `evaluation` is `NULL`.
  86  *     * The type of the condition of `evaluation` is not
  87  *       `LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES`.
  88  *     * `field_val` is `NULL`.
  89  *
  90  * `LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_NONE`:
  91  *     * The condition of `evaluation` has no capture descriptors.
  92  */
  93 LTTNG_EXPORT extern enum lttng_evaluation_event_rule_matches_status
  94 lttng_evaluation_event_rule_matches_get_captured_values(
  95                 const struct lttng_evaluation *evaluation,
  96                 const struct lttng_event_field_value **field_val);
  97
  98 /*
  99  * Appends (transfering the ownership) the capture descriptor `expr` to
 100  * the Event Rule Matches condition `condition`.
 101  *
 102  * Returns:
 103  *
 104  * `LTTNG_CONDITION_STATUS_OK`:
 105  *     Success.
 106  *
 107  * `LTTNG_CONDITION_STATUS_ERROR`:
 108  *     Memory error.
 109  *
 110  * `LTTNG_CONDITION_STATUS_INVALID`:
 111  *     * `condition` is `NULL`.
 112  *     * The type of `condition` is not
 113  *       `LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES`.
 114  *     * `expr` is `NULL`.
 115  *     * `expr` is not a locator expression, that is, its type is not
 116  *       one of:
 117  *
 118  *       * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD`
 119  *       * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD`
 120  *       * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`
 121  *       * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`
 122  *
 123  * `LTTNG_CONDITION_STATUS_UNSUPPORTED`:
 124  *     * The associated event-rule does not support runtime capture.
 125  */
 126 LTTNG_EXPORT extern enum lttng_condition_status
 127 lttng_condition_event_rule_matches_append_capture_descriptor(
 128                 struct lttng_condition *condition,
 129                 struct lttng_event_expr *expr);
 130
 131 /*
 132  * Sets `*count` to the number of capture descriptors in the Event Rule Matches
 133  * condition `condition`.
 134  *
 135  * Returns:
 136  *
 137  * `LTTNG_CONDITION_STATUS_OK`:
 138  *     Success.
 139  *
 140  * `LTTNG_CONDITION_STATUS_INVALID`:
 141  *     * `condition` is `NULL`.
 142  *     * The type of `condition` is not
 143  *       `LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES`.
 144  *     * `count` is `NULL`.
 145  */
 146 LTTNG_EXPORT extern enum lttng_condition_status
 147 lttng_condition_event_rule_matches_get_capture_descriptor_count(
 148                 const struct lttng_condition *condition, unsigned int *count);
 149
 150 /*
 151  * Returns the capture descriptor (borrowed) of the Event Rule Matches condition
 152  * `condition` at the index `index`, or `NULL` if:
 153  *
 154  * * `condition` is `NULL`.
 155  * * The type of `condition` is not
 156  *   `LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES`.
 157  * * `index` is greater than or equal to the number of capture
 158  *   descriptors in `condition` (as returned by
 159  *   lttng_condition_event_rule_matches_get_capture_descriptor_count()).
 160  */
 161 LTTNG_EXPORT extern const struct lttng_event_expr *
 162 lttng_condition_event_rule_matches_get_capture_descriptor_at_index(
 163                 const struct lttng_condition *condition, unsigned int index);
 164
 165 #ifdef __cplusplus
 166 }
 167 #endif
 168
 169 #endif /* LTTNG_CONDITION_EVENT_RULE_MATCHES_H */