include/babeltrace/ctf-ir/event.h

   1 #ifndef BABELTRACE_CTF_IR_EVENT_H
   2 #define BABELTRACE_CTF_IR_EVENT_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Event
   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 ctfirevent CTF IR event
  43 @ingroup ctfir
  44 @brief CTF IR event.
  45
  46 @code
  47 #include <babeltrace/ctf-ir/event.h>
  48 @endcode
  49
  50 A CTF IR <strong><em>event</em></strong> is a container of event
  51 fields:
  52
  53 - <strong>Stream event header</strong> field, described by the
  54   <em>stream event header field type</em> of a
  55   \link ctfirstreamclass CTF IR stream class\endlink.
  56 - <strong>Stream event context</strong> field, described by the
  57   <em>stream event context field type</em> of a stream class.
  58 - <strong>Event context</strong> field, described by the
  59   <em>event context field type</em> of a
  60   \link ctfireventclass CTF IR event class\endlink.
  61 - <strong>Event payload</strong>, described by the
  62   <em>event payload field type</em> of an event class.
  63
  64 As a reminder, here's the structure of a CTF packet:
  65
  66 @imgpacketstructure
  67
  68 You can create a CTF IR event \em from a
  69 \link ctfireventclass CTF IR event class\endlink with
  70 bt_ctf_event_create(). The event class you use to create an event
  71 object becomes its parent.
  72
  73 If the \link ctfirtraceclass CTF IR trace class\endlink of an event
  74 object (parent of its \link ctfirstreamclass CTF IR stream class\endlink,
  75 which is the parent of its event class) was created by a
  76 \link ctfirwriter CTF IR writer\endlink object, then the only possible
  77 action you can do with this event object is to append it to a
  78 \link ctfirstream CTF IR stream\endlink with
  79 bt_ctf_stream_append_event(). Otherwise, you can create an event
  80 notification with bt_notification_event_create(). The event you pass
  81 to this function \em must have an attached packet object first.
  82
  83 You can attach a \link ctfirpacket CTF IR packet object\endlink to an
  84 event object with bt_ctf_event_set_packet().
  85
  86 A CTF IR event has a mapping of
  87 \link ctfirclockvalue CTF IR clock values\endlink. A clock value is
  88 an instance of a specific
  89 \link ctfirclockclass CTF IR clock class\endlink when the event is
  90 emitted. You can set an event object's clock value with
  91 bt_ctf_event_set_clock_value().
  92
  93 As with any Babeltrace object, CTF IR event objects have
  94 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
  95 counts</a>. See \ref refs to learn more about the reference counting
  96 management of Babeltrace objects.
  97
  98 bt_notification_event_create() \em freezes its event parameter on
  99 success. You cannot modify a frozen event object: it is considered
 100 immutable, except for \link refs reference counting\endlink.
 101
 102 @sa ctfireventclass
 103 @sa ctfirpacket
 104
 105 @file
 106 @brief CTF IR event type and functions.
 107 @sa ctfirevent
 108
 109 @addtogroup ctfirevent
 110 @{
 111 */
 112
 113 /**
 114 @struct bt_ctf_event
 115 @brief A CTF IR event.
 116 @sa ctfirevent
 117 */
 118 struct bt_ctf_event;
 119 struct bt_ctf_clock;
 120 struct bt_ctf_clock_value;
 121 struct bt_ctf_event_class;
 122 struct bt_ctf_field;
 123 struct bt_ctf_field_type;
 124 struct bt_ctf_stream_class;
 125 struct bt_ctf_packet;
 126
 127 /**
 128 @name Creation and parent access functions
 129 @{
 130 */
 131
 132 /**
 133 @brief  Creates a default CTF IR event from the CTF IR event class
 134         \p event_class.
 135
 136 \p event_class \em must have a parent
 137 \link ctfirstreamclass CTF IR stream class\endlink.
 138
 139 On success, the four fields of the created event object are not set. You
 140 can set them with bt_ctf_event_set_header(),
 141 bt_ctf_event_set_stream_event_context(),
 142 bt_ctf_event_set_event_context(), and bt_ctf_event_set_payload_field().
 143
 144 @param[in] event_class  CTF IR event class to use to create the
 145                         CTF IR event.
 146 @returns                Created event object, or \c NULL on error.
 147
 148 @prenotnull{event_class}
 149 @pre \p event_class has a parent stream class.
 150 @postsuccessrefcountret1
 151 */
 152 extern struct bt_ctf_event *bt_ctf_event_create(
 153                 struct bt_ctf_event_class *event_class);
 154
 155 /**
 156 @brief  Returns the parent CTF IR event class of the CTF IR event
 157         \p event.
 158
 159 This function returns a reference to the event class which was used to
 160 create the event object in the first place with bt_ctf_event_create().
 161
 162 @param[in] event        Event of which to get the parent event class.
 163 @returns                Parent event class of \p event,
 164                         or \c NULL on error.
 165
 166 @prenotnull{event}
 167 @postrefcountsame{event}
 168 @postsuccessrefcountretinc
 169 */
 170 extern struct bt_ctf_event_class *bt_ctf_event_get_class(
 171                 struct bt_ctf_event *event);
 172
 173 /**
 174 @brief  Returns the CTF IR packet associated to the CTF IR event
 175         \p event.
 176
 177 This function returns a reference to the event class which was set to
 178 \p event in the first place with bt_ctf_event_set_packet().
 179
 180 @param[in] event        Event of which to get the associated packet.
 181 @returns                Packet associated to \p event,
 182                         or \c NULL if no packet is associated to
 183                         \p event or on error.
 184
 185 @prenotnull{event}
 186 @postrefcountsame{event}
 187 @postsuccessrefcountretinc
 188
 189 @sa bt_ctf_event_set_packet(): Associates a given event to a given
 190         packet.
 191 */
 192 extern struct bt_ctf_packet *bt_ctf_event_get_packet(
 193                 struct bt_ctf_event *event);
 194
 195 /**
 196 @brief  Associates the CTF IR event \p event to the CTF IR packet
 197         \p packet.
 198
 199 The \link ctfirstreamclass CTF IR stream class\endlink of the
 200 parent \link ctfirstream CTF IR stream\endlink of \p packet \em must
 201 be the same as the parent stream class of the
 202 \link ctfireventclass CTF IR event class\endlink returned
 203 by bt_ctf_event_get_class() for \p event.
 204
 205 You \em must call this function to create an event-packet association
 206 before you call bt_notification_event_create() with \p event.
 207
 208 On success, this function also sets the parent stream object of
 209 \p event to the parent stream of \p packet.
 210
 211 @param[in] event        Event to which to associate \p packet.
 212 @returns                0 on success, or a negative value on error.
 213
 214 @prenotnull{event}
 215 @prenotnull{packet}
 216 @prehot{event}
 217 @pre The parent stream class of \p packet is the same as the parent
 218         stream class of \p event.
 219 @postsuccessrefcountretinc
 220
 221 @sa bt_ctf_event_get_packet(): Returns the associated packet of a
 222         given event object.
 223 */
 224 extern int bt_ctf_event_set_packet(struct bt_ctf_event *event,
 225                 struct bt_ctf_packet *packet);
 226
 227 /**
 228 @brief  Returns the parent CTF IR stream associated to the CTF IR event
 229         \p event.
 230
 231 @param[in] event        Event of which to get the parent stream.
 232 @returns                Parent stream of \p event, or \c NULL on error.
 233
 234 @prenotnull{event}
 235 @postrefcountsame{event}
 236 @postsuccessrefcountretinc
 237 */
 238 extern struct bt_ctf_stream *bt_ctf_event_get_stream(
 239                 struct bt_ctf_event *event);
 240
 241 /** @} */
 242
 243 /**
 244 @name Contained fields functions
 245 @{
 246 */
 247
 248 /**
 249 @brief  Returns the stream event header field of the CTF IR event
 250         \p event.
 251
 252 @param[in] event        Event of which to get the stream event header
 253                         field.
 254 @returns                Stream event header field of \p event,
 255                         or \c NULL if the stream event header
 256                         field is not set or on error.
 257
 258 @prenotnull{event}
 259 @postrefcountsame{event}
 260 @postsuccessrefcountretinc
 261
 262 @sa bt_ctf_event_get_header(): Sets the stream event header
 263         field of a given event.
 264 */
 265 extern struct bt_ctf_field *bt_ctf_event_get_header(
 266                 struct bt_ctf_event *event);
 267
 268 /**
 269 @brief  Sets the stream event header field of the CTF IR event
 270         \p event to \p header.
 271
 272 The field type of \p header, as returned by bt_ctf_field_get_type(),
 273 \em must be equivalent to the field type returned by
 274 bt_ctf_stream_class_get_event_header_type() for the parent stream class
 275 of \p event.
 276
 277 @param[in] event        Event of which to set the stream event header
 278                         field.
 279 @param[in] header       Stream event header field.
 280 @returns                0 on success, or a negative value on error.
 281
 282 @prenotnull{event}
 283 @prenotnull{header}
 284 @prehot{event}
 285 @pre \p header has a field type equivalent to the field type returned by
 286         bt_ctf_stream_class_get_event_header_type() for the parent
 287         stream class of \p event.
 288 @postrefcountsame{event}
 289 @postsuccessrefcountinc{header}
 290
 291 @sa bt_ctf_event_get_header(): Returns the stream event header field
 292         of a given event.
 293 */
 294 extern int bt_ctf_event_set_header(struct bt_ctf_event *event,
 295                 struct bt_ctf_field *header);
 296
 297 /**
 298 @brief  Returns the stream event context field of the CTF IR event
 299         \p event.
 300
 301 @param[in] event        Event of which to get the stream event context
 302                         field.
 303 @returns                Stream event context field of \p event,
 304                         or \c NULL if the stream event context
 305                         field is not set or on error.
 306
 307 @prenotnull{event}
 308 @postrefcountsame{event}
 309 @postsuccessrefcountretinc
 310
 311 @sa bt_ctf_event_set_stream_event_context(): Sets the stream event
 312         context field of a given event.
 313 */
 314 extern struct bt_ctf_field *bt_ctf_event_get_stream_event_context(
 315                 struct bt_ctf_event *event);
 316
 317 /**
 318 @brief  Sets the stream event context field of the CTF IR event
 319         \p event to \p context.
 320
 321 The field type of \p context, as returned by bt_ctf_field_get_type(),
 322 \em must be equivalent to the field type returned by
 323 bt_ctf_stream_class_get_event_context_type() for the parent stream class
 324 of \p event.
 325
 326 @param[in] event        Event of which to set the stream event context
 327                         field.
 328 @param[in] context      Stream event context field.
 329 @returns                0 on success, or a negative value on error.
 330
 331 @prenotnull{event}
 332 @prenotnull{context}
 333 @prehot{event}
 334 @pre \p context has a field type equivalent to the field type returned
 335         by bt_ctf_stream_class_get_event_context_type() for the parent
 336         stream class of \p event.
 337 @postrefcountsame{event}
 338 @postsuccessrefcountinc{context}
 339
 340 @sa bt_ctf_event_get_stream_event_context(): Returns the stream event
 341         context field of a given event.
 342 */
 343 extern int bt_ctf_event_set_stream_event_context(struct bt_ctf_event *event,
 344                 struct bt_ctf_field *context);
 345
 346 /**
 347 @brief  Returns the event context field of the CTF IR event
 348         \p event.
 349
 350 @param[in] event        Event of which to get the event context
 351                         field.
 352 @returns                Event context field of \p event, or \c NULL if
 353                         the event context field is not set or on error.
 354
 355 @prenotnull{event}
 356 @postrefcountsame{event}
 357 @postsuccessrefcountretinc
 358
 359 @sa bt_ctf_event_set_event_context(): Sets the event context field of a
 360         given event.
 361 */
 362 extern struct bt_ctf_field *bt_ctf_event_get_event_context(
 363                 struct bt_ctf_event *event);
 364
 365 /**
 366 @brief  Sets the event context field of the CTF IR event
 367         \p event to \p context.
 368
 369 The field type of \p context, as returned by bt_ctf_field_get_type(),
 370 \em must be equivalent to the field type returned by
 371 bt_ctf_event_class_get_context_type() for the parent event class
 372 of \p event.
 373
 374 @param[in] event        Event of which to set the event context field.
 375 @param[in] context      Event context field.
 376 @returns                0 on success, or a negative value on error.
 377
 378 @prenotnull{event}
 379 @prenotnull{context}
 380 @prehot{event}
 381 @pre \p context has a field type equivalent to the field type returned
 382         by bt_ctf_event_class_get_context_type() for the parent
 383         event class of \p event.
 384 @postrefcountsame{event}
 385 @postsuccessrefcountinc{context}
 386
 387 @sa bt_ctf_event_get_event_context(): Returns the event context field of
 388         a given event.
 389 */
 390 extern int bt_ctf_event_set_event_context(struct bt_ctf_event *event,
 391                 struct bt_ctf_field *context);
 392
 393 /**
 394 @brief  Returns the event payload field of the CTF IR event
 395         \p event.
 396
 397 @param[in] event        Event of which to get the event payload
 398                         field.
 399 @returns                Event payload field of \p event, or \c NULL if
 400                         the event payload field is not set or on error.
 401
 402 @prenotnull{event}
 403 @postrefcountsame{event}
 404 @postsuccessrefcountretinc
 405
 406 @sa bt_ctf_event_set_payload_field(): Sets the event payload field of a
 407         given event.
 408 */
 409 extern struct bt_ctf_field *bt_ctf_event_get_payload_field(
 410                 struct bt_ctf_event *event);
 411
 412 /**
 413 @brief  Sets the event payload field of the CTF IR event
 414         \p event to \p payload.
 415
 416 The field type of \p payload, as returned by bt_ctf_field_get_type(),
 417 \em must be equivalent to the field type returned by
 418 bt_ctf_event_class_get_payload_type() for the parent event class
 419 of \p event.
 420
 421 @param[in] event        Event of which to set the event payload field.
 422 @param[in] payload      Event payload field.
 423 @returns                0 on success, or a negative value on error.
 424
 425 @prenotnull{event}
 426 @prenotnull{payload}
 427 @prehot{event}
 428 @pre \p payload has a field type equivalent to the field type returned
 429         by bt_ctf_event_class_get_payload_type() for the parent
 430         event class of \p event.
 431 @postrefcountsame{event}
 432 @postsuccessrefcountinc{payload}
 433
 434 @sa bt_ctf_event_get_payload_field(): Returns the event payload field of
 435         a given event.
 436 */
 437 extern int bt_ctf_event_set_payload_field(struct bt_ctf_event *event,
 438                 struct bt_ctf_field *payload);
 439
 440 /**
 441 @cond DOCUMENT
 442 */
 443
 444 /*
 445  * TODO: Doxygenize.
 446  *
 447  * bt_ctf_event_get_payload: get an event's field.
 448  *
 449  * Returns the field matching "name". bt_put() must be called on the
 450  * returned value.
 451  *
 452  * @param event Event instance.
 453  * @param name Event field name, see notes.
 454  *
 455  * Returns a field instance on success, NULL on error.
 456  *
 457  * Note: Passing a name will cause the function to perform a look-up by
 458  *      name assuming the event's payload is a structure. This will return
 459  *      the raw payload instance if name is NULL.
 460  */
 461 extern struct bt_ctf_field *bt_ctf_event_get_payload(struct bt_ctf_event *event,
 462                 const char *name);
 463
 464 /*
 465  * TODO: Doxygenize.
 466  *
 467  * bt_ctf_event_get_payload_by_index: Get event's field by index.
 468  *
 469  * Returns the field associated with the provided index. bt_put()
 470  * must be called on the returned value. The indexes to be provided are
 471  * the same as can be retrieved from the event class.
 472  *
 473  * @param event Event.
 474  * @param index Index of field.
 475  *
 476  * Returns the event's field, NULL on error.
 477  *
 478  * Note: Will return an error if the payload's type is not a structure.
 479  */
 480 extern struct bt_ctf_field *bt_ctf_event_get_payload_by_index(
 481                 struct bt_ctf_event *event, int index);
 482
 483 /*
 484  * TODO: Doxygenize.
 485  *
 486  * bt_ctf_event_set_payload: set an event's field.
 487  *
 488  * Set a manually allocated field as an event's payload. The event will share
 489  * the field's ownership by using its reference count.
 490  * bt_put() must be called on the returned value.
 491  *
 492  * @param event Event instance.
 493  * @param name Event field name, see notes.
 494  * @param value Instance of a field whose type corresponds to the event's field.
 495  *
 496  * Returns 0 on success, a negative value on error.
 497  *
 498  * Note: The function will return an error if a name is provided and the payload
 499  *      type is not a structure. If name is NULL, the payload field will be set
 500  *      directly and must match the event class' payload's type.
 501  */
 502 extern int bt_ctf_event_set_payload(struct bt_ctf_event *event,
 503                 const char *name,
 504                 struct bt_ctf_field *value);
 505
 506 /**
 507 @endcond
 508 */
 509
 510 /** @} */
 511
 512 /**
 513 @name Clock value functions
 514 @{
 515 */
 516
 517 /**
 518 @brief  Returns the value, as of the CTF IR event \p event, of the
 519         clock described by the
 520         \link ctfirclockclass CTF IR clock class\endlink \p clock_class.
 521
 522 @param[in] event        Event of which to get the value of the clock
 523                         described by \p clock_class.
 524 @param[in] clock_class  Class of the clock of which to get the value.
 525 @returns                Value of the clock described by \p clock_class
 526                         as of \p event.
 527
 528 @prenotnull{event}
 529 @prenotnull{clock_class}
 530 @postrefcountsame{event}
 531 @postrefcountsame{clock_class}
 532 @postsuccessrefcountretinc
 533
 534 @sa bt_ctf_event_set_clock_value(): Sets the clock value of a given event.
 535 */
 536 extern struct bt_ctf_clock_value *bt_ctf_event_get_clock_value(
 537                 struct bt_ctf_event *event, struct bt_ctf_clock *clock_class);
 538
 539 /**
 540 @brief  Sets the value, as of the CTF IR event \p event, of the
 541         clock described by the
 542         \link ctfirclockclass CTF IR clock class\endlink \p clock_class.
 543
 544 @param[in] event        Event of which to set the value of the clock
 545                         described by \p clock_class.
 546 @param[in] clock_class  Class of the clock of which to set the value
 547                         for \p event.
 548 @param[in] clock_value  Value of the clock described by \p clock_class
 549                         as of \p event.
 550 @returns                0 on success, or a negative value on error.
 551
 552 @prenotnull{event}
 553 @prenotnull{clock_class}
 554 @prenotnull{clock_value}
 555 @prehot{event}
 556 @postrefcountsame{event}
 557 @postrefcountsame{clock_class}
 558
 559 @sa bt_ctf_event_get_clock_value(): Returns the clock value of
 560         a given event.
 561 */
 562 extern int bt_ctf_event_set_clock_value(
 563                 struct bt_ctf_event *event, struct bt_ctf_clock *clock_class,
 564                 struct bt_ctf_clock_value *clock_value);
 565
 566 /** @} */
 567
 568 /** @} */
 569
 570 #ifdef __cplusplus
 571 }
 572 #endif
 573
 574 #endif /* BABELTRACE_CTF_IR_EVENT_H */