[babeltrace.git] / include / babeltrace / ctf-ir / field-path.h

#ifndef BABELTRACE_CTF_IR_FIELD_PATH
#define BABELTRACE_CTF_IR_FIELD_PATH

/*
 * BabelTrace - CTF IR: Field path
 *
 * Copyright 2016 Philippe Proulx <pproulx@efficios.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * 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.
 *
 * The Common Trace Format (CTF) Specification is available at
 * http://www.efficios.com/ctf
 */

#include <babeltrace/ctf-ir/field-types.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
@defgroup ctfirfieldpath CTF IR field path
@ingroup ctfir
@brief CTF IR field path.

@code
#include <babeltrace/ctf-ir/field-path.h>
@endcode

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_ctf_field_type_sequence_get_length_field_path() and
bt_ctf_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_ctf_field_path
@brief A CTF IR field path.
@sa ctfirfieldpath
*/
struct bt_ctf_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_CTF_SCOPE_UNKNOWN on error.

@prenotnull{field_path}
@postrefcountsame{field_path}
*/
extern enum bt_ctf_scope bt_ctf_field_path_get_root_scope(
		const struct bt_ctf_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 int bt_ctf_field_path_get_index_count(
		const struct bt_ctf_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_ctf_field_path_get_index_count()).
@postrefcountsame{field_path}
*/
extern int bt_ctf_field_path_get_index(
		const struct bt_ctf_field_path *field_path,
		int index);

/** @} */

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE_CTF_IR_FIELD_PATH */
Commit	Line	Data
b011f6b0 PP	1	#ifndef BABELTRACE_CTF_IR_FIELD_PATH
	2	#define BABELTRACE_CTF_IR_FIELD_PATH
	3
	4	/*
	5	* BabelTrace - CTF IR: Field path
	6	*
	7	* Copyright 2016 Philippe Proulx <pproulx@efficios.com>
	8	*
	9	* Permission is hereby granted, free of charge, to any person obtaining a copy
	10	* of this software and associated documentation files (the "Software"), to deal
	11	* in the Software without restriction, including without limitation the rights
	12	* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
	13	* copies of the Software, and to permit persons to whom the Software is
	14	* furnished to do so, subject to the following conditions:
	15	*
	16	* The above copyright notice and this permission notice shall be included in
	17	* all copies or substantial portions of the Software.
	18	*
	19	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	20	* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
	21	* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
	22	* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
	23	* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
	24	* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
	25	* SOFTWARE.
	26	*
	27	* The Common Trace Format (CTF) Specification is available at
	28	* http://www.efficios.com/ctf
	29	*/
	30
2e33ac5a	31	#include <babeltrace/ctf-ir/field-types.h>
b011f6b0 PP	32
	33	#ifdef __cplusplus
	34	extern "C" {
	35	#endif
	36
269b496c PP	37	/**
	38	@defgroup ctfirfieldpath CTF IR field path
	39	@ingroup ctfir
	40	@brief CTF IR field path.
	41
	42	@code
	43	#include <babeltrace/ctf-ir/field-path.h>
	44	@endcode
	45
	46	A CTF IR <strong><em>field path</em></strong> represents an absolute
	47	path to a field in the hierarchy of a
	48	\link ctfirtraceclass CTF IR trace class\endlink, of a
	49	\link ctfirstreamclass CTF IR stream class\endlink, or of a
	50	\link ctfireventclass CTF IR event class\endlink.
	51
	52	As a reminder, here's the structure of a CTF packet:
	53
	54	@imgpacketstructure
	55
	56	Sequence and variant \link ctfirfieldtypes CTF IR field types\endlink
	57	can return a field path to resp. their length field and tag field
	58	with resp. bt_ctf_field_type_sequence_get_length_field_path() and
	59	bt_ctf_field_type_variant_get_tag_field_path().
	60
	61	A field path has a <em>root scope</em> which indicates from which of the
	62	six CTF scopes to begin. It also has a list of structure field <em>path
	63	indexes</em> which indicate the path to take to reach the destination
	64	field. A path index set to -1 means that you need to continue the lookup
	65	within the current element of an array or sequence field.
	66
	67	As with any Babeltrace object, CTF IR field path objects have
	68	<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
	69	counts</a>. See \ref refs to learn more about the reference counting
	70	management of Babeltrace objects.
	71
	72	@file
	73	@brief CTF IR field path type and functions.
	74	@sa ctfirfieldpath
	75
	76	@addtogroup ctfirfieldpath
	77	@{
	78	*/
	79
	80	/**
	81	@struct bt_ctf_field_path
	82	@brief A CTF IR field path.
	83	@sa ctfirfieldpath
	84	*/
b011f6b0 PP	85	struct bt_ctf_field_path;
b011f6b0 PP	86
269b496c PP	87	/**
	88	@brief Returns the root scope of the CTF IR field path \p field_path.
	89
	90	@param[in] field_path Field path of which to get the root scope.
	91	@returns Root scope of \p field_path, or
	92	#BT_CTF_SCOPE_UNKNOWN on error.
	93
	94	@prenotnull{field_path}
	95	@postrefcountsame{field_path}
	96	*/
b74f1a20	97	extern enum bt_ctf_scope bt_ctf_field_path_get_root_scope(
b011f6b0 PP	98	const struct bt_ctf_field_path *field_path);
b011f6b0 PP	99
269b496c PP	100	/**
	101	@brief Returns the number of path indexes contained in the CTF IR field
	102	path \p field_path.
	103
	104	@param[in] field_path Field path of which to get the number of
	105	path indexes.
	106	@returns Number of path indexes contained in
	107	\p field_path, or a negative value on error.
	108
	109	@prenotnull{field_path}
	110	@postrefcountsame{field_path}
	111	*/
b011f6b0 PP	112	extern int bt_ctf_field_path_get_index_count(
	113	const struct bt_ctf_field_path *field_path);
	114
269b496c PP	115	/**
	116	@brief Returns the path index contained in the CTF IR field
	117	path \p field_path at index \p index.
	118
	119	@param[in] field_path Field path of which to get the path index
	120	at index \p index.
	121	@param[in] index Index of path index to get.
	122	@returns Path index of \p field_path at index \p index,
	123	or \c INT_MIN on error.
	124
	125	@prenotnull{field_path}
	126	@pre \p index is lesser than the number of path indexes contained in the
	127	field path \p field_path (see
	128	bt_ctf_field_path_get_index_count()).
	129	@postrefcountsame{field_path}
	130	*/
b011f6b0 PP	131	extern int bt_ctf_field_path_get_index(
	132	const struct bt_ctf_field_path *field_path,
	133	int index);
	134
269b496c PP	135	/** @} */
269b496c PP	136
b011f6b0 PP	137	#ifdef __cplusplus
	138	}
	139	#endif
	140
	141	#endif /* BABELTRACE_CTF_IR_FIELD_PATH */