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 /* For bt_get() */
  34 #include <babeltrace/ref.h>
  35
  36 #include <stdint.h>
  37 #include <stddef.h>
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 struct bt_value;
  44
  45 /**
  46 @defgroup ctfireventclass CTF IR event class
  47 @ingroup ctfir
  48 @brief CTF IR event class.
  49
  50 @code
  51 #include <babeltrace/ctf-ir/event-class.h>
  52 @endcode
  53
  54 A CTF IR <strong><em>event class</em></strong> is a template that you
  55 can use to create concrete \link ctfirevent CTF IR events\endlink.
  56
  57 An event class has the following properties:
  58
  59 - A \b name.
  60 - A numeric \b ID (\em must be unique amongst all the event classes
  61   contained in the same
  62   \link ctfirstreamclass CTF IR stream class\endlink).
  63 - A optional <strong>log level</strong>.
  64 - An optional <strong>Eclipse Modeling Framework URI</strong>.
  65
  66 A CTF IR event class owns two
  67 \link ctfirfieldtypes field types\endlink:
  68
  69 - An optional <strong>event context</strong> field type, which
  70   represents the \c event.context CTF scope.
  71 - A mandatory <strong>event payload</strong> field type, which
  72   represents the \c event.fields CTF scope.
  73
  74 Both field types \em must be structure field types as of
  75 Babeltrace \btversion.
  76 The event payload field type <em>must not</em> be empty.
  77
  78 As a reminder, here's the structure of a CTF packet:
  79
  80 @imgpacketstructure
  81
  82 In the Babeltrace CTF IR system, a \link ctfirtraceclass trace
  83 class\endlink contains zero or more \link ctfirstreamclass stream
  84 classes\endlink, and a stream class contains zero or more event classes.
  85
  86 Before you can create an event from an event class with
  87 bt_event_create(), you \em must add the prepared event class to a
  88 stream class by calling bt_stream_class_add_event_class(). This
  89 function, when successful, \em freezes the event class, disallowing any
  90 future modification of its properties and field types by the user.
  91
  92 As with any Babeltrace object, CTF IR event class objects have
  93 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
  94 counts</a>. See \ref refs to learn more about the reference counting
  95 management of Babeltrace objects.
  96
  97 bt_stream_class_add_event_class() \em freezes its event class
  98 parameter on success. You cannot modify a frozen event class: it is
  99 considered immutable, except for \link refs reference counting\endlink.
 100
 101 @sa ctfirevent
 102 @sa ctfirstreamclass
 103
 104 @file
 105 @brief CTF IR event class type and functions.
 106 @sa ctfireventclass
 107
 108 @addtogroup ctfireventclass
 109 @{
 110 */
 111
 112 /**
 113 @struct bt_event_class
 114 @brief A CTF IR event class.
 115 @sa ctfireventclass
 116 */
 117 struct bt_event_class;
 118 struct bt_field;
 119 struct bt_field_type;
 120 struct bt_stream_class;
 121
 122 /**
 123 @brief  Log level of an event class.
 124 */
 125 enum bt_event_class_log_level {
 126         /// Unknown, used for errors.
 127         BT_EVENT_CLASS_LOG_LEVEL_UNKNOWN        = -1,
 128
 129         /// Unspecified log level.
 130         BT_EVENT_CLASS_LOG_LEVEL_UNSPECIFIED    = 255,
 131
 132         /// System is unusable.
 133         BT_EVENT_CLASS_LOG_LEVEL_EMERGENCY      = 0,
 134
 135         /// Action must be taken immediately.
 136         BT_EVENT_CLASS_LOG_LEVEL_ALERT          = 1,
 137
 138         /// Critical conditions.
 139         BT_EVENT_CLASS_LOG_LEVEL_CRITICAL       = 2,
 140
 141         /// Error conditions.
 142         BT_EVENT_CLASS_LOG_LEVEL_ERROR          = 3,
 143
 144         /// Warning conditions.
 145         BT_EVENT_CLASS_LOG_LEVEL_WARNING        = 4,
 146
 147         /// Normal, but significant, condition.
 148         BT_EVENT_CLASS_LOG_LEVEL_NOTICE         = 5,
 149
 150         /// Informational message.
 151         BT_EVENT_CLASS_LOG_LEVEL_INFO           = 6,
 152
 153         /// Debug information with system-level scope (set of programs).
 154         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM   = 7,
 155
 156         /// Debug information with program-level scope (set of processes).
 157         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM  = 8,
 158
 159         /// Debug information with process-level scope (set of modules).
 160         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS  = 9,
 161
 162         /// Debug information with module (executable/library) scope (set of units).
 163         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE   = 10,
 164
 165         /// Debug information with compilation unit scope (set of functions).
 166         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT     = 11,
 167
 168         /// Debug information with function-level scope.
 169         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION = 12,
 170
 171         /// Debug information with line-level scope (default log level).
 172         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE     = 13,
 173
 174         /// Debug-level message.
 175         BT_EVENT_CLASS_LOG_LEVEL_DEBUG          = 14,
 176 };
 177
 178 /**
 179 @name Creation and parent access functions
 180 @{
 181 */
 182
 183 /**
 184 @brief  Creates a default CTF IR event class named \p name.
 185
 186 On success, the context and payload field types are empty structure
 187 field types. You can modify those default field types after the
 188 event class is created with
 189 bt_event_class_set_context_field_type() and
 190 bt_event_class_set_payload_field_type().
 191
 192 Upon creation, the event class's ID is <em>not set</em>. You
 193 can set it to a specific value with bt_event_class_set_id(). If it
 194 is still unset when you call bt_stream_class_add_event_class(), then
 195 the stream class assigns a unique ID to this event class before
 196 freezing it.
 197
 198 The created event class's log level is initially set to
 199 #BT_EVENT_CLASS_LOG_LEVEL_UNSPECIFIED and it has no Eclipse Modeling
 200 Framework URI.
 201
 202 @param[in] name Name of the event class to create (copied on success).
 203 @returns        Created event class, or \c NULL on error.
 204
 205 @prenotnull{name}
 206 @postsuccessrefcountret1
 207 */
 208 extern struct bt_event_class *bt_event_class_create(const char *name);
 209
 210 extern struct bt_stream_class *bt_event_class_borrow_stream_class(
 211                 struct bt_event_class *event_class);
 212
 213 /**
 214 @brief  Returns the parent CTF IR stream class of the CTF IR event
 215         class \p event_class.
 216
 217 It is possible that the event class was not added to a stream class
 218 yet, in which case this function returns \c NULL. You can add an
 219 event class to a stream class with
 220 bt_stream_class_add_event_class().
 221
 222 @param[in] event_class  Event class of which to get the parent
 223                         stream class.
 224 @returns                Parent stream class of \p event_class,
 225                         or \c NULL if \p event_class was not
 226                         added to a stream class yet or on error.
 227
 228 @prenotnull{event_class}
 229 @postrefcountsame{event_class}
 230 @postsuccessrefcountretinc
 231
 232 @sa bt_stream_class_add_event_class(): Add an event class to
 233         a stream class.
 234 */
 235 static inline
 236 struct bt_stream_class *bt_event_class_get_stream_class(
 237                 struct bt_event_class *event_class)
 238 {
 239         return bt_get(bt_event_class_borrow_stream_class(event_class));
 240 }
 241
 242 /** @} */
 243
 244 /**
 245 @name Attribute functions
 246 @{
 247 */
 248
 249 /**
 250 @brief  Returns the name of the CTF IR event class \p event_class.
 251
 252 On success, \p event_class remains the sole owner of the returned
 253 string.
 254
 255 @param[in] event_class  Event class of which to get the name.
 256 @returns                Name of event class \p event_class, or
 257                         \c NULL on error.
 258
 259 @prenotnull{event_class}
 260 @postrefcountsame{event_class}
 261 */
 262 extern const char *bt_event_class_get_name(
 263                 struct bt_event_class *event_class);
 264
 265 /**
 266 @brief  Returns the numeric ID of the CTF IR event class \p event_class.
 267
 268 @param[in] event_class  Event class of which to get the numeric ID.
 269 @returns                ID of event class \p event_class, or a
 270                         negative value on error.
 271
 272 @prenotnull{event_class}
 273 @postrefcountsame{event_class}
 274
 275 @sa bt_event_class_set_id(): Sets the numeric ID of a given
 276         event class.
 277 */
 278 extern int64_t bt_event_class_get_id(
 279                 struct bt_event_class *event_class);
 280
 281 /**
 282 @brief  Sets the numeric ID of the CTF IR event class
 283         \p event_class to \p id.
 284
 285 \p id must be unique amongst the IDs of all the event classes
 286 of the stream class to which you eventually add \p event_class.
 287
 288 @param[in] event_class  Event class of which to set the numeric ID.
 289 @param[in] id           ID of the event class.
 290 @returns                0 on success, or a negative value on error.
 291
 292 @prenotnull{event_class}
 293 @prehot{event_class}
 294 @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
 295 @postrefcountsame{event_class}
 296
 297 @sa bt_event_class_get_id(): Returns the numeric ID of a given
 298         event class.
 299 */
 300 extern int bt_event_class_set_id(
 301                 struct bt_event_class *event_class, uint64_t id);
 302
 303 /**
 304 @brief  Returns the log level of the CTF IR event class \p event_class.
 305
 306 @param[in] event_class  Event class of which to get the log level.
 307 @returns                Log level of event class \p event_class,
 308                         #BT_EVENT_CLASS_LOG_LEVEL_UNSPECIFIED if
 309                         not specified, or
 310                         #BT_EVENT_CLASS_LOG_LEVEL_UNKNOWN on error.
 311
 312 @prenotnull{event_class}
 313 @postrefcountsame{event_class}
 314
 315 @sa bt_event_class_set_log_level(): Sets the log level of a given
 316         event class.
 317 */
 318 extern enum bt_event_class_log_level bt_event_class_get_log_level(
 319                 struct bt_event_class *event_class);
 320
 321 /**
 322 @brief  Sets the log level of the CTF IR event class
 323         \p event_class to \p log_level.
 324
 325 @param[in] event_class  Event class of which to set the log level.
 326 @param[in] log_level    Log level of the event class.
 327 @returns                0 on success, or a negative value on error.
 328
 329 @prenotnull{event_class}
 330 @prehot{event_class}
 331 @pre \p log_level is #BT_EVENT_CLASS_LOG_LEVEL_UNSPECIFIED,
 332         #BT_EVENT_CLASS_LOG_LEVEL_EMERGENCY,
 333         #BT_EVENT_CLASS_LOG_LEVEL_ALERT,
 334         #BT_EVENT_CLASS_LOG_LEVEL_CRITICAL,
 335         #BT_EVENT_CLASS_LOG_LEVEL_ERROR,
 336         #BT_EVENT_CLASS_LOG_LEVEL_WARNING,
 337         #BT_EVENT_CLASS_LOG_LEVEL_NOTICE,
 338         #BT_EVENT_CLASS_LOG_LEVEL_INFO,
 339         #BT_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM,
 340         #BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM,
 341         #BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS,
 342         #BT_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE,
 343         #BT_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT,
 344         #BT_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION,
 345         #BT_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE, or
 346         #BT_EVENT_CLASS_LOG_LEVEL_DEBUG.
 347 @postrefcountsame{event_class}
 348
 349 @sa bt_event_class_get_log_level(): Returns the log level of a given
 350         event class.
 351 */
 352 extern int bt_event_class_set_log_level(
 353                 struct bt_event_class *event_class,
 354                 enum bt_event_class_log_level log_level);
 355
 356 /**
 357 @brief  Returns the Eclipse Modeling Framework URI of the CTF IR event
 358         class \p event_class.
 359
 360 @param[in] event_class  Event class of which to get the
 361                         Eclipse Modeling Framework URI.
 362 @returns                Eclipse Modeling Framework URI of event
 363                         class \p event_class, or \c NULL on error.
 364
 365 @prenotnull{event_class}
 366 @postrefcountsame{event_class}
 367
 368 @sa bt_event_class_set_emf_uri(): Sets the Eclipse Modeling
 369         Framework URI of a given event class.
 370 */
 371 extern const char *bt_event_class_get_emf_uri(
 372                 struct bt_event_class *event_class);
 373
 374 /**
 375 @brief  Sets the Eclipse Modeling Framework URI of the CTF IR event class
 376         \p event_class to \p emf_uri, or unsets the event class's EMF URI.
 377
 378 @param[in] event_class  Event class of which to set the
 379                         Eclipse Modeling Framework URI.
 380 @param[in] emf_uri      Eclipse Modeling Framework URI of the
 381                         event class (copied on success), or \c NULL
 382                         to unset the current EMF URI.
 383 @returns                0 on success, or a negative value if there's
 384                         no EMF URI or on error.
 385
 386 @prenotnull{event_class}
 387 @prenotnull{emf_uri}
 388 @prehot{event_class}
 389 @postrefcountsame{event_class}
 390
 391 @sa bt_event_class_get_emf_uri(): Returns the Eclipse Modeling
 392         Framework URI of a given event class.
 393 */
 394 extern int bt_event_class_set_emf_uri(
 395                 struct bt_event_class *event_class,
 396                 const char *emf_uri);
 397
 398 /** @} */
 399
 400 /**
 401 @name Contained field types functions
 402 @{
 403 */
 404
 405 extern struct bt_field_type *bt_event_class_borrow_context_field_type(
 406                 struct bt_event_class *event_class);
 407
 408 /**
 409 @brief  Returns the context field type of the CTF IR event class
 410         \p event_class.
 411
 412 @param[in] event_class  Event class of which to get the context field type.
 413 @returns                Context field type of \p event_class, or \c NULL if
 414                         \p event_class has no context field type or on error.
 415
 416 @prenotnull{event_class}
 417 @postrefcountsame{event_class}
 418 @post <strong>On success, if the return value is a field type</strong>, its
 419         reference count is incremented.
 420
 421 @sa bt_event_class_set_context_field_type(): Sets the context field type of a
 422         given event class.
 423 */
 424 static inline
 425 struct bt_field_type *bt_event_class_get_context_field_type(
 426                 struct bt_event_class *event_class)
 427 {
 428         return bt_get(bt_event_class_borrow_context_field_type(event_class));
 429 }
 430
 431 /**
 432 @brief  Sets the context field type of the CTF IR event class \p event_class to
 433         \p context_type, or unsets the current context field type from
 434         \p event_class.
 435
 436 If \p context_type is \c NULL, then this function unsets the current context
 437 field type from \p event_class, effectively making \p event_class an event class
 438 without a context field type.
 439
 440 As of Babeltrace \btversion, if \p context_type is not \c NULL,
 441 \p context_type \em must be a CTF IR structure field type object.
 442
 443 @param[in] event_class          Event class of which to set the context field
 444                                 type.
 445 @param[in] context_type         Context field type, or \c NULL to unset the
 446                                 current context field type.
 447 @returns                        0 on success, or a negative value on error.
 448
 449 @prenotnull{event_class}
 450 @prehot{event_class}
 451 @pre <strong>If \p context_type is not \c NULL</strong>, \p context_type is a
 452         CTF IR structure field type.
 453 @postrefcountsame{event_class}
 454 @post <strong>On success, if \p context_type is not \c NULL</strong>,
 455         the reference count of \p context_type is incremented.
 456
 457 @sa bt_event_class_get_context_field_type(): Returns the context field type of a
 458         given event class.
 459 */
 460 extern int bt_event_class_set_context_field_type(
 461                 struct bt_event_class *event_class,
 462                 struct bt_field_type *context_type);
 463
 464 extern struct bt_field_type *bt_event_class_borrow_payload_field_type(
 465                 struct bt_event_class *event_class);
 466
 467 /**
 468 @brief  Returns the payload field type of the CTF IR event class
 469         \p event_class.
 470
 471 @param[in] event_class  Event class of which to get the payload field type.
 472 @returns                Payload field type of \p event_class, or \c NULL if
 473                         \p event_class has no payload field type or on error.
 474
 475 @prenotnull{event_class}
 476 @postrefcountsame{event_class}
 477 @post <strong>On success, if the return value is a field type</strong>, its
 478         reference count is incremented.
 479
 480 @sa bt_event_class_set_payload_field_type(): Sets the payload field type of a
 481         given event class.
 482 */
 483 static inline
 484 struct bt_field_type *bt_event_class_get_payload_field_type(
 485                 struct bt_event_class *event_class)
 486 {
 487         return bt_get(bt_event_class_borrow_payload_field_type(event_class));
 488 }
 489
 490 /**
 491 @brief  Sets the payload field type of the CTF IR event class \p event_class to
 492         \p payload_type, or unsets the current payload field type from
 493         \p event_class.
 494
 495 If \p payload_type is \c NULL, then this function unsets the current payload
 496 field type from \p event_class, effectively making \p event_class an event class
 497 without a payload field type.
 498
 499 As of Babeltrace \btversion, if \p payload_type is not \c NULL,
 500 \p payload_type \em must be a CTF IR structure field type object.
 501
 502 @param[in] event_class          Event class of which to set the payload field
 503                                 type.
 504 @param[in] payload_type         Payload field type, or \c NULL to unset the
 505                                 current payload field type.
 506 @returns                        0 on success, or a negative value on error.
 507
 508 @prenotnull{event_class}
 509 @prehot{event_class}
 510 @pre <strong>If \p payload_type is not \c NULL</strong>, \p payload_type is a
 511         CTF IR structure field type.
 512 @postrefcountsame{event_class}
 513 @post <strong>On success, if \p payload_type is not \c NULL</strong>,
 514         the reference count of \p payload_type is incremented.
 515
 516 @sa bt_event_class_get_payload_field_type(): Returns the payload field type of a
 517         given event class.
 518 */
 519 extern int bt_event_class_set_payload_field_type(
 520                 struct bt_event_class *event_class,
 521                 struct bt_field_type *payload_type);
 522
 523 /** @} */
 524
 525 /** @} */
 526
 527 #ifdef __cplusplus
 528 }
 529 #endif
 530
 531 #endif /* BABELTRACE_CTF_IR_EVENT_CLASS_H */