+/*!
+@brief
+ Borrows the user attributes of the field class \bt_p{field_class}.
+
+See the \ref api-tir-fc-prop-user-attrs "user attributes" property.
+
+@note
+ When you create a field class with one of the
+ <code>bt_field_class_*_create()</code> functions, the field class's
+ initial user attributes is an empty \bt_map_val.
+
+@param[in] field_class
+ Field class from which to borrow the user attributes.
+
+@returns
+ User attributes of \bt_p{field_class} (a \bt_map_val).
+
+@bt_pre_not_null{field_class}
+
+@sa bt_field_class_set_user_attributes() —
+ Sets the user attributes of a field class.
+@sa bt_field_class_borrow_user_attributes_const() —
+ \c const version of this function.
+*/
+extern bt_value *bt_field_class_borrow_user_attributes(
+ bt_field_class *field_class);
+
+/*!
+@brief
+ Borrows the user attributes of the field class \bt_p{field_class}
+ (\c const version).
+
+See bt_field_class_borrow_user_attributes().
+*/
+extern const bt_value *bt_field_class_borrow_user_attributes_const(
+ const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Boolean field class
+@{
+*/
+
+/*!
+@brief
+ Creates a \bt_bool_fc from the trace class \bt_p{trace_class}.
+
+On success, the returned boolean field class has the following
+property value:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create a boolean field class.
+
+@returns
+ New boolean field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_bool_create(
+ bt_trace_class *trace_class);
+
+/*!
+@}
+*/
+
+/*!
+@name Bit array field class
+@{
+*/
+
+/*!
+@brief
+ Creates a \bt_ba_fc with the length \bt_p{length} from the trace
+ class \bt_p{trace_class}.
+
+On success, the returned bit array field class has the following
+property values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-ba-prop-len "Length"
+ <td>\bt_p{length}
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create a bit array field class.
+@param[in] length
+ Length (number of bits) of the instances of the bit array field
+ class to create.
+
+@returns
+ New bit array field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@pre
+ 0 < \bt_p{length} ≤ 64.
+*/
+extern bt_field_class *bt_field_class_bit_array_create(
+ bt_trace_class *trace_class, uint64_t length);
+
+/*!
+@brief
+ Returns the length of the \bt_ba_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-ba-prop-len "length" property.
+
+@param[in] field_class
+ Bit array field class of which to get the length.
+
+@returns
+ Length of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_ba_fc{field_class}
+*/
+extern uint64_t bt_field_class_bit_array_get_length(
+ const bt_field_class *field_class);
+
+/*!
+@}
+*/
+
+/*!
+@name Integer field class
+@{
+*/
+
+/*!
+@brief
+ Sets the field value range of the \bt_int_fc \bt_p{field_class}
+ to \bt_p{n}.
+
+See the \ref api-tir-fc-int-prop-size "field value range" property.
+
+@param[in] field_class
+ Integer field class of which to set the field value range to
+ \bt_p{n}.
+@param[in] n
+ @parblock
+ \em N in:
+
+ <dl>
+ <dt>Unsigned integer field class</dt>
+ <dd>[0, 2<sup><em>N</em></sup> - 1]</dd>
+
+ <dt>Signed integer field class</dt>
+ <dd>[-2<sup><em>N</em></sup>, 2<sup><em>N</em></sup> - 1]</dd>
+ </dl>
+ @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_is_int_fc{field_class}
+@pre
+ \bt_p{n} ⩽ 64.
+
+@sa bt_field_class_integer_get_field_value_range() —
+ Returns the field value range of an integer field class.
+*/
+extern void bt_field_class_integer_set_field_value_range(
+ bt_field_class *field_class, uint64_t n);
+
+/*!
+@brief
+ Returns the field value range of the \bt_int_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-int-prop-size "field value range" property.
+
+@param[in] field_class
+ Integer field class of which to get the field value range.
+
+@returns
+ @parblock
+ Field value range of \bt_p{field_class}, that is, \em N in:
+
+ <dl>
+ <dt>Unsigned integer field class</dt>
+ <dd>[0, 2<sup><em>N</em></sup> - 1]</dd>
+
+ <dt>Signed integer field class</dt>
+ <dd>[-2<sup><em>N</em></sup>, 2<sup><em>N</em></sup> - 1]</dd>
+ </dl>
+ @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_int_fc{field_class}
+
+@sa bt_field_class_integer_set_field_value_range() —
+ Sets the field value range of an integer field class.
+*/
+extern uint64_t bt_field_class_integer_get_field_value_range(
+ const bt_field_class *field_class);
+
+/*!
+@brief
+ Integer field class preferred display bases.
+*/
+typedef enum bt_field_class_integer_preferred_display_base {
+ /*!
+ @brief
+ Binary (2).
+ */
+ BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY = 2,
+
+ /*!
+ @brief
+ Octal (8).
+ */
+ BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL = 8,
+
+ /*!
+ @brief
+ Decimal (10).
+ */
+ BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL = 10,
+
+ /*!
+ @brief
+ Hexadecimal (16).
+ */
+ BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL = 16,
+} bt_field_class_integer_preferred_display_base;
+
+/*!
+@brief
+ Sets the preferred display base of the \bt_int_fc \bt_p{field_class}
+ to \bt_p{preferred_display_base}.
+
+See the \ref api-tir-fc-int-prop-base "preferred display base" property.
+
+@param[in] field_class
+ Integer field class of which to set the preferred display base to
+ \bt_p{preferred_display_base}.
+@param[in] preferred_display_base
+ New preferred display base of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_is_int_fc{field_class}
+
+@sa bt_field_class_integer_get_preferred_display_base() —
+ Returns the preferred display base of an integer field class.
+*/
+extern void bt_field_class_integer_set_preferred_display_base(
+ bt_field_class *field_class,
+ bt_field_class_integer_preferred_display_base preferred_display_base);
+
+/*!
+@brief
+ Returns the preferred display base of the \bt_int_fc
+ \bt_p{field_class}.
+
+See the \ref api-tir-fc-int-prop-base "preferred display base" property.
+
+@param[in] field_class
+ Integer field class of which to get the preferred display base.
+
+@retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY
+ 2 (binary)
+@retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL
+ 8 (octal)
+@retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
+ 10 (decimal)
+@retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL
+ 16 (hexadecimal)
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_int_fc{field_class}
+
+@sa bt_field_class_integer_set_preferred_display_base() —
+ Sets the preferred display base of an integer field class.
+*/
+extern bt_field_class_integer_preferred_display_base
+bt_field_class_integer_get_preferred_display_base(
+ const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Unsigned integer field class
+@{
+*/
+
+/*!
+@brief
+ Creates an \bt_uint_fc from the trace class \bt_p{trace_class}.
+
+On success, the returned unsigned integer field class has the following
+property values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-int-prop-size "Field value range"
+ <td>[0, 2<sup>64</sup> - 1]
+ <tr>
+ <td>\ref api-tir-fc-int-prop-base "Preferred display base"
+ <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create an unsigned integer field class.
+
+@returns
+ New unsigned integer field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_integer_unsigned_create(
+ bt_trace_class *trace_class);
+
+/*! @} */
+
+/*!
+@name Signed integer field class
+@{
+*/
+
+/*!
+@brief
+ Creates an \bt_sint_fc from the trace class \bt_p{trace_class}.
+
+On success, the returned signed integer field class has the following
+property values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-int-prop-size "Field value range"
+ <td>[-2<sup>63</sup>, 2<sup>63</sup> - 1]
+ <tr>
+ <td>\ref api-tir-fc-int-prop-base "Preferred display base"
+ <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create a signed integer field class.
+
+@returns
+ New signed integer field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_integer_signed_create(
+ bt_trace_class *trace_class);
+
+/*! @} */
+
+/*!
+@name Single-precision real field class
+@{
+*/
+
+/*!
+@brief
+ Creates a single-precision \bt_real_fc from the trace class
+ \bt_p{trace_class}.
+
+On success, the returned single-precision real field class has the
+following property value:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create a single-preicision real
+ field class.
+
+@returns
+ New single-precision real field class reference, or \c NULL on
+ memory error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_real_single_precision_create(
+ bt_trace_class *trace_class);
+
+/*! @} */
+
+/*!
+@name Double-precision real field class
+@{
+*/
+
+/*!
+@brief
+ Creates a double-precision \bt_real_fc from the trace class
+ \bt_p{trace_class}.
+
+On success, the returned double-precision real field class has the
+following property value:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create a double-preicision real
+ field class.
+
+@returns
+ New double-precision real field class reference, or \c NULL on
+ memory error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_real_double_precision_create(
+ bt_trace_class *trace_class);
+
+/*! @} */
+
+/*!
+@name Enumeration field class
+@{
+*/
+
+/*!
+@brief
+ Array of \c const \bt_enum_fc labels.
+
+Returned by bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
+and bt_field_class_enumeration_signed_get_mapping_labels_for_value().
+*/
+typedef char const * const *bt_field_class_enumeration_mapping_label_array;
+
+/*!
+@brief
+ Status codes for
+ bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
+ and
+ bt_field_class_enumeration_signed_get_mapping_labels_for_value().
+*/
+typedef enum bt_field_class_enumeration_get_mapping_labels_for_value_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_field_class_enumeration_get_mapping_labels_for_value_status;
+
+/*!
+@brief
+ Status codes for bt_field_class_enumeration_unsigned_add_mapping()
+ and bt_field_class_enumeration_signed_add_mapping().
+*/
+typedef enum bt_field_class_enumeration_add_mapping_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_field_class_enumeration_add_mapping_status;
+
+/*! @} */
+
+/*!
+@name Enumeration field class mapping
+@{
+*/
+
+/*!
+@typedef struct bt_field_class_enumeration_mapping bt_field_class_enumeration_mapping;
+
+@brief
+ Enumeration field class mapping.
+*/
+
+/*!
+@brief
+ Returns the number of mappings contained in the \bt_enum_fc
+ \bt_p{field_class}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] field_class
+ Enumeration field class of which to get the number of contained
+ mappings.
+
+@returns
+ Number of contained mappings in \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_enum_fc{field_class}
+*/
+extern uint64_t bt_field_class_enumeration_get_mapping_count(
+ const bt_field_class *field_class);
+
+/*!
+@brief
+ Returns the label of the \bt_enum_fc mapping \bt_p{mapping}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] mapping
+ Enumeration field class mapping of which to get the label.
+
+@returns
+ @parblock
+ Label of \bt_p{mapping}.
+
+ The returned pointer remains valid as long as \bt_p{mapping} exists.
+ @endparblock
+
+@bt_pre_not_null{mapping}
+*/
+extern const char *bt_field_class_enumeration_mapping_get_label(
+ const bt_field_class_enumeration_mapping *mapping);
+
+/*! @} */
+
+/*!
+@name Unsigned enumeration field class
+@{
+*/
+
+/*!
+@brief
+ Creates an \bt_uenum_fc from the trace class \bt_p{trace_class}.
+
+On success, the returned unsigned enumeration field class has the
+following property values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-int-prop-size "Field value range"
+ <td>[0, 2<sup>64</sup> - 1]
+ <tr>
+ <td>\ref api-tir-fc-int-prop-base "Preferred display base"
+ <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
+ <tr>
+ <td>\ref api-tir-fc-enum-prop-mappings "Mappings"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create an unsigned enumeration field
+ class.
+
+@returns
+ New unsigned enumeration field class reference, or \c NULL on memory
+ error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_enumeration_unsigned_create(
+ bt_trace_class *trace_class);
+
+/*!
+@brief
+ Adds a mapping to the \bt_uenum_fc \bt_p{field_class} having the
+ label \bt_p{label} and the unsigned integer ranges \bt_p{ranges}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] field_class
+ Unsigned enumeration field class to which to add a mapping having
+ the label \bt_p{label} and the integer ranges \bt_p{ranges}.
+@param[in] label
+ Label of the mapping to add to \bt_p{field_class} (copied).
+@param[in] ranges
+ Unsigned integer ranges of the mapping to add to
+ \bt_p{field_class}.
+
+@retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
+ Success.
+@retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
+ Out of memory.
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_is_uenum_fc{field_class}
+@bt_pre_not_null{label}
+@pre
+ \bt_p{field_class} has no mapping with the label \bt_p{label}.
+@bt_pre_not_null{ranges}
+@pre
+ \bt_p{ranges} contains one or more unsigned integer ranges.
+*/
+extern bt_field_class_enumeration_add_mapping_status
+bt_field_class_enumeration_unsigned_add_mapping(
+ bt_field_class *field_class, const char *label,
+ const bt_integer_range_set_unsigned *ranges);
+
+/*!
+@brief
+ Borrows the mapping at index \bt_p{index} from the
+ \bt_uenum_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] field_class
+ Unsigned enumeration field class from which to borrow the mapping at
+ index \bt_p{index}.
+@param[in] index
+ Index of the mapping to borrow from \bt_p{field_class}.
+
+@returns
+ @parblock
+ \em Borrowed reference of the mapping of
+ \bt_p{field_class} at index \bt_p{index}.
+
+ The returned pointer remains valid as long as \bt_p{field_class}
+ is not modified.
+ @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_uenum_fc{field_class}
+@pre
+ \bt_p{index} is less than the number of mappings in
+ \bt_p{field_class} (as returned by
+ bt_field_class_enumeration_get_mapping_count()).
+
+@sa bt_field_class_enumeration_get_mapping_count() —
+ Returns the number of mappings contained in an
+ enumeration field class.
+*/
+extern const bt_field_class_enumeration_unsigned_mapping *
+bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const(
+ const bt_field_class *field_class, uint64_t index);
+
+/*!
+@brief
+ Borrows the mapping having the label \bt_p{label} from the
+ \bt_uenum_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+If there's no mapping having the label \bt_p{label} in
+\bt_p{field_class}, this function returns \c NULL.
+
+@param[in] field_class
+ Unsigned enumeration field class from which to borrow the mapping
+ having the label \bt_p{label}.
+@param[in] label
+ Label of the mapping to borrow from \bt_p{field_class}.
+
+@returns
+ @parblock
+ \em Borrowed reference of the mapping of
+ \bt_p{field_class} having the label \bt_p{label}, or \c NULL
+ if none.
+
+ The returned pointer remains valid as long as \bt_p{field_class}
+ is not modified.
+ @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_uenum_fc{field_class}
+@bt_pre_not_null{label}
+*/
+extern const bt_field_class_enumeration_unsigned_mapping *
+bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const(
+ const bt_field_class *field_class, const char *label);
+
+/*!
+@brief
+ Returns an array of all the labels of the mappings of the
+ \bt_uenum_fc \bt_p{field_class} of which the \bt_p_uint_rg contain
+ the integral value \bt_p{value}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+This function sets \bt_p{*labels} to the resulting array and
+\bt_p{*count} to the number of labels in \bt_p{*labels}.
+
+On success, if there's no mapping ranges containing the value
+\bt_p{value}, \bt_p{*count} is 0.
+
+@param[in] field_class
+ Unsigned enumeration field class from which to get the labels of the
+ mappings of which the ranges contain \bt_p{value}.
+@param[in] value
+ Value for which to get the mapped labels in \bt_p{field_class}.
+@param[out] labels
+ @parblock
+ <strong>On success</strong>, \bt_p{*labels}
+ is an array of labels of the mappings of \bt_p{field_class}
+ containing \bt_p{value}.
+
+ The number of labels in \bt_p{*labels} is \bt_p{*count}.
+
+ The array is owned by \bt_p{field_class} and remains valid as long
+ as \bt_p{field_class} is not modified.
+ @endparblock
+@param[out] count
+ <strong>On success</strong>, \bt_p{*count} is the number of labels
+ in \bt_p{*labels} (can be 0).
+
+@retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
+ Success.
+@retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
+ Out of memory.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_uenum_fc{field_class}
+@bt_pre_not_null{labels}
+@bt_pre_not_null{count}
+*/
+extern bt_field_class_enumeration_get_mapping_labels_for_value_status
+bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
+ const bt_field_class *field_class, uint64_t value,
+ bt_field_class_enumeration_mapping_label_array *labels,
+ uint64_t *count);
+
+/*! @} */
+
+/*!
+@name Unsigned enumeration field class mapping
+@{
+*/
+
+/*!
+@typedef struct bt_field_class_enumeration_unsigned_mapping bt_field_class_enumeration_unsigned_mapping;
+
+@brief
+ Unsigned enumeration field class mapping.
+*/
+
+/*!
+@brief
+ Borrows the \bt_p_uint_rg from the \bt_uenum_fc mapping
+ \bt_p{mapping}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] mapping
+ Unsigned enumeration field class mapping from which to borrow the
+ unsigned integer ranges.
+
+@returns
+ Unsigned integer ranges of \bt_p{mapping}.
+
+@bt_pre_not_null{mapping}
+*/
+extern const bt_integer_range_set_unsigned *
+bt_field_class_enumeration_unsigned_mapping_borrow_ranges_const(
+ const bt_field_class_enumeration_unsigned_mapping *mapping);
+
+/*!
+@brief
+ \ref api-fund-c-typing "Upcasts" the \bt_uenum_fc mapping
+ \bt_p{mapping} to the common #bt_field_class_enumeration_mapping
+ type.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] mapping
+ @parblock
+ Unsigned enumeration field class mapping to upcast.
+
+ Can be \c NULL.
+ @endparblock
+
+@returns
+ \bt_p{mapping} as a common enumeration field class mapping.
+*/
+static inline
+const bt_field_class_enumeration_mapping *
+bt_field_class_enumeration_unsigned_mapping_as_mapping_const(
+ const bt_field_class_enumeration_unsigned_mapping *mapping)
+{
+ return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping, mapping);
+}
+
+/*! @} */
+
+/*!
+@name Signed enumeration field class
+@{
+*/
+
+/*!
+@brief
+ Creates a \bt_senum_fc from the trace class \bt_p{trace_class}.
+
+On success, the returned signed enumeration field class has the
+following property values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-int-prop-size "Field value range"
+ <td>[-2<sup>63</sup>, 2<sup>63</sup> - 1]
+ <tr>
+ <td>\ref api-tir-fc-int-prop-base "Preferred display base"
+ <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
+ <tr>
+ <td>\ref api-tir-fc-enum-prop-mappings "Mappings"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create a signed enumeration field
+ class.
+
+@returns
+ New signed enumeration field class reference, or \c NULL on memory
+ error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_enumeration_signed_create(
+ bt_trace_class *trace_class);
+
+/*!
+@brief
+ Adds a mapping to the \bt_senum_fc \bt_p{field_class} having the
+ label \bt_p{label} and the \bt_p_sint_rg \bt_p{ranges}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] field_class
+ Signed enumeration field class to which to add a mapping having
+ the label \bt_p{label} and the integer ranges \bt_p{ranges}.
+@param[in] label
+ Label of the mapping to add to \bt_p{field_class} (copied).
+@param[in] ranges
+ Signed integer ranges of the mapping to add to
+ \bt_p{field_class}.
+
+@retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
+ Success.
+@retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
+ Out of memory.
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_is_senum_fc{field_class}
+@bt_pre_not_null{label}
+@pre
+ \bt_p{field_class} has no mapping with the label \bt_p{label}.
+@bt_pre_not_null{ranges}
+@pre
+ \bt_p{ranges} contains one or more signed integer ranges.
+*/
+extern bt_field_class_enumeration_add_mapping_status
+bt_field_class_enumeration_signed_add_mapping(
+ bt_field_class *field_class, const char *label,
+ const bt_integer_range_set_signed *ranges);
+
+/*!
+@brief
+ Borrows the mapping at index \bt_p{index} from the
+ \bt_senum_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] field_class
+ Signed enumeration field class from which to borrow the mapping at
+ index \bt_p{index}.
+@param[in] index
+ Index of the mapping to borrow from \bt_p{field_class}.
+
+@returns
+ @parblock
+ \em Borrowed reference of the mapping of
+ \bt_p{field_class} at index \bt_p{index}.
+
+ The returned pointer remains valid as long as \bt_p{field_class}
+ is not modified.
+ @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_senum_fc{field_class}
+@pre
+ \bt_p{index} is less than the number of mappings in
+ \bt_p{field_class} (as returned by
+ bt_field_class_enumeration_get_mapping_count()).
+
+@sa bt_field_class_enumeration_get_mapping_count() —
+ Returns the number of mappings contained in an
+ enumeration field class.
+*/
+extern const bt_field_class_enumeration_signed_mapping *
+bt_field_class_enumeration_signed_borrow_mapping_by_index_const(
+ const bt_field_class *field_class, uint64_t index);
+
+/*!
+@brief
+ Borrows the mapping having the label \bt_p{label} from the
+ \bt_senum_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+If there's no mapping having the label \bt_p{label} in
+\bt_p{field_class}, this function returns \c NULL.
+
+@param[in] field_class
+ Signed enumeration field class from which to borrow the mapping
+ having the label \bt_p{label}.
+@param[in] label
+ Label of the mapping to borrow from \bt_p{field_class}.
+
+@returns
+ @parblock
+ \em Borrowed reference of the mapping of
+ \bt_p{field_class} having the label \bt_p{label}, or \c NULL
+ if none.
+
+ The returned pointer remains valid as long as \bt_p{field_class}
+ is not modified.
+ @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_senum_fc{field_class}
+@bt_pre_not_null{label}
+*/
+extern const bt_field_class_enumeration_signed_mapping *
+bt_field_class_enumeration_signed_borrow_mapping_by_label_const(
+ const bt_field_class *field_class, const char *label);
+
+/*!
+@brief
+ Returns an array of all the labels of the mappings of the
+ \bt_senum_fc \bt_p{field_class} of which the \bt_p_sint_rg contain
+ the integral value \bt_p{value}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+This function sets \bt_p{*labels} to the resulting array and
+\bt_p{*count} to the number of labels in \bt_p{*labels}.
+
+On success, if there's no mapping ranges containing the value
+\bt_p{value}, \bt_p{*count} is 0.
+
+@param[in] field_class
+ Signed enumeration field class from which to get the labels of the
+ mappings of which the ranges contain \bt_p{value}.
+@param[in] value
+ Value for which to get the mapped labels in \bt_p{field_class}.
+@param[out] labels
+ @parblock
+ <strong>On success</strong>, \bt_p{*labels}
+ is an array of labels of the mappings of \bt_p{field_class}
+ containing \bt_p{value}.
+
+ The number of labels in \bt_p{*labels} is \bt_p{*count}.
+
+ The array is owned by \bt_p{field_class} and remains valid as long
+ as \bt_p{field_class} is not modified.
+ @endparblock
+@param[out] count
+ <strong>On success</strong>, \bt_p{*count} is the number of labels
+ in \bt_p{*labels} (can be 0).
+
+@retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
+ Success.
+@retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
+ Out of memory.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_senum_fc{field_class}
+@bt_pre_not_null{labels}
+@bt_pre_not_null{count}
+*/
+extern bt_field_class_enumeration_get_mapping_labels_for_value_status
+bt_field_class_enumeration_signed_get_mapping_labels_for_value(
+ const bt_field_class *field_class, int64_t value,
+ bt_field_class_enumeration_mapping_label_array *labels,
+ uint64_t *count);
+
+/*! @} */
+
+/*!
+@name Signed enumeration field class mapping
+@{
+*/
+
+/*!
+@typedef struct bt_field_class_enumeration_signed_mapping bt_field_class_enumeration_signed_mapping;
+
+@brief
+ Signed enumeration field class mapping.
+*/
+
+/*!
+@brief
+ Borrows the \bt_p_sint_rg from the \bt_senum_fc mapping
+ \bt_p{mapping}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] mapping
+ Signed enumeration field class mapping from which to borrow the
+ signed integer ranges.
+
+@returns
+ Signed integer ranges of \bt_p{mapping}.
+
+@bt_pre_not_null{mapping}
+*/
+extern const bt_integer_range_set_signed *
+bt_field_class_enumeration_signed_mapping_borrow_ranges_const(
+ const bt_field_class_enumeration_signed_mapping *mapping);
+
+/*!
+@brief
+ \ref api-fund-c-typing "Upcasts" the \bt_senum_fc mapping
+ \bt_p{mapping} to the common #bt_field_class_enumeration_mapping
+ type.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] mapping
+ @parblock
+ Signed enumeration field class mapping to upcast.
+
+ Can be \c NULL.
+ @endparblock
+
+@returns
+ \bt_p{mapping} as a common enumeration field class mapping.
+*/
+static inline
+const bt_field_class_enumeration_mapping *
+bt_field_class_enumeration_signed_mapping_as_mapping_const(
+ const bt_field_class_enumeration_signed_mapping *mapping)
+{
+ return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping, mapping);
+}
+
+/*! @} */
+
+/*!
+@name String field class
+@{
+*/
+
+/*!
+@brief
+ Creates a \bt_string_fc from the trace class \bt_p{trace_class}.
+
+On success, the returned string field class has the following property
+value:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create a string field class.
+
+@returns
+ New string field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_string_create(
+ bt_trace_class *trace_class);
+
+/*! @} */
+
+/*!
+@name Array field class
+@{
+*/
+
+/*!
+@brief
+ Borrows the element field class from the \bt_array_fc
+ \bt_p{field_class}.
+
+See the \ref api-tir-fc-array-prop-elem-fc "element field class"
+property.
+
+@param[in] field_class
+ Array field class from which to borrow the element field class.
+
+@returns
+ Element field class of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_array_fc{field_class}
+
+@sa bt_field_class_array_borrow_element_field_class_const() —
+ \c const version of this function.
+*/
+extern bt_field_class *bt_field_class_array_borrow_element_field_class(
+ bt_field_class *field_class);
+
+/*!
+@brief
+ Borrows the element field class from the \bt_array_fc
+ \bt_p{field_class} (\c const version).
+
+See bt_field_class_array_borrow_element_field_class().
+*/
+extern const bt_field_class *
+bt_field_class_array_borrow_element_field_class_const(
+ const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Static array field class
+@{
+*/
+
+/*!
+@brief
+ Creates a \bt_sarray_fc having the element field class
+ \bt_p{element_field_class} and the length \bt_p{length} from the
+ trace class \bt_p{trace_class}.
+
+On success, the returned static array field class has the following
+property values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
+ <td>\bt_p{element_field_class}
+ <tr>
+ <td>\ref api-tir-fc-sarray-prop-len "Length"
+ <td>\bt_p{length}
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create a static array field class.
+@param[in] element_field_class
+ Class of the element fields of the instances of the static array
+ field class to create.
+@param[in] length
+ Length of the instances of the static array field class to create.
+
+@returns
+ New static array field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_not_null{element_field_class}
+bt_pre_fc_not_in_tc{element_field_class}
+
+@bt_post_success_frozen{element_field_class}
+*/
+extern bt_field_class *bt_field_class_array_static_create(
+ bt_trace_class *trace_class,
+ bt_field_class *element_field_class, uint64_t length);
+
+/*!
+@brief
+ Returns the length of the \bt_sarray_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-sarray-prop-len "length" property.
+
+@param[in] field_class
+ Static array field class of which to get the length.
+
+@returns
+ Length of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_sarray_fc{field_class}
+*/
+extern uint64_t bt_field_class_array_static_get_length(
+ const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Dynamic array field class
+@{
+*/
+
+/*!
+@brief
+ Creates a \bt_darray_fc having the element field class
+ \bt_p{element_field_class} from the trace class \bt_p{trace_class}.
+
+If \bt_p{length_field_class} is not \c NULL, then the created dynamic
+array field class has a linked length field class.
+See
+\ref api-tir-fc-link "Field classes with links to other field classes"
+to learn more.
+
+On success, the returned dynamic array field class has the following
+property values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
+ <td>\bt_p{element_field_class}
+ <tr>
+ <td>\ref api-tir-fc-darray-prop-len-fp "Length field path"
+ <td>
+ \em None (if \bt_p{length_field_class} is not \c NULL, this
+ property becomes available when the returned field class becomes
+ part of an \bt_ev_cls or of a \bt_stream_cls)
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create a dynamic array field class.
+@param[in] element_field_class
+ Class of the element fields of the instances of the dynamic array
+ field class to create.
+@param[in] length_field_class
+ @parblock
+ Linked length field class of the dynamic array field class to
+ create.
+
+ Can be \c NULL.
+ @endparblock
+
+@returns
+ New dynamic array field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_not_null{element_field_class}
+@bt_pre_fc_not_in_tc{element_field_class}
+@pre
+ <strong>If \bt_p{length_field_class} is not \c NULL</strong>,
+ \bt_p{length_field_class} is an \bt_uint_fc.
+
+@bt_post_success_frozen{element_field_class}
+@bt_post_success_frozen{length_field_class}
+*/
+extern bt_field_class *bt_field_class_array_dynamic_create(
+ bt_trace_class *trace_class,
+ bt_field_class *element_field_class,
+ bt_field_class *length_field_class);
+
+/*! @} */
+
+/*!
+@name Dynamic array field class with length field
+@{
+*/
+
+/*!
+@brief
+ Borrows the length field path from the \bt_darray_fc (with a length
+ field) \bt_p{field_class}.
+
+See the \ref api-tir-fc-darray-prop-len-fp "length field path" property.
+
+This property is only available when a \bt_struct_fc containing
+(recursively) \bt_p{field_class} is passed to one of:
+
+- bt_stream_class_set_packet_context_field_class()
+- bt_stream_class_set_event_common_context_field_class()
+- bt_event_class_set_specific_context_field_class()
+- bt_event_class_set_payload_field_class()
+
+In the meantime, this function returns \c NULL.
+
+@param[in] field_class
+ Dynamic array field class from which to borrow the length
+ field path.
+
+@returns
+ Length field path of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_darray_wl_fc{field_class}
+*/
+extern const bt_field_path *
+bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(
+ const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Structure field class
+@{
+*/
+
+/*!
+@brief
+ Creates a \bt_struct_fc from the trace class \bt_p{trace_class}.
+
+On success, the returned structure field class has the following
+property values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-struct-prop-members "Members"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create a structure field class.
+
+@returns
+ New structure field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_structure_create(
+ bt_trace_class *trace_class);
+
+/*!
+@brief
+ Status codes for bt_field_class_structure_append_member().
+*/
+typedef enum bt_field_class_structure_append_member_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_field_class_structure_append_member_status;
+
+/*!
+@brief
+ Appends a member to the \bt_struct_fc \bt_p{field_class} having the
+ name \bt_p{name} and the field class \bt_p{member_field_class}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+@param[in] field_class
+ Structure field class to which to append a member having
+ the name \bt_p{name} and the field class \bt_p{member_field_class}.
+@param[in] name
+ Name of the member to append to \bt_p{field_class} (copied).
+@param[in] member_field_class
+ Field class of the member to append to \bt_p{field_class}.
+
+@retval #BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK
+ Success.
+@retval #BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR
+ Out of memory.
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_is_struct_fc{field_class}
+@pre
+ \bt_p{field_class} has no member with the name \bt_p{name}.
+@bt_pre_not_null{name}
+@bt_pre_not_null{member_field_class}
+@bt_pre_fc_not_in_tc{member_field_class}
+
+@bt_post_success_frozen{member_field_class}
+*/
+extern bt_field_class_structure_append_member_status
+bt_field_class_structure_append_member(
+ bt_field_class *field_class,
+ const char *name, bt_field_class *member_field_class);
+
+/*!
+@brief
+ Returns the number of members contained in the \bt_struct_fc
+ \bt_p{field_class}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+@param[in] field_class
+ Structure field class of which to get the number of contained
+ members.
+
+@returns
+ Number of contained members in \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_struct_fc{field_class}
+*/
+extern uint64_t bt_field_class_structure_get_member_count(
+ const bt_field_class *field_class);
+
+/*!
+@brief
+ Borrows the member at index \bt_p{index} from the
+ \bt_struct_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+@param[in] field_class
+ Structure field class from which to borrow the member at
+ index \bt_p{index}.
+@param[in] index
+ Index of the member to borrow from \bt_p{field_class}.
+
+@returns
+ @parblock
+ \em Borrowed reference of the member of
+ \bt_p{field_class} at index \bt_p{index}.
+
+ The returned pointer remains valid as long as \bt_p{field_class}
+ is not modified.
+ @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_struct_fc{field_class}
+@pre
+ \bt_p{index} is less than the number of members in
+ \bt_p{field_class} (as returned by
+ bt_field_class_structure_get_member_count()).
+
+@sa bt_field_class_structure_get_member_count() —
+ Returns the number of members contained in a structure field class.
+@sa bt_field_class_structure_borrow_member_by_index_const() —
+ \c const version of this function.
+*/
+extern bt_field_class_structure_member *
+bt_field_class_structure_borrow_member_by_index(
+ bt_field_class *field_class, uint64_t index);
+
+/*!
+@brief
+ Borrows the member at index \bt_p{index} from the
+ \bt_struct_fc \bt_p{field_class} (\c const version).
+
+See bt_field_class_structure_borrow_member_by_index().
+*/
+extern const bt_field_class_structure_member *
+bt_field_class_structure_borrow_member_by_index_const(
+ const bt_field_class *field_class, uint64_t index);
+
+/*!
+@brief
+ Borrows the member having the name \bt_p{name} from the
+ \bt_struct_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+If there's no member having the name \bt_p{name} in
+\bt_p{field_class}, this function returns \c NULL.
+
+@param[in] field_class
+ Structure field class from which to borrow the member having the
+ name \bt_p{name}.
+@param[in] name
+ Name of the member to borrow from \bt_p{field_class}.
+
+@returns
+ @parblock
+ \em Borrowed reference of the member of
+ \bt_p{field_class} having the name \bt_p{name}, or \c NULL
+ if none.
+
+ The returned pointer remains valid as long as \bt_p{field_class}
+ is not modified.
+ @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_struct_fc{field_class}
+@bt_pre_not_null{name}
+
+@sa bt_field_class_structure_borrow_member_by_name_const() —
+ \c const version of this function.
+*/
+extern bt_field_class_structure_member *
+bt_field_class_structure_borrow_member_by_name(
+ bt_field_class *field_class, const char *name);
+
+/*!
+@brief
+ Borrows the member having the name \bt_p{name} from the
+ \bt_struct_fc \bt_p{field_class} (\c const version).
+
+See bt_field_class_structure_borrow_member_by_name().
+*/
+extern const bt_field_class_structure_member *
+bt_field_class_structure_borrow_member_by_name_const(
+ const bt_field_class *field_class, const char *name);
+
+/*! @} */
+
+/*!
+@name Structure field class member
+@{
+*/
+
+/*!
+@typedef struct bt_field_class_structure_member bt_field_class_structure_member;
+
+@brief
+ Structure field class member.
+*/
+
+/*!
+@brief
+ Returns the name of the \bt_struct_fc member \bt_p{member}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+@param[in] member
+ Structure field class member of which to get the name.
+
+@returns
+ @parblock
+ Name of \bt_p{member}.
+
+ The returned pointer remains valid as long as \bt_p{member} exists.
+ @endparblock
+
+@bt_pre_not_null{member}
+*/
+extern const char *bt_field_class_structure_member_get_name(
+ const bt_field_class_structure_member *member);
+
+/*!
+@brief
+ Borrows the field class from the \bt_struct_fc member
+ \bt_p{member}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+@param[in] member
+ Structure field class member from which to borrow the field class.
+
+@returns
+ Field class of \bt_p{member}.
+
+@bt_pre_not_null{member}
+
+@sa bt_field_class_structure_member_borrow_field_class_const() —
+ \c const version of this function.
+*/
+extern bt_field_class *
+bt_field_class_structure_member_borrow_field_class(
+ bt_field_class_structure_member *member);
+
+/*!
+@brief
+ Borrows the field class from the \bt_struct_fc member
+ \bt_p{member} (\c const version).
+
+See bt_field_class_structure_member_borrow_field_class().
+*/
+extern const bt_field_class *
+bt_field_class_structure_member_borrow_field_class_const(
+ const bt_field_class_structure_member *member);
+
+/*!
+@brief
+ Sets the user attributes of the \bt_struct_fc member \bt_p{member}
+ to \bt_p{user_attributes}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+@note
+ When you append a member to a structure field class with
+ bt_field_class_structure_append_member(), the member's
+ initial user attributes is an empty \bt_map_val. Therefore you can
+ borrow it with
+ bt_field_class_structure_member_borrow_user_attributes() and fill it
+ directly instead of setting a new one with this function.
+
+@param[in] member
+ Structure field class member of which to set the user attributes to
+ \bt_p{user_attributes}.
+@param[in] user_attributes
+ New user attributes of \bt_p{member}.
+
+@bt_pre_not_null{member}
+@bt_pre_hot{member}
+@bt_pre_not_null{user_attributes}
+@bt_pre_is_map_val{user_attributes}
+
+@sa bt_field_class_structure_member_borrow_user_attributes() —
+ Borrows the user attributes of a structure field class member.
+*/
+extern void bt_field_class_structure_member_set_user_attributes(
+ bt_field_class_structure_member *member,
+ const bt_value *user_attributes);
+
+/*!
+@brief
+ Borrows the user attributes of the \bt_struct_fc member
+ \bt_p{member}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+@note
+ When you append a member to a structure field class with
+ bt_field_class_structure_append_member(), the member's
+ initial user attributes is an empty \bt_map_val.
+
+@param[in] member
+ Structure field class member from which to borrow the user
+ attributes.
+
+@returns
+ User attributes of \bt_p{member} (a \bt_map_val).
+
+@bt_pre_not_null{member}
+
+@sa bt_field_class_structure_member_set_user_attributes() —
+ Sets the user attributes of a structure field class member.
+@sa bt_field_class_structure_member_borrow_user_attributes_const() —
+ \c const version of this function.
+*/
+extern bt_value *
+bt_field_class_structure_member_borrow_user_attributes(
+ bt_field_class_structure_member *member);
+
+/*!
+@brief
+ Borrows the user attributes of the \bt_struct_fc member
+ \bt_p{member} (\c const version).
+
+See bt_field_class_structure_member_borrow_user_attributes().
+*/
+extern const bt_value *
+bt_field_class_structure_member_borrow_user_attributes_const(
+ const bt_field_class_structure_member *member);
+
+/*! @} */
+
+/*!
+@name Option field class
+@{
+*/
+
+/*!
+@brief
+ Borrows the optional field class from the \bt_opt_fc
+ \bt_p{field_class}.
+
+See the \ref api-tir-fc-opt-prop-fc "optional field class" property.
+
+@param[in] field_class
+ Option field class from which to borrow the optional field class.
+
+@returns
+ Optional field class of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_opt_fc{field_class}
+
+@sa bt_field_class_option_borrow_field_class_const() —
+ \c const version of this function.
+*/
+extern bt_field_class *bt_field_class_option_borrow_field_class(
+ bt_field_class *field_class);
+
+/*!
+@brief
+ Borrows the optional field class from the \bt_opt_fc
+ \bt_p{field_class} (\c const version).
+
+See bt_field_class_option_borrow_field_class().
+*/
+extern const bt_field_class *
+bt_field_class_option_borrow_field_class_const(
+ const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Option field class without a selector field
+@{
+*/
+
+/*!
+@brief
+ Creates an \bt_opt_fc (without a selector field) having the optional
+ field class \bt_p{optional_field_class} from the trace class
+ \bt_p{trace_class}.
+
+On success, the returned option field class has the following property
+values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
+ <td>\bt_p{optional_field_class}
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create an option field class.
+@param[in] optional_field_class
+ Class of the optional fields of the instances of the option field
+ class to create.
+
+@returns
+ New option field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_not_null{optional_field_class}
+@bt_pre_fc_not_in_tc{optional_field_class}
+
+@bt_post_success_frozen{optional_field_class}
+*/
+extern bt_field_class *bt_field_class_option_without_selector_create(
+ bt_trace_class *trace_class,
+ bt_field_class *optional_field_class);
+
+/*! @} */
+
+/*!
+@name Option field class with a selector field
+@{
+*/
+
+/*!
+@brief
+ Borrows the selector field path from the \bt_opt_fc (with a selector
+ field) \bt_p{field_class}.
+
+See the \ref api-tir-fc-opt-prop-sel-fp "selector field path" property.
+
+This property is only available when a \bt_struct_fc containing
+(recursively) \bt_p{field_class} is passed to one of:
+
+- bt_stream_class_set_packet_context_field_class()
+- bt_stream_class_set_event_common_context_field_class()
+- bt_event_class_set_specific_context_field_class()
+- bt_event_class_set_payload_field_class()
+
+In the meantime, this function returns \c NULL.
+
+@param[in] field_class
+ Option field class from which to borrow the selector field path.
+
+@returns
+ Selector field path of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_opt_ws_fc{field_class}
+*/
+extern const bt_field_path *
+bt_field_class_option_with_selector_field_borrow_selector_field_path_const(
+ const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Option field class with a boolean selector field
+@{
+*/
+
+/*!
+@brief
+ Creates an \bt_opt_fc (with a boolean selector field) having the
+ optional field class \bt_p{optional_field_class} from the trace
+ class \bt_p{trace_class}.
+
+On success, the returned option field class has the following property
+values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
+ <td>\bt_p{optional_field_class}
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
+ <td>
+ \em None (this property becomes available when the returned field
+ class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-sel-rev "Selector is reversed?"
+ <td>#BT_FALSE
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create an option field class.
+@param[in] optional_field_class
+ Class of the optional fields of the instances of the option field
+ class to create.
+@param[in] selector_field_class
+ Linked selector field class of the option field class to create.
+
+@returns
+ New option field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_not_null{optional_field_class}
+@bt_pre_fc_not_in_tc{optional_field_class}
+@bt_pre_not_null{selector_field_class}
+@pre
+ \bt_p{selector_field_class} is a \bt_bool_fc.
+
+@bt_post_success_frozen{optional_field_class}
+@bt_post_success_frozen{selector_field_class}
+*/
+extern bt_field_class *bt_field_class_option_with_selector_field_bool_create(
+ bt_trace_class *trace_class,
+ bt_field_class *optional_field_class,
+ bt_field_class *selector_field_class);
+
+/*!
+@brief
+ Sets whether or not the selector of the \bt_opt_fc (with a boolean
+ selector field) \bt_p{field_class} is reversed.
+
+See the \ref api-tir-fc-opt-prop-sel-rev "selector is reversed?"
+property.
+
+@param[in] field_class
+ Option field class of which to set whether or not its selector
+ is reversed.
+@param[in] selector_is_reversed
+ #BT_TRUE to make \bt_p{field_class} have a reversed selector.
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_is_opt_wbs_fc{field_class}
+
+@sa bt_field_class_option_with_selector_field_bool_selector_is_reversed() —
+ Returns whether or not the selector of an option field class (with
+ a boolean selector field) is reversed.
+*/
+extern void
+bt_field_class_option_with_selector_field_bool_set_selector_is_reversed(
+ bt_field_class *field_class, bt_bool selector_is_reversed);
+
+/*!
+@brief
+ Returns whether or not the selector of the
+ \bt_opt_fc (with a boolean selector field) is reversed.
+
+See the \ref api-tir-fc-opt-prop-sel-rev "selector is reversed?"
+property.
+
+@param[in] field_class
+ Option field class of which to get whether or not its selector is
+ reversed.
+
+@returns
+ #BT_TRUE if the selector of \bt_p{field_class} is reversed.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_opt_wbs_fc{field_class}
+
+@sa bt_field_class_option_with_selector_field_bool_set_selector_is_reversed() —
+ Sets whether or not the selector of an option field class (with
+ a boolean selector field) is reversed.
+*/
+extern bt_bool
+bt_field_class_option_with_selector_field_bool_selector_is_reversed(
+ const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Option field class with an unsigned integer selector field
+@{
+*/
+
+/*!
+@brief
+ Creates an \bt_opt_fc (with an unsigned integer selector field)
+ having the optional field class \bt_p{optional_field_class} from the
+ trace class \bt_p{trace_class}.
+
+On success, the returned option field class has the following property
+values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
+ <td>\bt_p{optional_field_class}
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
+ <td>
+ \em None (this property becomes available when the returned field
+ class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-uint-rs "Selector's unsigned integer ranges"
+ <td>\bt_p{ranges}
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create an option field class.
+@param[in] optional_field_class
+ Class of the optional fields of the instances of the option field
+ class to create.
+@param[in] selector_field_class
+ Linked selector field class of the option field class to create.
+@param[in] ranges
+ Selector's unsigned integer ranges of the option field class to
+ create.
+
+@returns
+ New option field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_not_null{optional_field_class}
+@bt_pre_fc_not_in_tc{optional_field_class}
+@bt_pre_not_null{selector_field_class}
+@pre
+ \bt_p{selector_field_class} is a \bt_uint_fc.
+@bt_pre_not_null{ranges}
+@pre
+ \bt_p{ranges} contains one or more \bt_p_uint_rg.
+
+@bt_post_success_frozen{optional_field_class}
+@bt_post_success_frozen{selector_field_class}
+@bt_post_success_frozen{ranges}
+*/
+extern bt_field_class *
+bt_field_class_option_with_selector_field_integer_unsigned_create(
+ bt_trace_class *trace_class,
+ bt_field_class *optional_field_class,
+ bt_field_class *selector_field_class,
+ const bt_integer_range_set_unsigned *ranges);
+
+/*!
+@brief
+ Borrows the \bt_p_uint_rg from the \bt_opt_fc (with an unsigned
+ integer selector field) \bt_p{field_class}.
+
+See the
+\ref api-tir-fc-opt-prop-uint-rs "selector's unsigned integer ranges"
+property.
+
+@param[in] field_class
+ Option field class from which to borrow the unsigned integer ranges.
+
+@returns
+ Unsigned integer ranges of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_opt_wuis_fc{field_class}
+*/
+extern const bt_integer_range_set_unsigned *
+bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const(
+ const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Option field class with a signed integer selector field
+@{
+*/
+
+/*!
+@brief
+ Creates an \bt_opt_fc (with a signed integer selector field)
+ having the optional field class \bt_p{optional_field_class} from the
+ trace class \bt_p{trace_class}.
+
+On success, the returned option field class has the following property
+values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
+ <td>\bt_p{optional_field_class}
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
+ <td>
+ \em None (this property becomes available when the returned field
+ class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-sint-rs "Selector's signed integer ranges"
+ <td>\bt_p{ranges}
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create an option field class.
+@param[in] optional_field_class
+ Class of the optional fields of the instances of the option field
+ class to create.
+@param[in] selector_field_class
+ Linked selector field class of the option field class to create.
+@param[in] ranges
+ Selector's signed integer ranges of the option field class to
+ create.
+
+@returns
+ New option field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_not_null{optional_field_class}
+@bt_pre_fc_not_in_tc{optional_field_class}
+@bt_pre_not_null{selector_field_class}
+@pre
+ \bt_p{selector_field_class} is a \bt_uint_fc.
+@bt_pre_not_null{ranges}
+@pre
+ \bt_p{ranges} contains one or more \bt_p_uint_rg.
+
+@bt_post_success_frozen{optional_field_class}
+@bt_post_success_frozen{selector_field_class}
+@bt_post_success_frozen{ranges}
+*/
+extern bt_field_class *
+bt_field_class_option_with_selector_field_integer_signed_create(
+ bt_trace_class *trace_class,
+ bt_field_class *optional_field_class,
+ bt_field_class *selector_field_class,
+ const bt_integer_range_set_signed *ranges);
+
+/*!
+@brief
+ Borrows the \bt_p_sint_rg from the \bt_opt_fc (with a signed
+ integer selector field) \bt_p{field_class}.