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/objects.h>
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 struct bt_ctf_event_class;
  42 struct bt_ctf_event;
  43 struct bt_ctf_field;
  44 struct bt_ctf_field_type;
  45 struct bt_ctf_stream_class;
  46
  47 /*
  48  * bt_ctf_event_class_create: create an event class.
  49  *
  50  * Allocate a new event class of the given name. The creation of an event class
  51  * sets its reference count to 1. A unique event id is automatically assigned
  52  * to the event class.
  53  *
  54  * @param name Event class name (will be copied).
  55  *
  56  * Returns an allocated event class on success, NULL on error.
  57  */
  58 extern struct bt_ctf_event_class *bt_ctf_event_class_create(const char *name);
  59
  60 /*
  61  * bt_ctf_event_class_get_name: Get an event class' name.
  62  *
  63  * @param event_class Event class.
  64  *
  65  * Returns the event class' name, NULL on error.
  66  */
  67 extern const char *bt_ctf_event_class_get_name(
  68                 struct bt_ctf_event_class *event_class);
  69
  70 /*
  71  * bt_ctf_event_class_get_id: Get an event class' id.
  72  *
  73  * @param event_class Event class.
  74  *
  75  * Returns the event class' id, a negative value on error.
  76  */
  77 extern int64_t bt_ctf_event_class_get_id(
  78                 struct bt_ctf_event_class *event_class);
  79
  80 /*
  81  * bt_ctf_event_class_set_id: Set an event class' id.
  82  *
  83  * Set an event class' id. Must be unique stream-wise.
  84  * Note that event classes are already assigned a unique id when added to a
  85  * stream class if none was set explicitly.
  86  *
  87  * @param event_class Event class.
  88  * @param id Event class id.
  89  *
  90  * Returns 0 on success, a negative value on error.
  91  */
  92 extern int bt_ctf_event_class_set_id(
  93                 struct bt_ctf_event_class *event_class, uint32_t id);
  94
  95 /*
  96  * bt_ctf_event_class_set_attribute: sets an attribute to the event
  97  *      class.
  98  *
  99  * Sets an attribute to the event class. The name parameter is copied,
 100  * whereas the value parameter's reference count is incremented
 101  * (if the function succeeds).
 102  *
 103  * If an attribute exists in the event class for the specified name, it
 104  * is replaced by the new value.
 105  *
 106  * Valid attributes and object types are:
 107  *
 108  *   - "id":            integer object with a value >= 0
 109  *   - "name":          string object
 110  *   - "loglevel":      integer object with a value >= 0
 111  *   - "model.emf.uri": string object
 112  *
 113  * @param event_class Event class.
 114  * @param name Name of the attribute (will be copied).
 115  * @param value Value of the attribute.
 116  *
 117  * Returns 0 on success, a negative value on error.
 118  */
 119 extern int bt_ctf_event_class_set_attribute(
 120                 struct bt_ctf_event_class *event_class, const char *name,
 121                 struct bt_object *value);
 122
 123 /*
 124  * bt_ctf_event_class_get_attribute_count: get the number of attributes
 125  *      in this event class.
 126  *
 127  * Get the event class' attribute count.
 128  *
 129  * @param event_class Event class.
 130  *
 131  * Returns the attribute count, a negative value on error.
 132  */
 133 extern int bt_ctf_event_class_get_attribute_count(
 134                 struct bt_ctf_event_class *event_class);
 135
 136 /*
 137  * bt_ctf_event_class_get_attribute_name: get attribute name.
 138  *
 139  * Get an attribute's name. The string's ownership is not
 140  * transferred to the caller. The string data is valid as long as
 141  * this event class' attributes are not modified.
 142  *
 143  * @param event_class Event class.
 144  * @param index Index of the attribute.
 145  *
 146  * Returns the attribute's name, NULL on error.
 147  */
 148 extern const char *
 149 bt_ctf_event_class_get_attribute_name(
 150                 struct bt_ctf_event_class *event_class, int index);
 151
 152 /*
 153  * bt_ctf_event_class_get_attribute_value: get attribute value (an object).
 154  *
 155  * Get an attribute's value (an object). The returned object's
 156  * reference count is incremented. When done with the object, the caller
 157  * must call bt_object_put() on it.
 158  *
 159  * @param event_class Event class.
 160  * @param index Index of the attribute.
 161  *
 162  * Returns the attribute's object value, NULL on error.
 163  */
 164 extern struct bt_object *
 165 bt_ctf_event_class_get_attribute_value(struct bt_ctf_event_class *event_class,
 166                 int index);
 167
 168 /*
 169  * bt_ctf_event_class_get_attribute_value_by_name: get attribute
 170  *      value (an object) by name.
 171  *
 172  * Get an attribute's value (an object) by its name. The returned object's
 173  * reference count is incremented. When done with the object, the caller
 174  * must call bt_object_put() on it.
 175  *
 176  * @param event_class Event class.
 177  * @param name Attribute's name
 178  *
 179  * Returns the attribute's object value, NULL on error.
 180  */
 181 extern struct bt_object *
 182 bt_ctf_event_class_get_attribute_value_by_name(
 183                 struct bt_ctf_event_class *event_class, const char *name);
 184
 185 /*
 186  * bt_ctf_event_class_get_stream_class: Get an event class' stream class.
 187  *
 188  * @param event_class Event class.
 189  *
 190  * Returns the event class' stream class, NULL on error or if the event class
 191  * is not associated with a stream class.
 192  */
 193 extern struct bt_ctf_stream_class *bt_ctf_event_class_get_stream_class(
 194                 struct bt_ctf_event_class *event_class);
 195
 196 /*
 197  * bt_ctf_event_class_get_payload_type: get an event class' payload.
 198  *
 199  * Get an event class' payload type.
 200  *
 201  * @param event_class Event class.
 202  *
 203  * Returns the event class' payload, NULL on error.
 204  */
 205 extern struct bt_ctf_field_type *bt_ctf_event_class_get_payload_type(
 206                 struct bt_ctf_event_class *event_class);
 207
 208 /*
 209  * bt_ctf_event_class_set_payload_type: set an event class' payload.
 210  *
 211  * Set an event class' payload type.
 212  *
 213  * @param event_class Event class.
 214  * @param payload The payload's type (must be a structure).
 215  *
 216  * Returns 0 on success, a negative value on error.
 217  */
 218 extern int bt_ctf_event_class_set_payload_type(
 219                 struct bt_ctf_event_class *event_class,
 220                 struct bt_ctf_field_type *payload);
 221
 222 /*
 223  * bt_ctf_event_class_add_field: add a field to an event class.
 224  *
 225  * Add a field of type "type" to the event class. The event class will share
 226  * type's ownership by increasing its reference count. The "name" will be
 227  * copied.
 228  *
 229  * @param event_class Event class.
 230  * @param type Field type to add to the event class.
 231  * @param name Name of the new field.
 232  *
 233  * Returns 0 on success, a negative value on error.
 234  *
 235  * Note: Returns an error if the payload is not a structure.
 236  */
 237 extern int bt_ctf_event_class_add_field(struct bt_ctf_event_class *event_class,
 238                 struct bt_ctf_field_type *type,
 239                 const char *name);
 240
 241 /*
 242  * bt_ctf_event_class_get_field_count: Get an event class' field count.
 243  *
 244  * @param event_class Event class.
 245  *
 246  * Returns the event class' field count, a negative value on error.
 247  *
 248  * Note: Returns an error if the payload is not a structure.
 249  */
 250 extern int bt_ctf_event_class_get_field_count(
 251                 struct bt_ctf_event_class *event_class);
 252
 253 /*
 254  * bt_ctf_event_class_get_field: Get event class' field type and name by index.
 255  *
 256  * @param event_class Event class.
 257  * @param field_name Pointer to a const char* where the field's name will
 258  *      be returned.
 259  * @param field_type Pointer to a bt_ctf_field_type* where the field's type will
 260  *      be returned.
 261  * @param index Index of field.
 262  *
 263  * Returns 0 on success, a negative error on value.
 264  *
 265  * Note: Returns an error if the payload is not a structure.
 266  */
 267 extern int bt_ctf_event_class_get_field(struct bt_ctf_event_class *event_class,
 268                 const char **field_name, struct bt_ctf_field_type **field_type,
 269                 int index);
 270
 271 /*
 272  * bt_ctf_event_class_get_field_type_by_name: Get an event class's field by name
 273  *
 274  * @param event_class Event class.
 275  * @param name Name of the field.
 276  *
 277  * Returns a field type on success, NULL on error.
 278  *
 279  * Note: Returns an error if the payload is not a structure.
 280  */
 281 extern struct bt_ctf_field_type *bt_ctf_event_class_get_field_by_name(
 282                 struct bt_ctf_event_class *event_class, const char *name);
 283
 284 /*
 285  * bt_ctf_event_class_get_context_type: Get an event class's context type
 286  *
 287  * @param event_class Event class.
 288  *
 289  * Returns a field type (a structure) on success, NULL on error.
 290  */
 291 extern struct bt_ctf_field_type *bt_ctf_event_class_get_context_type(
 292                 struct bt_ctf_event_class *event_class);
 293
 294 /*
 295  * bt_ctf_event_class_set_context_type: Set an event class's context type
 296  *
 297  * @param event_class Event class.
 298  * @param context Event context field type (must be a structure).
 299  *
 300  * Returns 0 on success, a negative value on error.
 301  */
 302 extern int bt_ctf_event_class_set_context_type(
 303                 struct bt_ctf_event_class *event_class,
 304                 struct bt_ctf_field_type *context);
 305
 306 /*
 307  * bt_ctf_event_class_get and bt_ctf_event_class_put: increment and decrement
 308  * the event class' reference count.
 309  *
 310  * You may also use bt_ctf_get() and bt_ctf_put() with event class objects.
 311  *
 312  * These functions ensure that the event class won't be destroyed while it
 313  * is in use. The same number of get and put (plus one extra put to
 314  * release the initial reference done at creation) have to be done to
 315  * destroy an event class.
 316  *
 317  * When the event class' reference count is decremented to 0 by a
 318  * bt_ctf_event_class_put, the event class is freed.
 319  *
 320  * @param event_class Event class.
 321  */
 322 extern void bt_ctf_event_class_get(struct bt_ctf_event_class *event_class);
 323 extern void bt_ctf_event_class_put(struct bt_ctf_event_class *event_class);
 324
 325 /*
 326  * bt_ctf_event_create: instanciate an event.
 327  *
 328  * Allocate a new event of the given event class. The creation of an event
 329  * sets its reference count to 1. Each instance shares the ownership of the
 330  * event class using its reference count.
 331  *
 332  * An event class must be associated with a stream class before events
 333  * may be instanciated.
 334  *
 335  * @param event_class Event class.
 336  *
 337  * Returns an allocated field type on success, NULL on error.
 338  */
 339 extern struct bt_ctf_event *bt_ctf_event_create(
 340                 struct bt_ctf_event_class *event_class);
 341
 342 /*
 343  * bt_ctf_event_get_class: get an event's class.
 344  *
 345  * @param event Event.
 346  *
 347  * Returns the event's class, NULL on error.
 348  */
 349 extern struct bt_ctf_event_class *bt_ctf_event_get_class(
 350                 struct bt_ctf_event *event);
 351
 352 /*
 353  * bt_ctf_event_get_stream: get an event's associated stream.
 354  *
 355  * @param event Event.
 356  *
 357  * Returns the event's associated stream, NULL on error.
 358  */
 359 extern struct bt_ctf_stream *bt_ctf_event_get_stream(
 360                 struct bt_ctf_event *event);
 361
 362 /*
 363  * bt_ctf_event_get_clock: get an event's associated clock.
 364  *
 365  * @param event Event.
 366  *
 367  * Returns the event's clock, NULL on error.
 368  */
 369 extern struct bt_ctf_clock *bt_ctf_event_get_clock(
 370                 struct bt_ctf_event *event);
 371
 372 /*
 373  * bt_ctf_event_get_payload_field: get an event's payload.
 374  *
 375  * @param event Event instance.
 376  *
 377  * Returns a field instance on success, NULL on error.
 378  */
 379 extern struct bt_ctf_field *bt_ctf_event_get_payload_field(
 380                 struct bt_ctf_event *event);
 381
 382 /*
 383  * bt_ctf_event_set_payload_field: set an event's payload.
 384  *
 385  * @param event Event instance.
 386  * @param payload Field instance (must be a structure).
 387  *
 388  * Returns 0 on success, a negative value on error.
 389  */
 390 extern int bt_ctf_event_set_payload_field(struct bt_ctf_event *event,
 391                 struct bt_ctf_field *payload);
 392
 393 /*
 394  * bt_ctf_event_get_payload: get an event's field.
 395  *
 396  * Returns the field matching "name". bt_ctf_field_put() must be called on the
 397  * returned value.
 398  *
 399  * @param event Event instance.
 400  * @param name Event field name, see notes.
 401  *
 402  * Returns a field instance on success, NULL on error.
 403  *
 404  * Note: Passing a name will cause the function to perform a look-up by
 405  *      name assuming the event's payload is a structure. This will return
 406  *      the raw payload instance if name is NULL.
 407  */
 408 extern struct bt_ctf_field *bt_ctf_event_get_payload(struct bt_ctf_event *event,
 409                 const char *name);
 410
 411 /*
 412  * bt_ctf_event_set_payload: set an event's field.
 413  *
 414  * Set a manually allocated field as an event's payload. The event will share
 415  * the field's ownership by using its reference count.
 416  * bt_ctf_field_put() must be called on the returned value.
 417  *
 418  * @param event Event instance.
 419  * @param name Event field name, see notes.
 420  * @param value Instance of a field whose type corresponds to the event's field.
 421  *
 422  * Returns 0 on success, a negative value on error.
 423  *
 424  * Note: The function will return an error if a name is provided and the payload
 425  *      type is not a structure. If name is NULL, the payload field will be set
 426  *      directly and must match the event class' payload's type.
 427  */
 428 extern int bt_ctf_event_set_payload(struct bt_ctf_event *event,
 429                 const char *name,
 430                 struct bt_ctf_field *value);
 431
 432 /*
 433  * bt_ctf_event_get_payload_by_index: Get event's field by index.
 434  *
 435  * Returns the field associated with the provided index. bt_ctf_field_put()
 436  * must be called on the returned value. The indexes to be provided are
 437  * the same as can be retrieved from the event class.
 438  *
 439  * @param event Event.
 440  * @param index Index of field.
 441  *
 442  * Returns the event's field, NULL on error.
 443  *
 444  * Note: Will return an error if the payload's type is not a structure.
 445  */
 446 extern struct bt_ctf_field *bt_ctf_event_get_payload_by_index(
 447                 struct bt_ctf_event *event, int index);
 448
 449 /*
 450  * bt_ctf_event_get_header: get an event's header.
 451  *
 452  * @param event Event instance.
 453  *
 454  * Returns a field instance on success, NULL on error.
 455  */
 456 extern struct bt_ctf_field *bt_ctf_event_get_header(
 457                 struct bt_ctf_event *event);
 458
 459 /*
 460  * bt_ctf_event_set_header: set an event's header.
 461  *
 462  * The event header's type must match the stream class' event
 463  * header type.
 464  *
 465  * @param event Event instance.
 466  * @param header Event header field instance.
 467  *
 468  * Returns a field instance on success, NULL on error.
 469  */
 470 extern int bt_ctf_event_set_header(
 471                 struct bt_ctf_event *event,
 472                 struct bt_ctf_field *header);
 473
 474 /*
 475  * bt_ctf_event_get_event_context: Get an event's context
 476  *
 477  * @param event_class Event class.
 478  *
 479  * Returns a field on success (a structure), NULL on error.
 480  *
 481  * Note: This function is named this way instead of the expected
 482  * "bt_ctf_event_get_context" in order to work around a name clash with
 483  * an unrelated function bearing this name in context.h.
 484  */
 485 extern struct bt_ctf_field *bt_ctf_event_get_event_context(
 486                 struct bt_ctf_event *event);
 487
 488 /*
 489  * bt_ctf_event_set_event_context: Set an event's context
 490  *
 491  * @param event Event.
 492  * @param context Event context field (must match the event class'
 493  *      context type).
 494  *
 495  * Returns 0 on success, a negative value on error.
 496  */
 497 extern int bt_ctf_event_set_event_context(struct bt_ctf_event *event,
 498                 struct bt_ctf_field *context);
 499
 500 /*
 501  * bt_ctf_event_copy: Deep-copy an event.
 502  *
 503  * Get an event's deep copy.
 504  *
 505  * On success, the returned copy has its reference count set to 1.
 506  *
 507  * @param event Event to copy.
 508  *
 509  * Returns the deep-copied event on success, NULL on error.
 510  */
 511 extern struct bt_ctf_event *bt_ctf_event_copy(struct bt_ctf_event *event);
 512
 513 /*
 514  * bt_ctf_event_get and bt_ctf_event_put: increment and decrement
 515  * the event's reference count.
 516  *
 517  * You may also use bt_ctf_get() and bt_ctf_put() with event objects.
 518  *
 519  * These functions ensure that the event won't be destroyed while it
 520  * is in use. The same number of get and put (plus one extra put to
 521  * release the initial reference done at creation) have to be done to
 522  * destroy an event.
 523  *
 524  * When the event's reference count is decremented to 0 by a
 525  * bt_ctf_event_put, the event is freed.
 526  *
 527  * @param event Event instance.
 528  */
 529 extern void bt_ctf_event_get(struct bt_ctf_event *event);
 530 extern void bt_ctf_event_put(struct bt_ctf_event *event);
 531
 532 #ifdef __cplusplus
 533 }
 534 #endif
 535
 536 #endif /* BABELTRACE_CTF_IR_EVENT_H */