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 @postrefcountsame{event_class}
 220
 221 @sa bt_ctf_event_class_get_id(): Returns the numeric ID of a given
 222         event class.
 223 */
 224 extern int bt_ctf_event_class_set_id(
 225                 struct bt_ctf_event_class *event_class, uint32_t id);
 226
 227 /**
 228 @brief  Returns the number of attributes contained in the CTF IR event
 229         class \p event_class.
 230
 231 @param[in] event_class  Event class of which to get the number
 232                         of contained attributes.
 233 @returns                Number of contained attributes in
 234                         \p event_class, or a negative value on error.
 235
 236 @prenotnull{event_class}
 237 @postrefcountsame{event_class}
 238
 239 @sa bt_ctf_event_class_get_attribute_name(): Returns the name of
 240         the attribute of a given event class at a given index.
 241 @sa bt_ctf_event_class_get_attribute_value(): Returns the value of
 242         the attribute of a given event class at a given index.
 243 */
 244 extern int64_t bt_ctf_event_class_get_attribute_count(
 245                 struct bt_ctf_event_class *event_class);
 246
 247 /**
 248 @brief  Returns the name of the attribute at the index \p index of the
 249         CTF IR event class \p event_class.
 250
 251 On success, \p event_class remains the sole owner of the returned
 252 string.
 253
 254 @param[in] event_class  Event class of which to get the name
 255                         of an attribute.
 256 @param[in] index        Index of the attribute of which to get the name.
 257 @returns                Attribute name, or \c NULL on error.
 258
 259 @prenotnull{event_class}
 260 @pre \p index is lesser than the number of attributes contained by
 261         \p event_class.
 262 @postrefcountsame{event_class}
 263
 264 @sa bt_ctf_event_class_get_attribute_value(): Returns the value of
 265         the attribute of a given event class at a given index.
 266 */
 267 extern const char *
 268 bt_ctf_event_class_get_attribute_name(
 269                 struct bt_ctf_event_class *event_class, int index);
 270
 271 /**
 272 @brief  Returns the value of the attribute at the index \p index of the
 273         CTF IR event class \p event_class.
 274
 275 @param[in] event_class  Event class of which to get the value
 276                         of an attribute.
 277 @param[in] index        Index of the attribute of which to get the value.
 278 @returns                Attribute value, or \c NULL on error.
 279
 280 @prenotnull{event_class}
 281 @pre \p index is lesser than the number of attributes contained by
 282         \p event_class.
 283 @postsuccessrefcountretinc
 284 @postrefcountsame{event_class}
 285
 286 @sa bt_ctf_event_class_get_attribute_name(): Returns the name of
 287         the attribute of a given event class at a given index.
 288 */
 289 extern struct bt_value *
 290 bt_ctf_event_class_get_attribute_value(struct bt_ctf_event_class *event_class,
 291                 int index);
 292
 293 /**
 294 @brief  Returns the value of the attribute named \p name of the CTF IR
 295         event class \p event_class.
 296
 297 On success, the reference count of the returned value object is
 298 incremented.
 299
 300 @param[in] event_class  Event class of which to get the value
 301                         of an attribute.
 302 @param[in] name         Name of the attribute to get.
 303 @returns                Attribute value, or \c NULL on error.
 304
 305 @prenotnull{event_class}
 306 @prenotnull{name}
 307 @postsuccessrefcountretinc
 308 @postrefcountsame{event_class}
 309 */
 310 extern struct bt_value *
 311 bt_ctf_event_class_get_attribute_value_by_name(
 312                 struct bt_ctf_event_class *event_class, const char *name);
 313
 314 /**
 315 @brief  Sets the attribute named \p name of the CTF IR event class
 316         \p event_class to the value \p value.
 317
 318 Valid attributes, as of Babeltrace \btversion, are:
 319
 320 - <code>id</code>: \em must be an integer value object with a raw value
 321   that is greater than or equal to 0. This represents the event class's
 322   numeric ID and you can also set it with bt_ctf_event_class_set_id().
 323
 324 - <code>name</code>: must be a string value object. This represents
 325   the name of the event class.
 326
 327 - <code>loglevel</code>: must be an integer value object with a raw
 328   value greater than or equal to 0. This represents the numeric log level
 329   associated with this event class. Log level values
 330   are application-specific.
 331
 332 - <code>model.emf.uri</code>: must be a string value object. This
 333   represents the application-specific Eclipse Modeling Framework URI
 334   of the event class.
 335
 336 @param[in] event_class  Event class of which to set an
 337                         attribute.
 338 @param[in] name         Attribute name (copied on success).
 339 @param[in] value        Attribute value.
 340 @returns                0 on success, or a negative value on error.
 341
 342 @prenotnull{event_class}
 343 @prenotnull{name}
 344 @prenotnull{value}
 345 @prehot{event_class}
 346 @postrefcountsame{event_class}
 347 @postsuccessrefcountinc{value}
 348
 349 @sa bt_ctf_event_class_get_attribute_value_by_name(): Returns the
 350         attribute of a given event class having a given name.
 351 */
 352 extern int bt_ctf_event_class_set_attribute(
 353                 struct bt_ctf_event_class *event_class, const char *name,
 354                 struct bt_value *value);
 355
 356 /** @} */
 357
 358 /**
 359 @name Contained field types functions
 360 @{
 361 */
 362
 363 /**
 364 @brief  Returns the context field type of the CTF IR event class
 365         \p event_class.
 366
 367 @param[in] event_class  Event class of which to get the context field type.
 368 @returns                Context field type of \p event_class, or \c NULL if
 369                         \p event_class has no context field type or on error.
 370
 371 @prenotnull{event_class}
 372 @postrefcountsame{event_class}
 373 @post <strong>On success, if the return value is a field type</strong>, its
 374         reference count is incremented.
 375
 376 @sa bt_ctf_event_class_set_context_type(): Sets the context field type of a
 377         given event class.
 378 */
 379 extern struct bt_ctf_field_type *bt_ctf_event_class_get_context_type(
 380                 struct bt_ctf_event_class *event_class);
 381
 382 /**
 383 @brief  Sets the context field type of the CTF IR event class \p event_class to
 384         \p context_type, or unsets the current context field type from
 385         \p event_class.
 386
 387 If \p context_type is \c NULL, then this function unsets the current context
 388 field type from \p event_class, effectively making \p event_class an event class
 389 without a context field type.
 390
 391 As of Babeltrace \btversion, if \p context_type is not \c NULL,
 392 \p context_type \em must be a CTF IR structure field type object.
 393
 394 @param[in] event_class          Event class of which to set the context field
 395                                 type.
 396 @param[in] context_type         Context field type, or \c NULL to unset the
 397                                 current context field type.
 398 @returns                        0 on success, or a negative value on error.
 399
 400 @prenotnull{event_class}
 401 @prehot{event_class}
 402 @pre <strong>If \p context_type is not \c NULL</strong>, \p context_type is a
 403         CTF IR structure field type.
 404 @postrefcountsame{event_class}
 405 @post <strong>On success, if \p context_type is not \c NULL</strong>,
 406         the reference count of \p context_type is incremented.
 407
 408 @sa bt_ctf_event_class_get_context_type(): Returns the context field type of a
 409         given event class.
 410 */
 411 extern int bt_ctf_event_class_set_context_type(
 412                 struct bt_ctf_event_class *event_class,
 413                 struct bt_ctf_field_type *context_type);
 414
 415 /**
 416 @brief  Returns the payload field type of the CTF IR event class
 417         \p event_class.
 418
 419 @param[in] event_class  Event class of which to get the payload field type.
 420 @returns                Payload field type of \p event_class, or \c NULL if
 421                         \p event_class has no payload field type or on error.
 422
 423 @prenotnull{event_class}
 424 @postrefcountsame{event_class}
 425 @post <strong>On success, if the return value is a field type</strong>, its
 426         reference count is incremented.
 427
 428 @sa bt_ctf_event_class_set_payload_type(): Sets the payload field type of a
 429         given event class.
 430 */
 431 extern struct bt_ctf_field_type *bt_ctf_event_class_get_payload_type(
 432                 struct bt_ctf_event_class *event_class);
 433
 434 /**
 435 @brief  Sets the payload field type of the CTF IR event class \p event_class to
 436         \p payload_type, or unsets the current payload field type from
 437         \p event_class.
 438
 439 If \p payload_type is \c NULL, then this function unsets the current payload
 440 field type from \p event_class, effectively making \p event_class an event class
 441 without a payload field type.
 442
 443 As of Babeltrace \btversion, if \p payload_type is not \c NULL,
 444 \p payload_type \em must be a CTF IR structure field type object.
 445
 446 @param[in] event_class          Event class of which to set the payload field
 447                                 type.
 448 @param[in] payload_type         Payload field type, or \c NULL to unset the
 449                                 current payload field type.
 450 @returns                        0 on success, or a negative value on error.
 451
 452 @prenotnull{event_class}
 453 @prehot{event_class}
 454 @pre <strong>If \p payload_type is not \c NULL</strong>, \p payload_type is a
 455         CTF IR structure field type.
 456 @postrefcountsame{event_class}
 457 @post <strong>On success, if \p payload_type is not \c NULL</strong>,
 458         the reference count of \p payload_type is incremented.
 459
 460 @sa bt_ctf_event_class_get_payload_type(): Returns the payload field type of a
 461         given event class.
 462 */
 463 extern int bt_ctf_event_class_set_payload_type(
 464                 struct bt_ctf_event_class *event_class,
 465                 struct bt_ctf_field_type *payload_type);
 466
 467 /**
 468 @brief  Returns the number of fields contained in the
 469         payload field type of the CTF IR event class \p event_class.
 470
 471 @remarks
 472 Calling this function is the equivalent of getting the payload field
 473 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 474 getting its field count with
 475 bt_ctf_field_type_structure_get_field_count().
 476
 477 @param[in] event_class  Event class of which to get the number
 478                         of fields contained in its payload field type.
 479 @returns                Number of fields in the payload field type
 480                         of \p event_class, or a negative value on error.
 481
 482 @prenotnull{event_class}
 483 @postrefcountsame{event_class}
 484 */
 485 extern int64_t bt_ctf_event_class_get_field_count(
 486                 struct bt_ctf_event_class *event_class);
 487
 488 /**
 489 @brief  Returns the type and the name of the field at index \p index
 490         in the payload field type of the CTF IR event class
 491         \p event_class.
 492
 493 On success, the field's type is placed in \p *field_type if
 494 \p field_type is not \c NULL. The field's name is placed in
 495 \p *name if \p name is not \c NULL. \p event_class remains the sole
 496 owner of \p *name.
 497
 498 Both \p name and \p field_type can be \c NULL if the caller is not
 499 interested in one of them.
 500
 501 @remarks
 502 Calling this function is the equivalent of getting the payload field
 503 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 504 getting the type and name of one of its field with
 505 bt_ctf_field_type_structure_get_field().
 506
 507 @param[in] event_class  Event class of which to get the type and name
 508                         of a field in its payload field type.
 509 @param[out] field_name  Name of the field at the index
 510                         \p index in the payload field type of
 511                         \p event_class (can be \c NULL).
 512 @param[out] field_type  Type of the field at the index \p index in the
 513                         payload field type of \p event_class
 514                         (can be \c NULL).
 515 @param[in] index        Index of the payload field type's field to find.
 516 @returns                0 on success, or a negative value on error.
 517
 518 @prenotnull{event_class}
 519 @pre \p index is lesser than the number of fields contained in the
 520         payload field type of \p event_class (see
 521         bt_ctf_event_class_get_field_count()).
 522 @postrefcountsame{event_class}
 523 @post <strong>On success, if \p field_type is not \c NULL</strong>, the
 524         reference count of \p *field_type is incremented.
 525 */
 526 extern int bt_ctf_event_class_get_field(struct bt_ctf_event_class *event_class,
 527                 const char **field_name, struct bt_ctf_field_type **field_type,
 528                 int index);
 529
 530 /**
 531 @brief  Returns the type of the field named \p name in the payload
 532         field type of the CTF IR event class \p event_class.
 533
 534 @remarks
 535 Calling this function is the equivalent of getting the payload field
 536 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 537 getting the type of one of its field with
 538 bt_ctf_field_type_structure_get_field_type_by_name().
 539
 540 @param[in] event_class  Event class of which to get the type of a
 541                         payload field type's field.
 542 @param[in] name         Name of the payload field type's field to get.
 543 @returns                Type of the field named \p name in the payload
 544                         field type of \p event_class, or \c NULL if
 545                         the function cannot find the field or
 546                         on error.
 547
 548 @prenotnull{event_class}
 549 @prenotnull{name}
 550 @postrefcountsame{event_class}
 551 @postsuccessrefcountretinc
 552 */
 553 extern struct bt_ctf_field_type *bt_ctf_event_class_get_field_by_name(
 554                 struct bt_ctf_event_class *event_class, const char *name);
 555
 556 /**
 557 @brief  Adds a field named \p name with the type \p field_type to the
 558         payload field type of the CTF IR event class \p event_class.
 559
 560 @remarks
 561 Calling this function is the equivalent of getting the payload field
 562 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 563 adding a field to it with bt_ctf_field_type_structure_add_field().
 564
 565 @param[in] event_class  Event class containing the payload field
 566                         type in which to add a field.
 567 @param[in] field_type   Type of the field to add.
 568 @param[in] name         Name of the field to add (copied on
 569                         success).
 570 @returns                0 on success, or a negative value on error.
 571
 572 @prenotnull{event_class}
 573 @prenotnull{type}
 574 @prenotnull{name}
 575 @prehot{event_class}
 576 @postrefcountsame{event_class}
 577 @postsuccessrefcountinc{field_type}
 578 */
 579 extern int bt_ctf_event_class_add_field(struct bt_ctf_event_class *event_class,
 580                 struct bt_ctf_field_type *field_type,
 581                 const char *name);
 582
 583 /** @} */
 584
 585 /** @} */
 586
 587 #ifdef __cplusplus
 588 }
 589 #endif
 590
 591 #endif /* BABELTRACE_CTF_IR_EVENT_CLASS_H */