X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace%2Fiterator.h;h=360a9c70a5a159eed3bd11b00e1bfa97060084c8;hp=94df03c868526b1bcdf3fdbe935d8dfbf09406c9;hb=c462e188f3e7819c7bc74f671038cdbf36e8c3c0;hpb=9347cbab752c9672e64f8a71a465cca15f7b45ce

diff --git a/include/babeltrace/iterator.h b/include/babeltrace/iterator.h
index 94df03c8..360a9c70 100644
--- a/include/babeltrace/iterator.h
+++ b/include/babeltrace/iterator.h
@@ -15,22 +15,63 @@
  *
  * The above copyright notice and this permission notice shall be included in
  * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
  */
 
 #include <babeltrace/format.h>
 #include <babeltrace/context.h>
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Flags for the iterator read_event */
+enum {
+	BT_ITER_FLAG_LOST_EVENTS	= (1 << 0),
+};
+
 /* Forward declarations */
 struct bt_iter;
 struct bt_saved_pos;
 
+/*
+ * bt_iter is an abstract class, each format has to implement its own
+ * iterator derived from this parent class.
+ */
+
+/*
+ * bt_iter_pos
+ *
+ * This structure represents the position where to set an iterator.
+ *
+ * type represents the type of seek to use.
+ * u is the argument of the seek if necessary :
+ * - seek_time is the real timestamp to seek to when using BT_SEEK_TIME, it
+ *   is expressed in nanoseconds
+ * - restore is a position saved with bt_iter_get_pos, it is used with
+ *   BT_SEEK_RESTORE.
+ *
+ * Note about BT_SEEK_LAST: if many events happen to be at the last
+ * timestamp, it is implementation-defined which event will be the last,
+ * and the order of events with the same timestamp may not be the same
+ * as normal iteration on the trace. Therefore, it is recommended to
+ * only use BT_SEEK_LAST to get the timestamp of the last event(s) in
+ * the trace.
+ */
 struct bt_iter_pos {
 	enum {
 		BT_SEEK_TIME,		/* uses u.seek_time */
 		BT_SEEK_RESTORE,	/* uses u.restore */
 		BT_SEEK_CUR,
 		BT_SEEK_BEGIN,
-		BT_SEEK_END,
+		BT_SEEK_LAST,
 	} type;
 	union {
 		uint64_t seek_time;
@@ -77,9 +118,13 @@ int bt_iter_set_pos(struct bt_iter *iter, const struct bt_iter_pos *pos);
  *
  * This function allocates and returns a new bt_iter_pos (which must be freed
  * with bt_iter_free_pos) to be able to restore an iterator position based on a
- * timestamp.
+ * real timestamp.
  */
 struct bt_iter_pos *bt_iter_create_time_pos(struct bt_iter *iter,
 		uint64_t timestamp);
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif /* _BABELTRACE_ITERATOR_H */