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.
46 A CTF IR <strong><em>event class</em></strong> is a template that you
47 can use to create concrete \link ctfirevent CTF IR events\endlink.
49 An event class has the following properties, both of which \em must
50 be unique amongst all the event classes contained in the same
51 \link ctfirstreamclass CTF IR stream class\endlink:
56 A CTF IR event class owns two
57 \link ctfirfieldtypes field types\endlink:
59 - An optional <strong>event context</strong> field type, which
60 represents the \c event.context CTF scope.
61 - A mandatory <strong>event payload</strong> field type, which
62 represents the \c event.fields CTF scope.
64 Both field types \em must be structure field types as of
65 Babeltrace \btversion.
66 The event payload field type <em>must not</em> be empty.
68 As a reminder, here's the structure of a CTF packet:
72 In the Babeltrace CTF IR system, a \link ctfirtraceclass trace
73 class\endlink contains zero or more \link ctfirstreamclass stream
74 classes\endlink, and a stream class contains zero or more event classes.
76 Before you can create an event from an event class with
77 bt_ctf_event_create(), you \em must add the prepared event class to a
78 stream class by calling bt_ctf_stream_class_add_event_class(). This
79 function, when successful, \em freezes the event class, disallowing any
80 future modification of its properties and field types by the user.
82 As with any Babeltrace object, CTF IR event class objects have
83 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
84 counts</a>. See \ref refs to learn more about the reference counting
85 management of Babeltrace objects.
87 bt_ctf_stream_class_add_event_class() \em freezes its event class
88 parameter on success. You cannot modify a frozen event class: it is
89 considered immutable, except for \link refs reference counting\endlink.
95 @brief CTF IR event class type and functions.
98 @addtogroup ctfireventclass
103 @struct bt_ctf_event_class
104 @brief A CTF IR event class.
107 struct bt_ctf_event_class
;
109 struct bt_ctf_field_type
;
110 struct bt_ctf_stream_class
;
113 @name Creation and parent access functions
118 @brief Creates a default CTF IR event class named \p name.
120 The event class is created \em without an event context
121 \link ctfirfieldtypes field type\endlink and with an empty event
124 Upon creation, the event class's ID is <em>not set</em>. You
125 can set it to a specific value with bt_ctf_event_class_set_id(). If it
126 is still unset when you call bt_ctf_stream_class_add_event_class(), then
127 the stream class assigns a unique ID to this event class before
130 @param[in] name Name of the event class to create (copied on success).
131 @returns Created event class, or \c NULL on error.
134 @postsuccessrefcountret1
136 extern struct bt_ctf_event_class
*bt_ctf_event_class_create(const char *name
);
139 @brief Returns the parent CTF IR stream class of the CTF IR event
140 class \p event_class.
142 It is possible that the event class was not added to a stream class
143 yet, in which case this function returns \c NULL. You can add an
144 event class to a stream class with
145 bt_ctf_stream_class_add_event_class().
147 @param[in] event_class Event class of which to get the parent
149 @returns Parent stream class of \p event_class,
150 or \c NULL if \p event_class was not
151 added to a stream class yet or on error.
153 @prenotnull{event_class}
154 @postsuccessrefcountretinc
156 @sa bt_ctf_stream_class_add_event_class(): Add an event class to
159 extern struct bt_ctf_stream_class
*bt_ctf_event_class_get_stream_class(
160 struct bt_ctf_event_class
*event_class
);
165 @name Attribute functions
170 @brief Returns the name of the CTF IR event class \p event_class.
172 On success, \p event_class remains the sole owner of the returned
175 @param[in] event_class Event class of which to get the name.
176 @returns Name of event class \p event_class, or
179 @prenotnull{event_class}
180 @postrefcountsame{event_class}
182 extern const char *bt_ctf_event_class_get_name(
183 struct bt_ctf_event_class
*event_class
);
186 @brief Returns the numeric ID of the CTF IR event class \p event_class.
188 @param[in] event_class Event class of which to get the numeric ID.
189 @returns ID of event class \p event_class, or a
190 negative value on error.
192 @prenotnull{event_class}
193 @postrefcountsame{event_class}
195 @sa bt_ctf_event_class_set_id(): Sets the numeric ID of a given
198 extern int64_t bt_ctf_event_class_get_id(
199 struct bt_ctf_event_class
*event_class
);
202 @brief Sets the numeric ID of the CTF IR event class
203 \p event_class to \p id.
205 \p id must be unique amongst the IDs of all the event classes
206 of the stream class to which you eventually add \p event_class.
208 @param[in] event_class Event class of which to set the numeric ID.
209 @param[in] id ID of the event class.
210 @returns 0 on success, or a negative value on error.
212 @prenotnull{event_class}
214 @postrefcountsame{event_class}
216 @sa bt_ctf_event_class_get_id(): Returns the numeric ID of a given
219 extern int bt_ctf_event_class_set_id(
220 struct bt_ctf_event_class
*event_class
, uint32_t id
);
223 @brief Returns the number of attributes contained in the CTF IR event
224 class \p event_class.
226 @param[in] event_class Event class of which to get the number
227 of contained attributes.
228 @returns Number of contained attributes in
229 \p event_class, or a negative value on error.
231 @prenotnull{event_class}
232 @postrefcountsame{event_class}
234 @sa bt_ctf_event_class_get_attribute_name(): Returns the name of
235 the attribute of a given event class at a given index.
236 @sa bt_ctf_event_class_get_attribute_value(): Returns the value of
237 the attribute of a given event class at a given index.
239 extern int bt_ctf_event_class_get_attribute_count(
240 struct bt_ctf_event_class
*event_class
);
243 @brief Returns the name of the attribute at the index \p index of the
244 CTF IR event class \p event_class.
246 On success, \p event_class remains the sole owner of the returned
249 @param[in] event_class Event class of which to get the name
251 @param[in] index Index of the attribute of which to get the name.
252 @returns Attribute name, or \c NULL on error.
254 @prenotnull{event_class}
255 @pre \p index is lesser than the number of attributes contained by
257 @postrefcountsame{event_class}
259 @sa bt_ctf_event_class_get_attribute_value(): Returns the value of
260 the attribute of a given event class at a given index.
263 bt_ctf_event_class_get_attribute_name(
264 struct bt_ctf_event_class
*event_class
, int index
);
267 @brief Returns the value of the attribute at the index \p index of the
268 CTF IR event class \p event_class.
270 @param[in] event_class Event class of which to get the value
272 @param[in] index Index of the attribute of which to get the value.
273 @returns Attribute value, or \c NULL on error.
275 @prenotnull{event_class}
276 @pre \p index is lesser than the number of attributes contained by
278 @postsuccessrefcountretinc
279 @postrefcountsame{event_class}
281 @sa bt_ctf_event_class_get_attribute_name(): Returns the name of
282 the attribute of a given event class at a given index.
284 extern struct bt_value
*
285 bt_ctf_event_class_get_attribute_value(struct bt_ctf_event_class
*event_class
,
289 @brief Returns the value of the attribute named \p name of the CTF IR
290 event class \p event_class.
292 On success, the reference count of the returned value object is
295 @param[in] event_class Event class of which to get the value
297 @param[in] name Name of the attribute to get.
298 @returns Attribute value, or \c NULL on error.
300 @prenotnull{event_class}
302 @postsuccessrefcountretinc
303 @postrefcountsame{event_class}
305 extern struct bt_value
*
306 bt_ctf_event_class_get_attribute_value_by_name(
307 struct bt_ctf_event_class
*event_class
, const char *name
);
310 @brief Sets the attribute named \p name of the CTF IR event class
311 \p event_class to the value \p value.
313 Valid attributes, as of Babeltrace \btversion, are:
315 - <code>id</code>: \em must be an integer value object with a raw value
316 that is greater than or equal to 0. This represents the event class's
317 numeric ID and you can also set it with bt_ctf_event_class_set_id().
319 - <code>name</code>: must be a string value object. This represents
320 the name of the event class.
322 - <code>loglevel</code>: must be an integer value object with a raw
323 value greater than or equal to 0. This represents the numeric log level
324 associated with this event class. Log level values
325 are application-specific.
327 - <code>model.emf.uri</code>: must be a string value object. This
328 represents the application-specific Eclipse Modeling Framework URI
331 @param[in] event_class Event class of which to set an
333 @param[in] name Attribute name (copied on success).
334 @param[in] value Attribute value.
335 @returns 0 on success, or a negative value on error.
337 @prenotnull{event_class}
341 @postrefcountsame{event_class}
342 @postsuccessrefcountinc{value}
344 @sa bt_ctf_event_class_get_attribute_value_by_name(): Returns the
345 attribute of a given event class having a given name.
347 extern int bt_ctf_event_class_set_attribute(
348 struct bt_ctf_event_class
*event_class
, const char *name
,
349 struct bt_value
*value
);
354 @name Contained field types functions
359 @brief Returns the payload field type of the CTF IR event class
362 @param[in] event_class Event class of which to get the
364 @returns Payload field type of \p event_class,
367 @prenotnull{event_class}
368 @postsuccessrefcountretinc
370 @sa bt_ctf_event_class_set_payload_type(): Sets the payload field
371 type of a given event class.
373 extern struct bt_ctf_field_type
*bt_ctf_event_class_get_payload_type(
374 struct bt_ctf_event_class
*event_class
);
377 @brief Sets the payload field type of the CTF IR event class
378 \p event_class to \p payload_type.
380 As of Babeltrace \btversion, \p payload_type \em must be a
381 CTF IR structure field type object.
383 @param[in] event_class Event class of which to set the payload
385 @param[in] payload_type Payload field type.
386 @returns 0 on success, or a negative value on error.
388 @prenotnull{event_class}
389 @prenotnull{payload_type}
391 @preisstructft{payload_type}
392 @postrefcountsame{event_class}
393 @postsuccessrefcountinc{payload_type}
395 @sa bt_ctf_event_class_get_payload_type(): Returns the payload field
396 type of a given event class.
398 extern int bt_ctf_event_class_set_payload_type(
399 struct bt_ctf_event_class
*event_class
,
400 struct bt_ctf_field_type
*payload_type
);
403 @brief Returns the number of fields contained in the
404 payload field type of the CTF IR event class \p event_class.
407 Calling this function is the equivalent of getting the payload field
408 type of \p event_class with bt_ctf_event_class_get_payload_type() and
409 getting its field count with
410 bt_ctf_field_type_structure_get_field_count().
412 @param[in] event_class Event class of which to get the number
413 of fields contained in its payload field type.
414 @returns Number of fields in the payload field type
415 of \p event_class, or a negative value on error.
417 @prenotnull{event_class}
418 @postrefcountsame{event_class}
420 extern int bt_ctf_event_class_get_field_count(
421 struct bt_ctf_event_class
*event_class
);
424 @brief Returns the type and the name of the field at index \p index
425 in the payload field type of the CTF IR event class
428 On success, the field's type is placed in \p *field_type if
429 \p field_type is not \c NULL. The field's name is placed in
430 \p *name if \p name is not \c NULL. \p event_class remains the sole
433 Both \p name and \p field_type can be \c NULL if the caller is not
434 interested in one of them.
437 Calling this function is the equivalent of getting the payload field
438 type of \p event_class with bt_ctf_event_class_get_payload_type() and
439 getting the type and name of one of its field with
440 bt_ctf_field_type_structure_get_field().
442 @param[in] event_class Event class of which to get the type and name
443 of a field in its payload field type.
444 @param[out] field_name Name of the field at the index
445 \p index in the payload field type of
446 \p event_class (can be \c NULL).
447 @param[out] field_type Type of the field at the index \p index in the
448 payload field type of \p event_class
450 @param[in] index Index of the payload field type's field to find.
451 @returns 0 on success, or a negative value on error.
453 @prenotnull{event_class}
454 @pre \p index is lesser than the number of fields contained in the
455 payload field type of \p event_class (see
456 bt_ctf_event_class_get_field_count()).
457 @postrefcountsame{event_class}
458 @post <strong>On success, if \p field_type is not \c NULL</strong>, the
459 reference count of \p *field_type is incremented.
461 extern int bt_ctf_event_class_get_field(struct bt_ctf_event_class
*event_class
,
462 const char **field_name
, struct bt_ctf_field_type
**field_type
,
466 @brief Returns the type of the field named \p name in the payload
467 field type of the CTF IR event class \p event_class.
470 Calling this function is the equivalent of getting the payload field
471 type of \p event_class with bt_ctf_event_class_get_payload_type() and
472 getting the type of one of its field with
473 bt_ctf_field_type_structure_get_field_type_by_name().
475 @param[in] event_class Event class of which to get the type of a
476 payload field type's field.
477 @param[in] name Name of the payload field type's field to get.
478 @returns Type of the field named \p name in the payload
479 field type of \p event_class, or \c NULL if
480 the function cannot find the field or
483 @prenotnull{event_class}
485 @postrefcountsame{event_class}
486 @postsuccessrefcountretinc
489 extern struct bt_ctf_field_type
*bt_ctf_event_class_get_field_by_name(
490 struct bt_ctf_event_class
*event_class
, const char *name
);
493 @brief Adds a field named \p name with the type \p field_type to the
494 payload field type of the CTF IR event class \p event_class.
497 Calling this function is the equivalent of getting the payload field
498 type of \p event_class with bt_ctf_event_class_get_payload_type() and
499 adding a field to it with bt_ctf_field_type_structure_add_field().
501 @param[in] event_class Event class containing the payload field
502 type in which to add a field.
503 @param[in] field_type Type of the field to add.
504 @param[in] name Name of the field to add (copied on
506 @returns 0 on success, or a negative value on error.
508 @prenotnull{event_class}
512 @postrefcountsame{event_class}
513 @postsuccessrefcountinc{field_type}
515 extern int bt_ctf_event_class_add_field(struct bt_ctf_event_class
*event_class
,
516 struct bt_ctf_field_type
*field_type
,
520 @brief Returns the context field type of the CTF IR event class
523 @param[in] event_class Event class of which to get the
525 @returns Context field type of \p event_class,
528 @prenotnull{event_class}
529 @postsuccessrefcountretinc
531 @sa bt_ctf_event_class_set_context_type(): Sets the context field
532 type of a given event class.
534 extern struct bt_ctf_field_type
*bt_ctf_event_class_get_context_type(
535 struct bt_ctf_event_class
*event_class
);
538 @brief Sets the context field type of the CTF IR event class
539 \p event_class to \p context_type.
541 As of Babeltrace \btversion, \p context_type \em must be a
542 CTF IR structure field type object.
544 @param[in] event_class Event class of which to set the context
546 @param[in] context_type Context field type.
547 @returns 0 on success, or a negative value on error.
549 @prenotnull{event_class}
550 @prenotnull{context_type}
552 @preisstructft{context_type}
553 @postrefcountsame{event_class}
554 @postsuccessrefcountinc{context_type}
556 @sa bt_ctf_event_class_get_context_type(): Returns the context field
557 type of a given event class.
559 extern int bt_ctf_event_class_set_context_type(
560 struct bt_ctf_event_class
*event_class
,
561 struct bt_ctf_field_type
*context_type
);
571 #endif /* BABELTRACE_CTF_IR_EVENT_CLASS_H */
This page took 0.056484 seconds and 5 git commands to generate.