Document libbabeltrace2's C API

[babeltrace.git] / include / babeltrace2 / graph / self-message-iterator.h

diff --git a/include/babeltrace2/graph/self-message-iterator.h b/include/babeltrace2/graph/self-message-iterator.h
index 9aaa2767159918a63a4995e11c684dbd54e880a4..0a6697d14b1d0d159111d986d840ce7838a30f0c 100644 (file)
--- a/include/babeltrace2/graph/self-message-iterator.h
+++ b/include/babeltrace2/graph/self-message-iterator.h
@@ -33,28 +33,214 @@
 extern "C" {
 #endif
 
-extern bt_bool bt_self_message_iterator_is_interrupted(
-               const bt_self_message_iterator *message_iterator);
+/*!
+@defgroup api-self-msg-iter Self message iterator
+@ingroup api-msg-iter-cls
+
+@brief
+    Private view of a \bt_msg_iter for methods.
+
+The #bt_self_message_iterator type is a private view of a \bt_msg_iter
+from within a \bt_msg_iter_cls method.
+
+Borrow the \bt_comp which provides a message iterator with
+bt_self_message_iterator_borrow_component().
+
+Borrow the \bt_oport on which a message iterator operates with
+bt_self_message_iterator_borrow_port().
+
+Set and get user data attached to a message iterator with
+bt_self_message_iterator_set_data() and
+bt_self_message_iterator_get_data().
+
+Check whether or not a message iterator is interrupted with
+bt_self_message_iterator_is_interrupted().
+
+Set whether or not a message iterator can seek forward with
+bt_self_message_iterator_configuration_set_can_seek_forward().
+*/
+
+/*! @{ */
+
+/*!
+@name Types
+@{
+
+@typedef struct bt_self_message_iterator bt_self_message_iterator;
+
+@brief
+    Self \bt_msg_iter.
+
+@typedef struct bt_self_message_iterator_configuration bt_self_message_iterator_configuration;
 
+@brief
+    Self \bt_msg_iter configuration.
+
+@}
+*/
+
+/*!
+@name Component access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_comp which provides the \bt_msg_iter
+    \bt_p{self_message_iterator}.
+
+@param[in] self_message_iterator
+    Message iterator instance.
+
+@returns
+    Component which provides \bt_p{self_message_iterator}.
+
+@bt_pre_not_null{self_message_iterator}
+*/
 extern bt_self_component *
 bt_self_message_iterator_borrow_component(
-               bt_self_message_iterator *message_iterator);
+               bt_self_message_iterator *self_message_iterator);
 
+/*! @} */
+
+/*!
+@name Output port access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_oport on which the \bt_msg_iter
+    \bt_p{self_message_iterator} operates.
+
+@param[in] self_message_iterator
+    Message iterator instance.
+
+@returns
+    Output port on which \bt_p{self_message_iterator} operates.
+
+@bt_pre_not_null{self_message_iterator}
+*/
 extern bt_self_component_port_output *
 bt_self_message_iterator_borrow_port(
-               bt_self_message_iterator *message_iterator);
+               bt_self_message_iterator *self_message_iterator);
+
+/*! @} */
 
+/*!
+@name User data
+@{
+*/
+
+/*!
+@brief
+    Sets the user data of the \bt_msg_iter \bt_p{self_message_iterator}
+    to \bt_p{data}.
+
+@param[in] self_message_iterator
+    Message iterator instance.
+@param[in] user_data
+    New user data of \bt_p{self_message_iterator}.
+
+@bt_pre_not_null{self_message_iterator}
+
+@sa bt_self_message_iterator_get_data() —
+    Returns the user data of a message iterator.
+*/
 extern void bt_self_message_iterator_set_data(
-               bt_self_message_iterator *message_iterator,
+               bt_self_message_iterator *self_message_iterator,
                void *user_data);
 
-extern void *bt_self_message_iterator_get_data(
-               const bt_self_message_iterator *message_iterator);
+/*!
+@brief
+    Returns the user data of the \bt_msg_iter
+    \bt_p{self_message_iterator}.
+
+@param[in] self_message_iterator
+    Message iterator instance.
+
+@returns
+    User data of \bt_p{self_message_iterator}.
+
+@bt_pre_not_null{self_message_iterator}
+
+@sa bt_self_message_iterator_set_data() —
+    Sets the user data of a message iterator.
+*/
+extern
+void *bt_self_message_iterator_get_data(
+               const bt_self_message_iterator *self_message_iterator);
+
+/*! @} */
+
+/*!
+@name Interruption query
+@{
+*/
+
+/*!
+@brief
+    Returns whether or not the \bt_msg_iter \bt_p{self_message_iterator}
+    is interrupted, that is, whether or not any of its \bt_p_intr
+    is set.
+
+@param[in] self_message_iterator
+    Message iterator instance.
+
+@returns
+    #BT_TRUE if \bt_p{self_message_iterator} is interrupted (any of its
+    interrupters is set).
 
+@bt_pre_not_null{self_message_iterator}
+
+@sa bt_graph_borrow_default_interrupter() —
+    Borrows a trace processing graph's default interrupter.
+@sa bt_graph_add_interrupter() —
+    Adds an interrupter to a graph.
+*/
+extern bt_bool bt_self_message_iterator_is_interrupted(
+               const bt_self_message_iterator *self_message_iterator);
+
+/*! @} */
+
+/*!
+@name Configuration
+@{
+*/
+
+/*!
+@brief
+    Sets whether or not the \bt_msg_iter of which the configuration
+    is \bt_p{configuration} can seek forward.
+
+A message iterator can seek forward if all the \bt_p_msg of its
+message sequence have some \bt_cs.
+
+@attention
+    You can only call this function during the execution of a
+    message iterator's
+    \ref api-msg-iter-cls-meth-init "initialization method".
+
+@param[in] configuration
+    Configuration of the message iterator of which to set whether or
+    not it can seek forward.
+@param[in] can_seek_forward
+    #BT_TRUE to make the message iterator of which the configuration is
+    \bt_p{configuration} forward-seekable.
+
+@bt_pre_not_null{configuration}
+
+@sa bt_message_iterator_can_seek_forward() —
+    Returns whether or not a message iterator can seek forward.
+*/
 extern void bt_self_message_iterator_configuration_set_can_seek_forward(
-               bt_self_message_iterator_configuration *config,
+               bt_self_message_iterator_configuration *configuration,
                bt_bool can_seek_forward);
 
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif