include/babeltrace/ctf-ir/fields-internal.h

   1 #ifndef BABELTRACE_CTF_IR_FIELDS_INTERNAL_H
   2 #define BABELTRACE_CTF_IR_FIELDS_INTERNAL_H
   3
   4 /*
   5  * Babeltrace - CTF IR: Event Fields internal
   6  *
   7  * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   8  *
   9  * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  10  *
  11  * Permission is hereby granted, free of charge, to any person obtaining a copy
  12  * of this software and associated documentation files (the "Software"), to deal
  13  * in the Software without restriction, including without limitation the rights
  14  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  15  * copies of the Software, and to permit persons to whom the Software is
  16  * furnished to do so, subject to the following conditions:
  17  *
  18  * The above copyright notice and this permission notice shall be included in
  19  * all copies or substantial portions of the Software.
  20  *
  21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  22  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  23  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  24  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  25  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  26  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  27  * SOFTWARE.
  28  */
  29
  30 #include <babeltrace/ctf-writer/event-fields.h>
  31 #include <babeltrace/object-internal.h>
  32 #include <babeltrace/babeltrace-internal.h>
  33 #include <babeltrace/ctf/types.h>
  34 #include <glib.h>
  35
  36 struct bt_ctf_field {
  37         struct bt_object base;
  38         struct bt_ctf_field_type *type;
  39         int payload_set;
  40         int frozen;
  41 };
  42
  43 struct bt_ctf_field_integer {
  44         struct bt_ctf_field parent;
  45         struct definition_integer definition;
  46 };
  47
  48 struct bt_ctf_field_enumeration {
  49         struct bt_ctf_field parent;
  50         struct bt_ctf_field *payload;
  51 };
  52
  53 struct bt_ctf_field_floating_point {
  54         struct bt_ctf_field parent;
  55         struct definition_float definition;
  56         struct definition_integer sign, mantissa, exp;
  57 };
  58
  59 struct bt_ctf_field_structure {
  60         struct bt_ctf_field parent;
  61         GHashTable *field_name_to_index;
  62         GPtrArray *fields; /* Array of pointers to struct bt_ctf_field */
  63 };
  64
  65 struct bt_ctf_field_variant {
  66         struct bt_ctf_field parent;
  67         struct bt_ctf_field *tag;
  68         struct bt_ctf_field *payload;
  69 };
  70
  71 struct bt_ctf_field_array {
  72         struct bt_ctf_field parent;
  73         GPtrArray *elements; /* Array of pointers to struct bt_ctf_field */
  74 };
  75
  76 struct bt_ctf_field_sequence {
  77         struct bt_ctf_field parent;
  78         struct bt_ctf_field *length;
  79         GPtrArray *elements; /* Array of pointers to struct bt_ctf_field */
  80 };
  81
  82 struct bt_ctf_field_string {
  83         struct bt_ctf_field parent;
  84         GString *payload;
  85 };
  86
  87 /*
  88  * Set a field's value with an already allocated field instance.
  89  */
  90 BT_HIDDEN
  91 int bt_ctf_field_structure_set_field(struct bt_ctf_field *structure,
  92                 const char *name, struct bt_ctf_field *value);
  93
  94 /* Validate that the field's payload is set (returns 0 if set). */
  95 BT_HIDDEN
  96 int bt_ctf_field_validate(struct bt_ctf_field *field);
  97
  98 /* Mark field payload as unset. */
  99 BT_HIDDEN
 100 int bt_ctf_field_reset(struct bt_ctf_field *field);
 101
 102 BT_HIDDEN
 103 int bt_ctf_field_serialize(struct bt_ctf_field *field,
 104                 struct ctf_stream_pos *pos);
 105
 106 BT_HIDDEN
 107 void bt_ctf_field_freeze(struct bt_ctf_field *field);
 108
 109 /*
 110  * bt_ctf_field_copy: get a field's deep copy.
 111  *
 112  * Get a field's deep copy. The created field copy shares the source's
 113  * associated field types.
 114  *
 115  * On success, the returned copy has its reference count set to 1.
 116  *
 117  * @param field Field instance.
 118  *
 119  * Returns the field copy on success, NULL on error.
 120  */
 121 BT_HIDDEN
 122 struct bt_ctf_field *bt_ctf_field_copy(struct bt_ctf_field *field);
 123
 124
 125 /*
 126  * bt_ctf_field_is_integer: returns whether or not a given field
 127  *      is an integer type.
 128  *
 129  * @param field Field instance.
 130  *
 131  * Returns 1 if the field instance is an integer type, 0 otherwise.
 132  */
 133 BT_HIDDEN
 134 int bt_ctf_field_is_integer(struct bt_ctf_field *field);
 135
 136 /*
 137  * bt_ctf_field_is_floating_point: returns whether or not a given field
 138  *      is a floating point number type.
 139  *
 140  * @param field Field instance.
 141  *
 142  * Returns 1 if the field instance is a floating point number type, 0 otherwise.
 143  */
 144 BT_HIDDEN
 145 int bt_ctf_field_is_floating_point(struct bt_ctf_field *field);
 146
 147 /*
 148  * bt_ctf_field_is_enumeration: returns whether or not a given field
 149  *      is an enumeration type.
 150  *
 151  * @param field Field instance.
 152  *
 153  * Returns 1 if the field instance is an enumeration type, 0 otherwise.
 154  */
 155 BT_HIDDEN
 156 int bt_ctf_field_is_enumeration(struct bt_ctf_field *field);
 157
 158 /*
 159  * bt_ctf_field_is_string: returns whether or not a given field
 160  *      is a string type.
 161  *
 162  * @param field Field instance.
 163  *
 164  * Returns 1 if the field instance is a string type, 0 otherwise.
 165  */
 166 BT_HIDDEN
 167 int bt_ctf_field_is_string(struct bt_ctf_field *field);
 168
 169 /*
 170  * bt_ctf_field_is_structure: returns whether or not a given field
 171  *      is a structure type.
 172  *
 173  * @param field Field instance.
 174  *
 175  * Returns 1 if the field instance is a structure type, 0 otherwise.
 176  */
 177 BT_HIDDEN
 178 int bt_ctf_field_is_structure(struct bt_ctf_field *field);
 179
 180 /*
 181  * bt_ctf_field_is_array: returns whether or not a given field
 182  *      is an array type.
 183  *
 184  * @param field Field instance.
 185  *
 186  * Returns 1 if the field instance is an array type, 0 otherwise.
 187  */
 188 BT_HIDDEN
 189 int bt_ctf_field_is_array(struct bt_ctf_field *field);
 190
 191 /*
 192  * bt_ctf_field_is_sequence: returns whether or not a given field
 193  *      is a sequence type.
 194  *
 195  * @param field Field instance.
 196  *
 197  * Returns 1 if the field instance is a sequence type, 0 otherwise.
 198  */
 199 BT_HIDDEN
 200 int bt_ctf_field_is_sequence(struct bt_ctf_field *field);
 201
 202 /*
 203  * bt_ctf_field_is_variant: returns whether or not a given field
 204  *      is a variant type.
 205  *
 206  * @param field Field instance.
 207  *
 208  * Returns 1 if the field instance is a variant type, 0 otherwise.
 209  */
 210 BT_HIDDEN
 211 int bt_ctf_field_is_variant(struct bt_ctf_field *field);
 212
 213 /*
 214  * bt_ctf_field_structure_get_field_by_index: get a structure's field by index.
 215  *
 216  * Get the structure's field corresponding to the provided field name.
 217  * bt_ctf_field_put() must be called on the returned value.
 218  * The indexes are the same as those provided for bt_ctf_field_type_structure.
 219  *
 220  * @param structure Structure field instance.
 221  * @param index Index of the field in the provided structure.
 222  *
 223  * Returns a field instance on success, NULL on error.
 224  */
 225 BT_HIDDEN
 226 struct bt_ctf_field *bt_ctf_field_structure_get_field_by_index(
 227                 struct bt_ctf_field *structure, int index);
 228
 229 /*
 230  * bt_ctf_field_sequence_get_length: get a sequence's length.
 231  *
 232  * Get the sequence's length field.
 233  *
 234  * @param sequence Sequence field instance.
 235  *
 236  * Returns a field instance on success, NULL if a length was never set.
 237  */
 238 BT_HIDDEN
 239 struct bt_ctf_field *bt_ctf_field_sequence_get_length(
 240                 struct bt_ctf_field *sequence);
 241
 242 /*
 243  * bt_ctf_field_variant_get_current_field: get the current selected field of a
 244  *      variant.
 245  *
 246  * Return the variant's current selected field. This function, unlike
 247  * bt_ctf_field_variant_get_field(), does not create any field; it
 248  * returns NULL if there's no current selected field yet.
 249  *
 250  * @param variant Variant field instance.
 251  *
 252  * Returns a field instance on success, NULL on error or when there's no
 253  * current selected field.
 254  */
 255 BT_HIDDEN
 256 struct bt_ctf_field *bt_ctf_field_variant_get_current_field(
 257                 struct bt_ctf_field *variant);
 258
 259 /*
 260  * bt_ctf_field_enumeration_get_mapping_name: get an enumeration field's mapping
 261  *      name.
 262  *
 263  * Return the enumeration's underlying container field (an integer).
 264  * bt_ctf_field_put() must be called on the returned value.
 265  *
 266  * @param enumeration Enumeration field instance.
 267  *
 268  * Returns a field instance on success, NULL on error.
 269  */
 270 BT_HIDDEN
 271 const char *bt_ctf_field_enumeration_get_mapping_name(
 272                 struct bt_ctf_field *enumeration);
 273
 274 /*
 275  * bt_ctf_field_signed_integer_get_value: get a signed integer field's value
 276  *
 277  * Get a signed integer field's value.
 278  *
 279  * @param integer Signed integer field instance.
 280  * @param value Pointer to a signed integer where the value will be stored.
 281  *
 282  * Returns 0 on success, a negative value on error.
 283  */
 284 BT_HIDDEN
 285 int bt_ctf_field_signed_integer_get_value(struct bt_ctf_field *integer,
 286                 int64_t *value);
 287
 288 /*
 289  * bt_ctf_field_unsigned_integer_get_value: get unsigned integer field's value
 290  *
 291  * Get an unsigned integer field's value.
 292  *
 293  * @param integer Unsigned integer field instance.
 294  * @param value Pointer to an unsigned integer where the value will be stored.
 295  *
 296  * Returns 0 on success, a negative value on error.
 297  */
 298 BT_HIDDEN
 299 int bt_ctf_field_unsigned_integer_get_value(struct bt_ctf_field *integer,
 300                 uint64_t *value);
 301
 302 /*
 303  * bt_ctf_field_floating_point_get_value: get a floating point field's value
 304  *
 305  * Get a floating point field's value.
 306  *
 307  * @param floating_point Floating point field instance.
 308  * @param value Pointer to a double where the value will be stored.
 309  *
 310  * Returns 0 on success, a negative value on error.
 311  */
 312 BT_HIDDEN
 313 int bt_ctf_field_floating_point_get_value(struct bt_ctf_field *floating_point,
 314                 double *value);
 315
 316 /*
 317  * bt_ctf_field_string_get_value: get a string field's value
 318  *
 319  * Get a string field's value.
 320  *
 321  * @param string_field String field instance.
 322  *
 323  * Returns the string's value, NULL if unset.
 324  */
 325 BT_HIDDEN
 326 const char *bt_ctf_field_string_get_value(struct bt_ctf_field *string_field);
 327
 328 /*
 329  * bt_ctf_field_string_append: append a string to a string field's
 330  * current value.
 331  *
 332  * Append a string to the current value of a string field. If the string
 333  * field was never set using bt_ctf_field_string_set_value(), it is
 334  * first set to an empty string, and then the concatenation happens.
 335  *
 336  * @param string_field String field instance.
 337  * @param value String to append to the current string field's value.
 338  *
 339  * Returns 0 on success, a negative value on error.
 340  */
 341 BT_HIDDEN
 342 int bt_ctf_field_string_append(struct bt_ctf_field *string_field,
 343                 const char *value);
 344
 345 /*
 346  * bt_ctf_field_string_append_len: append a string of a given length to
 347  * a string field's current value.
 348  *
 349  * Append a string of a given length to the current value of a string
 350  * field. If the string field was never set using
 351  * bt_ctf_field_string_set_value(), it is first set to an empty string,
 352  * and then the concatenation happens.
 353  *
 354  * If a null byte is encountered before the given length, only the
 355  * substring before the first null byte is appended.
 356  *
 357  * @param string_field String field instance.
 358  * @param value String to append to the current string field's value.
 359  * @param length Length of string value to append.
 360  *
 361  * Returns 0 on success, a negative value on error.
 362  */
 363 BT_HIDDEN
 364 int bt_ctf_field_string_append_len(
 365                 struct bt_ctf_field *string_field, const char *value,
 366                 unsigned int length);
 367
 368 /*
 369  * bt_ctf_field_get_type_id: get a field's ctf_type_id.
 370  *
 371  * This is a helper function which avoids a call to
 372  * bt_ctf_field_get_type(), followed by a call to
 373  * bt_ctf_field_type_get_type_id(), followed by a call to
 374  * bt_ctf_put().
 375  *
 376  * @param field Field instance.
 377  *
 378  * Returns the field's ctf_type_id, CTF_TYPE_UNKNOWN on error.
 379  */
 380 BT_HIDDEN
 381 enum bt_ctf_type_id bt_ctf_field_get_type_id(struct bt_ctf_field *field);
 382
 383 /*
 384  * bt_ctf_field_get_type: get a field's type
 385  *
 386  * @param field Field intance.
 387  *
 388  * Returns a field type instance on success, NULL on error.
 389  */
 390 BT_HIDDEN
 391 struct bt_ctf_field_type *bt_ctf_field_get_type(struct bt_ctf_field *field);
 392
 393 #endif /* BABELTRACE_CTF_IR_FIELDS_INTERNAL_H */