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, both of which \em must
54 be unique amongst all the event classes contained in the same
55 \link ctfirstreamclass CTF IR stream class\endlink:
60 A CTF IR event class owns two
61 \link ctfirfieldtypes field types\endlink:
63 - An optional <strong>event context</strong> field type, which
64 represents the \c event.context CTF scope.
65 - A mandatory <strong>event payload</strong> field type, which
66 represents the \c event.fields CTF scope.
68 Both field types \em must be structure field types as of
69 Babeltrace \btversion.
70 The event payload field type <em>must not</em> be empty.
72 As a reminder, here's the structure of a CTF packet:
76 In the Babeltrace CTF IR system, a \link ctfirtraceclass trace
77 class\endlink contains zero or more \link ctfirstreamclass stream
78 classes\endlink, and a stream class contains zero or more event classes.
80 Before you can create an event from an event class with
81 bt_ctf_event_create(), you \em must add the prepared event class to a
82 stream class by calling bt_ctf_stream_class_add_event_class(). This
83 function, when successful, \em freezes the event class, disallowing any
84 future modification of its properties and field types by the user.
86 As with any Babeltrace object, CTF IR event class objects have
87 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
88 counts</a>. See \ref refs to learn more about the reference counting
89 management of Babeltrace objects.
91 bt_ctf_stream_class_add_event_class() \em freezes its event class
92 parameter on success. You cannot modify a frozen event class: it is
93 considered immutable, except for \link refs reference counting\endlink.
99 @brief CTF IR event class type and functions.
102 @addtogroup ctfireventclass
107 @struct bt_ctf_event_class
108 @brief A CTF IR event class.
111 struct bt_ctf_event_class
;
113 struct bt_ctf_field_type
;
114 struct bt_ctf_stream_class
;
117 @name Creation and parent access functions
122 @brief Creates a default CTF IR event class named \p name.
124 On success, the context and payload field types are empty structure
125 field types. You can modify those default field types after the
126 event class is created with
127 bt_ctf_event_class_set_context_type() and
128 bt_ctf_event_class_set_payload_type().
130 Upon creation, the event class's ID is <em>not set</em>. You
131 can set it to a specific value with bt_ctf_event_class_set_id(). If it
132 is still unset when you call bt_ctf_stream_class_add_event_class(), then
133 the stream class assigns a unique ID to this event class before
136 @param[in] name Name of the event class to create (copied on success).
137 @returns Created event class, or \c NULL on error.
140 @postsuccessrefcountret1
142 extern struct bt_ctf_event_class
*bt_ctf_event_class_create(const char *name
);
145 @brief Returns the parent CTF IR stream class of the CTF IR event
146 class \p event_class.
148 It is possible that the event class was not added to a stream class
149 yet, in which case this function returns \c NULL. You can add an
150 event class to a stream class with
151 bt_ctf_stream_class_add_event_class().
153 @param[in] event_class Event class of which to get the parent
155 @returns Parent stream class of \p event_class,
156 or \c NULL if \p event_class was not
157 added to a stream class yet or on error.
159 @prenotnull{event_class}
160 @postrefcountsame{event_class}
161 @postsuccessrefcountretinc
163 @sa bt_ctf_stream_class_add_event_class(): Add an event class to
166 extern struct bt_ctf_stream_class
*bt_ctf_event_class_get_stream_class(
167 struct bt_ctf_event_class
*event_class
);
172 @name Attribute functions
177 @brief Returns the name of the CTF IR event class \p event_class.
179 On success, \p event_class remains the sole owner of the returned
182 @param[in] event_class Event class of which to get the name.
183 @returns Name of event class \p event_class, or
186 @prenotnull{event_class}
187 @postrefcountsame{event_class}
189 extern const char *bt_ctf_event_class_get_name(
190 struct bt_ctf_event_class
*event_class
);
193 @brief Returns the numeric ID of the CTF IR event class \p event_class.
195 @param[in] event_class Event class of which to get the numeric ID.
196 @returns ID of event class \p event_class, or a
197 negative value on error.
199 @prenotnull{event_class}
200 @postrefcountsame{event_class}
202 @sa bt_ctf_event_class_set_id(): Sets the numeric ID of a given
205 extern int64_t bt_ctf_event_class_get_id(
206 struct bt_ctf_event_class
*event_class
);
209 @brief Sets the numeric ID of the CTF IR event class
210 \p event_class to \p id.
212 \p id must be unique amongst the IDs of all the event classes
213 of the stream class to which you eventually add \p event_class.
215 @param[in] event_class Event class of which to set the numeric ID.
216 @param[in] id ID of the event class.
217 @returns 0 on success, or a negative value on error.
219 @prenotnull{event_class}
221 @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
222 @postrefcountsame{event_class}
224 @sa bt_ctf_event_class_get_id(): Returns the numeric ID of a given
227 extern int bt_ctf_event_class_set_id(
228 struct bt_ctf_event_class
*event_class
, uint64_t id
);
231 @brief Returns the number of attributes contained in the CTF IR event
232 class \p event_class.
234 @param[in] event_class Event class of which to get the number
235 of contained attributes.
236 @returns Number of contained attributes in
237 \p event_class, or a negative value on error.
239 @prenotnull{event_class}
240 @postrefcountsame{event_class}
242 @sa bt_ctf_event_class_get_attribute_name_by_index(): Returns the name
243 of the attribute of a given event class at a given index.
244 @sa bt_ctf_event_class_get_attribute_value_by_index(): Returns the value
245 of the attribute of a given event class at a given index.
247 extern int64_t bt_ctf_event_class_get_attribute_count(
248 struct bt_ctf_event_class
*event_class
);
251 @brief Returns the name of the attribute at the index \p index of the
252 CTF IR event class \p event_class.
254 On success, \p event_class remains the sole owner of the returned
257 @param[in] event_class Event class of which to get the name
259 @param[in] index Index of the attribute of which to get the name.
260 @returns Attribute name, or \c NULL on error.
262 @prenotnull{event_class}
263 @pre \p index is lesser than the number of attributes contained by
265 @postrefcountsame{event_class}
267 @sa bt_ctf_event_class_get_attribute_value_by_index(): Returns the value
268 of the attribute of a given event class at a given index.
271 bt_ctf_event_class_get_attribute_name_by_index(
272 struct bt_ctf_event_class
*event_class
, uint64_t index
);
275 @brief Returns the value of the attribute at the index \p index of the
276 CTF IR event class \p event_class.
278 @param[in] event_class Event class of which to get the value
280 @param[in] index Index of the attribute of which to get the value.
281 @returns Attribute value, or \c NULL on error.
283 @prenotnull{event_class}
284 @pre \p index is lesser than the number of attributes contained by
286 @postsuccessrefcountretinc
287 @postrefcountsame{event_class}
289 @sa bt_ctf_event_class_get_attribute_name_by_index(): Returns the name
290 of the attribute of a given event class at a given index.
292 extern struct bt_value
*
293 bt_ctf_event_class_get_attribute_value_by_index(
294 struct bt_ctf_event_class
*event_class
, uint64_t index
);
297 @brief Returns the value of the attribute named \p name of the CTF IR
298 event class \p event_class.
300 On success, the reference count of the returned value object is
303 @param[in] event_class Event class of which to get the value
305 @param[in] name Name of the attribute to get.
306 @returns Attribute value, or \c NULL on error.
308 @prenotnull{event_class}
310 @postsuccessrefcountretinc
311 @postrefcountsame{event_class}
313 extern struct bt_value
*
314 bt_ctf_event_class_get_attribute_value_by_name(
315 struct bt_ctf_event_class
*event_class
, const char *name
);
318 @brief Sets the attribute named \p name of the CTF IR event class
319 \p event_class to the value \p value.
321 Valid attributes, as of Babeltrace \btversion, are:
323 - <code>id</code>: \em must be an integer value object with a raw value
324 that is greater than or equal to 0. This represents the event class's
325 numeric ID and you can also set it with bt_ctf_event_class_set_id().
327 - <code>name</code>: must be a string value object. This represents
328 the name of the event class.
330 - <code>loglevel</code>: must be an integer value object with a raw
331 value greater than or equal to 0. This represents the numeric log level
332 associated with this event class. Log level values
333 are application-specific.
335 - <code>model.emf.uri</code>: must be a string value object. This
336 represents the application-specific Eclipse Modeling Framework URI
339 @param[in] event_class Event class of which to set an
341 @param[in] name Attribute name (copied on success).
342 @param[in] value Attribute value.
343 @returns 0 on success, or a negative value on error.
345 @prenotnull{event_class}
349 @postrefcountsame{event_class}
350 @postsuccessrefcountinc{value}
352 @sa bt_ctf_event_class_get_attribute_value_by_name(): Returns the
353 attribute of a given event class having a given name.
355 extern int bt_ctf_event_class_set_attribute(
356 struct bt_ctf_event_class
*event_class
, const char *name
,
357 struct bt_value
*value
);
362 @name Contained field types functions
367 @brief Returns the context field type of the CTF IR event class
370 @param[in] event_class Event class of which to get the context field type.
371 @returns Context field type of \p event_class, or \c NULL if
372 \p event_class has no context field type or on error.
374 @prenotnull{event_class}
375 @postrefcountsame{event_class}
376 @post <strong>On success, if the return value is a field type</strong>, its
377 reference count is incremented.
379 @sa bt_ctf_event_class_set_context_type(): Sets the context field type of a
382 extern struct bt_ctf_field_type
*bt_ctf_event_class_get_context_type(
383 struct bt_ctf_event_class
*event_class
);
386 @brief Sets the context field type of the CTF IR event class \p event_class to
387 \p context_type, or unsets the current context field type from
390 If \p context_type is \c NULL, then this function unsets the current context
391 field type from \p event_class, effectively making \p event_class an event class
392 without a context field type.
394 As of Babeltrace \btversion, if \p context_type is not \c NULL,
395 \p context_type \em must be a CTF IR structure field type object.
397 @param[in] event_class Event class of which to set the context field
399 @param[in] context_type Context field type, or \c NULL to unset the
400 current context field type.
401 @returns 0 on success, or a negative value on error.
403 @prenotnull{event_class}
405 @pre <strong>If \p context_type is not \c NULL</strong>, \p context_type is a
406 CTF IR structure field type.
407 @postrefcountsame{event_class}
408 @post <strong>On success, if \p context_type is not \c NULL</strong>,
409 the reference count of \p context_type is incremented.
411 @sa bt_ctf_event_class_get_context_type(): Returns the context field type of a
414 extern int bt_ctf_event_class_set_context_type(
415 struct bt_ctf_event_class
*event_class
,
416 struct bt_ctf_field_type
*context_type
);
419 @brief Returns the payload field type of the CTF IR event class
422 @param[in] event_class Event class of which to get the payload field type.
423 @returns Payload field type of \p event_class, or \c NULL if
424 \p event_class has no payload field type or on error.
426 @prenotnull{event_class}
427 @postrefcountsame{event_class}
428 @post <strong>On success, if the return value is a field type</strong>, its
429 reference count is incremented.
431 @sa bt_ctf_event_class_set_payload_type(): Sets the payload field type of a
434 extern struct bt_ctf_field_type
*bt_ctf_event_class_get_payload_type(
435 struct bt_ctf_event_class
*event_class
);
438 @brief Sets the payload field type of the CTF IR event class \p event_class to
439 \p payload_type, or unsets the current payload field type from
442 If \p payload_type is \c NULL, then this function unsets the current payload
443 field type from \p event_class, effectively making \p event_class an event class
444 without a payload field type.
446 As of Babeltrace \btversion, if \p payload_type is not \c NULL,
447 \p payload_type \em must be a CTF IR structure field type object.
449 @param[in] event_class Event class of which to set the payload field
451 @param[in] payload_type Payload field type, or \c NULL to unset the
452 current payload field type.
453 @returns 0 on success, or a negative value on error.
455 @prenotnull{event_class}
457 @pre <strong>If \p payload_type is not \c NULL</strong>, \p payload_type is a
458 CTF IR structure field type.
459 @postrefcountsame{event_class}
460 @post <strong>On success, if \p payload_type is not \c NULL</strong>,
461 the reference count of \p payload_type is incremented.
463 @sa bt_ctf_event_class_get_payload_type(): Returns the payload field type of a
466 extern int bt_ctf_event_class_set_payload_type(
467 struct bt_ctf_event_class
*event_class
,
468 struct bt_ctf_field_type
*payload_type
);
471 @brief Returns the number of fields contained in the
472 payload field type of the CTF IR event class \p event_class.
475 Calling this function is the equivalent of getting the payload field
476 type of \p event_class with bt_ctf_event_class_get_payload_type() and
477 getting its field count with
478 bt_ctf_field_type_structure_get_field_count().
480 @param[in] event_class Event class of which to get the number
481 of fields contained in its payload field type.
482 @returns Number of fields in the payload field type
483 of \p event_class, or a negative value on error.
485 @prenotnull{event_class}
486 @postrefcountsame{event_class}
488 extern int64_t bt_ctf_event_class_get_payload_type_field_count(
489 struct bt_ctf_event_class
*event_class
);
492 @brief Returns the type and the name of the field at index \p index
493 in the payload field type of the CTF IR event class
496 On success, the field's type is placed in \p *field_type if
497 \p field_type is not \c NULL. The field's name is placed in
498 \p *name if \p name is not \c NULL. \p event_class remains the sole
501 Both \p name and \p field_type can be \c NULL if the caller is not
502 interested in one of them.
505 Calling this function is the equivalent of getting the payload field
506 type of \p event_class with bt_ctf_event_class_get_payload_type() and
507 getting the type and name of one of its field with
508 bt_ctf_field_type_structure_get_field().
510 @param[in] event_class Event class of which to get the type and name
511 of a field in its payload field type.
512 @param[out] field_name Name of the field at the index
513 \p index in the payload field type of
514 \p event_class (can be \c NULL).
515 @param[out] field_type Type of the field at the index \p index in the
516 payload field type of \p event_class
518 @param[in] index Index of the payload field type's field to find.
519 @returns 0 on success, or a negative value on error.
521 @prenotnull{event_class}
522 @pre \p index is lesser than the number of fields contained in the
523 payload field type of \p event_class (see
524 bt_ctf_event_class_get_payload_type_field_count()).
525 @postrefcountsame{event_class}
526 @post <strong>On success, if \p field_type is not \c NULL</strong>, the
527 reference count of \p *field_type is incremented.
529 extern int bt_ctf_event_class_get_payload_type_field_by_index(
530 struct bt_ctf_event_class
*event_class
,
531 const char **field_name
, struct bt_ctf_field_type
**field_type
,
535 @brief Returns the type of the field named \p name in the payload
536 field type of the CTF IR event class \p event_class.
539 Calling this function is the equivalent of getting the payload field
540 type of \p event_class with bt_ctf_event_class_get_payload_type() and
541 getting the type of one of its field with
542 bt_ctf_field_type_structure_get_field_type_by_name().
544 @param[in] event_class Event class of which to get the type of a
545 payload field type's field.
546 @param[in] name Name of the payload field type's field to get.
547 @returns Type of the field named \p name in the payload
548 field type of \p event_class, or \c NULL if
549 the function cannot find the field or
552 @prenotnull{event_class}
554 @postrefcountsame{event_class}
555 @postsuccessrefcountretinc
557 extern struct bt_ctf_field_type
*
558 bt_ctf_event_class_get_payload_type_field_type_by_name(
559 struct bt_ctf_event_class
*event_class
, const char *name
);
561 /* Pre-2.0 CTF writer compatibility */
562 #define bt_ctf_event_class_get_field_by_name bt_ctf_event_class_get_payload_type_field_type_by_name
565 @brief Adds a field named \p name with the type \p field_type to the
566 payload field type of the CTF IR event class \p event_class.
569 Calling this function is the equivalent of getting the payload field
570 type of \p event_class with bt_ctf_event_class_get_payload_type() and
571 adding a field to it with bt_ctf_field_type_structure_add_field().
573 @param[in] event_class Event class containing the payload field
574 type in which to add a field.
575 @param[in] field_type Type of the field to add.
576 @param[in] name Name of the field to add (copied on
578 @returns 0 on success, or a negative value on error.
580 @prenotnull{event_class}
584 @postrefcountsame{event_class}
585 @postsuccessrefcountinc{field_type}
587 extern int bt_ctf_event_class_add_field(struct bt_ctf_event_class
*event_class
,
588 struct bt_ctf_field_type
*field_type
,
599 #endif /* BABELTRACE_CTF_IR_EVENT_CLASS_H */
This page took 0.04254 seconds and 4 git commands to generate.