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>
41 struct bt_ctf_event_class
;
43 struct bt_ctf_field_type
;
44 struct bt_ctf_stream_class
;
47 * bt_ctf_event_class_create: create an event class.
49 * Allocate a new event class of the given name. The creation of an event class
50 * sets its reference count to 1. A unique event id is automatically assigned
53 * @param name Event class name (will be copied).
55 * Returns an allocated event class on success, NULL on error.
57 extern struct bt_ctf_event_class
*bt_ctf_event_class_create(const char *name
);
60 * bt_ctf_event_class_get_name: Get an event class' name.
62 * @param event_class Event class.
64 * Returns the event class' name, NULL on error.
66 extern const char *bt_ctf_event_class_get_name(
67 struct bt_ctf_event_class
*event_class
);
70 * bt_ctf_event_class_get_id: Get an event class' id.
72 * @param event_class Event class.
74 * Returns the event class' id, a negative value on error.
76 extern int64_t bt_ctf_event_class_get_id(
77 struct bt_ctf_event_class
*event_class
);
80 * bt_ctf_event_class_set_id: Set an event class' id.
82 * Set an event class' id. Must be unique stream-wise.
83 * Note that event classes are already assigned a unique id when added to a
84 * stream class if none was set explicitly.
86 * @param event_class Event class.
87 * @param id Event class id.
89 * Returns 0 on success, a negative value on error.
91 extern int bt_ctf_event_class_set_id(
92 struct bt_ctf_event_class
*event_class
, uint32_t id
);
95 * bt_ctf_event_class_set_attribute: sets an attribute to the event
98 * Sets an attribute to the event class. The name parameter is copied,
99 * whereas the value parameter's reference count is incremented
100 * (if the function succeeds).
102 * If an attribute exists in the event class for the specified name, it
103 * is replaced by the new value.
105 * Valid attributes and object types are:
107 * - "id": integer object with a value >= 0
108 * - "name": string object
109 * - "loglevel": integer object with a value >= 0
110 * - "model.emf.uri": string object
112 * @param event_class Event class.
113 * @param name Name of the attribute (will be copied).
114 * @param value Value of the attribute.
116 * Returns 0 on success, a negative value on error.
118 extern int bt_ctf_event_class_set_attribute(
119 struct bt_ctf_event_class
*event_class
, const char *name
,
120 struct bt_value
*value
);
123 * bt_ctf_event_class_get_attribute_count: get the number of attributes
124 * in this event class.
126 * Get the event class' attribute count.
128 * @param event_class Event class.
130 * Returns the attribute count, a negative value on error.
132 extern int bt_ctf_event_class_get_attribute_count(
133 struct bt_ctf_event_class
*event_class
);
136 * bt_ctf_event_class_get_attribute_name: get attribute name.
138 * Get an attribute's name. The string's ownership is not
139 * transferred to the caller. The string data is valid as long as
140 * this event class' attributes are not modified.
142 * @param event_class Event class.
143 * @param index Index of the attribute.
145 * Returns the attribute's name, NULL on error.
148 bt_ctf_event_class_get_attribute_name(
149 struct bt_ctf_event_class
*event_class
, int index
);
152 * bt_ctf_event_class_get_attribute_value: get attribute value (an object).
154 * Get an attribute's value (an object). The returned object's
155 * reference count is incremented. When done with the object, the caller
156 * must call bt_value_put() on it.
158 * @param event_class Event class.
159 * @param index Index of the attribute.
161 * Returns the attribute's object value, NULL on error.
163 extern struct bt_value
*
164 bt_ctf_event_class_get_attribute_value(struct bt_ctf_event_class
*event_class
,
168 * bt_ctf_event_class_get_attribute_value_by_name: get attribute
169 * value (an object) by name.
171 * Get an attribute's value (an object) by its name. The returned object's
172 * reference count is incremented. When done with the object, the caller
173 * must call bt_value_put() on it.
175 * @param event_class Event class.
176 * @param name Attribute's name
178 * Returns the attribute's object value, NULL on error.
180 extern struct bt_value
*
181 bt_ctf_event_class_get_attribute_value_by_name(
182 struct bt_ctf_event_class
*event_class
, const char *name
);
185 * bt_ctf_event_class_get_stream_class: Get an event class' stream class.
187 * @param event_class Event class.
189 * Returns the event class' stream class, NULL on error or if the event class
190 * is not associated with a stream class.
192 extern struct bt_ctf_stream_class
*bt_ctf_event_class_get_stream_class(
193 struct bt_ctf_event_class
*event_class
);
196 * bt_ctf_event_class_get_payload_type: get an event class' payload.
198 * Get an event class' payload type.
200 * @param event_class Event class.
202 * Returns the event class' payload, NULL on error.
204 extern struct bt_ctf_field_type
*bt_ctf_event_class_get_payload_type(
205 struct bt_ctf_event_class
*event_class
);
208 * bt_ctf_event_class_set_payload_type: set an event class' payload.
210 * Set an event class' payload type.
212 * @param event_class Event class.
213 * @param payload The payload's type (must be a structure).
215 * Returns 0 on success, a negative value on error.
217 extern int bt_ctf_event_class_set_payload_type(
218 struct bt_ctf_event_class
*event_class
,
219 struct bt_ctf_field_type
*payload
);
222 * bt_ctf_event_class_add_field: add a field to an event class.
224 * Add a field of type "type" to the event class. The event class will share
225 * type's ownership by increasing its reference count. The "name" will be
228 * @param event_class Event class.
229 * @param type Field type to add to the event class.
230 * @param name Name of the new field.
232 * Returns 0 on success, a negative value on error.
234 * Note: Returns an error if the payload is not a structure.
236 extern int bt_ctf_event_class_add_field(struct bt_ctf_event_class
*event_class
,
237 struct bt_ctf_field_type
*type
,
241 * bt_ctf_event_class_get_field_count: Get an event class' field count.
243 * @param event_class Event class.
245 * Returns the event class' field count, a negative value on error.
247 * Note: Returns an error if the payload is not a structure.
249 extern int bt_ctf_event_class_get_field_count(
250 struct bt_ctf_event_class
*event_class
);
253 * bt_ctf_event_class_get_field: Get event class' field type and name by index.
255 * @param event_class Event class.
256 * @param field_name Pointer to a const char* where the field's name will
258 * @param field_type Pointer to a bt_ctf_field_type* where the field's type will
260 * @param index Index of field.
262 * Returns 0 on success, a negative error on value.
264 * Note: Returns an error if the payload is not a structure.
266 extern int bt_ctf_event_class_get_field(struct bt_ctf_event_class
*event_class
,
267 const char **field_name
, struct bt_ctf_field_type
**field_type
,
271 * bt_ctf_event_class_get_field_type_by_name: Get an event class's field by name
273 * @param event_class Event class.
274 * @param name Name of the field.
276 * Returns a field type on success, NULL on error.
278 * Note: Returns an error if the payload is not a structure.
280 extern struct bt_ctf_field_type
*bt_ctf_event_class_get_field_by_name(
281 struct bt_ctf_event_class
*event_class
, const char *name
);
284 * bt_ctf_event_class_get_context_type: Get an event class's context type
286 * @param event_class Event class.
288 * Returns a field type (a structure) on success, NULL on error.
290 extern struct bt_ctf_field_type
*bt_ctf_event_class_get_context_type(
291 struct bt_ctf_event_class
*event_class
);
294 * bt_ctf_event_class_set_context_type: Set an event class's context type
296 * @param event_class Event class.
297 * @param context Event context field type (must be a structure).
299 * Returns 0 on success, a negative value on error.
301 extern int bt_ctf_event_class_set_context_type(
302 struct bt_ctf_event_class
*event_class
,
303 struct bt_ctf_field_type
*context
);
306 * bt_ctf_event_class_get and bt_ctf_event_class_put: increment and decrement
307 * the event class' reference count.
309 * You may also use bt_ctf_get() and bt_ctf_put() with event class objects.
311 * These functions ensure that the event class won't be destroyed while it
312 * is in use. The same number of get and put (plus one extra put to
313 * release the initial reference done at creation) have to be done to
314 * destroy an event class.
316 * When the event class' reference count is decremented to 0 by a
317 * bt_ctf_event_class_put, the event class is freed.
319 * @param event_class Event class.
321 extern void bt_ctf_event_class_get(struct bt_ctf_event_class
*event_class
);
322 extern void bt_ctf_event_class_put(struct bt_ctf_event_class
*event_class
);
328 #endif /* BABELTRACE_CTF_IR_EVENT_CLASS_H */
This page took 0.03812 seconds and 4 git commands to generate.