X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ffield-path.h;h=d5e5e43dc9e12e9ced15fd5472282b9b63142637;hb=50842bdc4c21f3de2b63e29cdac730af8b6dcca6;hp=40acfc8b3e56d633c5cded9c60a74109cc376bf8;hpb=2e33ac5abec88a4be03907091474324dfcc42e23;p=babeltrace.git

diff --git a/include/babeltrace/ctf-ir/field-path.h b/include/babeltrace/ctf-ir/field-path.h
index 40acfc8b..d5e5e43d 100644
--- a/include/babeltrace/ctf-ir/field-path.h
+++ b/include/babeltrace/ctf-ir/field-path.h
@@ -1,5 +1,5 @@
-#ifndef BABELTRACE_CTF_IR_FIELD_PATH
-#define BABELTRACE_CTF_IR_FIELD_PATH
+#ifndef BABELTRACE_CTF_IR_FIELD_PATH_H
+#define BABELTRACE_CTF_IR_FIELD_PATH_H
 
 /*
  * BabelTrace - CTF IR: Field path
@@ -28,54 +28,115 @@
  * http://www.efficios.com/ctf
  */
 
-#include <babeltrace/ctf-ir/field-types.h>
+#include <stdint.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-struct bt_ctf_field_path;
+struct bt_field_type;
 
-/*
- * bt_ctf_field_path_get_root_scope: get the root node of a field path.
- *
- * Get the field path's root node.
- *
- * @param field_path Field path.
- *
- * Returns the root node of a field path, or BT_CTF_SCOPE_UNKNOWN on error.
- */
-extern enum bt_ctf_scope bt_ctf_field_path_get_root_scope(
-		const struct bt_ctf_field_path *field_path);
+/**
+@defgroup ctfirfieldpath CTF IR field path
+@ingroup ctfir
+@brief CTF IR field path.
 
-/*
- * bt_ctf_field_path_get_index_count: get the number of indexes of a field path.
- *
- * Get the number of indexes of a field path.
- *
- * @param field_path Field path.
- *
- * Returns the field path's index count, or a negative value on error.
- */
-extern int bt_ctf_field_path_get_index_count(
-		const struct bt_ctf_field_path *field_path);
+@code
+#include <babeltrace/ctf-ir/field-path.h>
+@endcode
 
-/*
- * bt_ctf_field_path_get_index: get the field path's index at a specific index.
- *
- * Get the field path's index at a specific index.
- *
- * @param field_path Field path.
- * @param index Index.
- *
- * Returns a field path index, or INT_MIN on error.
- */
-extern int bt_ctf_field_path_get_index(
-		const struct bt_ctf_field_path *field_path,
-		int index);
+A CTF IR <strong><em>field path</em></strong> represents an absolute
+path to a field in the hierarchy of a
+\link ctfirtraceclass CTF IR trace class\endlink, of a
+\link ctfirstreamclass CTF IR stream class\endlink, or of a
+\link ctfireventclass CTF IR event class\endlink.
+
+As a reminder, here's the structure of a CTF packet:
+
+@imgpacketstructure
+
+Sequence and variant \link ctfirfieldtypes CTF IR field types\endlink
+can return a field path to resp. their length field and tag field
+with resp. bt_field_type_sequence_get_length_field_path() and
+bt_field_type_variant_get_tag_field_path().
+
+A field path has a <em>root scope</em> which indicates from which of the
+six CTF scopes to begin. It also has a list of structure field <em>path
+indexes</em> which indicate the path to take to reach the destination
+field. A path index set to -1 means that you need to continue the lookup
+within the current element of an array or sequence field.
+
+As with any Babeltrace object, CTF IR field path objects have
+<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
+counts</a>. See \ref refs to learn more about the reference counting
+management of Babeltrace objects.
+
+@file
+@brief CTF IR field path type and functions.
+@sa ctfirfieldpath
+
+@addtogroup ctfirfieldpath
+@{
+*/
+
+/**
+@struct bt_field_path
+@brief A CTF IR field path.
+@sa ctfirfieldpath
+*/
+struct bt_field_path;
+
+/**
+@brief	Returns the root scope of the CTF IR field path \p field_path.
+
+@param[in] field_path	Field path of which to get the root scope.
+@returns		Root scope of \p field_path, or
+			#BT_SCOPE_UNKNOWN on error.
+
+@prenotnull{field_path}
+@postrefcountsame{field_path}
+*/
+extern enum bt_scope bt_field_path_get_root_scope(
+		const struct bt_field_path *field_path);
+
+/**
+@brief	Returns the number of path indexes contained in the CTF IR field
+	path \p field_path.
+
+@param[in] field_path	Field path of which to get the number of
+			path indexes.
+@returns		Number of path indexes contained in
+			\p field_path, or a negative value on error.
+
+@prenotnull{field_path}
+@postrefcountsame{field_path}
+*/
+extern int64_t bt_field_path_get_index_count(
+		const struct bt_field_path *field_path);
+
+/**
+@brief	Returns the path index contained in the CTF IR field
+	path \p field_path at index \p index.
+
+@param[in] field_path	Field path of which to get the path index
+			at index \p index.
+@param[in] index	Index of path index to get.
+@returns		Path index of \p field_path at index \p index,
+			or \c INT_MIN on error.
+
+@prenotnull{field_path}
+@pre \p index is lesser than the number of path indexes contained in the
+	field path \p field_path (see
+	bt_field_path_get_index_count()).
+@postrefcountsame{field_path}
+*/
+extern int bt_field_path_get_index(
+		const struct bt_field_path *field_path, uint64_t index);
+
+/** @} */
 
 #ifdef __cplusplus
 }
 #endif
 
-#endif /* BABELTRACE_CTF_IR_FIELD_PATH */
+#endif /* BABELTRACE_CTF_IR_FIELD_PATH_H */