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
43 @defgroup ctfireventclass CTF IR event class
45 @brief CTF IR event class.
48 #include <babeltrace/ctf-ir/event-class.h>
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.
54 An event class has the following properties:
57 - A numeric \b ID (\em must be unique amongst all the event classes
59 \link ctfirstreamclass CTF IR stream class\endlink).
60 - A optional <strong>log level</strong>.
61 - An optional <strong>Eclipse Modeling Framework URI</strong>.
63 A CTF IR event class owns two
64 \link ctfirfieldtypes field types\endlink:
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.
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.
75 As a reminder, here's the structure of a CTF packet:
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.
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.
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.
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.
102 @brief CTF IR event class type and functions.
105 @addtogroup ctfireventclass
110 @struct bt_event_class
111 @brief A CTF IR event class.
114 struct bt_event_class
;
116 struct bt_field_type
;
117 struct bt_stream_class
;
120 @brief Log level of an event class.
122 enum bt_event_class_log_level
{
123 /// Unknown, used for errors.
124 BT_EVENT_CLASS_LOG_LEVEL_UNKNOWN
= -1,
126 /// Unspecified log level.
127 BT_EVENT_CLASS_LOG_LEVEL_UNSPECIFIED
= 255,
129 /// System is unusable.
130 BT_EVENT_CLASS_LOG_LEVEL_EMERGENCY
= 0,
132 /// Action must be taken immediately.
133 BT_EVENT_CLASS_LOG_LEVEL_ALERT
= 1,
135 /// Critical conditions.
136 BT_EVENT_CLASS_LOG_LEVEL_CRITICAL
= 2,
138 /// Error conditions.
139 BT_EVENT_CLASS_LOG_LEVEL_ERROR
= 3,
141 /// Warning conditions.
142 BT_EVENT_CLASS_LOG_LEVEL_WARNING
= 4,
144 /// Normal, but significant, condition.
145 BT_EVENT_CLASS_LOG_LEVEL_NOTICE
= 5,
147 /// Informational message.
148 BT_EVENT_CLASS_LOG_LEVEL_INFO
= 6,
150 /// Debug information with system-level scope (set of programs).
151 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM
= 7,
153 /// Debug information with program-level scope (set of processes).
154 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM
= 8,
156 /// Debug information with process-level scope (set of modules).
157 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS
= 9,
159 /// Debug information with module (executable/library) scope (set of units).
160 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE
= 10,
162 /// Debug information with compilation unit scope (set of functions).
163 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT
= 11,
165 /// Debug information with function-level scope.
166 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION
= 12,
168 /// Debug information with line-level scope (default log level).
169 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE
= 13,
171 /// Debug-level message.
172 BT_EVENT_CLASS_LOG_LEVEL_DEBUG
= 14,
176 @name Creation and parent access functions
181 @brief Creates a default CTF IR event class named \p name.
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().
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
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
199 @param[in] name Name of the event class to create (copied on success).
200 @returns Created event class, or \c NULL on error.
203 @postsuccessrefcountret1
205 extern struct bt_event_class
*bt_event_class_create(const char *name
);
208 @brief Returns the parent CTF IR stream class of the CTF IR event
209 class \p event_class.
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().
216 @param[in] event_class Event class of which to get the parent
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.
222 @prenotnull{event_class}
223 @postrefcountsame{event_class}
224 @postsuccessrefcountretinc
226 @sa bt_stream_class_add_event_class(): Add an event class to
229 extern struct bt_stream_class
*bt_event_class_get_stream_class(
230 struct bt_event_class
*event_class
);
235 @name Attribute functions
240 @brief Returns the name of the CTF IR event class \p event_class.
242 On success, \p event_class remains the sole owner of the returned
245 @param[in] event_class Event class of which to get the name.
246 @returns Name of event class \p event_class, or
249 @prenotnull{event_class}
250 @postrefcountsame{event_class}
252 extern const char *bt_event_class_get_name(
253 struct bt_event_class
*event_class
);
256 @brief Returns the numeric ID of the CTF IR event class \p event_class.
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.
262 @prenotnull{event_class}
263 @postrefcountsame{event_class}
265 @sa bt_event_class_set_id(): Sets the numeric ID of a given
268 extern int64_t bt_event_class_get_id(
269 struct bt_event_class
*event_class
);
272 @brief Sets the numeric ID of the CTF IR event class
273 \p event_class to \p id.
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.
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.
282 @prenotnull{event_class}
284 @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
285 @postrefcountsame{event_class}
287 @sa bt_event_class_get_id(): Returns the numeric ID of a given
290 extern int bt_event_class_set_id(
291 struct bt_event_class
*event_class
, uint64_t id
);
294 @brief Returns the log level of the CTF IR event class \p event_class.
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
300 #BT_EVENT_CLASS_LOG_LEVEL_UNKNOWN on error.
302 @prenotnull{event_class}
303 @postrefcountsame{event_class}
305 @sa bt_event_class_set_log_level(): Sets the log level of a given
308 extern enum bt_event_class_log_level
bt_event_class_get_log_level(
309 struct bt_event_class
*event_class
);
312 @brief Sets the log level of the CTF IR event class
313 \p event_class to \p log_level.
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.
319 @prenotnull{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}
339 @sa bt_event_class_get_log_level(): Returns the log level of a given
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
);
347 @brief Returns the Eclipse Modeling Framework URI of the CTF IR event
348 class \p event_class.
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.
355 @prenotnull{event_class}
356 @postrefcountsame{event_class}
358 @sa bt_event_class_set_emf_uri(): Sets the Eclipse Modeling
359 Framework URI of a given event class.
361 extern const char *bt_event_class_get_emf_uri(
362 struct bt_event_class
*event_class
);
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.
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.
376 @prenotnull{event_class}
379 @postrefcountsame{event_class}
381 @sa bt_event_class_get_emf_uri(): Returns the Eclipse Modeling
382 Framework URI of a given event class.
384 extern int bt_event_class_set_emf_uri(
385 struct bt_event_class
*event_class
,
386 const char *emf_uri
);
391 @name Contained field types functions
396 @brief Returns the context field type of the CTF IR event class
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.
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.
408 @sa bt_event_class_set_context_field_type(): Sets the context field type of a
411 extern struct bt_field_type
*bt_event_class_get_context_field_type(
412 struct bt_event_class
*event_class
);
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
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.
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.
426 @param[in] event_class Event class of which to set the context field
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.
432 @prenotnull{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.
440 @sa bt_event_class_get_context_field_type(): Returns the context field type of a
443 extern int bt_event_class_set_context_field_type(
444 struct bt_event_class
*event_class
,
445 struct bt_field_type
*context_type
);
448 @brief Returns the payload field type of the CTF IR event class
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.
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.
460 @sa bt_event_class_set_payload_field_type(): Sets the payload field type of a
463 extern struct bt_field_type
*bt_event_class_get_payload_field_type(
464 struct bt_event_class
*event_class
);
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
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.
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.
478 @param[in] event_class Event class of which to set the payload field
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.
484 @prenotnull{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.
492 @sa bt_event_class_get_payload_field_type(): Returns the payload field type of a
495 extern int bt_event_class_set_payload_field_type(
496 struct bt_event_class
*event_class
,
497 struct bt_field_type
*payload_type
);
507 #endif /* BABELTRACE_CTF_IR_EVENT_CLASS_H */