Make bt_graph_connect_ports() return a status code
[babeltrace.git] / include / babeltrace / graph / notification-iterator.h
CommitLineData
1ca80abd
PP
1#ifndef BABELTRACE_GRAPH_NOTIFICATION_ITERATOR_H
2#define BABELTRACE_GRAPH_NOTIFICATION_ITERATOR_H
90354d3a
JG
3
4/*
5 * BabelTrace - Plug-in Notification Iterator
6 *
7 * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
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
30#include <stdint.h>
31
32#ifdef __cplusplus
33extern "C" {
34#endif
35
36struct bt_notification;
37struct bt_notification_iterator;
38
1d7b7871
JG
39/**
40 * Status code. Errors are always negative.
41 */
42enum bt_notification_iterator_status {
bd14d768
PP
43 /** Canceled. */
44 BT_NOTIFICATION_ITERATOR_STATUS_CANCELED = 125,
7cdc2bab 45 /** No notifications available for now. Try again later. */
fe8ad2b6 46 BT_NOTIFICATION_ITERATOR_STATUS_AGAIN = 11,
663618ee
JG
47 /** No more notifications to be delivered. */
48 BT_NOTIFICATION_ITERATOR_STATUS_END = 1,
d01e0f33
JG
49 /** No error, okay. */
50 BT_NOTIFICATION_ITERATOR_STATUS_OK = 0,
1d7b7871 51 /** Invalid arguments. */
fe8ad2b6 52 BT_NOTIFICATION_ITERATOR_STATUS_INVALID = -22,
1d7b7871 53 /** General error. */
fe8ad2b6 54 BT_NOTIFICATION_ITERATOR_STATUS_ERROR = -1,
5b29e799 55 /** Out of memory. */
fe8ad2b6 56 BT_NOTIFICATION_ITERATOR_STATUS_NOMEM = -12,
1d7b7871 57 /** Unsupported iterator feature. */
fe8ad2b6 58 BT_NOTIFICATION_ITERATOR_STATUS_UNSUPPORTED = -2,
1d7b7871
JG
59};
60
c602a809
JG
61/**
62 * Notification iterator seek reference.
63 */
9531634f 64enum bt_notification_iterator_seek_origin {
1d7b7871 65 /** Seek at a time relative to the beginning of the trace. */
9531634f 66 BT_NOTIFICATION_ITERATOR_SEEK_ORIGIN_BEGIN = 0,
1d7b7871 67
c602a809 68 /** Seek at a time relative to the current position. */
9531634f 69 BT_NOTIFICATION_ITERATOR_SEEK_ORIGIN_CURRENT = 1,
90354d3a 70
c602a809 71 /** Seek at a time relative to the end of the trace. */
9531634f
JG
72 BT_NOTIFICATION_ITERATOR_SEEK_ORIGIN_END = 2,
73
74 /** Seek at a time relative to EPOCH. */
75 BT_NOTIFICATION_ITERATOR_SEEK_ORIGIN_EPOCH = 3,
1d7b7871
JG
76};
77
41a2b7ae
PP
78struct bt_notification_iterator_next_return {
79 struct bt_notification *notification;
80 enum bt_notification_iterator_status status;
81};
82
1d7b7871
JG
83/**
84 * Get current notification at iterator's position.
85 *
86 * This functions will <b>not</b> advance the cursor's position.
87 * The returned notification's reference count is already incremented.
88 *
9900dfa7 89 * @param iterator Iterator instance
1d7b7871
JG
90 * @returns Returns a bt_notification instance
91 *
448143d9 92 * @see bt_put()
1d7b7871 93 */
0db5ca2c 94extern struct bt_notification *bt_notification_iterator_get_notification(
90354d3a
JG
95 struct bt_notification_iterator *iterator);
96
1d7b7871
JG
97/**
98 * Advance the iterator's position forward.
99 *
100 * This function can be called repeatedly to iterate through the iterator's
101 * associated trace.
102 *
103 * @param iterator Iterator instance
104 * @returns Returns a bt_notification instance
105 *
106 * @see bt_notification_iterator_get_notification()
107 */
108extern enum bt_notification_iterator_status
109bt_notification_iterator_next(struct bt_notification_iterator *iterator);
110
111/**
9531634f 112 * Seek iterator to time.
1d7b7871
JG
113 *
114 * Sets the iterator's position for the trace associated with the iterator.
115 * The new position is computed by adding \p time to the position specified
9531634f
JG
116 * by \p seek_origin.
117 *
118 * time is expressed in nanoseconds.
1d7b7871
JG
119 *
120 * @param iterator Iterator instance
9531634f 121 * @param seek_origin One of #bt_notification_iterator_seek_type values.
1d7b7871
JG
122 * @returns One of #bt_notification_iterator_status values;
123 * if \iterator does not support seeking,
124 * #BT_NOTIFICATION_ITERATOR_STATUS_UNSUPPORTED is
125 * returned.
126 *
127 * @see bt_notification_iterator_get_notification()
128 */
9531634f
JG
129extern enum bt_notification_iterator_status bt_notification_iterator_seek_time(
130 struct bt_notification_iterator *iterator,
131 enum bt_notification_iterator_seek_origin seek_origin,
1d7b7871 132 int64_t time);
90354d3a 133
413bc2c4
JG
134extern struct bt_component *bt_notification_iterator_get_component(
135 struct bt_notification_iterator *iterator);
136
90354d3a
JG
137#ifdef __cplusplus
138}
139#endif
140
1ca80abd 141#endif /* BABELTRACE_GRAPH_NOTIFICATION_ITERATOR_H */
This page took 0.039747 seconds and 4 git commands to generate.