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  * These functions ensure that the event class won't be destroyed while it
 311  * is in use. The same number of get and put (plus one extra put to
 312  * release the initial reference done at creation) have to be done to
 313  * destroy an event class.
 314  *
 315  * When the event class' reference count is decremented to 0 by a
 316  * bt_ctf_event_class_put, the event class is freed.
 317  *
 318  * @param event_class Event class.
 319  */
 320 extern void bt_ctf_event_class_get(struct bt_ctf_event_class *event_class);
 321 extern void bt_ctf_event_class_put(struct bt_ctf_event_class *event_class);
 322
 323 /*
 324  * bt_ctf_event_create: instanciate an event.
 325  *
 326  * Allocate a new event of the given event class. The creation of an event
 327  * sets its reference count to 1. Each instance shares the ownership of the
 328  * event class using its reference count.
 329  *
 330  * An event class must be associated with a stream class before events
 331  * may be instanciated.
 332  *
 333  * @param event_class Event class.
 334  *
 335  * Returns an allocated field type on success, NULL on error.
 336  */
 337 extern struct bt_ctf_event *bt_ctf_event_create(
 338                 struct bt_ctf_event_class *event_class);
 339
 340 /*
 341  * bt_ctf_event_get_class: get an event's class.
 342  *
 343  * @param event Event.
 344  *
 345  * Returns the event's class, NULL on error.
 346  */
 347 extern struct bt_ctf_event_class *bt_ctf_event_get_class(
 348                 struct bt_ctf_event *event);
 349
 350 /*
 351  * bt_ctf_event_get_stream: get an event's associated stream.
 352  *
 353  * @param event Event.
 354  *
 355  * Returns the event's associated stream, NULL on error.
 356  */
 357 extern struct bt_ctf_stream *bt_ctf_event_get_stream(
 358                 struct bt_ctf_event *event);
 359
 360 /*
 361  * bt_ctf_event_get_clock: get an event's associated clock.
 362  *
 363  * @param event Event.
 364  *
 365  * Returns the event's clock, NULL on error.
 366  */
 367 extern struct bt_ctf_clock *bt_ctf_event_get_clock(
 368                 struct bt_ctf_event *event);
 369
 370 /*
 371  * bt_ctf_event_get_payload_field: get an event's payload.
 372  *
 373  * @param event Event instance.
 374  *
 375  * Returns a field instance on success, NULL on error.
 376  */
 377 extern struct bt_ctf_field *bt_ctf_event_get_payload_field(
 378                 struct bt_ctf_event *event);
 379
 380 /*
 381  * bt_ctf_event_get_payload: get an event's field.
 382  *
 383  * Returns the field matching "name". bt_ctf_field_put() must be called on the
 384  * returned value.
 385  *
 386  * @param event Event instance.
 387  * @param name Event field name, see notes.
 388  *
 389  * Returns a field instance on success, NULL on error.
 390  *
 391  * Note: Passing a name will cause the function to perform a look-up by
 392  *      name assuming the event's payload is a structure. This will return
 393  *      the raw payload instance if name is NULL.
 394  */
 395 extern struct bt_ctf_field *bt_ctf_event_get_payload(struct bt_ctf_event *event,
 396                 const char *name);
 397
 398 /*
 399  * bt_ctf_event_set_payload: set an event's field.
 400  *
 401  * Set a manually allocated field as an event's payload. The event will share
 402  * the field's ownership by using its reference count.
 403  * bt_ctf_field_put() must be called on the returned value.
 404  *
 405  * @param event Event instance.
 406  * @param name Event field name, see notes.
 407  * @param value Instance of a field whose type corresponds to the event's field.
 408  *
 409  * Returns 0 on success, a negative value on error.
 410  *
 411  * Note: The function will return an error if a name is provided and the payload
 412  *      type is not a structure. If name is NULL, the payload field will be set
 413  *      directly and must match the event class' payload's type.
 414  */
 415 extern int bt_ctf_event_set_payload(struct bt_ctf_event *event,
 416                 const char *name,
 417                 struct bt_ctf_field *value);
 418
 419 /*
 420  * bt_ctf_event_get_payload_by_index: Get event's field by index.
 421  *
 422  * Returns the field associated with the provided index. bt_ctf_field_put()
 423  * must be called on the returned value. The indexes to be provided are
 424  * the same as can be retrieved from the event class.
 425  *
 426  * @param event Event.
 427  * @param index Index of field.
 428  *
 429  * Returns the event's field, NULL on error.
 430  *
 431  * Note: Will return an error if the payload's type is not a structure.
 432  */
 433 extern struct bt_ctf_field *bt_ctf_event_get_payload_by_index(
 434                 struct bt_ctf_event *event, int index);
 435
 436 /*
 437  * bt_ctf_event_get_header: get an event's header.
 438  *
 439  * @param event Event instance.
 440  *
 441  * Returns a field instance on success, NULL on error.
 442  */
 443 extern struct bt_ctf_field *bt_ctf_event_get_header(
 444                 struct bt_ctf_event *event);
 445
 446 /*
 447  * bt_ctf_event_set_header: set an event's header.
 448  *
 449  * The event header's type must match the stream class' event
 450  * header type.
 451  *
 452  * @param event Event instance.
 453  * @param header Event header field instance.
 454  *
 455  * Returns a field instance on success, NULL on error.
 456  */
 457 extern int bt_ctf_event_set_header(
 458                 struct bt_ctf_event *event,
 459                 struct bt_ctf_field *header);
 460
 461 /*
 462  * bt_ctf_event_get_event_context: Get an event's context
 463  *
 464  * @param event_class Event class.
 465  *
 466  * Returns a field on success (a structure), NULL on error.
 467  *
 468  * Note: This function is named this way instead of the expected
 469  * "bt_ctf_event_get_context" in order to work around a name clash with
 470  * an unrelated function bearing this name in context.h.
 471  */
 472 extern struct bt_ctf_field *bt_ctf_event_get_event_context(
 473                 struct bt_ctf_event *event);
 474
 475 /*
 476  * bt_ctf_event_set_event_context: Set an event's context
 477  *
 478  * @param event Event.
 479  * @param context Event context field (must match the event class'
 480  *      context type).
 481  *
 482  * Returns 0 on success, a negative value on error.
 483  */
 484 extern int bt_ctf_event_set_event_context(struct bt_ctf_event *event,
 485                 struct bt_ctf_field *context);
 486
 487 /*
 488  * bt_ctf_event_copy: Deep-copy an event.
 489  *
 490  * Get an event's deep copy.
 491  *
 492  * On success, the returned copy has its reference count set to 1.
 493  *
 494  * @param event Event to copy.
 495  *
 496  * Returns the deep-copied event on success, NULL on error.
 497  */
 498 extern struct bt_ctf_event *bt_ctf_event_copy(struct bt_ctf_event *event);
 499
 500 /*
 501  * bt_ctf_event_get and bt_ctf_event_put: increment and decrement
 502  * the event's reference count.
 503  *
 504  * These functions ensure that the event won't be destroyed while it
 505  * is in use. The same number of get and put (plus one extra put to
 506  * release the initial reference done at creation) have to be done to
 507  * destroy an event.
 508  *
 509  * When the event's reference count is decremented to 0 by a
 510  * bt_ctf_event_put, the event is freed.
 511  *
 512  * @param event Event instance.
 513  */
 514 extern void bt_ctf_event_get(struct bt_ctf_event *event);
 515 extern void bt_ctf_event_put(struct bt_ctf_event *event);
 516
 517 #ifdef __cplusplus
 518 }
 519 #endif
 520
 521 #endif /* BABELTRACE_CTF_IR_EVENT_H */