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 struct bt_ctf_event_class;
  42 struct bt_ctf_field;
  43 struct bt_ctf_field_type;
  44 struct bt_ctf_stream_class;
  45
  46 /*
  47  * bt_ctf_event_class_create: create an event class.
  48  *
  49  * Allocate a new event class of the given name. The creation of an event class
  50  * sets its reference count to 1. A unique event id is automatically assigned
  51  * to the event class.
  52  *
  53  * @param name Event class name (will be copied).
  54  *
  55  * Returns an allocated event class on success, NULL on error.
  56  */
  57 extern struct bt_ctf_event_class *bt_ctf_event_class_create(const char *name);
  58
  59 /*
  60  * bt_ctf_event_class_get_name: Get an event class' name.
  61  *
  62  * @param event_class Event class.
  63  *
  64  * Returns the event class' name, NULL on error.
  65  */
  66 extern const char *bt_ctf_event_class_get_name(
  67                 struct bt_ctf_event_class *event_class);
  68
  69 /*
  70  * bt_ctf_event_class_get_id: Get an event class' id.
  71  *
  72  * @param event_class Event class.
  73  *
  74  * Returns the event class' id, a negative value on error.
  75  */
  76 extern int64_t bt_ctf_event_class_get_id(
  77                 struct bt_ctf_event_class *event_class);
  78
  79 /*
  80  * bt_ctf_event_class_set_id: Set an event class' id.
  81  *
  82  * Set an event class' id. Must be unique stream-wise.
  83  * Note that event classes are already assigned a unique id when added to a
  84  * stream class if none was set explicitly.
  85  *
  86  * @param event_class Event class.
  87  * @param id Event class id.
  88  *
  89  * Returns 0 on success, a negative value on error.
  90  */
  91 extern int bt_ctf_event_class_set_id(
  92                 struct bt_ctf_event_class *event_class, uint32_t id);
  93
  94 /*
  95  * bt_ctf_event_class_set_attribute: sets an attribute to the event
  96  *      class.
  97  *
  98  * Sets an attribute to the event class. The name parameter is copied,
  99  * whereas the value parameter's reference count is incremented
 100  * (if the function succeeds).
 101  *
 102  * If an attribute exists in the event class for the specified name, it
 103  * is replaced by the new value.
 104  *
 105  * Valid attributes and object types are:
 106  *
 107  *   - "id":            integer object with a value >= 0
 108  *   - "name":          string object
 109  *   - "loglevel":      integer object with a value >= 0
 110  *   - "model.emf.uri": string object
 111  *
 112  * @param event_class Event class.
 113  * @param name Name of the attribute (will be copied).
 114  * @param value Value of the attribute.
 115  *
 116  * Returns 0 on success, a negative value on error.
 117  */
 118 extern int bt_ctf_event_class_set_attribute(
 119                 struct bt_ctf_event_class *event_class, const char *name,
 120                 struct bt_value *value);
 121
 122 /*
 123  * bt_ctf_event_class_get_attribute_count: get the number of attributes
 124  *      in this event class.
 125  *
 126  * Get the event class' attribute count.
 127  *
 128  * @param event_class Event class.
 129  *
 130  * Returns the attribute count, a negative value on error.
 131  */
 132 extern int bt_ctf_event_class_get_attribute_count(
 133                 struct bt_ctf_event_class *event_class);
 134
 135 /*
 136  * bt_ctf_event_class_get_attribute_name: get attribute name.
 137  *
 138  * Get an attribute's name. The string's ownership is not
 139  * transferred to the caller. The string data is valid as long as
 140  * this event class' attributes are not modified.
 141  *
 142  * @param event_class Event class.
 143  * @param index Index of the attribute.
 144  *
 145  * Returns the attribute's name, NULL on error.
 146  */
 147 extern const char *
 148 bt_ctf_event_class_get_attribute_name(
 149                 struct bt_ctf_event_class *event_class, int index);
 150
 151 /*
 152  * bt_ctf_event_class_get_attribute_value: get attribute value (an object).
 153  *
 154  * Get an attribute's value (an object). The returned object's
 155  * reference count is incremented. When done with the object, the caller
 156  * must call bt_value_put() on it.
 157  *
 158  * @param event_class Event class.
 159  * @param index Index of the attribute.
 160  *
 161  * Returns the attribute's object value, NULL on error.
 162  */
 163 extern struct bt_value *
 164 bt_ctf_event_class_get_attribute_value(struct bt_ctf_event_class *event_class,
 165                 int index);
 166
 167 /*
 168  * bt_ctf_event_class_get_attribute_value_by_name: get attribute
 169  *      value (an object) by name.
 170  *
 171  * Get an attribute's value (an object) by its name. The returned object's
 172  * reference count is incremented. When done with the object, the caller
 173  * must call bt_value_put() on it.
 174  *
 175  * @param event_class Event class.
 176  * @param name Attribute's name
 177  *
 178  * Returns the attribute's object value, NULL on error.
 179  */
 180 extern struct bt_value *
 181 bt_ctf_event_class_get_attribute_value_by_name(
 182                 struct bt_ctf_event_class *event_class, const char *name);
 183
 184 /*
 185  * bt_ctf_event_class_get_stream_class: Get an event class' stream class.
 186  *
 187  * @param event_class Event class.
 188  *
 189  * Returns the event class' stream class, NULL on error or if the event class
 190  * is not associated with a stream class.
 191  */
 192 extern struct bt_ctf_stream_class *bt_ctf_event_class_get_stream_class(
 193                 struct bt_ctf_event_class *event_class);
 194
 195 /*
 196  * bt_ctf_event_class_get_payload_type: get an event class' payload.
 197  *
 198  * Get an event class' payload type.
 199  *
 200  * @param event_class Event class.
 201  *
 202  * Returns the event class' payload, NULL on error.
 203  */
 204 extern struct bt_ctf_field_type *bt_ctf_event_class_get_payload_type(
 205                 struct bt_ctf_event_class *event_class);
 206
 207 /*
 208  * bt_ctf_event_class_set_payload_type: set an event class' payload.
 209  *
 210  * Set an event class' payload type.
 211  *
 212  * @param event_class Event class.
 213  * @param payload The payload's type (must be a structure).
 214  *
 215  * Returns 0 on success, a negative value on error.
 216  */
 217 extern int bt_ctf_event_class_set_payload_type(
 218                 struct bt_ctf_event_class *event_class,
 219                 struct bt_ctf_field_type *payload);
 220
 221 /*
 222  * bt_ctf_event_class_add_field: add a field to an event class.
 223  *
 224  * Add a field of type "type" to the event class. The event class will share
 225  * type's ownership by increasing its reference count. The "name" will be
 226  * copied.
 227  *
 228  * @param event_class Event class.
 229  * @param type Field type to add to the event class.
 230  * @param name Name of the new field.
 231  *
 232  * Returns 0 on success, a negative value on error.
 233  *
 234  * Note: Returns an error if the payload is not a structure.
 235  */
 236 extern int bt_ctf_event_class_add_field(struct bt_ctf_event_class *event_class,
 237                 struct bt_ctf_field_type *type,
 238                 const char *name);
 239
 240 /*
 241  * bt_ctf_event_class_get_field_count: Get an event class' field count.
 242  *
 243  * @param event_class Event class.
 244  *
 245  * Returns the event class' field count, a negative value on error.
 246  *
 247  * Note: Returns an error if the payload is not a structure.
 248  */
 249 extern int bt_ctf_event_class_get_field_count(
 250                 struct bt_ctf_event_class *event_class);
 251
 252 /*
 253  * bt_ctf_event_class_get_field: Get event class' field type and name by index.
 254  *
 255  * @param event_class Event class.
 256  * @param field_name Pointer to a const char* where the field's name will
 257  *      be returned.
 258  * @param field_type Pointer to a bt_ctf_field_type* where the field's type will
 259  *      be returned.
 260  * @param index Index of field.
 261  *
 262  * Returns 0 on success, a negative error on value.
 263  *
 264  * Note: Returns an error if the payload is not a structure.
 265  */
 266 extern int bt_ctf_event_class_get_field(struct bt_ctf_event_class *event_class,
 267                 const char **field_name, struct bt_ctf_field_type **field_type,
 268                 int index);
 269
 270 /*
 271  * bt_ctf_event_class_get_field_type_by_name: Get an event class's field by name
 272  *
 273  * @param event_class Event class.
 274  * @param name Name of the field.
 275  *
 276  * Returns a field type on success, NULL on error.
 277  *
 278  * Note: Returns an error if the payload is not a structure.
 279  */
 280 extern struct bt_ctf_field_type *bt_ctf_event_class_get_field_by_name(
 281                 struct bt_ctf_event_class *event_class, const char *name);
 282
 283 /*
 284  * bt_ctf_event_class_get_context_type: Get an event class's context type
 285  *
 286  * @param event_class Event class.
 287  *
 288  * Returns a field type (a structure) on success, NULL on error.
 289  */
 290 extern struct bt_ctf_field_type *bt_ctf_event_class_get_context_type(
 291                 struct bt_ctf_event_class *event_class);
 292
 293 /*
 294  * bt_ctf_event_class_set_context_type: Set an event class's context type
 295  *
 296  * @param event_class Event class.
 297  * @param context Event context field type (must be a structure).
 298  *
 299  * Returns 0 on success, a negative value on error.
 300  */
 301 extern int bt_ctf_event_class_set_context_type(
 302                 struct bt_ctf_event_class *event_class,
 303                 struct bt_ctf_field_type *context);
 304
 305 #ifdef __cplusplus
 306 }
 307 #endif
 308
 309 #endif /* BABELTRACE_CTF_IR_EVENT_CLASS_H */