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

/*
 * SPDX-License-Identifier: MIT
 *
 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
 */

#ifndef BABELTRACE2_TRACE_IR_FIELD_PATH_H
#define BABELTRACE2_TRACE_IR_FIELD_PATH_H

/* IWYU pragma: private, include <babeltrace2/babeltrace.h> */

#ifndef __BT_IN_BABELTRACE_H
# error "Please include <babeltrace2/babeltrace.h> instead."
#endif

#include <stdint.h>

#include <babeltrace2/types.h>

#ifdef __cplusplus
extern "C" {
#endif

/*!
@defgroup api-tir-field-path Field path
@ingroup api-tir

@brief
    Path to a \bt_field.

A <strong><em>field path</em></strong> indicates how to reach a given
\bt_field from a given <em>root scope</em>.

More specifically, a field path indicates how to reach:

- The length field of a \bt_darray_field (with a length field).
- The selector field of a \bt_opt_field (with a selector field).
- The selector field of a \bt_var_field (with a selector field).

You can borrow the field path from the \ref api-tir-fc "classes" of such
fields with
bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(),
bt_field_class_option_with_selector_field_borrow_selector_field_path_const(),
and
bt_field_class_variant_with_selector_field_borrow_selector_field_path_const().
Note that the field path properties of those field classes only becomes
available when the field class becomes part of an \bt_ev_cls or of a
\bt_stream_cls. See
\ref api-tir-fc-link "Field classes with links to other field classes".

A field path is a \ref api-tir "trace IR" metadata object.

A field path is a \ref api-fund-shared-object "shared object": get a
new reference with bt_field_path_get_ref() and put an existing
reference with bt_field_path_put_ref().

The type of a field path is #bt_field_path.

<h1>Properties</h1>

A field path has the following properties:

<dl>
  <dt>
    \anchor api-tir-field-path-prop-root
    Root scope
  </dt>
  <dd>
    Indicates from which \bt_struct_field to start a lookup.

    See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
    learn more.

    Get a field path's root scope with bt_field_path_get_root_scope().
  </dd>

  <dt>
    \anchor api-tir-field-path-prop-items
    Items
  </dt>
  <dd>
    Each item in a field path's item list indicates which action to take
    to follow the path to the linked \bt_field.

    See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
    learn more.

    Get the number of items in a field path with
    bt_field_path_get_item_count().

    Borrow an item from a field path with
    bt_field_path_borrow_item_by_index_const(). This function
    returns the #bt_field_path_item type.

    A field path item is a \ref api-fund-unique-object "unique object":
    it belongs to the field path which contains it.
  </dd>
</dl>

<h1>\anchor api-tir-field-path-lookup-algo Lookup algorithm</h1>

The field resolution algorithm using a field path is:

-# Use the appropriate function to set a <em>current field</em> variable
   from the root scope (as returned by bt_field_path_get_root_scope()):

   <dl>
     <dt>#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT</dt>
     <dd>
       bt_packet_borrow_context_field_const().
     </dd>
     <dt>#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT</dt>
     <dd>
       bt_event_borrow_common_context_field_const().
     </dd>
     <dt>#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
     <dd>
       bt_event_borrow_specific_context_field_const().
     </dd>
     <dt>#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD</dt>
     <dd>
       bt_event_borrow_payload_field_const().
     </dd>
   </dl>

-# For each field path item (use bt_field_path_get_item_count()
   and bt_field_path_borrow_item_by_index_const()), depending on
   the item's type (as returned by bt_field_path_item_get_type()):

   <dl>
     <dt>#BT_FIELD_PATH_ITEM_TYPE_INDEX</dt>
     <dd>
       Call bt_field_path_item_index_get_index() to get the item's
       index value.

       Depending on the current field's class's type (as
       returned by bt_field_get_class_type()):

       <dl>
         <dt>\bt_c_struct_fc</dt>
         <dd>
           Call bt_field_structure_borrow_member_field_by_index_const()
           with the current field and with the item's index to set the
           new current field.
         </dd>

         <dt>\bt_c_var_fc</dt>
         <dd>
           Call bt_field_variant_borrow_selected_option_field_const()
           with the current field to set the new current field.
         </dd>
       </dl>
     </dd>

     <dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT</dt>
     <dd>
       Call bt_field_array_borrow_element_field_by_index_const()
       with the index of the field eventually containing the
       field with a link (\bt_darray_field, \bt_opt_field, or
       \bt_var_field) and the current field to set the new current
       field.
     </dd>

     <dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT</dt>
     <dd>
       Call bt_field_option_borrow_field_const() with the current
       field to set the new current field.
     </dd>
   </dl>

After applying this procedure, the current field is the linked
field.
*/

/*! @{ */

/*!
@name Field path
@{

@typedef struct bt_field_path bt_field_path;

@brief
    Field path.

*/

/*!
@brief
    Field path scopes.
*/
typedef enum bt_field_path_scope {
	/*!
	@brief
	    Packet context.
	*/
	BT_FIELD_PATH_SCOPE_PACKET_CONTEXT		= 0,

	/*!
	@brief
	    Event common context.
	*/
	BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT	= 1,

	/*!
	@brief
	    Event specific context.
	*/
	BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT	= 2,

	/*!
	@brief
	    Event payload.
	*/
	BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD		= 3,
} bt_field_path_scope;

/*!
@brief
    Returns the root scope of the field path \bt_p{field_path}.

See the \ref api-tir-field-path-prop-root "root scope" property.

@param[in] field_path
    Field path of which to get the root scope.

@returns
    Root scope of \bt_p{field_path}.

@bt_pre_not_null{field_path}
*/
extern bt_field_path_scope bt_field_path_get_root_scope(
		const bt_field_path *field_path) __BT_NOEXCEPT;

/*!
@brief
    Returns the number of items contained in the field path
    \bt_p{field_path}.

See the \ref api-tir-field-path-prop-items "items" property.

@param[in] field_path
    Field path of which to get the number of contained items.

@returns
    Number of contained items in \bt_p{field_path}.

@bt_pre_not_null{field_path}
*/
extern uint64_t bt_field_path_get_item_count(
		const bt_field_path *field_path) __BT_NOEXCEPT;

/*!
@brief
    Borrows the item at index \bt_p{index} from the
    field path \bt_p{field_path}.

See the \ref api-tir-field-path-prop-items "items" property.

@param[in] field_path
    Field path from which to borrow the item at index \bt_p{index}.
@param[in] index
    Index of the item to borrow from \bt_p{field_path}.

@returns
    @parblock
    \em Borrowed reference of the item of
    \bt_p{field_path} at index \bt_p{index}.

    The returned pointer remains valid as long as \bt_p{field_path}
    exists.
    @endparblock

@bt_pre_not_null{field_path}
@pre
    \bt_p{index} is less than the number of items in
    \bt_p{field_path} (as returned by bt_field_path_get_item_count()).

@sa bt_field_path_get_item_count() &mdash;
    Returns the number of items contained in a field path.
*/
extern const bt_field_path_item *bt_field_path_borrow_item_by_index_const(
		const bt_field_path *field_path, uint64_t index) __BT_NOEXCEPT;

/*!
@brief
    Increments the \ref api-fund-shared-object "reference count" of
    the field path \bt_p{field_path}.

@param[in] field_path
    @parblock
    Field path of which to increment the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_field_path_put_ref() &mdash;
    Decrements the reference count of a field path.
*/
extern void bt_field_path_get_ref(const bt_field_path *field_path)
		__BT_NOEXCEPT;

/*!
@brief
    Decrements the \ref api-fund-shared-object "reference count" of
    the field path \bt_p{field_path}.

@param[in] field_path
    @parblock
    Field path of which to decrement the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_field_path_get_ref() &mdash;
    Increments the reference count of a field path.
*/
extern void bt_field_path_put_ref(const bt_field_path *field_path)
		__BT_NOEXCEPT;

/*!
@brief
    Decrements the reference count of the field path
    \bt_p{_field_path}, and then sets \bt_p{_field_path} to \c NULL.

@param _field_path
    @parblock
    Field path of which to decrement the reference count.

    Can contain \c NULL.
    @endparblock

@bt_pre_assign_expr{_field_path}
*/
#define BT_FIELD_PATH_PUT_REF_AND_RESET(_field_path)	\
	do {						\
		bt_field_path_put_ref(_field_path);	\
		(_field_path) = NULL;			\
	} while (0)

/*!
@brief
    Decrements the reference count of the field path \bt_p{_dst}, sets
    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.

This macro effectively moves a field path reference from the expression
\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
\bt_p{_dst} reference.

@param _dst
    @parblock
    Destination expression.

    Can contain \c NULL.
    @endparblock
@param _src
    @parblock
    Source expression.

    Can contain \c NULL.
    @endparblock

@bt_pre_assign_expr{_dst}
@bt_pre_assign_expr{_src}
*/
#define BT_FIELD_PATH_MOVE_REF(_dst, _src)	\
	do {					\
		bt_field_path_put_ref(_dst);	\
		(_dst) = (_src);		\
		(_src) = NULL;			\
	} while (0)

/*! @} */

/*!
@name Field path item
@{

@typedef struct bt_field_path_item bt_field_path_item;

@brief
    Field path item.

*/

/*!
@brief
    Field path item type enumerators.
*/
typedef enum bt_field_path_item_type {
	/*!
	@brief
	    Index of a \bt_struct_field member or selected \bt_var_field
	    option's field.
	*/
	BT_FIELD_PATH_ITEM_TYPE_INDEX				= 1 << 0,

	/*!
	@brief
	    Common field of an \bt_array_field.
	*/
	BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT		= 1 << 1,

	/*!
	@brief
	    Current field of an \bt_opt_field.
	*/
	BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT		= 1 << 2,
} bt_field_path_item_type;

/*!
@brief
    Returns the type enumerator of the field path item
    \bt_p{item}.

See the \ref api-tir-field-path-prop-items "items" property.

@param[in] item
    Field path item of which to get the type enumerator

@returns
    Type enumerator of \bt_p{item}.

@bt_pre_not_null{item}
*/
extern bt_field_path_item_type bt_field_path_item_get_type(
		const bt_field_path_item *item) __BT_NOEXCEPT;

/*!
@brief
    Returns the index value of the index field path item
    \bt_p{item}.

See the \ref api-tir-field-path-prop-items "items" property.

@param[in] item
    Index field path item of which to get the index value.

@returns
    Index value of \bt_p{item}.

@bt_pre_not_null{item}
@pre
    \bt_p{item} is an index field path item
    (bt_field_path_item_get_type() returns
    #BT_FIELD_PATH_ITEM_TYPE_INDEX).
*/
extern uint64_t bt_field_path_item_index_get_index(
		const bt_field_path_item *item) __BT_NOEXCEPT;

/*! @} */

/*! @} */

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE2_TRACE_IR_FIELD_PATH_H */
Commit	Line	Data
43c59509	1	/*
0235b0db	2	* SPDX-License-Identifier: MIT
43c59509	3	*
0235b0db	4	* Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
43c59509 PP	5	*/
43c59509 PP	6
0235b0db MJ	7	#ifndef BABELTRACE2_TRACE_IR_FIELD_PATH_H
	8	#define BABELTRACE2_TRACE_IR_FIELD_PATH_H
	9
f38da6ca SM	10	/* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
f38da6ca SM	11
43c59509 PP	12	#ifndef __BT_IN_BABELTRACE_H
	13	# error "Please include <babeltrace2/babeltrace.h> instead."
	14	#endif
	15
	16	#include <stdint.h>
	17
	18	#include <babeltrace2/types.h>
	19
	20	#ifdef __cplusplus
	21	extern "C" {
	22	#endif
	23
	24	/*!
	25	@defgroup api-tir-field-path Field path
	26	@ingroup api-tir
	27
	28	@brief
	29	Path to a \bt_field.
	30
	31	A <strong><em>field path</em></strong> indicates how to reach a given
	32	\bt_field from a given <em>root scope</em>.
	33
	34	More specifically, a field path indicates how to reach:
	35
	36	- The length field of a \bt_darray_field (with a length field).
	37	- The selector field of a \bt_opt_field (with a selector field).
	38	- The selector field of a \bt_var_field (with a selector field).
	39
	40	You can borrow the field path from the \ref api-tir-fc "classes" of such
	41	fields with
	42	bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(),
	43	bt_field_class_option_with_selector_field_borrow_selector_field_path_const(),
	44	and
	45	bt_field_class_variant_with_selector_field_borrow_selector_field_path_const().
	46	Note that the field path properties of those field classes only becomes
	47	available when the field class becomes part of an \bt_ev_cls or of a
	48	\bt_stream_cls. See
	49	\ref api-tir-fc-link "Field classes with links to other field classes".
	50
	51	A field path is a \ref api-tir "trace IR" metadata object.
	52
	53	A field path is a \ref api-fund-shared-object "shared object": get a
	54	new reference with bt_field_path_get_ref() and put an existing
	55	reference with bt_field_path_put_ref().
	56
	57	The type of a field path is #bt_field_path.
	58
	59	<h1>Properties</h1>
	60
	61	A field path has the following properties:
	62
	63	<dl>
	64	<dt>
	65	\anchor api-tir-field-path-prop-root
	66	Root scope
	67	</dt>
	68	<dd>
	69	Indicates from which \bt_struct_field to start a lookup.
	70
	71	See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
	72	learn more.
	73
	74	Get a field path's root scope with bt_field_path_get_root_scope().
	75	</dd>
76
77	<dt>
78	\anchor api-tir-field-path-prop-items
79	Items
80	</dt>
81	<dd>
82	Each item in a field path's item list indicates which action to take
83	to follow the path to the linked \bt_field.
84
85	See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
86	learn more.
87
88	Get the number of items in a field path with
89	bt_field_path_get_item_count().
90
91	Borrow an item from a field path with
92	bt_field_path_borrow_item_by_index_const(). This function
93	returns the #bt_field_path_item type.
94
95	A field path item is a \ref api-fund-unique-object "unique object":
96	it belongs to the field path which contains it.
97	</dd>
98	</dl>
99
100	<h1>\anchor api-tir-field-path-lookup-algo Lookup algorithm</h1>
101
102	The field resolution algorithm using a field path is:
103
104	-# Use the appropriate function to set a <em>current field</em> variable
105	from the root scope (as returned by bt_field_path_get_root_scope()):
106
107	<dl>
108	<dt>#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT</dt>
109	<dd>
110	bt_packet_borrow_context_field_const().
111	</dd>
112	<dt>#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT</dt>
113	<dd>
114	bt_event_borrow_common_context_field_const().
115	</dd>
116	<dt>#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
117	<dd>
118	bt_event_borrow_specific_context_field_const().
119	</dd>
120	<dt>#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD</dt>
121	<dd>
122	bt_event_borrow_payload_field_const().
123	</dd>
124	</dl>
125
126	-# For each field path item (use bt_field_path_get_item_count()
127	and bt_field_path_borrow_item_by_index_const()), depending on
128	the item's type (as returned by bt_field_path_item_get_type()):
129
130	<dl>
131	<dt>#BT_FIELD_PATH_ITEM_TYPE_INDEX</dt>
132	<dd>
133	Call bt_field_path_item_index_get_index() to get the item's
134	index value.
135
136	Depending on the current field's class's type (as
137	returned by bt_field_get_class_type()):
138
139	<dl>
140	<dt>\bt_c_struct_fc</dt>
141	<dd>
142	Call bt_field_structure_borrow_member_field_by_index_const()
143	with the current field and with the item's index to set the
144	new current field.
145	</dd>
146
147	<dt>\bt_c_var_fc</dt>
148	<dd>
149	Call bt_field_variant_borrow_selected_option_field_const()
150	with the current field to set the new current field.
151	</dd>
152	</dl>
153	</dd>
154
155	<dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT</dt>
156	<dd>
157	Call bt_field_array_borrow_element_field_by_index_const()
158	with the index of the field eventually containing the
159	field with a link (\bt_darray_field, \bt_opt_field, or
160	\bt_var_field) and the current field to set the new current
161	field.
162	</dd>
163
164	<dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT</dt>
165	<dd>
166	Call bt_field_option_borrow_field_const() with the current
167	field to set the new current field.
168	</dd>
169	</dl>
170
171	After applying this procedure, the current field is the linked
172	field.
173	*/
174
175	/! @{ /
176
177	/*!
178	@name Field path
179	@{
180
181	@typedef struct bt_field_path bt_field_path;
182
183	@brief
184	Field path.
185
186	*/
187
188	/*!
189	@brief
190	Field path scopes.
191	*/
192	typedef enum bt_field_path_scope {
193	/*!
194	@brief
195	Packet context.
196	*/
197	BT_FIELD_PATH_SCOPE_PACKET_CONTEXT = 0,
198
199	/*!
200	@brief
201	Event common context.
202	*/
203	BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT = 1,
204
205	/*!
206	@brief
207	Event specific context.
208	*/
209	BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT = 2,
210
211	/*!
212	@brief
213	Event payload.
214	*/
215	BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD = 3,
216	} bt_field_path_scope;
217
218	/*!
219	@brief
220	Returns the root scope of the field path \bt_p{field_path}.
221
222	See the \ref api-tir-field-path-prop-root "root scope" property.
223
224	@param[in] field_path
225	Field path of which to get the root scope.
226
227	@returns
228	Root scope of \bt_p{field_path}.
229
230	@bt_pre_not_null{field_path}
231	*/
232	extern bt_field_path_scope bt_field_path_get_root_scope(
4c81a2b7	233	const bt_field_path *field_path) __BT_NOEXCEPT;
43c59509 PP	234
	235	/*!
	236	@brief
	237	Returns the number of items contained in the field path
	238	\bt_p{field_path}.
	239
	240	See the \ref api-tir-field-path-prop-items "items" property.
	241
	242	@param[in] field_path
	243	Field path of which to get the number of contained items.
	244
	245	@returns
	246	Number of contained items in \bt_p{field_path}.
	247
	248	@bt_pre_not_null{field_path}
	249	*/
	250	extern uint64_t bt_field_path_get_item_count(
4c81a2b7	251	const bt_field_path *field_path) __BT_NOEXCEPT;
43c59509 PP	252
	253	/*!
	254	@brief
	255	Borrows the item at index \bt_p{index} from the
	256	field path \bt_p{field_path}.
	257
	258	See the \ref api-tir-field-path-prop-items "items" property.
	259
	260	@param[in] field_path
	261	Field path from which to borrow the item at index \bt_p{index}.
	262	@param[in] index
	263	Index of the item to borrow from \bt_p{field_path}.
	264
	265	@returns
	266	@parblock
	267	\em Borrowed reference of the item of
	268	\bt_p{field_path} at index \bt_p{index}.
	269
	270	The returned pointer remains valid as long as \bt_p{field_path}
	271	exists.
	272	@endparblock
	273
	274	@bt_pre_not_null{field_path}
	275	@pre
	276	\bt_p{index} is less than the number of items in
	277	\bt_p{field_path} (as returned by bt_field_path_get_item_count()).
	278
	279	@sa bt_field_path_get_item_count() —
	280	Returns the number of items contained in a field path.
	281	*/
	282	extern const bt_field_path_item *bt_field_path_borrow_item_by_index_const(
4c81a2b7	283	const bt_field_path *field_path, uint64_t index) __BT_NOEXCEPT;
43c59509 PP	284
	285	/*!
	286	@brief
	287	Increments the \ref api-fund-shared-object "reference count" of
	288	the field path \bt_p{field_path}.
	289
	290	@param[in] field_path
	291	@parblock
	292	Field path of which to increment the reference count.
	293
	294	Can be \c NULL.
	295	@endparblock
	296
	297	@sa bt_field_path_put_ref() —
	298	Decrements the reference count of a field path.
	299	*/
4c81a2b7 PP	300	extern void bt_field_path_get_ref(const bt_field_path *field_path)
4c81a2b7 PP	301	__BT_NOEXCEPT;
43c59509 PP	302
	303	/*!
	304	@brief
	305	Decrements the \ref api-fund-shared-object "reference count" of
	306	the field path \bt_p{field_path}.
	307
	308	@param[in] field_path
	309	@parblock
	310	Field path of which to decrement the reference count.
	311
	312	Can be \c NULL.
	313	@endparblock
	314
	315	@sa bt_field_path_get_ref() —
	316	Increments the reference count of a field path.
	317	*/
4c81a2b7 PP	318	extern void bt_field_path_put_ref(const bt_field_path *field_path)
4c81a2b7 PP	319	__BT_NOEXCEPT;
43c59509 PP	320
	321	/*!
	322	@brief
	323	Decrements the reference count of the field path
	324	\bt_p{_field_path}, and then sets \bt_p{_field_path} to \c NULL.
	325
	326	@param _field_path
	327	@parblock
	328	Field path of which to decrement the reference count.
	329
	330	Can contain \c NULL.
	331	@endparblock
	332
	333	@bt_pre_assign_expr{_field_path}
	334	*/
	335	#define BT_FIELD_PATH_PUT_REF_AND_RESET(_field_path) \
	336	do { \
	337	bt_field_path_put_ref(_field_path); \
	338	(_field_path) = NULL; \
	339	} while (0)
	340
	341	/*!
	342	@brief
	343	Decrements the reference count of the field path \bt_p{_dst}, sets
	344	\bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
	345
	346	This macro effectively moves a field path reference from the expression
	347	\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
	348	\bt_p{_dst} reference.
	349
	350	@param _dst
	351	@parblock
	352	Destination expression.
	353
	354	Can contain \c NULL.
	355	@endparblock
	356	@param _src
	357	@parblock
	358	Source expression.
	359
	360	Can contain \c NULL.
	361	@endparblock
	362
	363	@bt_pre_assign_expr{_dst}
	364	@bt_pre_assign_expr{_src}
	365	*/
	366	#define BT_FIELD_PATH_MOVE_REF(_dst, _src) \
	367	do { \
	368	bt_field_path_put_ref(_dst); \
	369	(_dst) = (_src); \
	370	(_src) = NULL; \
	371	} while (0)
	372
	373	/! @} /
	374
	375	/*!
	376	@name Field path item
	377	@{
	378
	379	@typedef struct bt_field_path_item bt_field_path_item;
	380
	381	@brief
	382	Field path item.
	383
384	*/
385
386	/*!
387	@brief
388	Field path item type enumerators.
389	*/
390	typedef enum bt_field_path_item_type {
391	/*!
392	@brief
393	Index of a \bt_struct_field member or selected \bt_var_field
394	option's field.
395	*/
396	BT_FIELD_PATH_ITEM_TYPE_INDEX = 1 << 0,
397
398	/*!
399	@brief
400	Common field of an \bt_array_field.
401	*/
402	BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT = 1 << 1,
403
404	/*!
405	@brief
406	Current field of an \bt_opt_field.
407	*/
408	BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT = 1 << 2,
409	} bt_field_path_item_type;
410
411	/*!
412	@brief
413	Returns the type enumerator of the field path item
414	\bt_p{item}.
415
416	See the \ref api-tir-field-path-prop-items "items" property.
417
418	@param[in] item
419	Field path item of which to get the type enumerator
420
421	@returns
422	Type enumerator of \bt_p{item}.
423
424	@bt_pre_not_null{item}
425	*/
426	extern bt_field_path_item_type bt_field_path_item_get_type(
4c81a2b7	427	const bt_field_path_item *item) __BT_NOEXCEPT;
43c59509 PP	428
	429	/*!
	430	@brief
	431	Returns the index value of the index field path item
	432	\bt_p{item}.
	433
	434	See the \ref api-tir-field-path-prop-items "items" property.
	435
	436	@param[in] item
	437	Index field path item of which to get the index value.
	438
	439	@returns
	440	Index value of \bt_p{item}.
	441
	442	@bt_pre_not_null{item}
	443	@pre
	444	\bt_p{item} is an index field path item
	445	(bt_field_path_item_get_type() returns
	446	#BT_FIELD_PATH_ITEM_TYPE_INDEX).
	447	*/
	448	extern uint64_t bt_field_path_item_index_get_index(
4c81a2b7	449	const bt_field_path_item *item) __BT_NOEXCEPT;
43c59509 PP	450
	451	/! @} /
	452
	453	/! @} /
	454
	455	#ifdef __cplusplus
	456	}
	457	#endif
	458
	459	#endif /* BABELTRACE2_TRACE_IR_FIELD_PATH_H */