include/babeltrace/ctf-ir/event-class.h

   1 #ifndef BABELTRACE_CTF_IR_EVENT_CLASS_H
   2 #define BABELTRACE_CTF_IR_EVENT_CLASS_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Event class
   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  * The Common Trace Format (CTF) Specification is available at
  30  * http://www.efficios.com/ctf
  31  */
  32
  33 #include <stdint.h>
  34 #include <stddef.h>
  35 #include <babeltrace/values.h>
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /**
  42 @defgroup ctfireventclass CTF IR event class
  43 @ingroup ctfir
  44 @brief CTF IR event class.
  45
  46 @code
  47 #include <babeltrace/ctf-ir/event-class.h>
  48 @endcode
  49
  50 A CTF IR <strong><em>event class</em></strong> is a template that you
  51 can use to create concrete \link ctfirevent CTF IR events\endlink.
  52
  53 An event class has the following properties, both of which \em must
  54 be unique amongst all the event classes contained in the same
  55 \link ctfirstreamclass CTF IR stream class\endlink:
  56
  57 - A \b name.
  58 - A numeric \b ID.
  59
  60 A CTF IR event class owns two
  61 \link ctfirfieldtypes field types\endlink:
  62
  63 - An optional <strong>event context</strong> field type, which
  64   represents the \c event.context CTF scope.
  65 - A mandatory <strong>event payload</strong> field type, which
  66   represents the \c event.fields CTF scope.
  67
  68 Both field types \em must be structure field types as of
  69 Babeltrace \btversion.
  70 The event payload field type <em>must not</em> be empty.
  71
  72 As a reminder, here's the structure of a CTF packet:
  73
  74 @imgpacketstructure
  75
  76 In the Babeltrace CTF IR system, a \link ctfirtraceclass trace
  77 class\endlink contains zero or more \link ctfirstreamclass stream
  78 classes\endlink, and a stream class contains zero or more event classes.
  79
  80 Before you can create an event from an event class with
  81 bt_ctf_event_create(), you \em must add the prepared event class to a
  82 stream class by calling bt_ctf_stream_class_add_event_class(). This
  83 function, when successful, \em freezes the event class, disallowing any
  84 future modification of its properties and field types by the user.
  85
  86 As with any Babeltrace object, CTF IR event class objects have
  87 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
  88 counts</a>. See \ref refs to learn more about the reference counting
  89 management of Babeltrace objects.
  90
  91 bt_ctf_stream_class_add_event_class() \em freezes its event class
  92 parameter on success. You cannot modify a frozen event class: it is
  93 considered immutable, except for \link refs reference counting\endlink.
  94
  95 @sa ctfirevent
  96 @sa ctfirstreamclass
  97
  98 @file
  99 @brief CTF IR event class type and functions.
 100 @sa ctfireventclass
 101
 102 @addtogroup ctfireventclass
 103 @{
 104 */
 105
 106 /**
 107 @struct bt_ctf_event_class
 108 @brief A CTF IR event class.
 109 @sa ctfireventclass
 110 */
 111 struct bt_ctf_event_class;
 112 struct bt_ctf_field;
 113 struct bt_ctf_field_type;
 114 struct bt_ctf_stream_class;
 115
 116 /**
 117 @name Creation and parent access functions
 118 @{
 119 */
 120
 121 /**
 122 @brief  Creates a default CTF IR event class named \p name.
 123
 124 On success, the context and payload field types are empty structure
 125 field types. You can modify those default field types after the
 126 event class is created with
 127 bt_ctf_event_class_set_context_type() and
 128 bt_ctf_event_class_set_payload_type().
 129
 130 Upon creation, the event class's ID is <em>not set</em>. You
 131 can set it to a specific value with bt_ctf_event_class_set_id(). If it
 132 is still unset when you call bt_ctf_stream_class_add_event_class(), then
 133 the stream class assigns a unique ID to this event class before
 134 freezing it.
 135
 136 @param[in] name Name of the event class to create (copied on success).
 137 @returns        Created event class, or \c NULL on error.
 138
 139 @prenotnull{name}
 140 @postsuccessrefcountret1
 141 */
 142 extern struct bt_ctf_event_class *bt_ctf_event_class_create(const char *name);
 143
 144 /**
 145 @brief  Returns the parent CTF IR stream class of the CTF IR event
 146         class \p event_class.
 147
 148 It is possible that the event class was not added to a stream class
 149 yet, in which case this function returns \c NULL. You can add an
 150 event class to a stream class with
 151 bt_ctf_stream_class_add_event_class().
 152
 153 @param[in] event_class  Event class of which to get the parent
 154                         stream class.
 155 @returns                Parent stream class of \p event_class,
 156                         or \c NULL if \p event_class was not
 157                         added to a stream class yet or on error.
 158
 159 @prenotnull{event_class}
 160 @postrefcountsame{event_class}
 161 @postsuccessrefcountretinc
 162
 163 @sa bt_ctf_stream_class_add_event_class(): Add an event class to
 164         a stream class.
 165 */
 166 extern struct bt_ctf_stream_class *bt_ctf_event_class_get_stream_class(
 167                 struct bt_ctf_event_class *event_class);
 168
 169 /** @} */
 170
 171 /**
 172 @name Attribute functions
 173 @{
 174 */
 175
 176 /**
 177 @brief  Returns the name of the CTF IR event class \p event_class.
 178
 179 On success, \p event_class remains the sole owner of the returned
 180 string.
 181
 182 @param[in] event_class  Event class of which to get the name.
 183 @returns                Name of event class \p event_class, or
 184                         \c NULL on error.
 185
 186 @prenotnull{event_class}
 187 @postrefcountsame{event_class}
 188 */
 189 extern const char *bt_ctf_event_class_get_name(
 190                 struct bt_ctf_event_class *event_class);
 191
 192 /**
 193 @brief  Returns the numeric ID of the CTF IR event class \p event_class.
 194
 195 @param[in] event_class  Event class of which to get the numeric ID.
 196 @returns                ID of event class \p event_class, or a
 197                         negative value on error.
 198
 199 @prenotnull{event_class}
 200 @postrefcountsame{event_class}
 201
 202 @sa bt_ctf_event_class_set_id(): Sets the numeric ID of a given
 203         event class.
 204 */
 205 extern int64_t bt_ctf_event_class_get_id(
 206                 struct bt_ctf_event_class *event_class);
 207
 208 /**
 209 @brief  Sets the numeric ID of the CTF IR event class
 210         \p event_class to \p id.
 211
 212 \p id must be unique amongst the IDs of all the event classes
 213 of the stream class to which you eventually add \p event_class.
 214
 215 @param[in] event_class  Event class of which to set the numeric ID.
 216 @param[in] id           ID of the event class.
 217 @returns                0 on success, or a negative value on error.
 218
 219 @prenotnull{event_class}
 220 @prehot{event_class}
 221 @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
 222 @postrefcountsame{event_class}
 223
 224 @sa bt_ctf_event_class_get_id(): Returns the numeric ID of a given
 225         event class.
 226 */
 227 extern int bt_ctf_event_class_set_id(
 228                 struct bt_ctf_event_class *event_class, uint64_t id);
 229
 230 /**
 231 @brief  Returns the number of attributes contained in the CTF IR event
 232         class \p event_class.
 233
 234 @param[in] event_class  Event class of which to get the number
 235                         of contained attributes.
 236 @returns                Number of contained attributes in
 237                         \p event_class, or a negative value on error.
 238
 239 @prenotnull{event_class}
 240 @postrefcountsame{event_class}
 241
 242 @sa bt_ctf_event_class_get_attribute_name_by_index(): Returns the name
 243         of the attribute of a given event class at a given index.
 244 @sa bt_ctf_event_class_get_attribute_value_by_index(): Returns the value
 245         of the attribute of a given event class at a given index.
 246 */
 247 extern int64_t bt_ctf_event_class_get_attribute_count(
 248                 struct bt_ctf_event_class *event_class);
 249
 250 /**
 251 @brief  Returns the name of the attribute at the index \p index of the
 252         CTF IR event class \p event_class.
 253
 254 On success, \p event_class remains the sole owner of the returned
 255 string.
 256
 257 @param[in] event_class  Event class of which to get the name
 258                         of an attribute.
 259 @param[in] index        Index of the attribute of which to get the name.
 260 @returns                Attribute name, or \c NULL on error.
 261
 262 @prenotnull{event_class}
 263 @pre \p index is lesser than the number of attributes contained by
 264         \p event_class.
 265 @postrefcountsame{event_class}
 266
 267 @sa bt_ctf_event_class_get_attribute_value_by_index(): Returns the value
 268         of the attribute of a given event class at a given index.
 269 */
 270 extern const char *
 271 bt_ctf_event_class_get_attribute_name_by_index(
 272                 struct bt_ctf_event_class *event_class, uint64_t index);
 273
 274 /**
 275 @brief  Returns the value of the attribute at the index \p index of the
 276         CTF IR event class \p event_class.
 277
 278 @param[in] event_class  Event class of which to get the value
 279                         of an attribute.
 280 @param[in] index        Index of the attribute of which to get the value.
 281 @returns                Attribute value, or \c NULL on error.
 282
 283 @prenotnull{event_class}
 284 @pre \p index is lesser than the number of attributes contained by
 285         \p event_class.
 286 @postsuccessrefcountretinc
 287 @postrefcountsame{event_class}
 288
 289 @sa bt_ctf_event_class_get_attribute_name_by_index(): Returns the name
 290         of the attribute of a given event class at a given index.
 291 */
 292 extern struct bt_value *
 293 bt_ctf_event_class_get_attribute_value_by_index(
 294                 struct bt_ctf_event_class *event_class, uint64_t index);
 295
 296 /**
 297 @brief  Returns the value of the attribute named \p name of the CTF IR
 298         event class \p event_class.
 299
 300 On success, the reference count of the returned value object is
 301 incremented.
 302
 303 @param[in] event_class  Event class of which to get the value
 304                         of an attribute.
 305 @param[in] name         Name of the attribute to get.
 306 @returns                Attribute value, or \c NULL on error.
 307
 308 @prenotnull{event_class}
 309 @prenotnull{name}
 310 @postsuccessrefcountretinc
 311 @postrefcountsame{event_class}
 312 */
 313 extern struct bt_value *
 314 bt_ctf_event_class_get_attribute_value_by_name(
 315                 struct bt_ctf_event_class *event_class, const char *name);
 316
 317 /**
 318 @brief  Sets the attribute named \p name of the CTF IR event class
 319         \p event_class to the value \p value.
 320
 321 Valid attributes, as of Babeltrace \btversion, are:
 322
 323 - <code>id</code>: \em must be an integer value object with a raw value
 324   that is greater than or equal to 0. This represents the event class's
 325   numeric ID and you can also set it with bt_ctf_event_class_set_id().
 326
 327 - <code>name</code>: must be a string value object. This represents
 328   the name of the event class.
 329
 330 - <code>loglevel</code>: must be an integer value object with a raw
 331   value greater than or equal to 0. This represents the numeric log level
 332   associated with this event class. Log level values
 333   are application-specific.
 334
 335 - <code>model.emf.uri</code>: must be a string value object. This
 336   represents the application-specific Eclipse Modeling Framework URI
 337   of the event class.
 338
 339 @param[in] event_class  Event class of which to set an
 340                         attribute.
 341 @param[in] name         Attribute name (copied on success).
 342 @param[in] value        Attribute value.
 343 @returns                0 on success, or a negative value on error.
 344
 345 @prenotnull{event_class}
 346 @prenotnull{name}
 347 @prenotnull{value}
 348 @prehot{event_class}
 349 @postrefcountsame{event_class}
 350 @postsuccessrefcountinc{value}
 351
 352 @sa bt_ctf_event_class_get_attribute_value_by_name(): Returns the
 353         attribute of a given event class having a given name.
 354 */
 355 extern int bt_ctf_event_class_set_attribute(
 356                 struct bt_ctf_event_class *event_class, const char *name,
 357                 struct bt_value *value);
 358
 359 /** @} */
 360
 361 /**
 362 @name Contained field types functions
 363 @{
 364 */
 365
 366 /**
 367 @brief  Returns the context field type of the CTF IR event class
 368         \p event_class.
 369
 370 @param[in] event_class  Event class of which to get the context field type.
 371 @returns                Context field type of \p event_class, or \c NULL if
 372                         \p event_class has no context field type or on error.
 373
 374 @prenotnull{event_class}
 375 @postrefcountsame{event_class}
 376 @post <strong>On success, if the return value is a field type</strong>, its
 377         reference count is incremented.
 378
 379 @sa bt_ctf_event_class_set_context_type(): Sets the context field type of a
 380         given event class.
 381 */
 382 extern struct bt_ctf_field_type *bt_ctf_event_class_get_context_type(
 383                 struct bt_ctf_event_class *event_class);
 384
 385 /**
 386 @brief  Sets the context field type of the CTF IR event class \p event_class to
 387         \p context_type, or unsets the current context field type from
 388         \p event_class.
 389
 390 If \p context_type is \c NULL, then this function unsets the current context
 391 field type from \p event_class, effectively making \p event_class an event class
 392 without a context field type.
 393
 394 As of Babeltrace \btversion, if \p context_type is not \c NULL,
 395 \p context_type \em must be a CTF IR structure field type object.
 396
 397 @param[in] event_class          Event class of which to set the context field
 398                                 type.
 399 @param[in] context_type         Context field type, or \c NULL to unset the
 400                                 current context field type.
 401 @returns                        0 on success, or a negative value on error.
 402
 403 @prenotnull{event_class}
 404 @prehot{event_class}
 405 @pre <strong>If \p context_type is not \c NULL</strong>, \p context_type is a
 406         CTF IR structure field type.
 407 @postrefcountsame{event_class}
 408 @post <strong>On success, if \p context_type is not \c NULL</strong>,
 409         the reference count of \p context_type is incremented.
 410
 411 @sa bt_ctf_event_class_get_context_type(): Returns the context field type of a
 412         given event class.
 413 */
 414 extern int bt_ctf_event_class_set_context_type(
 415                 struct bt_ctf_event_class *event_class,
 416                 struct bt_ctf_field_type *context_type);
 417
 418 /**
 419 @brief  Returns the payload field type of the CTF IR event class
 420         \p event_class.
 421
 422 @param[in] event_class  Event class of which to get the payload field type.
 423 @returns                Payload field type of \p event_class, or \c NULL if
 424                         \p event_class has no payload field type or on error.
 425
 426 @prenotnull{event_class}
 427 @postrefcountsame{event_class}
 428 @post <strong>On success, if the return value is a field type</strong>, its
 429         reference count is incremented.
 430
 431 @sa bt_ctf_event_class_set_payload_type(): Sets the payload field type of a
 432         given event class.
 433 */
 434 extern struct bt_ctf_field_type *bt_ctf_event_class_get_payload_type(
 435                 struct bt_ctf_event_class *event_class);
 436
 437 /**
 438 @brief  Sets the payload field type of the CTF IR event class \p event_class to
 439         \p payload_type, or unsets the current payload field type from
 440         \p event_class.
 441
 442 If \p payload_type is \c NULL, then this function unsets the current payload
 443 field type from \p event_class, effectively making \p event_class an event class
 444 without a payload field type.
 445
 446 As of Babeltrace \btversion, if \p payload_type is not \c NULL,
 447 \p payload_type \em must be a CTF IR structure field type object.
 448
 449 @param[in] event_class          Event class of which to set the payload field
 450                                 type.
 451 @param[in] payload_type         Payload field type, or \c NULL to unset the
 452                                 current payload field type.
 453 @returns                        0 on success, or a negative value on error.
 454
 455 @prenotnull{event_class}
 456 @prehot{event_class}
 457 @pre <strong>If \p payload_type is not \c NULL</strong>, \p payload_type is a
 458         CTF IR structure field type.
 459 @postrefcountsame{event_class}
 460 @post <strong>On success, if \p payload_type is not \c NULL</strong>,
 461         the reference count of \p payload_type is incremented.
 462
 463 @sa bt_ctf_event_class_get_payload_type(): Returns the payload field type of a
 464         given event class.
 465 */
 466 extern int bt_ctf_event_class_set_payload_type(
 467                 struct bt_ctf_event_class *event_class,
 468                 struct bt_ctf_field_type *payload_type);
 469
 470 /**
 471 @brief  Returns the number of fields contained in the
 472         payload field type of the CTF IR event class \p event_class.
 473
 474 @remarks
 475 Calling this function is the equivalent of getting the payload field
 476 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 477 getting its field count with
 478 bt_ctf_field_type_structure_get_field_count().
 479
 480 @param[in] event_class  Event class of which to get the number
 481                         of fields contained in its payload field type.
 482 @returns                Number of fields in the payload field type
 483                         of \p event_class, or a negative value on error.
 484
 485 @prenotnull{event_class}
 486 @postrefcountsame{event_class}
 487 */
 488 extern int64_t bt_ctf_event_class_get_payload_type_field_count(
 489                 struct bt_ctf_event_class *event_class);
 490
 491 /**
 492 @brief  Returns the type and the name of the field at index \p index
 493         in the payload field type of the CTF IR event class
 494         \p event_class.
 495
 496 On success, the field's type is placed in \p *field_type if
 497 \p field_type is not \c NULL. The field's name is placed in
 498 \p *name if \p name is not \c NULL. \p event_class remains the sole
 499 owner of \p *name.
 500
 501 Both \p name and \p field_type can be \c NULL if the caller is not
 502 interested in one of them.
 503
 504 @remarks
 505 Calling this function is the equivalent of getting the payload field
 506 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 507 getting the type and name of one of its field with
 508 bt_ctf_field_type_structure_get_field().
 509
 510 @param[in] event_class  Event class of which to get the type and name
 511                         of a field in its payload field type.
 512 @param[out] field_name  Name of the field at the index
 513                         \p index in the payload field type of
 514                         \p event_class (can be \c NULL).
 515 @param[out] field_type  Type of the field at the index \p index in the
 516                         payload field type of \p event_class
 517                         (can be \c NULL).
 518 @param[in] index        Index of the payload field type's field to find.
 519 @returns                0 on success, or a negative value on error.
 520
 521 @prenotnull{event_class}
 522 @pre \p index is lesser than the number of fields contained in the
 523         payload field type of \p event_class (see
 524         bt_ctf_event_class_get_payload_type_field_count()).
 525 @postrefcountsame{event_class}
 526 @post <strong>On success, if \p field_type is not \c NULL</strong>, the
 527         reference count of \p *field_type is incremented.
 528 */
 529 extern int bt_ctf_event_class_get_payload_type_field_by_index(
 530                 struct bt_ctf_event_class *event_class,
 531                 const char **field_name, struct bt_ctf_field_type **field_type,
 532                 uint64_t index);
 533
 534 /**
 535 @brief  Returns the type of the field named \p name in the payload
 536         field type of the CTF IR event class \p event_class.
 537
 538 @remarks
 539 Calling this function is the equivalent of getting the payload field
 540 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 541 getting the type of one of its field with
 542 bt_ctf_field_type_structure_get_field_type_by_name().
 543
 544 @param[in] event_class  Event class of which to get the type of a
 545                         payload field type's field.
 546 @param[in] name         Name of the payload field type's field to get.
 547 @returns                Type of the field named \p name in the payload
 548                         field type of \p event_class, or \c NULL if
 549                         the function cannot find the field or
 550                         on error.
 551
 552 @prenotnull{event_class}
 553 @prenotnull{name}
 554 @postrefcountsame{event_class}
 555 @postsuccessrefcountretinc
 556 */
 557 extern struct bt_ctf_field_type *
 558 bt_ctf_event_class_get_payload_type_field_type_by_name(
 559                 struct bt_ctf_event_class *event_class, const char *name);
 560
 561 /* Pre-2.0 CTF writer compatibility */
 562 #define bt_ctf_event_class_get_field_by_name bt_ctf_event_class_get_payload_type_field_type_by_name
 563
 564 /**
 565 @brief  Adds a field named \p name with the type \p field_type to the
 566         payload field type of the CTF IR event class \p event_class.
 567
 568 @remarks
 569 Calling this function is the equivalent of getting the payload field
 570 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 571 adding a field to it with bt_ctf_field_type_structure_add_field().
 572
 573 @param[in] event_class  Event class containing the payload field
 574                         type in which to add a field.
 575 @param[in] field_type   Type of the field to add.
 576 @param[in] name         Name of the field to add (copied on
 577                         success).
 578 @returns                0 on success, or a negative value on error.
 579
 580 @prenotnull{event_class}
 581 @prenotnull{type}
 582 @prenotnull{name}
 583 @prehot{event_class}
 584 @postrefcountsame{event_class}
 585 @postsuccessrefcountinc{field_type}
 586 */
 587 extern int bt_ctf_event_class_add_field(struct bt_ctf_event_class *event_class,
 588                 struct bt_ctf_field_type *field_type,
 589                 const char *name);
 590
 591 /** @} */
 592
 593 /** @} */
 594
 595 #ifdef __cplusplus
 596 }
 597 #endif
 598
 599 #endif /* BABELTRACE_CTF_IR_EVENT_CLASS_H */