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