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