1 #ifndef BABELTRACE_CTF_IR_EVENT_CLASS_H
2 #define BABELTRACE_CTF_IR_EVENT_CLASS_H
5 * BabelTrace - CTF IR: Event class
7 * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
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:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
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
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
35 #include <babeltrace/values.h>
42 @defgroup ctfireventclass CTF IR event class
44 @brief CTF IR event class.
47 #include <babeltrace/ctf-ir/event-class.h>
50 A CTF IR <strong><em>event class</em></strong> is a template that you
51 can use to create concrete \link ctfirevent CTF IR events\endlink.
53 An event class has the following properties:
56 - A numeric \b ID (\em must be unique amongst all the event classes
58 \link ctfirstreamclass CTF IR stream class\endlink).
59 - A optional <strong>log level</strong>.
60 - An optional <strong>Eclipse Modeling Framework URI</strong>.
62 A CTF IR event class owns two
63 \link ctfirfieldtypes field types\endlink:
65 - An optional <strong>event context</strong> field type, which
66 represents the \c event.context CTF scope.
67 - A mandatory <strong>event payload</strong> field type, which
68 represents the \c event.fields CTF scope.
70 Both field types \em must be structure field types as of
71 Babeltrace \btversion.
72 The event payload field type <em>must not</em> be empty.
74 As a reminder, here's the structure of a CTF packet:
78 In the Babeltrace CTF IR system, a \link ctfirtraceclass trace
79 class\endlink contains zero or more \link ctfirstreamclass stream
80 classes\endlink, and a stream class contains zero or more event classes.
82 Before you can create an event from an event class with
83 bt_ctf_event_create(), you \em must add the prepared event class to a
84 stream class by calling bt_ctf_stream_class_add_event_class(). This
85 function, when successful, \em freezes the event class, disallowing any
86 future modification of its properties and field types by the user.
88 As with any Babeltrace object, CTF IR event class objects have
89 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
90 counts</a>. See \ref refs to learn more about the reference counting
91 management of Babeltrace objects.
93 bt_ctf_stream_class_add_event_class() \em freezes its event class
94 parameter on success. You cannot modify a frozen event class: it is
95 considered immutable, except for \link refs reference counting\endlink.
101 @brief CTF IR event class type and functions.
104 @addtogroup ctfireventclass
109 @struct bt_ctf_event_class
110 @brief A CTF IR event class.
113 struct bt_ctf_event_class
;
115 struct bt_ctf_field_type
;
116 struct bt_ctf_stream_class
;
119 @brief Log level of an event class.
121 enum bt_ctf_event_class_log_level
{
122 /// Unknown, used for errors.
123 BT_CTF_EVENT_CLASS_LOG_LEVEL_UNKNOWN
= -1,
125 /// Unspecified log level.
126 BT_CTF_EVENT_CLASS_LOG_LEVEL_UNSPECIFIED
= 255,
128 /// System is unusable.
129 BT_CTF_EVENT_CLASS_LOG_LEVEL_EMERGENCY
= 0,
131 /// Action must be taken immediately.
132 BT_CTF_EVENT_CLASS_LOG_LEVEL_ALERT
= 1,
134 /// Critical conditions.
135 BT_CTF_EVENT_CLASS_LOG_LEVEL_CRITICAL
= 2,
137 /// Error conditions.
138 BT_CTF_EVENT_CLASS_LOG_LEVEL_ERROR
= 3,
140 /// Warning conditions.
141 BT_CTF_EVENT_CLASS_LOG_LEVEL_WARNING
= 4,
143 /// Normal, but significant, condition.
144 BT_CTF_EVENT_CLASS_LOG_LEVEL_NOTICE
= 5,
146 /// Informational message.
147 BT_CTF_EVENT_CLASS_LOG_LEVEL_INFO
= 6,
149 /// Debug information with system-level scope (set of programs).
150 BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM
= 7,
152 /// Debug information with program-level scope (set of processes).
153 BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM
= 8,
155 /// Debug information with process-level scope (set of modules).
156 BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS
= 9,
158 /// Debug information with module (executable/library) scope (set of units).
159 BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE
= 10,
161 /// Debug information with compilation unit scope (set of functions).
162 BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT
= 11,
164 /// Debug information with function-level scope.
165 BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION
= 12,
167 /// Debug information with line-level scope (default log level).
168 BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE
= 13,
170 /// Debug-level message.
171 BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG
= 14,
175 @name Creation and parent access functions
180 @brief Creates a default CTF IR event class named \p name.
182 On success, the context and payload field types are empty structure
183 field types. You can modify those default field types after the
184 event class is created with
185 bt_ctf_event_class_set_context_type() and
186 bt_ctf_event_class_set_payload_type().
188 Upon creation, the event class's ID is <em>not set</em>. You
189 can set it to a specific value with bt_ctf_event_class_set_id(). If it
190 is still unset when you call bt_ctf_stream_class_add_event_class(), then
191 the stream class assigns a unique ID to this event class before
194 The created event class's log level is initially set to
195 #BT_CTF_EVENT_CLASS_LOG_LEVEL_UNSPECIFIED and it has no Eclipse Modeling
198 @param[in] name Name of the event class to create (copied on success).
199 @returns Created event class, or \c NULL on error.
202 @postsuccessrefcountret1
204 extern struct bt_ctf_event_class
*bt_ctf_event_class_create(const char *name
);
207 @brief Returns the parent CTF IR stream class of the CTF IR event
208 class \p event_class.
210 It is possible that the event class was not added to a stream class
211 yet, in which case this function returns \c NULL. You can add an
212 event class to a stream class with
213 bt_ctf_stream_class_add_event_class().
215 @param[in] event_class Event class of which to get the parent
217 @returns Parent stream class of \p event_class,
218 or \c NULL if \p event_class was not
219 added to a stream class yet or on error.
221 @prenotnull{event_class}
222 @postrefcountsame{event_class}
223 @postsuccessrefcountretinc
225 @sa bt_ctf_stream_class_add_event_class(): Add an event class to
228 extern struct bt_ctf_stream_class
*bt_ctf_event_class_get_stream_class(
229 struct bt_ctf_event_class
*event_class
);
234 @name Attribute functions
239 @brief Returns the name of the CTF IR event class \p event_class.
241 On success, \p event_class remains the sole owner of the returned
244 @param[in] event_class Event class of which to get the name.
245 @returns Name of event class \p event_class, or
248 @prenotnull{event_class}
249 @postrefcountsame{event_class}
251 extern const char *bt_ctf_event_class_get_name(
252 struct bt_ctf_event_class
*event_class
);
255 @brief Returns the numeric ID of the CTF IR event class \p event_class.
257 @param[in] event_class Event class of which to get the numeric ID.
258 @returns ID of event class \p event_class, or a
259 negative value on error.
261 @prenotnull{event_class}
262 @postrefcountsame{event_class}
264 @sa bt_ctf_event_class_set_id(): Sets the numeric ID of a given
267 extern int64_t bt_ctf_event_class_get_id(
268 struct bt_ctf_event_class
*event_class
);
271 @brief Sets the numeric ID of the CTF IR event class
272 \p event_class to \p id.
274 \p id must be unique amongst the IDs of all the event classes
275 of the stream class to which you eventually add \p event_class.
277 @param[in] event_class Event class of which to set the numeric ID.
278 @param[in] id ID of the event class.
279 @returns 0 on success, or a negative value on error.
281 @prenotnull{event_class}
283 @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
284 @postrefcountsame{event_class}
286 @sa bt_ctf_event_class_get_id(): Returns the numeric ID of a given
289 extern int bt_ctf_event_class_set_id(
290 struct bt_ctf_event_class
*event_class
, uint64_t id
);
293 @brief Returns the log level of the CTF IR event class \p event_class.
295 @param[in] event_class Event class of which to get the log level.
296 @returns Log level of event class \p event_class,
297 #BT_CTF_EVENT_CLASS_LOG_LEVEL_UNSPECIFIED if
299 #BT_CTF_EVENT_CLASS_LOG_LEVEL_UNKNOWN on error.
301 @prenotnull{event_class}
302 @postrefcountsame{event_class}
304 @sa bt_ctf_event_class_set_log_level(): Sets the log level of a given
307 extern enum bt_ctf_event_class_log_level
bt_ctf_event_class_get_log_level(
308 struct bt_ctf_event_class
*event_class
);
311 @brief Sets the log level of the CTF IR event class
312 \p event_class to \p log_level.
314 @param[in] event_class Event class of which to set the log level.
315 @param[in] log_level Log level of the event class.
316 @returns 0 on success, or a negative value on error.
318 @prenotnull{event_class}
320 @pre \p log_level is #BT_CTF_EVENT_CLASS_LOG_LEVEL_UNSPECIFIED,
321 #BT_CTF_EVENT_CLASS_LOG_LEVEL_EMERGENCY,
322 #BT_CTF_EVENT_CLASS_LOG_LEVEL_ALERT,
323 #BT_CTF_EVENT_CLASS_LOG_LEVEL_CRITICAL,
324 #BT_CTF_EVENT_CLASS_LOG_LEVEL_ERROR,
325 #BT_CTF_EVENT_CLASS_LOG_LEVEL_WARNING,
326 #BT_CTF_EVENT_CLASS_LOG_LEVEL_NOTICE,
327 #BT_CTF_EVENT_CLASS_LOG_LEVEL_INFO,
328 #BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM,
329 #BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM,
330 #BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS,
331 #BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE,
332 #BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT,
333 #BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION,
334 #BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE, or
335 #BT_CTF_EVENT_CLASS_LOG_LEVEL_DEBUG.
336 @postrefcountsame{event_class}
338 @sa bt_ctf_event_class_get_log_level(): Returns the log level of a given
341 extern int bt_ctf_event_class_set_log_level(
342 struct bt_ctf_event_class
*event_class
,
343 enum bt_ctf_event_class_log_level log_level
);
346 @brief Returns the Eclipse Modeling Framework URI of the CTF IR event
347 class \p event_class.
349 @param[in] event_class Event class of which to get the
350 Eclipse Modeling Framework URI.
351 @returns Eclipse Modeling Framework URI of event
352 class \p event_class, or \c NULL on error.
354 @prenotnull{event_class}
355 @postrefcountsame{event_class}
357 @sa bt_ctf_event_class_set_emf_uri(): Sets the Eclipse Modeling
358 Framework URI of a given event class.
360 extern const char *bt_ctf_event_class_get_emf_uri(
361 struct bt_ctf_event_class
*event_class
);
364 @brief Sets the Eclipse Modeling Framework URI of the CTF IR event class
365 \p event_class to \p emf_uri, or unsets the event class's EMF URI.
367 @param[in] event_class Event class of which to set the
368 Eclipse Modeling Framework URI.
369 @param[in] emf_uri Eclipse Modeling Framework URI of the
370 event class (copied on success), or \c NULL
371 to unset the current EMF URI.
372 @returns 0 on success, or a negative value if there's
373 no EMF URI or on error.
375 @prenotnull{event_class}
378 @postrefcountsame{event_class}
380 @sa bt_ctf_event_class_get_emf_uri(): Returns the Eclipse Modeling
381 Framework URI of a given event class.
383 extern int bt_ctf_event_class_set_emf_uri(
384 struct bt_ctf_event_class
*event_class
,
385 const char *emf_uri
);
390 @name Contained field types functions
395 @brief Returns the context field type of the CTF IR event class
398 @param[in] event_class Event class of which to get the context field type.
399 @returns Context field type of \p event_class, or \c NULL if
400 \p event_class has no context field type or on error.
402 @prenotnull{event_class}
403 @postrefcountsame{event_class}
404 @post <strong>On success, if the return value is a field type</strong>, its
405 reference count is incremented.
407 @sa bt_ctf_event_class_set_context_type(): Sets the context field type of a
410 extern struct bt_ctf_field_type
*bt_ctf_event_class_get_context_type(
411 struct bt_ctf_event_class
*event_class
);
414 @brief Sets the context field type of the CTF IR event class \p event_class to
415 \p context_type, or unsets the current context field type from
418 If \p context_type is \c NULL, then this function unsets the current context
419 field type from \p event_class, effectively making \p event_class an event class
420 without a context field type.
422 As of Babeltrace \btversion, if \p context_type is not \c NULL,
423 \p context_type \em must be a CTF IR structure field type object.
425 @param[in] event_class Event class of which to set the context field
427 @param[in] context_type Context field type, or \c NULL to unset the
428 current context field type.
429 @returns 0 on success, or a negative value on error.
431 @prenotnull{event_class}
433 @pre <strong>If \p context_type is not \c NULL</strong>, \p context_type is a
434 CTF IR structure field type.
435 @postrefcountsame{event_class}
436 @post <strong>On success, if \p context_type is not \c NULL</strong>,
437 the reference count of \p context_type is incremented.
439 @sa bt_ctf_event_class_get_context_type(): Returns the context field type of a
442 extern int bt_ctf_event_class_set_context_type(
443 struct bt_ctf_event_class
*event_class
,
444 struct bt_ctf_field_type
*context_type
);
447 @brief Returns the payload field type of the CTF IR event class
450 @param[in] event_class Event class of which to get the payload field type.
451 @returns Payload field type of \p event_class, or \c NULL if
452 \p event_class has no payload field type or on error.
454 @prenotnull{event_class}
455 @postrefcountsame{event_class}
456 @post <strong>On success, if the return value is a field type</strong>, its
457 reference count is incremented.
459 @sa bt_ctf_event_class_set_payload_type(): Sets the payload field type of a
462 extern struct bt_ctf_field_type
*bt_ctf_event_class_get_payload_type(
463 struct bt_ctf_event_class
*event_class
);
466 @brief Sets the payload field type of the CTF IR event class \p event_class to
467 \p payload_type, or unsets the current payload field type from
470 If \p payload_type is \c NULL, then this function unsets the current payload
471 field type from \p event_class, effectively making \p event_class an event class
472 without a payload field type.
474 As of Babeltrace \btversion, if \p payload_type is not \c NULL,
475 \p payload_type \em must be a CTF IR structure field type object.
477 @param[in] event_class Event class of which to set the payload field
479 @param[in] payload_type Payload field type, or \c NULL to unset the
480 current payload field type.
481 @returns 0 on success, or a negative value on error.
483 @prenotnull{event_class}
485 @pre <strong>If \p payload_type is not \c NULL</strong>, \p payload_type is a
486 CTF IR structure field type.
487 @postrefcountsame{event_class}
488 @post <strong>On success, if \p payload_type is not \c NULL</strong>,
489 the reference count of \p payload_type is incremented.
491 @sa bt_ctf_event_class_get_payload_type(): Returns the payload field type of a
494 extern int bt_ctf_event_class_set_payload_type(
495 struct bt_ctf_event_class
*event_class
,
496 struct bt_ctf_field_type
*payload_type
);
499 @brief Returns the number of fields contained in the
500 payload field type of the CTF IR event class \p event_class.
503 Calling this function is the equivalent of getting the payload field
504 type of \p event_class with bt_ctf_event_class_get_payload_type() and
505 getting its field count with
506 bt_ctf_field_type_structure_get_field_count().
508 @param[in] event_class Event class of which to get the number
509 of fields contained in its payload field type.
510 @returns Number of fields in the payload field type
511 of \p event_class, or a negative value on error.
513 @prenotnull{event_class}
514 @postrefcountsame{event_class}
516 extern int64_t bt_ctf_event_class_get_payload_type_field_count(
517 struct bt_ctf_event_class
*event_class
);
520 @brief Returns the type and the name of the field at index \p index
521 in the payload field type of the CTF IR event class
524 On success, the field's type is placed in \p *field_type if
525 \p field_type is not \c NULL. The field's name is placed in
526 \p *name if \p name is not \c NULL. \p event_class remains the sole
529 Both \p name and \p field_type can be \c NULL if the caller is not
530 interested in one of them.
533 Calling this function is the equivalent of getting the payload field
534 type of \p event_class with bt_ctf_event_class_get_payload_type() and
535 getting the type and name of one of its field with
536 bt_ctf_field_type_structure_get_field().
538 @param[in] event_class Event class of which to get the type and name
539 of a field in its payload field type.
540 @param[out] field_name Name of the field at the index
541 \p index in the payload field type of
542 \p event_class (can be \c NULL).
543 @param[out] field_type Type of the field at the index \p index in the
544 payload field type of \p event_class
546 @param[in] index Index of the payload field type's field to find.
547 @returns 0 on success, or a negative value on error.
549 @prenotnull{event_class}
550 @pre \p index is lesser than the number of fields contained in the
551 payload field type of \p event_class (see
552 bt_ctf_event_class_get_payload_type_field_count()).
553 @postrefcountsame{event_class}
554 @post <strong>On success, if \p field_type is not \c NULL</strong>, the
555 reference count of \p *field_type is incremented.
557 extern int bt_ctf_event_class_get_payload_type_field_by_index(
558 struct bt_ctf_event_class
*event_class
,
559 const char **field_name
, struct bt_ctf_field_type
**field_type
,
563 @brief Returns the type of the field named \p name in the payload
564 field type of the CTF IR event class \p event_class.
567 Calling this function is the equivalent of getting the payload field
568 type of \p event_class with bt_ctf_event_class_get_payload_type() and
569 getting the type of one of its field with
570 bt_ctf_field_type_structure_get_field_type_by_name().
572 @param[in] event_class Event class of which to get the type of a
573 payload field type's field.
574 @param[in] name Name of the payload field type's field to get.
575 @returns Type of the field named \p name in the payload
576 field type of \p event_class, or \c NULL if
577 the function cannot find the field or
580 @prenotnull{event_class}
582 @postrefcountsame{event_class}
583 @postsuccessrefcountretinc
585 extern struct bt_ctf_field_type
*
586 bt_ctf_event_class_get_payload_type_field_type_by_name(
587 struct bt_ctf_event_class
*event_class
, const char *name
);
589 /* Pre-2.0 CTF writer compatibility */
590 #define bt_ctf_event_class_get_field_by_name bt_ctf_event_class_get_payload_type_field_type_by_name
593 @brief Adds a field named \p name with the type \p field_type to the
594 payload field type of the CTF IR event class \p event_class.
597 Calling this function is the equivalent of getting the payload field
598 type of \p event_class with bt_ctf_event_class_get_payload_type() and
599 adding a field to it with bt_ctf_field_type_structure_add_field().
601 @param[in] event_class Event class containing the payload field
602 type in which to add a field.
603 @param[in] field_type Type of the field to add.
604 @param[in] name Name of the field to add (copied on
606 @returns 0 on success, or a negative value on error.
608 @prenotnull{event_class}
612 @postrefcountsame{event_class}
613 @postsuccessrefcountinc{field_type}
615 extern int bt_ctf_event_class_add_field(struct bt_ctf_event_class
*event_class
,
616 struct bt_ctf_field_type
*field_type
,
627 #endif /* BABELTRACE_CTF_IR_EVENT_CLASS_H */