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
34 #include <babeltrace/ref.h>
46 @defgroup ctfireventclass CTF IR event class
48 @brief CTF IR event class.
51 #include <babeltrace/ctf-ir/event-class.h>
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.
57 An event class has the following properties:
60 - A numeric \b ID (\em must be unique amongst all the event classes
62 \link ctfirstreamclass CTF IR stream class\endlink).
63 - A optional <strong>log level</strong>.
64 - An optional <strong>Eclipse Modeling Framework URI</strong>.
66 A CTF IR event class owns two
67 \link ctfirfieldtypes field types\endlink:
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.
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.
78 As a reminder, here's the structure of a CTF packet:
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.
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.
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.
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.
105 @brief CTF IR event class type and functions.
108 @addtogroup ctfireventclass
113 @struct bt_event_class
114 @brief A CTF IR event class.
117 struct bt_event_class
;
119 struct bt_field_type
;
120 struct bt_stream_class
;
123 @brief Log level of an event class.
125 enum bt_event_class_log_level
{
126 /// Unknown, used for errors.
127 BT_EVENT_CLASS_LOG_LEVEL_UNKNOWN
= -1,
129 /// Unspecified log level.
130 BT_EVENT_CLASS_LOG_LEVEL_UNSPECIFIED
= 255,
132 /// System is unusable.
133 BT_EVENT_CLASS_LOG_LEVEL_EMERGENCY
= 0,
135 /// Action must be taken immediately.
136 BT_EVENT_CLASS_LOG_LEVEL_ALERT
= 1,
138 /// Critical conditions.
139 BT_EVENT_CLASS_LOG_LEVEL_CRITICAL
= 2,
141 /// Error conditions.
142 BT_EVENT_CLASS_LOG_LEVEL_ERROR
= 3,
144 /// Warning conditions.
145 BT_EVENT_CLASS_LOG_LEVEL_WARNING
= 4,
147 /// Normal, but significant, condition.
148 BT_EVENT_CLASS_LOG_LEVEL_NOTICE
= 5,
150 /// Informational message.
151 BT_EVENT_CLASS_LOG_LEVEL_INFO
= 6,
153 /// Debug information with system-level scope (set of programs).
154 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM
= 7,
156 /// Debug information with program-level scope (set of processes).
157 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM
= 8,
159 /// Debug information with process-level scope (set of modules).
160 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS
= 9,
162 /// Debug information with module (executable/library) scope (set of units).
163 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE
= 10,
165 /// Debug information with compilation unit scope (set of functions).
166 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT
= 11,
168 /// Debug information with function-level scope.
169 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION
= 12,
171 /// Debug information with line-level scope (default log level).
172 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE
= 13,
174 /// Debug-level message.
175 BT_EVENT_CLASS_LOG_LEVEL_DEBUG
= 14,
179 @name Creation and parent access functions
184 @brief Creates a default CTF IR event class named \p name.
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().
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
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
202 @param[in] name Name of the event class to create (copied on success).
203 @returns Created event class, or \c NULL on error.
206 @postsuccessrefcountret1
208 extern struct bt_event_class
*bt_event_class_create(const char *name
);
210 extern struct bt_stream_class
*bt_event_class_borrow_stream_class(
211 struct bt_event_class
*event_class
);
214 @brief Returns the parent CTF IR stream class of the CTF IR event
215 class \p event_class.
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().
222 @param[in] event_class Event class of which to get the parent
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.
228 @prenotnull{event_class}
229 @postrefcountsame{event_class}
230 @postsuccessrefcountretinc
232 @sa bt_stream_class_add_event_class(): Add an event class to
236 struct bt_stream_class
*bt_event_class_get_stream_class(
237 struct bt_event_class
*event_class
)
239 return bt_get(bt_event_class_borrow_stream_class(event_class
));
245 @name Attribute functions
250 @brief Returns the name of the CTF IR event class \p event_class.
252 On success, \p event_class remains the sole owner of the returned
255 @param[in] event_class Event class of which to get the name.
256 @returns Name of event class \p event_class, or
259 @prenotnull{event_class}
260 @postrefcountsame{event_class}
262 extern const char *bt_event_class_get_name(
263 struct bt_event_class
*event_class
);
266 @brief Returns the numeric ID of the CTF IR event class \p event_class.
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.
272 @prenotnull{event_class}
273 @postrefcountsame{event_class}
275 @sa bt_event_class_set_id(): Sets the numeric ID of a given
278 extern int64_t bt_event_class_get_id(
279 struct bt_event_class
*event_class
);
282 @brief Sets the numeric ID of the CTF IR event class
283 \p event_class to \p id.
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.
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.
292 @prenotnull{event_class}
294 @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
295 @postrefcountsame{event_class}
297 @sa bt_event_class_get_id(): Returns the numeric ID of a given
300 extern int bt_event_class_set_id(
301 struct bt_event_class
*event_class
, uint64_t id
);
304 @brief Returns the log level of the CTF IR event class \p event_class.
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
310 #BT_EVENT_CLASS_LOG_LEVEL_UNKNOWN on error.
312 @prenotnull{event_class}
313 @postrefcountsame{event_class}
315 @sa bt_event_class_set_log_level(): Sets the log level of a given
318 extern enum bt_event_class_log_level
bt_event_class_get_log_level(
319 struct bt_event_class
*event_class
);
322 @brief Sets the log level of the CTF IR event class
323 \p event_class to \p log_level.
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.
329 @prenotnull{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}
349 @sa bt_event_class_get_log_level(): Returns the log level of a given
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
);
357 @brief Returns the Eclipse Modeling Framework URI of the CTF IR event
358 class \p event_class.
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.
365 @prenotnull{event_class}
366 @postrefcountsame{event_class}
368 @sa bt_event_class_set_emf_uri(): Sets the Eclipse Modeling
369 Framework URI of a given event class.
371 extern const char *bt_event_class_get_emf_uri(
372 struct bt_event_class
*event_class
);
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.
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.
386 @prenotnull{event_class}
389 @postrefcountsame{event_class}
391 @sa bt_event_class_get_emf_uri(): Returns the Eclipse Modeling
392 Framework URI of a given event class.
394 extern int bt_event_class_set_emf_uri(
395 struct bt_event_class
*event_class
,
396 const char *emf_uri
);
401 @name Contained field types functions
405 extern struct bt_field_type
*bt_event_class_borrow_context_field_type(
406 struct bt_event_class
*event_class
);
409 @brief Returns the context field type of the CTF IR event class
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.
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.
421 @sa bt_event_class_set_context_field_type(): Sets the context field type of a
425 struct bt_field_type
*bt_event_class_get_context_field_type(
426 struct bt_event_class
*event_class
)
428 return bt_get(bt_event_class_borrow_context_field_type(event_class
));
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
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.
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.
443 @param[in] event_class Event class of which to set the context field
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.
449 @prenotnull{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.
457 @sa bt_event_class_get_context_field_type(): Returns the context field type of a
460 extern int bt_event_class_set_context_field_type(
461 struct bt_event_class
*event_class
,
462 struct bt_field_type
*context_type
);
464 extern struct bt_field_type
*bt_event_class_borrow_payload_field_type(
465 struct bt_event_class
*event_class
);
468 @brief Returns the payload field type of the CTF IR event class
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.
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.
480 @sa bt_event_class_set_payload_field_type(): Sets the payload field type of a
484 struct bt_field_type
*bt_event_class_get_payload_field_type(
485 struct bt_event_class
*event_class
)
487 return bt_get(bt_event_class_borrow_payload_field_type(event_class
));
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
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.
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.
502 @param[in] event_class Event class of which to set the payload field
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.
508 @prenotnull{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.
516 @sa bt_event_class_get_payload_field_type(): Returns the payload field type of a
519 extern int bt_event_class_set_payload_field_type(
520 struct bt_event_class
*event_class
,
521 struct bt_field_type
*payload_type
);
531 #endif /* BABELTRACE_CTF_IR_EVENT_CLASS_H */