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 The event class is created \em without an event context
 125 \link ctfirfieldtypes field type\endlink and with an empty event
 126 payload field type.
 127
 128 Upon creation, the event class's ID is <em>not set</em>. You
 129 can set it to a specific value with bt_ctf_event_class_set_id(). If it
 130 is still unset when you call bt_ctf_stream_class_add_event_class(), then
 131 the stream class assigns a unique ID to this event class before
 132 freezing it.
 133
 134 @param[in] name Name of the event class to create (copied on success).
 135 @returns        Created event class, or \c NULL on error.
 136
 137 @prenotnull{name}
 138 @postsuccessrefcountret1
 139 */
 140 extern struct bt_ctf_event_class *bt_ctf_event_class_create(const char *name);
 141
 142 /**
 143 @brief  Returns the parent CTF IR stream class of the CTF IR event
 144         class \p event_class.
 145
 146 It is possible that the event class was not added to a stream class
 147 yet, in which case this function returns \c NULL. You can add an
 148 event class to a stream class with
 149 bt_ctf_stream_class_add_event_class().
 150
 151 @param[in] event_class  Event class of which to get the parent
 152                         stream class.
 153 @returns                Parent stream class of \p event_class,
 154                         or \c NULL if \p event_class was not
 155                         added to a stream class yet or on error.
 156
 157 @prenotnull{event_class}
 158 @postrefcountsame{event_class}
 159 @postsuccessrefcountretinc
 160
 161 @sa bt_ctf_stream_class_add_event_class(): Add an event class to
 162         a stream class.
 163 */
 164 extern struct bt_ctf_stream_class *bt_ctf_event_class_get_stream_class(
 165                 struct bt_ctf_event_class *event_class);
 166
 167 /** @} */
 168
 169 /**
 170 @name Attribute functions
 171 @{
 172 */
 173
 174 /**
 175 @brief  Returns the name of the CTF IR event class \p event_class.
 176
 177 On success, \p event_class remains the sole owner of the returned
 178 string.
 179
 180 @param[in] event_class  Event class of which to get the name.
 181 @returns                Name of event class \p event_class, or
 182                         \c NULL on error.
 183
 184 @prenotnull{event_class}
 185 @postrefcountsame{event_class}
 186 */
 187 extern const char *bt_ctf_event_class_get_name(
 188                 struct bt_ctf_event_class *event_class);
 189
 190 /**
 191 @brief  Returns the numeric ID of the CTF IR event class \p event_class.
 192
 193 @param[in] event_class  Event class of which to get the numeric ID.
 194 @returns                ID of event class \p event_class, or a
 195                         negative value on error.
 196
 197 @prenotnull{event_class}
 198 @postrefcountsame{event_class}
 199
 200 @sa bt_ctf_event_class_set_id(): Sets the numeric ID of a given
 201         event class.
 202 */
 203 extern int64_t bt_ctf_event_class_get_id(
 204                 struct bt_ctf_event_class *event_class);
 205
 206 /**
 207 @brief  Sets the numeric ID of the CTF IR event class
 208         \p event_class to \p id.
 209
 210 \p id must be unique amongst the IDs of all the event classes
 211 of the stream class to which you eventually add \p event_class.
 212
 213 @param[in] event_class  Event class of which to set the numeric ID.
 214 @param[in] id           ID of the event class.
 215 @returns                0 on success, or a negative value on error.
 216
 217 @prenotnull{event_class}
 218 @prehot{event_class}
 219 @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
 220 @postrefcountsame{event_class}
 221
 222 @sa bt_ctf_event_class_get_id(): Returns the numeric ID of a given
 223         event class.
 224 */
 225 extern int bt_ctf_event_class_set_id(
 226                 struct bt_ctf_event_class *event_class, uint64_t id);
 227
 228 /**
 229 @brief  Returns the number of attributes contained in the CTF IR event
 230         class \p event_class.
 231
 232 @param[in] event_class  Event class of which to get the number
 233                         of contained attributes.
 234 @returns                Number of contained attributes in
 235                         \p event_class, or a negative value on error.
 236
 237 @prenotnull{event_class}
 238 @postrefcountsame{event_class}
 239
 240 @sa bt_ctf_event_class_get_attribute_name_by_index(): Returns the name
 241         of the attribute of a given event class at a given index.
 242 @sa bt_ctf_event_class_get_attribute_value_by_index(): Returns the value
 243         of the attribute of a given event class at a given index.
 244 */
 245 extern int64_t bt_ctf_event_class_get_attribute_count(
 246                 struct bt_ctf_event_class *event_class);
 247
 248 /**
 249 @brief  Returns the name of the attribute at the index \p index of the
 250         CTF IR event class \p event_class.
 251
 252 On success, \p event_class remains the sole owner of the returned
 253 string.
 254
 255 @param[in] event_class  Event class of which to get the name
 256                         of an attribute.
 257 @param[in] index        Index of the attribute of which to get the name.
 258 @returns                Attribute name, or \c NULL on error.
 259
 260 @prenotnull{event_class}
 261 @pre \p index is lesser than the number of attributes contained by
 262         \p event_class.
 263 @postrefcountsame{event_class}
 264
 265 @sa bt_ctf_event_class_get_attribute_value_by_index(): Returns the value
 266         of the attribute of a given event class at a given index.
 267 */
 268 extern const char *
 269 bt_ctf_event_class_get_attribute_name_by_index(
 270                 struct bt_ctf_event_class *event_class, uint64_t index);
 271
 272 /**
 273 @brief  Returns the value of the attribute at the index \p index of the
 274         CTF IR event class \p event_class.
 275
 276 @param[in] event_class  Event class of which to get the value
 277                         of an attribute.
 278 @param[in] index        Index of the attribute of which to get the value.
 279 @returns                Attribute value, or \c NULL on error.
 280
 281 @prenotnull{event_class}
 282 @pre \p index is lesser than the number of attributes contained by
 283         \p event_class.
 284 @postsuccessrefcountretinc
 285 @postrefcountsame{event_class}
 286
 287 @sa bt_ctf_event_class_get_attribute_name_by_index(): Returns the name
 288         of the attribute of a given event class at a given index.
 289 */
 290 extern struct bt_value *
 291 bt_ctf_event_class_get_attribute_value_by_index(
 292                 struct bt_ctf_event_class *event_class, uint64_t index);
 293
 294 /**
 295 @brief  Returns the value of the attribute named \p name of the CTF IR
 296         event class \p event_class.
 297
 298 On success, the reference count of the returned value object is
 299 incremented.
 300
 301 @param[in] event_class  Event class of which to get the value
 302                         of an attribute.
 303 @param[in] name         Name of the attribute to get.
 304 @returns                Attribute value, or \c NULL on error.
 305
 306 @prenotnull{event_class}
 307 @prenotnull{name}
 308 @postsuccessrefcountretinc
 309 @postrefcountsame{event_class}
 310 */
 311 extern struct bt_value *
 312 bt_ctf_event_class_get_attribute_value_by_name(
 313                 struct bt_ctf_event_class *event_class, const char *name);
 314
 315 /**
 316 @brief  Sets the attribute named \p name of the CTF IR event class
 317         \p event_class to the value \p value.
 318
 319 Valid attributes, as of Babeltrace \btversion, are:
 320
 321 - <code>id</code>: \em must be an integer value object with a raw value
 322   that is greater than or equal to 0. This represents the event class's
 323   numeric ID and you can also set it with bt_ctf_event_class_set_id().
 324
 325 - <code>name</code>: must be a string value object. This represents
 326   the name of the event class.
 327
 328 - <code>loglevel</code>: must be an integer value object with a raw
 329   value greater than or equal to 0. This represents the numeric log level
 330   associated with this event class. Log level values
 331   are application-specific.
 332
 333 - <code>model.emf.uri</code>: must be a string value object. This
 334   represents the application-specific Eclipse Modeling Framework URI
 335   of the event class.
 336
 337 @param[in] event_class  Event class of which to set an
 338                         attribute.
 339 @param[in] name         Attribute name (copied on success).
 340 @param[in] value        Attribute value.
 341 @returns                0 on success, or a negative value on error.
 342
 343 @prenotnull{event_class}
 344 @prenotnull{name}
 345 @prenotnull{value}
 346 @prehot{event_class}
 347 @postrefcountsame{event_class}
 348 @postsuccessrefcountinc{value}
 349
 350 @sa bt_ctf_event_class_get_attribute_value_by_name(): Returns the
 351         attribute of a given event class having a given name.
 352 */
 353 extern int bt_ctf_event_class_set_attribute(
 354                 struct bt_ctf_event_class *event_class, const char *name,
 355                 struct bt_value *value);
 356
 357 /** @} */
 358
 359 /**
 360 @name Contained field types functions
 361 @{
 362 */
 363
 364 /**
 365 @brief  Returns the context field type of the CTF IR event class
 366         \p event_class.
 367
 368 @param[in] event_class  Event class of which to get the context field type.
 369 @returns                Context field type of \p event_class, or \c NULL if
 370                         \p event_class has no context field type or on error.
 371
 372 @prenotnull{event_class}
 373 @postrefcountsame{event_class}
 374 @post <strong>On success, if the return value is a field type</strong>, its
 375         reference count is incremented.
 376
 377 @sa bt_ctf_event_class_set_context_type(): Sets the context field type of a
 378         given event class.
 379 */
 380 extern struct bt_ctf_field_type *bt_ctf_event_class_get_context_type(
 381                 struct bt_ctf_event_class *event_class);
 382
 383 /**
 384 @brief  Sets the context field type of the CTF IR event class \p event_class to
 385         \p context_type, or unsets the current context field type from
 386         \p event_class.
 387
 388 If \p context_type is \c NULL, then this function unsets the current context
 389 field type from \p event_class, effectively making \p event_class an event class
 390 without a context field type.
 391
 392 As of Babeltrace \btversion, if \p context_type is not \c NULL,
 393 \p context_type \em must be a CTF IR structure field type object.
 394
 395 @param[in] event_class          Event class of which to set the context field
 396                                 type.
 397 @param[in] context_type         Context field type, or \c NULL to unset the
 398                                 current context field type.
 399 @returns                        0 on success, or a negative value on error.
 400
 401 @prenotnull{event_class}
 402 @prehot{event_class}
 403 @pre <strong>If \p context_type is not \c NULL</strong>, \p context_type is a
 404         CTF IR structure field type.
 405 @postrefcountsame{event_class}
 406 @post <strong>On success, if \p context_type is not \c NULL</strong>,
 407         the reference count of \p context_type is incremented.
 408
 409 @sa bt_ctf_event_class_get_context_type(): Returns the context field type of a
 410         given event class.
 411 */
 412 extern int bt_ctf_event_class_set_context_type(
 413                 struct bt_ctf_event_class *event_class,
 414                 struct bt_ctf_field_type *context_type);
 415
 416 /**
 417 @brief  Returns the payload field type of the CTF IR event class
 418         \p event_class.
 419
 420 @param[in] event_class  Event class of which to get the payload field type.
 421 @returns                Payload field type of \p event_class, or \c NULL if
 422                         \p event_class has no payload field type or on error.
 423
 424 @prenotnull{event_class}
 425 @postrefcountsame{event_class}
 426 @post <strong>On success, if the return value is a field type</strong>, its
 427         reference count is incremented.
 428
 429 @sa bt_ctf_event_class_set_payload_type(): Sets the payload field type of a
 430         given event class.
 431 */
 432 extern struct bt_ctf_field_type *bt_ctf_event_class_get_payload_type(
 433                 struct bt_ctf_event_class *event_class);
 434
 435 /**
 436 @brief  Sets the payload field type of the CTF IR event class \p event_class to
 437         \p payload_type, or unsets the current payload field type from
 438         \p event_class.
 439
 440 If \p payload_type is \c NULL, then this function unsets the current payload
 441 field type from \p event_class, effectively making \p event_class an event class
 442 without a payload field type.
 443
 444 As of Babeltrace \btversion, if \p payload_type is not \c NULL,
 445 \p payload_type \em must be a CTF IR structure field type object.
 446
 447 @param[in] event_class          Event class of which to set the payload field
 448                                 type.
 449 @param[in] payload_type         Payload field type, or \c NULL to unset the
 450                                 current payload field type.
 451 @returns                        0 on success, or a negative value on error.
 452
 453 @prenotnull{event_class}
 454 @prehot{event_class}
 455 @pre <strong>If \p payload_type is not \c NULL</strong>, \p payload_type is a
 456         CTF IR structure field type.
 457 @postrefcountsame{event_class}
 458 @post <strong>On success, if \p payload_type is not \c NULL</strong>,
 459         the reference count of \p payload_type is incremented.
 460
 461 @sa bt_ctf_event_class_get_payload_type(): Returns the payload field type of a
 462         given event class.
 463 */
 464 extern int bt_ctf_event_class_set_payload_type(
 465                 struct bt_ctf_event_class *event_class,
 466                 struct bt_ctf_field_type *payload_type);
 467
 468 /**
 469 @brief  Returns the number of fields contained in the
 470         payload field type of the CTF IR event class \p event_class.
 471
 472 @remarks
 473 Calling this function is the equivalent of getting the payload field
 474 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 475 getting its field count with
 476 bt_ctf_field_type_structure_get_field_count().
 477
 478 @param[in] event_class  Event class of which to get the number
 479                         of fields contained in its payload field type.
 480 @returns                Number of fields in the payload field type
 481                         of \p event_class, or a negative value on error.
 482
 483 @prenotnull{event_class}
 484 @postrefcountsame{event_class}
 485 */
 486 extern int64_t bt_ctf_event_class_get_payload_type_field_count(
 487                 struct bt_ctf_event_class *event_class);
 488
 489 /**
 490 @brief  Returns the type and the name of the field at index \p index
 491         in the payload field type of the CTF IR event class
 492         \p event_class.
 493
 494 On success, the field's type is placed in \p *field_type if
 495 \p field_type is not \c NULL. The field's name is placed in
 496 \p *name if \p name is not \c NULL. \p event_class remains the sole
 497 owner of \p *name.
 498
 499 Both \p name and \p field_type can be \c NULL if the caller is not
 500 interested in one of them.
 501
 502 @remarks
 503 Calling this function is the equivalent of getting the payload field
 504 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 505 getting the type and name of one of its field with
 506 bt_ctf_field_type_structure_get_field().
 507
 508 @param[in] event_class  Event class of which to get the type and name
 509                         of a field in its payload field type.
 510 @param[out] field_name  Name of the field at the index
 511                         \p index in the payload field type of
 512                         \p event_class (can be \c NULL).
 513 @param[out] field_type  Type of the field at the index \p index in the
 514                         payload field type of \p event_class
 515                         (can be \c NULL).
 516 @param[in] index        Index of the payload field type's field to find.
 517 @returns                0 on success, or a negative value on error.
 518
 519 @prenotnull{event_class}
 520 @pre \p index is lesser than the number of fields contained in the
 521         payload field type of \p event_class (see
 522         bt_ctf_event_class_get_payload_type_field_count()).
 523 @postrefcountsame{event_class}
 524 @post <strong>On success, if \p field_type is not \c NULL</strong>, the
 525         reference count of \p *field_type is incremented.
 526 */
 527 extern int bt_ctf_event_class_get_payload_type_field_by_index(
 528                 struct bt_ctf_event_class *event_class,
 529                 const char **field_name, struct bt_ctf_field_type **field_type,
 530                 uint64_t index);
 531
 532 /**
 533 @brief  Returns the type of the field named \p name in the payload
 534         field type of the CTF IR event class \p event_class.
 535
 536 @remarks
 537 Calling this function is the equivalent of getting the payload field
 538 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 539 getting the type of one of its field with
 540 bt_ctf_field_type_structure_get_field_type_by_name().
 541
 542 @param[in] event_class  Event class of which to get the type of a
 543                         payload field type's field.
 544 @param[in] name         Name of the payload field type's field to get.
 545 @returns                Type of the field named \p name in the payload
 546                         field type of \p event_class, or \c NULL if
 547                         the function cannot find the field or
 548                         on error.
 549
 550 @prenotnull{event_class}
 551 @prenotnull{name}
 552 @postrefcountsame{event_class}
 553 @postsuccessrefcountretinc
 554 */
 555 extern struct bt_ctf_field_type *
 556 bt_ctf_event_class_get_payload_type_field_type_by_name(
 557                 struct bt_ctf_event_class *event_class, const char *name);
 558
 559 /* Pre-2.0 CTF writer compatibility */
 560 #define bt_ctf_event_class_get_field_by_name bt_ctf_event_class_get_payload_type_field_type_by_name
 561
 562 /**
 563 @brief  Adds a field named \p name with the type \p field_type to the
 564         payload field type of the CTF IR event class \p event_class.
 565
 566 @remarks
 567 Calling this function is the equivalent of getting the payload field
 568 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 569 adding a field to it with bt_ctf_field_type_structure_add_field().
 570
 571 @param[in] event_class  Event class containing the payload field
 572                         type in which to add a field.
 573 @param[in] field_type   Type of the field to add.
 574 @param[in] name         Name of the field to add (copied on
 575                         success).
 576 @returns                0 on success, or a negative value on error.
 577
 578 @prenotnull{event_class}
 579 @prenotnull{type}
 580 @prenotnull{name}
 581 @prehot{event_class}
 582 @postrefcountsame{event_class}
 583 @postsuccessrefcountinc{field_type}
 584 */
 585 extern int bt_ctf_event_class_add_field(struct bt_ctf_event_class *event_class,
 586                 struct bt_ctf_field_type *field_type,
 587                 const char *name);
 588
 589 /** @} */
 590
 591 /** @} */
 592
 593 #ifdef __cplusplus
 594 }
 595 #endif
 596
 597 #endif /* BABELTRACE_CTF_IR_EVENT_CLASS_H */