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