ctf plugin: notif iter: use "borrow" functions for metadata where possible
[babeltrace.git] / 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 */
This page took 0.044161 seconds and 4 git commands to generate.