include/lttng/event-field-value.h

   1 /*
   2  * Copyright (C) 2020 Philippe Proulx <pproulx@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_EVENT_FIELD_VALUE_H
   9 #define LTTNG_EVENT_FIELD_VALUE_H
  10
  11 #include <lttng/lttng-export.h>
  12 #include <stdint.h>
  13
  14 struct lttng_event_field_value;
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif
  19
  20 /*
  21  * Types of a event field value expression.
  22  */
  23 enum lttng_event_field_value_type {
  24         /*
  25          * Unknown.
  26          */
  27         LTTNG_EVENT_FIELD_VALUE_TYPE_UNKNOWN = -2,
  28
  29         /*
  30          * Returned by lttng_event_field_value_get_type() with an
  31          * invalid parameter.
  32          */
  33         LTTNG_EVENT_FIELD_VALUE_TYPE_INVALID = -1,
  34
  35         /*
  36          * Unsigned integer event field value.
  37          */
  38         LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_INT = 0,
  39
  40         /*
  41          * Signed integer event field value.
  42          */
  43         LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_INT = 1,
  44
  45         /*
  46          * Unsigned enumeration event field value.
  47          *
  48          * This type conceptually inherits
  49          * `LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_INT`.
  50          */
  51         LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_ENUM = 2,
  52
  53         /*
  54          * Signed enumeration event field value.
  55          *
  56          * This type conceptually inherits
  57          * `LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_INT`.
  58          */
  59         LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_ENUM = 3,
  60
  61         /*
  62          * Real event field value.
  63          */
  64         LTTNG_EVENT_FIELD_VALUE_TYPE_REAL = 4,
  65
  66         /*
  67          * String event field value.
  68          */
  69         LTTNG_EVENT_FIELD_VALUE_TYPE_STRING = 5,
  70
  71         /*
  72          * Array event field value.
  73          */
  74         LTTNG_EVENT_FIELD_VALUE_TYPE_ARRAY = 6,
  75 };
  76
  77 /*
  78  * Event field value API status codes.
  79  */
  80 enum lttng_event_field_value_status {
  81         /*
  82          * Event field value is not available.
  83          */
  84         LTTNG_EVENT_FIELD_VALUE_STATUS_UNAVAILABLE = -2,
  85
  86         /*
  87          * Invalid parameter.
  88          */
  89         LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID = -1,
  90
  91         /*
  92          * Success.
  93          */
  94         LTTNG_EVENT_FIELD_VALUE_STATUS_OK = 0,
  95 };
  96
  97 /*
  98  * Returns the type of the event field value `field_val`, or:
  99  *
 100  * `LTTNG_EVENT_FIELD_VALUE_TYPE_UNKNOWN`:
 101  *     The type of `field_val` is unknown as of this version of the
 102  *     LTTng control library.
 103  *
 104  * `LTTNG_EVENT_FIELD_VALUE_TYPE_INVALID`:
 105  *     `field_val` is `NULL`.
 106  */
 107 LTTNG_EXPORT extern enum lttng_event_field_value_type lttng_event_field_value_get_type(
 108                 const struct lttng_event_field_value *field_val);
 109
 110 /*
 111  * Sets `*val` to the raw value of the unsigned integer/enumeration
 112  * event field value `field_val`.
 113  *
 114  * Returns:
 115  *
 116  * `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
 117  *     Success.
 118  *
 119  * `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
 120  *     * `field_val` is `NULL`.
 121  *     * The type of `field_val` is not
 122  *       `LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_INT` or
 123  *       `LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_ENUM`.
 124  *     * `val` is `NULL`.
 125  */
 126 LTTNG_EXPORT extern enum lttng_event_field_value_status
 127 lttng_event_field_value_unsigned_int_get_value(
 128                 const struct lttng_event_field_value *field_val, uint64_t *val);
 129
 130 /*
 131  * Sets `*val` to the raw value of the signed integer/enumeration event
 132  * field value `field_val`.
 133  *
 134  * Returns:
 135  *
 136  * `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
 137  *     Success.
 138  *
 139  * `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
 140  *     * `field_val` is `NULL`.
 141  *     * The type of `field_val` is not
 142  *       `LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_INT` or
 143  *       `LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_ENUM`.
 144  *     * `val` is `NULL`.
 145  */
 146 LTTNG_EXPORT extern enum lttng_event_field_value_status
 147 lttng_event_field_value_signed_int_get_value(
 148                 const struct lttng_event_field_value *field_val, int64_t *val);
 149
 150 /*
 151  * Sets `*val` to the raw value of the real event field value
 152  * `field_val`.
 153  *
 154  * Returns:
 155  *
 156  * `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
 157  *     Success.
 158  *
 159  * `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
 160  *     * `field_val` is `NULL`.
 161  *     * The type of `field_val` is not
 162  *       `LTTNG_EVENT_FIELD_VALUE_TYPE_REAL`.
 163  *     * `val` is `NULL`.
 164  */
 165 LTTNG_EXPORT extern enum lttng_event_field_value_status
 166 lttng_event_field_value_real_get_value(
 167                 const struct lttng_event_field_value *field_val, double *val);
 168
 169 /*
 170  * Returns the raw value (an UTF-8 C string) of the string event field
 171  * value `field_val`, or `NULL` if:
 172  *
 173  * `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
 174  *     Success.
 175  *
 176  * `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
 177  *     * `field_val` is `NULL`.
 178  *     * The type of `field_val` is not
 179  *       `LTTNG_EVENT_FIELD_VALUE_TYPE_STRING`.
 180  */
 181 LTTNG_EXPORT extern enum lttng_event_field_value_status
 182 lttng_event_field_value_string_get_value(
 183                 const struct lttng_event_field_value *field_val,
 184                 const char **value);
 185
 186 /*
 187  * Sets `*length` to the length (the number of contained elements) of
 188  * the array event field value `field_val`.
 189  *
 190  * Returns:
 191  *
 192  * `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
 193  *     Success.
 194  *
 195  * `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
 196  *     * `field_val` is `NULL`.
 197  *     * The type of `field_val` is not
 198  *       `LTTNG_EVENT_FIELD_VALUE_TYPE_ARRAY`.
 199  *     * `length` is `NULL`.
 200  */
 201 LTTNG_EXPORT extern enum lttng_event_field_value_status
 202 lttng_event_field_value_array_get_length(
 203                 const struct lttng_event_field_value *field_val,
 204                 unsigned int *length);
 205
 206 /*
 207  * Sets `*elem_field_val` to the event field value at index `index` in
 208  * the array event field value `field_val`.
 209  *
 210  * Returns:
 211  *
 212  * `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
 213  *     Success.
 214  *
 215  * `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
 216  *     * `field_val` is `NULL`.
 217  *     * The type of `field_val` is not
 218  *       `LTTNG_EVENT_FIELD_VALUE_TYPE_ARRAY`.
 219  *     * `index` is greater than or equal to the length of `field_val`,
 220  *       as returned by lttng_event_field_value_array_get_length().
 221  *
 222  * `LTTNG_EVENT_FIELD_VALUE_STATUS_UNAVAILABLE`:
 223  *     * No event field value exists at index `index` within
 224  *       `field_val`.
 225  */
 226 LTTNG_EXPORT extern enum lttng_event_field_value_status
 227 lttng_event_field_value_array_get_element_at_index(
 228                 const struct lttng_event_field_value *field_val,
 229                 unsigned int index,
 230                 const struct lttng_event_field_value **elem_field_val);
 231
 232 #ifdef __cplusplus
 233 }
 234 #endif
 235
 236 #endif /* LTTNG_EVENT_FIELD_VALUE_H */