ir: add bt_ctf_trace_get_stream_class_by_id()
[babeltrace.git] / include / babeltrace / ctf-ir / event.h
CommitLineData
adc315b8
JG
1#ifndef BABELTRACE_CTF_IR_EVENT_H
2#define BABELTRACE_CTF_IR_EVENT_H
3
4/*
5 * BabelTrace - CTF IR: Event
6 *
de9dd397 7 * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
adc315b8
JG
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
2f100782
JG
33#include <stdint.h>
34#include <stddef.h>
dac5c838 35#include <babeltrace/values.h>
2f100782 36
adc315b8
JG
37#ifdef __cplusplus
38extern "C" {
39#endif
40
41struct bt_ctf_event_class;
42struct bt_ctf_event;
43struct bt_ctf_field;
44struct bt_ctf_field_type;
2f100782 45struct bt_ctf_stream_class;
adc315b8
JG
46
47/*
48 * bt_ctf_event_class_create: create an event class.
49 *
50 * Allocate a new event class of the given name. The creation of an event class
2f100782
JG
51 * sets its reference count to 1. A unique event id is automatically assigned
52 * to the event class.
adc315b8
JG
53 *
54 * @param name Event class name (will be copied).
55 *
56 * Returns an allocated event class on success, NULL on error.
57 */
58extern struct bt_ctf_event_class *bt_ctf_event_class_create(const char *name);
59
2f100782
JG
60/*
61 * bt_ctf_event_class_get_name: Get an event class' name.
62 *
63 * @param event_class Event class.
64 *
65 * Returns the event class' name, NULL on error.
66 */
67extern const char *bt_ctf_event_class_get_name(
68 struct bt_ctf_event_class *event_class);
69
70/*
71 * bt_ctf_event_class_get_id: Get an event class' id.
72 *
73 * @param event_class Event class.
74 *
75 * Returns the event class' id, a negative value on error.
76 */
77extern int64_t bt_ctf_event_class_get_id(
78 struct bt_ctf_event_class *event_class);
79
80/*
81 * bt_ctf_event_class_set_id: Set an event class' id.
82 *
83 * Set an event class' id. Must be unique stream-wise.
84 * Note that event classes are already assigned a unique id when added to a
85 * stream class if none was set explicitly.
86 *
87 * @param event_class Event class.
88 * @param id Event class id.
89 *
90 * Returns 0 on success, a negative value on error.
91 */
92extern int bt_ctf_event_class_set_id(
93 struct bt_ctf_event_class *event_class, uint32_t id);
94
b8248cc0
PP
95/*
96 * bt_ctf_event_class_set_attribute: sets an attribute to the event
97 * class.
98 *
99 * Sets an attribute to the event class. The name parameter is copied,
100 * whereas the value parameter's reference count is incremented
101 * (if the function succeeds).
102 *
103 * If an attribute exists in the event class for the specified name, it
104 * is replaced by the new value.
105 *
106 * Valid attributes and object types are:
107 *
108 * - "id": integer object with a value >= 0
109 * - "name": string object
110 * - "loglevel": integer object with a value >= 0
111 * - "model.emf.uri": string object
112 *
113 * @param event_class Event class.
114 * @param name Name of the attribute (will be copied).
115 * @param value Value of the attribute.
116 *
117 * Returns 0 on success, a negative value on error.
118 */
119extern int bt_ctf_event_class_set_attribute(
120 struct bt_ctf_event_class *event_class, const char *name,
dac5c838 121 struct bt_value *value);
b8248cc0
PP
122
123/*
124 * bt_ctf_event_class_get_attribute_count: get the number of attributes
125 * in this event class.
126 *
127 * Get the event class' attribute count.
128 *
129 * @param event_class Event class.
130 *
131 * Returns the attribute count, a negative value on error.
132 */
133extern int bt_ctf_event_class_get_attribute_count(
134 struct bt_ctf_event_class *event_class);
135
136/*
137 * bt_ctf_event_class_get_attribute_name: get attribute name.
138 *
139 * Get an attribute's name. The string's ownership is not
140 * transferred to the caller. The string data is valid as long as
141 * this event class' attributes are not modified.
142 *
143 * @param event_class Event class.
144 * @param index Index of the attribute.
145 *
146 * Returns the attribute's name, NULL on error.
147 */
148extern const char *
149bt_ctf_event_class_get_attribute_name(
150 struct bt_ctf_event_class *event_class, int index);
151
152/*
153 * bt_ctf_event_class_get_attribute_value: get attribute value (an object).
154 *
155 * Get an attribute's value (an object). The returned object's
156 * reference count is incremented. When done with the object, the caller
dac5c838 157 * must call bt_value_put() on it.
b8248cc0
PP
158 *
159 * @param event_class Event class.
160 * @param index Index of the attribute.
161 *
162 * Returns the attribute's object value, NULL on error.
163 */
dac5c838 164extern struct bt_value *
b8248cc0
PP
165bt_ctf_event_class_get_attribute_value(struct bt_ctf_event_class *event_class,
166 int index);
167
168/*
169 * bt_ctf_event_class_get_attribute_value_by_name: get attribute
170 * value (an object) by name.
171 *
172 * Get an attribute's value (an object) by its name. The returned object's
173 * reference count is incremented. When done with the object, the caller
dac5c838 174 * must call bt_value_put() on it.
b8248cc0
PP
175 *
176 * @param event_class Event class.
177 * @param name Attribute's name
178 *
179 * Returns the attribute's object value, NULL on error.
180 */
dac5c838 181extern struct bt_value *
b8248cc0
PP
182bt_ctf_event_class_get_attribute_value_by_name(
183 struct bt_ctf_event_class *event_class, const char *name);
184
2f100782
JG
185/*
186 * bt_ctf_event_class_get_stream_class: Get an event class' stream class.
187 *
188 * @param event_class Event class.
189 *
190 * Returns the event class' stream class, NULL on error or if the event class
191 * is not associated with a stream class.
192 */
193extern struct bt_ctf_stream_class *bt_ctf_event_class_get_stream_class(
194 struct bt_ctf_event_class *event_class);
195
c5a9aa19
JG
196/*
197 * bt_ctf_event_class_get_payload_type: get an event class' payload.
198 *
199 * Get an event class' payload type.
200 *
201 * @param event_class Event class.
202 *
203 * Returns the event class' payload, NULL on error.
204 */
205extern struct bt_ctf_field_type *bt_ctf_event_class_get_payload_type(
206 struct bt_ctf_event_class *event_class);
207
208/*
209 * bt_ctf_event_class_set_payload_type: set an event class' payload.
210 *
211 * Set an event class' payload type.
212 *
213 * @param event_class Event class.
d2127f80 214 * @param payload The payload's type (must be a structure).
c5a9aa19
JG
215 *
216 * Returns 0 on success, a negative value on error.
217 */
218extern int bt_ctf_event_class_set_payload_type(
219 struct bt_ctf_event_class *event_class,
220 struct bt_ctf_field_type *payload);
221
adc315b8
JG
222/*
223 * bt_ctf_event_class_add_field: add a field to an event class.
224 *
225 * Add a field of type "type" to the event class. The event class will share
226 * type's ownership by increasing its reference count. The "name" will be
227 * copied.
228 *
229 * @param event_class Event class.
230 * @param type Field type to add to the event class.
231 * @param name Name of the new field.
232 *
233 * Returns 0 on success, a negative value on error.
c5a9aa19
JG
234 *
235 * Note: Returns an error if the payload is not a structure.
adc315b8
JG
236 */
237extern int bt_ctf_event_class_add_field(struct bt_ctf_event_class *event_class,
238 struct bt_ctf_field_type *type,
239 const char *name);
240
2f100782
JG
241/*
242 * bt_ctf_event_class_get_field_count: Get an event class' field count.
243 *
244 * @param event_class Event class.
245 *
246 * Returns the event class' field count, a negative value on error.
c5a9aa19
JG
247 *
248 * Note: Returns an error if the payload is not a structure.
2f100782 249 */
074ee56d 250extern int bt_ctf_event_class_get_field_count(
2f100782
JG
251 struct bt_ctf_event_class *event_class);
252
253/*
254 * bt_ctf_event_class_get_field: Get event class' field type and name by index.
255 *
256 * @param event_class Event class.
257 * @param field_name Pointer to a const char* where the field's name will
258 * be returned.
259 * @param field_type Pointer to a bt_ctf_field_type* where the field's type will
260 * be returned.
261 * @param index Index of field.
262 *
263 * Returns 0 on success, a negative error on value.
c5a9aa19
JG
264 *
265 * Note: Returns an error if the payload is not a structure.
2f100782
JG
266 */
267extern int bt_ctf_event_class_get_field(struct bt_ctf_event_class *event_class,
268 const char **field_name, struct bt_ctf_field_type **field_type,
074ee56d 269 int index);
2f100782
JG
270
271/*
272 * bt_ctf_event_class_get_field_type_by_name: Get an event class's field by name
273 *
274 * @param event_class Event class.
275 * @param name Name of the field.
276 *
277 * Returns a field type on success, NULL on error.
c5a9aa19
JG
278 *
279 * Note: Returns an error if the payload is not a structure.
2f100782
JG
280 */
281extern struct bt_ctf_field_type *bt_ctf_event_class_get_field_by_name(
282 struct bt_ctf_event_class *event_class, const char *name);
283
f655a84d
JG
284/*
285 * bt_ctf_event_class_get_context_type: Get an event class's context type
286 *
287 * @param event_class Event class.
288 *
289 * Returns a field type (a structure) on success, NULL on error.
290 */
291extern struct bt_ctf_field_type *bt_ctf_event_class_get_context_type(
292 struct bt_ctf_event_class *event_class);
293
294/*
295 * bt_ctf_event_class_set_context_type: Set an event class's context type
296 *
297 * @param event_class Event class.
298 * @param context Event context field type (must be a structure).
299 *
300 * Returns 0 on success, a negative value on error.
301 */
302extern int bt_ctf_event_class_set_context_type(
303 struct bt_ctf_event_class *event_class,
304 struct bt_ctf_field_type *context);
305
adc315b8 306/*
25faeb22 307 * bt_ctf_event_class_get and bt_ctf_event_class_put: increment and decrement
adc315b8
JG
308 * the event class' reference count.
309 *
de3dd40e
PP
310 * You may also use bt_ctf_get() and bt_ctf_put() with event class objects.
311 *
adc315b8
JG
312 * These functions ensure that the event class won't be destroyed while it
313 * is in use. The same number of get and put (plus one extra put to
314 * release the initial reference done at creation) have to be done to
315 * destroy an event class.
316 *
317 * When the event class' reference count is decremented to 0 by a
318 * bt_ctf_event_class_put, the event class is freed.
319 *
320 * @param event_class Event class.
321 */
322extern void bt_ctf_event_class_get(struct bt_ctf_event_class *event_class);
323extern void bt_ctf_event_class_put(struct bt_ctf_event_class *event_class);
324
325/*
326 * bt_ctf_event_create: instanciate an event.
327 *
328 * Allocate a new event of the given event class. The creation of an event
329 * sets its reference count to 1. Each instance shares the ownership of the
330 * event class using its reference count.
331 *
54fca895
JG
332 * An event class must be associated with a stream class before events
333 * may be instanciated.
334 *
adc315b8
JG
335 * @param event_class Event class.
336 *
337 * Returns an allocated field type on success, NULL on error.
338 */
339extern struct bt_ctf_event *bt_ctf_event_create(
340 struct bt_ctf_event_class *event_class);
341
2f100782
JG
342/*
343 * bt_ctf_event_get_class: get an event's class.
344 *
345 * @param event Event.
346 *
347 * Returns the event's class, NULL on error.
348 */
349extern struct bt_ctf_event_class *bt_ctf_event_get_class(
350 struct bt_ctf_event *event);
351
8e5003bb
JG
352/*
353 * bt_ctf_event_get_stream: get an event's associated stream.
354 *
355 * @param event Event.
356 *
357 * Returns the event's associated stream, NULL on error.
358 */
359extern struct bt_ctf_stream *bt_ctf_event_get_stream(
360 struct bt_ctf_event *event);
361
2f100782
JG
362/*
363 * bt_ctf_event_get_clock: get an event's associated clock.
364 *
365 * @param event Event.
366 *
367 * Returns the event's clock, NULL on error.
368 */
369extern struct bt_ctf_clock *bt_ctf_event_get_clock(
370 struct bt_ctf_event *event);
371
71362d53
PP
372/*
373 * bt_ctf_event_get_payload_field: get an event's payload.
374 *
375 * @param event Event instance.
376 *
377 * Returns a field instance on success, NULL on error.
378 */
379extern struct bt_ctf_field *bt_ctf_event_get_payload_field(
380 struct bt_ctf_event *event);
381
e5e6eb3a
JG
382/*
383 * bt_ctf_event_set_payload_field: set an event's payload.
384 *
385 * @param event Event instance.
386 * @param payload Field instance (must be a structure).
387 *
388 * Returns 0 on success, a negative value on error.
389 */
390extern int bt_ctf_event_set_payload_field(struct bt_ctf_event *event,
391 struct bt_ctf_field *payload);
392
2f100782
JG
393/*
394 * bt_ctf_event_get_payload: get an event's field.
395 *
396 * Returns the field matching "name". bt_ctf_field_put() must be called on the
397 * returned value.
398 *
399 * @param event Event instance.
c5a9aa19 400 * @param name Event field name, see notes.
2f100782
JG
401 *
402 * Returns a field instance on success, NULL on error.
c5a9aa19
JG
403 *
404 * Note: Passing a name will cause the function to perform a look-up by
405 * name assuming the event's payload is a structure. This will return
406 * the raw payload instance if name is NULL.
2f100782
JG
407 */
408extern struct bt_ctf_field *bt_ctf_event_get_payload(struct bt_ctf_event *event,
409 const char *name);
410
adc315b8
JG
411/*
412 * bt_ctf_event_set_payload: set an event's field.
413 *
414 * Set a manually allocated field as an event's payload. The event will share
415 * the field's ownership by using its reference count.
416 * bt_ctf_field_put() must be called on the returned value.
417 *
418 * @param event Event instance.
c5a9aa19 419 * @param name Event field name, see notes.
adc315b8
JG
420 * @param value Instance of a field whose type corresponds to the event's field.
421 *
422 * Returns 0 on success, a negative value on error.
c5a9aa19
JG
423 *
424 * Note: The function will return an error if a name is provided and the payload
425 * type is not a structure. If name is NULL, the payload field will be set
426 * directly and must match the event class' payload's type.
adc315b8
JG
427 */
428extern int bt_ctf_event_set_payload(struct bt_ctf_event *event,
429 const char *name,
430 struct bt_ctf_field *value);
431
432/*
2f100782 433 * bt_ctf_event_get_payload_by_index: Get event's field by index.
adc315b8 434 *
2f100782
JG
435 * Returns the field associated with the provided index. bt_ctf_field_put()
436 * must be called on the returned value. The indexes to be provided are
437 * the same as can be retrieved from the event class.
adc315b8 438 *
2f100782
JG
439 * @param event Event.
440 * @param index Index of field.
adc315b8 441 *
2f100782 442 * Returns the event's field, NULL on error.
c5a9aa19
JG
443 *
444 * Note: Will return an error if the payload's type is not a structure.
adc315b8 445 */
2f100782 446extern struct bt_ctf_field *bt_ctf_event_get_payload_by_index(
074ee56d 447 struct bt_ctf_event *event, int index);
adc315b8 448
662e778c
JG
449/*
450 * bt_ctf_event_get_header: get an event's header.
451 *
452 * @param event Event instance.
453 *
454 * Returns a field instance on success, NULL on error.
455 */
456extern struct bt_ctf_field *bt_ctf_event_get_header(
457 struct bt_ctf_event *event);
458
459/*
460 * bt_ctf_event_set_header: set an event's header.
461 *
462 * The event header's type must match the stream class' event
463 * header type.
464 *
465 * @param event Event instance.
466 * @param header Event header field instance.
467 *
468 * Returns a field instance on success, NULL on error.
469 */
470extern int bt_ctf_event_set_header(
471 struct bt_ctf_event *event,
472 struct bt_ctf_field *header);
473
f655a84d
JG
474/*
475 * bt_ctf_event_get_event_context: Get an event's context
476 *
477 * @param event_class Event class.
478 *
479 * Returns a field on success (a structure), NULL on error.
480 *
481 * Note: This function is named this way instead of the expected
482 * "bt_ctf_event_get_context" in order to work around a name clash with
483 * an unrelated function bearing this name in context.h.
484 */
485extern struct bt_ctf_field *bt_ctf_event_get_event_context(
486 struct bt_ctf_event *event);
487
488/*
489 * bt_ctf_event_set_event_context: Set an event's context
490 *
491 * @param event Event.
492 * @param context Event context field (must match the event class'
493 * context type).
494 *
495 * Returns 0 on success, a negative value on error.
496 */
497extern int bt_ctf_event_set_event_context(struct bt_ctf_event *event,
498 struct bt_ctf_field *context);
499
9c4c8f6e
PP
500/*
501 * bt_ctf_event_copy: Deep-copy an event.
502 *
503 * Get an event's deep copy.
504 *
505 * On success, the returned copy has its reference count set to 1.
506 *
507 * @param event Event to copy.
508 *
509 * Returns the deep-copied event on success, NULL on error.
510 */
511extern struct bt_ctf_event *bt_ctf_event_copy(struct bt_ctf_event *event);
512
adc315b8
JG
513/*
514 * bt_ctf_event_get and bt_ctf_event_put: increment and decrement
515 * the event's reference count.
516 *
de3dd40e
PP
517 * You may also use bt_ctf_get() and bt_ctf_put() with event objects.
518 *
adc315b8
JG
519 * These functions ensure that the event won't be destroyed while it
520 * is in use. The same number of get and put (plus one extra put to
521 * release the initial reference done at creation) have to be done to
522 * destroy an event.
523 *
524 * When the event's reference count is decremented to 0 by a
525 * bt_ctf_event_put, the event is freed.
526 *
527 * @param event Event instance.
528 */
529extern void bt_ctf_event_get(struct bt_ctf_event *event);
530extern void bt_ctf_event_put(struct bt_ctf_event *event);
531
532#ifdef __cplusplus
533}
534#endif
535
536#endif /* BABELTRACE_CTF_IR_EVENT_H */
This page took 0.048068 seconds and 4 git commands to generate.