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