lib: move bt_notification_iterator_next_return to component-class.h
[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
78/**
79 * Get current notification at iterator's position.
80 *
81 * This functions will <b>not</b> advance the cursor's position.
82 * The returned notification's reference count is already incremented.
83 *
9900dfa7 84 * @param iterator Iterator instance
1d7b7871
JG
85 * @returns Returns a bt_notification instance
86 *
448143d9 87 * @see bt_put()
1d7b7871 88 */
0db5ca2c 89extern struct bt_notification *bt_notification_iterator_get_notification(
90354d3a
JG
90 struct bt_notification_iterator *iterator);
91
1d7b7871
JG
92/**
93 * Advance the iterator's position forward.
94 *
95 * This function can be called repeatedly to iterate through the iterator's
96 * associated trace.
97 *
98 * @param iterator Iterator instance
99 * @returns Returns a bt_notification instance
100 *
101 * @see bt_notification_iterator_get_notification()
102 */
103extern enum bt_notification_iterator_status
104bt_notification_iterator_next(struct bt_notification_iterator *iterator);
105
106/**
9531634f 107 * Seek iterator to time.
1d7b7871
JG
108 *
109 * Sets the iterator's position for the trace associated with the iterator.
110 * The new position is computed by adding \p time to the position specified
9531634f
JG
111 * by \p seek_origin.
112 *
113 * time is expressed in nanoseconds.
1d7b7871
JG
114 *
115 * @param iterator Iterator instance
9531634f 116 * @param seek_origin One of #bt_notification_iterator_seek_type values.
1d7b7871
JG
117 * @returns One of #bt_notification_iterator_status values;
118 * if \iterator does not support seeking,
119 * #BT_NOTIFICATION_ITERATOR_STATUS_UNSUPPORTED is
120 * returned.
121 *
122 * @see bt_notification_iterator_get_notification()
123 */
9531634f
JG
124extern enum bt_notification_iterator_status bt_notification_iterator_seek_time(
125 struct bt_notification_iterator *iterator,
126 enum bt_notification_iterator_seek_origin seek_origin,
1d7b7871 127 int64_t time);
90354d3a 128
413bc2c4
JG
129extern struct bt_component *bt_notification_iterator_get_component(
130 struct bt_notification_iterator *iterator);
131
90354d3a
JG
132#ifdef __cplusplus
133}
134#endif
135
1ca80abd 136#endif /* BABELTRACE_GRAPH_NOTIFICATION_ITERATOR_H */
This page took 0.0391 seconds and 4 git commands to generate.