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 int 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
 368                         context field type.
 369 @returns                Context field type of \p event_class,
 370                         or \c NULL on error.
 371
 372 @prenotnull{event_class}
 373 @postrefcountsame{event_class}
 374 @postsuccessrefcountretinc
 375
 376 @sa bt_ctf_event_class_set_context_type(): Sets the context field
 377         type of a 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
 384         \p event_class to \p context_type.
 385
 386 As of Babeltrace \btversion, \p context_type \em must be a
 387 CTF IR structure field type object.
 388
 389 @param[in] event_class  Event class of which to set the context
 390                         field type.
 391 @param[in] context_type Context field type.
 392 @returns                0 on success, or a negative value on error.
 393
 394 @prenotnull{event_class}
 395 @prenotnull{context_type}
 396 @prehot{event_class}
 397 @preisstructft{context_type}
 398 @postrefcountsame{event_class}
 399 @postsuccessrefcountinc{context_type}
 400
 401 @sa bt_ctf_event_class_get_context_type(): Returns the context field
 402         type of a given event class.
 403 */
 404 extern int bt_ctf_event_class_set_context_type(
 405                 struct bt_ctf_event_class *event_class,
 406                 struct bt_ctf_field_type *context_type);
 407
 408 /**
 409 @brief  Returns the payload field type of the CTF IR event class
 410         \p event_class.
 411
 412 @param[in] event_class  Event class of which to get the
 413                         payload field type.
 414 @returns                Payload field type of \p event_class,
 415                         or \c NULL on error.
 416
 417 @prenotnull{event_class}
 418 @postrefcountsame{event_class}
 419 @postsuccessrefcountretinc
 420
 421 @sa bt_ctf_event_class_set_payload_type(): Sets the payload field
 422         type of a given event class.
 423 */
 424 extern struct bt_ctf_field_type *bt_ctf_event_class_get_payload_type(
 425                 struct bt_ctf_event_class *event_class);
 426
 427 /**
 428 @brief  Sets the payload field type of the CTF IR event class
 429         \p event_class to \p payload_type.
 430
 431 As of Babeltrace \btversion, \p payload_type \em must be a
 432 CTF IR structure field type object.
 433
 434 @param[in] event_class  Event class of which to set the payload
 435                         field type.
 436 @param[in] payload_type Payload field type.
 437 @returns                0 on success, or a negative value on error.
 438
 439 @prenotnull{event_class}
 440 @prenotnull{payload_type}
 441 @prehot{event_class}
 442 @preisstructft{payload_type}
 443 @postrefcountsame{event_class}
 444 @postsuccessrefcountinc{payload_type}
 445
 446 @sa bt_ctf_event_class_get_payload_type(): Returns the payload field
 447         type of a given event class.
 448 */
 449 extern int bt_ctf_event_class_set_payload_type(
 450                 struct bt_ctf_event_class *event_class,
 451                 struct bt_ctf_field_type *payload_type);
 452
 453 /**
 454 @brief  Returns the number of fields contained in the
 455         payload field type of the CTF IR event class \p event_class.
 456
 457 @remarks
 458 Calling this function is the equivalent of getting the payload field
 459 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 460 getting its field count with
 461 bt_ctf_field_type_structure_get_field_count().
 462
 463 @param[in] event_class  Event class of which to get the number
 464                         of fields contained in its payload field type.
 465 @returns                Number of fields in the payload field type
 466                         of \p event_class, or a negative value on error.
 467
 468 @prenotnull{event_class}
 469 @postrefcountsame{event_class}
 470 */
 471 extern int bt_ctf_event_class_get_field_count(
 472                 struct bt_ctf_event_class *event_class);
 473
 474 /**
 475 @brief  Returns the type and the name of the field at index \p index
 476         in the payload field type of the CTF IR event class
 477         \p event_class.
 478
 479 On success, the field's type is placed in \p *field_type if
 480 \p field_type is not \c NULL. The field's name is placed in
 481 \p *name if \p name is not \c NULL. \p event_class remains the sole
 482 owner of \p *name.
 483
 484 Both \p name and \p field_type can be \c NULL if the caller is not
 485 interested in one of them.
 486
 487 @remarks
 488 Calling this function is the equivalent of getting the payload field
 489 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 490 getting the type and name of one of its field with
 491 bt_ctf_field_type_structure_get_field().
 492
 493 @param[in] event_class  Event class of which to get the type and name
 494                         of a field in its payload field type.
 495 @param[out] field_name  Name of the field at the index
 496                         \p index in the payload field type of
 497                         \p event_class (can be \c NULL).
 498 @param[out] field_type  Type of the field at the index \p index in the
 499                         payload field type of \p event_class
 500                         (can be \c NULL).
 501 @param[in] index        Index of the payload field type's field to find.
 502 @returns                0 on success, or a negative value on error.
 503
 504 @prenotnull{event_class}
 505 @pre \p index is lesser than the number of fields contained in the
 506         payload field type of \p event_class (see
 507         bt_ctf_event_class_get_field_count()).
 508 @postrefcountsame{event_class}
 509 @post <strong>On success, if \p field_type is not \c NULL</strong>, the
 510         reference count of \p *field_type is incremented.
 511 */
 512 extern int bt_ctf_event_class_get_field(struct bt_ctf_event_class *event_class,
 513                 const char **field_name, struct bt_ctf_field_type **field_type,
 514                 int index);
 515
 516 /**
 517 @brief  Returns the type of the field named \p name in the payload
 518         field type of the CTF IR event class \p event_class.
 519
 520 @remarks
 521 Calling this function is the equivalent of getting the payload field
 522 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 523 getting the type of one of its field with
 524 bt_ctf_field_type_structure_get_field_type_by_name().
 525
 526 @param[in] event_class  Event class of which to get the type of a
 527                         payload field type's field.
 528 @param[in] name         Name of the payload field type's field to get.
 529 @returns                Type of the field named \p name in the payload
 530                         field type of \p event_class, or \c NULL if
 531                         the function cannot find the field or
 532                         on error.
 533
 534 @prenotnull{event_class}
 535 @prenotnull{name}
 536 @postrefcountsame{event_class}
 537 @postsuccessrefcountretinc
 538 */
 539 extern struct bt_ctf_field_type *bt_ctf_event_class_get_field_by_name(
 540                 struct bt_ctf_event_class *event_class, const char *name);
 541
 542 /**
 543 @brief  Adds a field named \p name with the type \p field_type to the
 544         payload field type of the CTF IR event class \p event_class.
 545
 546 @remarks
 547 Calling this function is the equivalent of getting the payload field
 548 type of \p event_class with bt_ctf_event_class_get_payload_type() and
 549 adding a field to it with bt_ctf_field_type_structure_add_field().
 550
 551 @param[in] event_class  Event class containing the payload field
 552                         type in which to add a field.
 553 @param[in] field_type   Type of the field to add.
 554 @param[in] name         Name of the field to add (copied on
 555                         success).
 556 @returns                0 on success, or a negative value on error.
 557
 558 @prenotnull{event_class}
 559 @prenotnull{type}
 560 @prenotnull{name}
 561 @prehot{event_class}
 562 @postrefcountsame{event_class}
 563 @postsuccessrefcountinc{field_type}
 564 */
 565 extern int bt_ctf_event_class_add_field(struct bt_ctf_event_class *event_class,
 566                 struct bt_ctf_field_type *field_type,
 567                 const char *name);
 568
 569 /** @} */
 570
 571 /** @} */
 572
 573 #ifdef __cplusplus
 574 }
 575 #endif
 576
 577 #endif /* BABELTRACE_CTF_IR_EVENT_CLASS_H */