1 #ifndef BABELTRACE_CTF_WRITER_VISITOR_H
2 #define BABELTRACE_CTF_WRITER_VISITOR_H
5 * Copyright 2016 Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
9 * Permission is hereby granted, free of charge, to any person obtaining a copy
10 * of this software and associated documentation files (the "Software"), to deal
11 * in the Software without restriction, including without limitation the rights
12 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13 * copies of the Software, and to permit persons to whom the Software is
14 * furnished to do so, subject to the following conditions:
16 * The above copyright notice and this permission notice shall be included in
17 * all copies or substantial portions of the Software.
19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 * The Common Trace Format (CTF) Specification is available at
28 * http://www.efficios.com/ctf
36 @defgroup ctfirvisitor CTF IR visitor
38 @brief CTF IR visitor.
41 #include <babeltrace/trace-ir/visitor.h>
44 A CTF IR <strong><em>visitor</em></strong> is a function that you
45 can use to visit the hierarchy of a
46 \link ctfirtraceclass CTF IR trace class\endlink with
47 bt_ctf_trace_visit() or of a
48 \link ctfirstreamclass CTF IR stream class\endlink with
49 bt_ctf_stream_class_visit().
51 The traversal of the object's hierarchy is always done in a
58 @brief CTF IR visitor types and functions.
61 @addtogroup ctfirvisitor
67 @brief A CTF IR object wrapper.
69 This structure wraps both a CTF IR object and its type
70 (see #bt_ctf_object_type). It is used in the visiting function.
72 You can use the bt_ctf_object_get_type() and
73 bt_ctf_object_get_object() accessors to get the type and wrapped
74 CTF IR object of a CTF IR object wrapper.
76 A CTF IR object wrapper has <strong>no reference count</strong>: do \em
77 not use bt_ctf_object_put_ref() or bt_ctf_object_get_ref() on it.
81 struct bt_ctf_visitor_object
;
84 @brief CTF IR object wrapper type.
86 enum bt_ctf_visitor_object_type
{
87 /// Unknown (used for errors).
88 BT_CTF_VISITOR_OBJECT_TYPE_UNKNOWN
= -1,
90 /// \ref ctfirtraceclass.
91 BT_CTF_VISITOR_OBJECT_TYPE_TRACE
= 0,
93 /// \ref ctfirstreamclass.
94 BT_CTF_VISITOR_OBJECT_TYPE_STREAM_CLASS
= 1,
97 BT_CTF_VISITOR_OBJECT_TYPE_STREAM
= 2,
99 /// \ref ctfireventclass.
100 BT_CTF_VISITOR_OBJECT_TYPE_EVENT_CLASS
= 3,
103 BT_CTF_VISITOR_OBJECT_TYPE_EVENT
= 4,
105 /// Number of entries in this enumeration.
106 BT_CTF_VISITOR_OBJECT_TYPE_NR
,
110 @brief Visting function type.
112 A function of this type is called by bt_ctf_trace_visit() or
113 bt_ctf_stream_class_visit() when visiting the CTF IR object wrapper
116 \p object has <strong>no reference count</strong>: do \em not use
117 bt_ctf_object_put_ref() or bt_ctf_object_get_ref() on it.
119 @param[in] object Currently visited CTF IR object wrapper.
120 @param[in] data User data.
121 @returns 0 on success, or a negative value on error.
125 @sa bt_ctf_trace_visit(): Accepts a visitor to visit a trace class.
126 @sa bt_ctf_stream_class_visit(): Accepts a visitor to visit a stream
129 typedef int (*bt_ctf_visitor
)(struct bt_ctf_visitor_object
*object
,
133 @brief Returns the type of the CTF IR object wrapped by the CTF IR
134 object wrapper \p object.
136 @param[in] object Object wrapper of which to get the type.
137 @returns Type of \p object.
141 @sa bt_ctf_visitor_object_get_object(): Returns the object wrapped by a given
142 CTF IR object wrapper.
144 enum bt_ctf_visitor_object_type
bt_ctf_visitor_object_get_type(
145 struct bt_ctf_visitor_object
*object
);
148 @brief Returns the CTF IR object wrapped by the CTF IR object
151 The reference count of \p object is \em not incremented by this
152 function. On success, you must call bt_ctf_object_get_ref() on the return value to
153 have your own reference.
155 @param[in] object Object wrapper of which to get the wrapped
157 @returns CTF IR object wrapped by \p object.
160 @post The reference count of the returned object is not modified.
162 @sa bt_ctf_visitor_object_get_type(): Returns the type of a given
163 CTF IR object wrapper.
165 void *bt_ctf_visitor_object_get_object(struct bt_ctf_visitor_object
*object
);
173 #endif /* BABELTRACE_CTF_WRITER_VISITOR_H */