struct bt_notification;
struct bt_notification_iterator;
-extern enum bt_notification_iterator_status
-bt_notification_iterator_next(struct bt_notification_iterator *iterator);
+/**
+ * Status code. Errors are always negative.
+ */
+enum bt_notification_iterator_status {
+ /** No error, okay. */
+ BT_NOTIFICATION_ITERATOR_STATUS_OK = 0,
+ /** Invalid arguments. */
+ BT_NOTIFICATION_ITERATOR_STATUS_INVAL = -1,
+ /** General error. */
+ BT_NOTIFICATION_ITERATOR_STATUS_ERROR = -2,
+ /** Unsupported iterator feature. */
+ BT_NOTIFICATION_ITERATOR_STATUS_UNSUPPORTED = -3,
+
+};
+
+/**
+ * Notification iterator seek reference.
+ */
+enum bt_notification_iterator_seek_type {
+ /** Seek at a time relative to the beginning of the trace. */
+ BT_NOTIFICATION_ITERATOR_SEEK_TYPE_BEGIN = 0,
+ /** Seek at a time relative to the current position. */
+ BT_NOTIFICATION_ITERATOR_SEEK_TYPE_CURRENT = 1,
+
+ /** Seek at a time relative to the end of the trace. */
+ BT_NOTIFICATION_ITERATOR_SEEK_TYPE_END = 1,
+};
+
+/**
+ * Get current notification at iterator's position.
+ *
+ * This functions will <b>not</b> advance the cursor's position.
+ * The returned notification's reference count is already incremented.
+ *
+ * @param iterator Iterator instance
+ * @returns Returns a bt_notification instance
+ *
+ * @see bt_put()
+ */
extern struct bt_notification *bt_notification_iterator_get_notification(
struct bt_notification_iterator *iterator);
-extern void bt_notification_iterator_get(struct bt_notification_iterator *iterator);
-extern void bt_notification_iterator_put(struct bt_notification_iterator *iterator);
+/**
+ * Advance the iterator's position forward.
+ *
+ * This function can be called repeatedly to iterate through the iterator's
+ * associated trace.
+ *
+ * @param iterator Iterator instance
+ * @returns Returns a bt_notification instance
+ *
+ * @see bt_notification_iterator_get_notification()
+ */
+extern enum bt_notification_iterator_status
+bt_notification_iterator_next(struct bt_notification_iterator *iterator);
-/* API for plug-in authors */
-struct bt_notification_iterator *bt_notification_iterator_create(
- struct bt_plugin *plugin);
+/**
+ * Seek iterator to position.
+ *
+ * Sets the iterator's position for the trace associated with the iterator.
+ * The new position is computed by adding \p time to the position specified
+ * by \p whence.
+ *
+ * @param iterator Iterator instance
+ * @param whence One of #bt_notification_iterator_seek_type values.
+ * @returns One of #bt_notification_iterator_status values;
+ * if \iterator does not support seeking,
+ * #BT_NOTIFICATION_ITERATOR_STATUS_UNSUPPORTED is
+ * returned.
+ *
+ * @see bt_notification_iterator_get_notification()
+ */
+extern enum bt_notification_iterator_status *bt_notification_iterator_seek(
+ struct bt_notification_iterator *iterator, int whence,
+ int64_t time);
+extern struct bt_component *bt_notification_iterator_get_component(
+ struct bt_notification_iterator *iterator);
#ifdef __cplusplus
}