X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace2%2Ftrace-ir%2Ffield-class.h;h=0aab9682e0383d637775763fd3e65153153010b1;hp=e8be1c51e75d1394ff670e682599da2e3874365b;hb=43c59509042845f8d42c3e99ec74d45fa2dc0908;hpb=1cda4ff4025e4b3f7bd2a861baa51d2113c4cbf9 diff --git a/include/babeltrace2/trace-ir/field-class.h b/include/babeltrace2/trace-ir/field-class.h index e8be1c51..0aab9682 100644 --- a/include/babeltrace2/trace-ir/field-class.h +++ b/include/babeltrace2/trace-ir/field-class.h @@ -31,188 +31,4590 @@ #include #include -#include #ifdef __cplusplus extern "C" { #endif +/*! +@defgroup api-tir-fc Field classes +@ingroup api-tir + +@brief + Classes of \bt_p_field. + +Field classes are the classes of \bt_p_field: + +@image html field-class-zoom.png + +Field classes are \ref api-tir "trace IR" metadata objects. + +There are many types of field classes. They can be divided into two main +categories: + +
+
Scalar
+
+ Classes of fields which contain a simple value. + + The scalar field classes are: + + - \ref api-tir-fc-bool "Boolean" + - \ref api-tir-fc-ba "Bit array" + - \ref api-tir-fc-int "Integer" (unsigned and signed) + - \ref api-tir-fc-enum "Enumeration" (unsigned and signed) + - \ref api-tir-fc-real "Real" (single-precision and double-precision) + - \ref api-tir-fc-string "String" +
+ +
Container
+
+ Classes of fields which contain other fields. + + The container field classes are: + + - \ref api-tir-fc-array "Array" (static and dynamic) + - \ref api-tir-fc-struct "Structure" + - \ref api-tir-fc-opt "Option" + - \ref api-tir-fc-var "Variant" +
+
+ +@image html fc-to-field.png "Fields (green) are instances of field classes (orange)." + +Some field classes conceptually inherit other field classes, eventually +making an inheritance hierarchy. For example, a \bt_sarray_fc +\em is an array field class. Therefore, a static array field class has +any property that an array field class has. + +The complete field class inheritance hierarchy is: + +@image html all-field-classes.png + +In the illustration above: + +- You can create any field class with a dark background with + a dedicated bt_field_class_*_create() function. + +- A field class with a pale background is an \em abstract field class: + you cannot create it, but it has properties, therefore there are + functions which apply to it. + + For example, bt_field_class_integer_set_preferred_display_base() + applies to any \bt_int_fc. + +Field classes are \ref api-fund-shared-object "shared objects": get a +new reference with bt_field_class_get_ref() and put an existing +reference with bt_field_class_put_ref(). + +Some library functions \ref api-fund-freezing "freeze" field classes on +success. The documentation of those functions indicate this +postcondition. + +All the field class types share the same C type, #bt_field_class. + +Get the type enumerator of a field class with bt_field_class_get_type(). +Get whether or not a field class type conceptually \em is a given type +with the inline bt_field_class_type_is() function. + +The following table shows the available type enumerators and creation +functions for each type of \em concrete (non-abstract) field class: + + + + + + + + + + + + + + + + + + + + + + + +
Name + Type enumerator + Creation function +
\ref api-tir-fc-bool "Boolean" + #BT_FIELD_CLASS_TYPE_BOOL + bt_field_class_bool_create() +
\ref api-tir-fc-ba "Bit array" + #BT_FIELD_CLASS_TYPE_BIT_ARRAY + bt_field_class_bit_array_create() +
Unsigned \ref api-tir-fc-int "integer" + #BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER + bt_field_class_integer_unsigned_create() +
Signed \ref api-tir-fc-int "integer" + #BT_FIELD_CLASS_TYPE_SIGNED_INTEGER + bt_field_class_integer_signed_create() +
Unsigned \ref api-tir-fc-enum "enumeration" + #BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION + bt_field_class_enumeration_unsigned_create() +
Signed \ref api-tir-fc-enum "enumeration" + #BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION + bt_field_class_enumeration_signed_create() +
Single-precision \ref api-tir-fc-real "real" + #BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL + bt_field_class_real_single_precision_create() +
Double-precision \ref api-tir-fc-real "real" + #BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL + bt_field_class_real_double_precision_create() +
\ref api-tir-fc-string "String" + #BT_FIELD_CLASS_TYPE_STRING + bt_field_class_string_create() +
Static \ref api-tir-fc-array "array" + #BT_FIELD_CLASS_TYPE_STATIC_ARRAY + bt_field_class_array_static_create() +
Dynamic \ref api-tir-fc-array "array" (no length field) + #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD + bt_field_class_array_dynamic_create() +
Dynamic \ref api-tir-fc-array "array" (with length field) + #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD + bt_field_class_array_dynamic_create() +
\ref api-tir-fc-struct "Structure" + #BT_FIELD_CLASS_TYPE_STRUCTURE + bt_field_class_structure_create() +
\ref api-tir-fc-opt "Option" (no selector field) + #BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD + bt_field_class_option_without_selector_create() +
\ref api-tir-fc-opt "Option" (boolean selector field) + #BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD + bt_field_class_option_with_selector_field_bool_create() +
\ref api-tir-fc-opt "Option" (unsigned integer selector field) + #BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD + bt_field_class_option_with_selector_field_integer_unsigned_create() +
\ref api-tir-fc-opt "Option" (signed integer selector field) + #BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD + bt_field_class_option_with_selector_field_integer_signed_create() +
\ref api-tir-fc-var "Variant" (no selector field) + #BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD + bt_field_class_variant_create() +
\ref api-tir-fc-var "Variant" (unsigned integer selector field) + #BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD + bt_field_class_variant_create() +
\ref api-tir-fc-var "Variant" (signed integer selector field) + #BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD + bt_field_class_variant_create() +
+ +You need a \bt_trace_cls to create a field class: create one from a +\bt_self_comp with bt_trace_class_create(). + +Outside the field class API, you can use field classes at four +locations, called scopes, within the trace IR API: + +- To set the packet context field class of a \bt_stream_cls with + bt_stream_class_set_packet_context_field_class(). + +- To set the event common context field class of a stream class with + bt_stream_class_set_event_common_context_field_class(). + +- To set the specific context field class of an \bt_ev_cls with + bt_event_class_set_specific_context_field_class(). + +- To set the payload field class of an event class with + bt_event_class_set_payload_field_class(). + +When you call one of the four functions above: + +- The passed field class must be a \bt_struct_fc. + +- You must \em not have already called any of the four functions above + with the passed field class or with any of its contained field + classes. + +- If any of the field classes recursively contained in the passed + field class has a \ref api-tir-fc-link "link to another field class", + it must honor the field class link rules. + +Once you have called one of the four functions above, the passed field +class becomes \ref api-fund-freezing "frozen". + +

Common field class property

+ +A field class has the following common property: + +
+
+ \anchor api-tir-fc-prop-user-attrs + \bt_dt_opt User attributes +
+
+ User attributes of the field class. + + User attributes are custom attributes attached to a field class. + + Use bt_field_class_set_user_attributes(), + bt_field_class_borrow_user_attributes(), and + bt_field_class_borrow_user_attributes_const(). +
+
+ +

\anchor api-tir-fc-bool Boolean field class

+ +@image html fc-bool.png + +A boolean field class is the class +of \bt_p_bool_field. + +A boolean field contains a boolean value (#BT_TRUE or #BT_FALSE). + +Create a boolean field class with bt_field_class_bool_create(). + +A boolean field class has no specific properties. + +

\anchor api-tir-fc-ba Bit array field class

+ +@image html fc-ba.png + +A bit array field class is the class +of \bt_p_ba_field. + +A bit array field contains a fixed-length array of bits. + +Create a bit array field class with bt_field_class_bit_array_create(). + +A bit array field class has the following property: + +
+
+ \anchor api-tir-fc-ba-prop-len + Length +
+
+ Number of bits contained in the instances (bit array fields) of + the bit array field class. + + As of \bt_name_version_min_maj, the maximum length of a bit array + field is 64. + + You cannot change the length once the bit array field class is + created. + + Get a bit array field class's length with + bt_field_class_bit_array_get_length(). +
+
+ +

\anchor api-tir-fc-int Integer field classes

+ +@image html fc-int.png + +Integer field classes are classes +of \bt_p_int_field. + +Integer fields contain integral values. + +An integer field class is an \em abstract field class: you cannot create +one. The concrete integer field classes are: + +
+
Unsigned integer field class
+
+ Its instances (unsigned integer fields) contain an unsigned integral + value (\c uint64_t). + + Create with bt_field_class_integer_unsigned_create(). +
+ +
Signed integer field class
+
+ Its instances (signed integer fields) contain a signed integral + value (\c int64_t). + + Create with bt_field_class_integer_signed_create(). +
+
+ +Integer field classes have the following common properties: + +
+
+ \anchor api-tir-fc-int-prop-size + Field value range +
+
+ Expected range of values that the instances (integer fields) + of the integer field class can contain. + + For example, if the field value range of an unsigned integer + field class is [0, 16383], then its unsigned integer fields + can only contain the values from 0 to 16383. + + \bt_cp_sink_comp can benefit from this property to make some space + optimizations when writing trace data. + + Use bt_field_class_integer_set_field_value_range() and + bt_field_class_integer_get_field_value_range(). +
+ +
+ \anchor api-tir-fc-int-prop-base + Preferred display base +
+
+ Preferred base (2, 8, 10, or 16) to use when displaying the + instances (integer fields) of the integer field class. + + Use bt_field_class_integer_set_preferred_display_base() and + bt_field_class_integer_get_preferred_display_base(). +
+
+ +

\anchor api-tir-fc-enum Enumeration field classes

+ +@image html fc-enum.png + +Enumeration field classes are classes +of \bt_p_enum_field. + +Enumeration field classes \em are \bt_p_int_fc: they have the integer +field classes properties. + +Enumeration fields \em are integer fields: they contain integral values. + +Enumeration field classes associate labels (strings) to specific +ranges of integral values. This association is called an enumeration +field class mapping. + +For example, if an enumeration field class maps the label \c SUGAR to +the integer ranges [1, 19] and [25, 31], then an instance +(enumeration field) of this field class with the value 15 or 28 has the +label SUGAR. + +An enumeration field class is an \em abstract field class: you cannot +create one. The concrete enumeration field classes are: + +
+
Unsigned enumeration field class
+
+ Its instances (unsigned enumeration fields) contain an unsigned + value (\c uint64_t). + + Create with bt_field_class_enumeration_unsigned_create(). +
+ +
Signed enumeration field class
+
+ Its instances (signed enumeration fields) contain a signed value + (\c int64_t). + + Create with bt_field_class_enumeration_signed_create(). +
+
+ +Enumeration field classes have the following common property: + +
+
+ \anchor api-tir-fc-enum-prop-mappings + Mappings +
+
+ Set of mappings of the enumeration field class. + + An enumeration field class mapping is a label (string) and an + \bt_int_rs. + + The integer ranges of a given mapping or of multiple mappings of + the same enumeration field class can overlap. For example, + an enumeration field class can have those two mappings: + + - CALORIES: [1, 11], [15, 37] + - SODIUM: [7, 13] + + In that case, the values 2 and 30 correpond to the label + CALORIES, the value 12 to the label + SODIUM, and the value 10 to the labels + \c CALORIES \em and SODIUM. + + Two mappings of the same enumeration field class cannot have the + same label. + + Add a mapping to an enumeration field class with + bt_field_class_enumeration_unsigned_add_mapping() or + bt_field_class_enumeration_signed_add_mapping(). + + Get the number of mappings in an enumeration field class with + bt_field_class_enumeration_get_mapping_count(). + + Borrow a mapping from an enumeration field class with + bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const(), + bt_field_class_enumeration_signed_borrow_mapping_by_index_const(), + bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const(), + and + bt_field_class_enumeration_signed_borrow_mapping_by_label_const(). + + An enumeration field class mapping is a + \ref api-fund-unique-object "unique object": it + belongs to the enumeration field class which contains it. + + There are two enumeration field class mapping types, depending on + the field class's type: + #bt_field_class_enumeration_unsigned_mapping and + #bt_field_class_enumeration_signed_mapping. + + There is also the #bt_field_class_enumeration_mapping type for + common properties and operations (for example, + bt_field_class_enumeration_mapping_get_label()). + \ref api-fund-c-typing "Upcast" a specific enumeration field class + mapping to the #bt_field_class_enumeration_mapping type with + bt_field_class_enumeration_unsigned_mapping_as_mapping_const() or + bt_field_class_enumeration_signed_mapping_as_mapping_const(). + + Get all the enumeration field class labels mapped to a given integer + value with + bt_field_class_enumeration_unsigned_get_mapping_labels_for_value() + and + bt_field_class_enumeration_signed_get_mapping_labels_for_value(). +
+
+ +

\anchor api-tir-fc-real Real field classes

+ +@image html fc-real.png + +Real field classes are classes +of \bt_p_real_field. + +Real fields contain +real +values (\c float or \c double types). + +A real field class is an \em abstract field class: you cannot create +one. The concrete real field classes are: + +
+
Single-precision real field class
+
+ Its instances (single-precision real fields) contain a \c float + value. + + Create with bt_field_class_real_single_precision_create(). +
+ +
Double-precision real field class
+
+ Its instances (double-precision real fields) contain a \c double + value. + + Create with bt_field_class_real_double_precision_create(). +
+
+ +Real field classes have no specific properties. + +

\anchor api-tir-fc-string String field class

+ +@image html fc-string.png + +A string field class is the class +of \bt_p_string_field. + +A string field contains an UTF-8 string value. + +Create a string field class with bt_field_class_string_create(). + +A string field class has no specific properties. + +

\anchor api-tir-fc-array Array field classes

+ +@image html fc-array.png + +Array field classes are classes +of \bt_p_array_field. + +Array fields contain zero or more fields which have the same class. + +An array field class is an \em abstract field class: you cannot create +one. The concrete array field classes are: + +
+
Static array field class
+
+ Its instances (static array fields) contain a fixed number of + fields. + + Create with bt_field_class_array_static_create(). + + A static array field class has the following specific property: + +
+
+ \anchor api-tir-fc-sarray-prop-len + Length +
+
+ Number of fields contained in the instances (static array + fields) of the static array field class. + + You cannot change the length once the static array field class + is created. + + Get a static array field class's length with + bt_field_class_array_static_get_length(). +
+
+
+ +
Dynamic array field class
+
+ Its instances (dynamic array fields) contain a variable number array + of fields. + + There are two types of dynamic array field classes: without or + with a length field. See + \ref api-tir-fc-link "Field classes with links to other field classes" + to learn more. + + @image html darray-link.png "Dynamic array field class with a length field." + + Create with bt_field_class_array_dynamic_create(). + + A dynamic array field class with a length field has the + specific property: + +
+
+ \anchor api-tir-fc-darray-prop-len-fp + Length field path +
+
+ Field path of the linked length field class. + + Get a dynamic array field class's length field path with + bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(). +
+
+
+
+ +Array field classes have the following common property: + +
+
+ \anchor api-tir-fc-array-prop-elem-fc + Element field class +
+
+ Class of the fields contained in the instances (array fields) of the + array field class. + + You cannot change the element field class once the array field class + is created. + + Borrow an array field class's element field class with + Use bt_field_class_array_borrow_element_field_class() and + bt_field_class_array_borrow_element_field_class_const(). +
+
+ +

\anchor api-tir-fc-struct Structure field class

+ +@image html fc-struct.png + +A structure field class is the class +of a \bt_struct_field. + +A structure field contains an ordered list of zero or more members. Each +structure field member is the instance of a structure field class +member. A structure field class member has a name, a field class, +and user attributes. + +Create a structure field class with bt_field_class_structure_create(). + +A structure field class has the following specific property: + +
+
+ \anchor api-tir-fc-struct-prop-members + Members +
+
+ Ordered list of members (zero or more) of the structure field class. + + Each member has: + + - A name, unique amongst all the member names of the same + structure field class. + - A field class. + - User attributes. + + The instances (structure fields) of a structure field class have + members which are instances of the corresponding structure field + class members. + + Append a member to a structure field class with + bt_field_class_structure_append_member(). + + Borrow a member from a structure field class with + bt_field_class_structure_borrow_member_by_index(), + bt_field_class_structure_borrow_member_by_name(), + bt_field_class_structure_borrow_member_by_index_const(), and + bt_field_class_structure_borrow_member_by_name_const(). + + A structure field class member is a + \ref api-fund-unique-object "unique object": it + belongs to the structure field class which contains it. + + The type of a structure field class member is + #bt_field_class_structure_member. + + Get a structure field class member's name with + bt_field_class_structure_member_get_name(). + + Borrow a structure field class member's field class with + bt_field_class_structure_member_borrow_field_class() and + bt_field_class_structure_member_borrow_field_class_const(). + + Set a structure field class member's user attributes with + bt_field_class_structure_member_set_user_attributes(). + + Borrow a structure field class member's user attributes with + bt_field_class_structure_member_borrow_user_attributes() and + bt_field_class_structure_member_borrow_user_attributes_const(). +
+
+ +

\anchor api-tir-fc-opt Option field classes

+ +@image html fc-opt.png + +Option field classes are classes +of \bt_p_opt_field. + +An option field either does or doesn't contain a field, called its +optional field. + +An option field class is an \em abstract field class: you cannot create +one. An option field class either has a selector field (it's linked to a +selector field class; see +\ref api-tir-fc-link "Field classes with links to other field classes") +or none. Therefore, the concrete option field classes are: + +
+
Option field class without a selector field
+
+ Create with bt_field_class_option_without_selector_create(). + + An option field class without a selector field has no specific + properties. +
+ +
Option field class with a boolean selector field
+
+ The linked selector field of an option field class's instance + (an option field) is a \bt_bool_field. + + Consequently, the option field class's selector field class is + a \bt_bool_fc. + + @image html opt-link.png "Option field class with a boolean selector field." + + Create with bt_field_class_option_with_selector_field_bool_create(). + + An option field class with a boolean selector field has the + following specific property: + +
+
+ \anchor api-tir-fc-opt-prop-sel-rev + Selector is reversed? +
+
+ Whether or not the linked boolean selector field makes the + option field class's instance (an option field) contain a field + when it's #BT_TRUE or when it's #BT_FALSE. + + If this property is #BT_TRUE, then if the linked selector field + has the value #BT_FALSE, the option field contains a field. + + Use + bt_field_class_option_with_selector_field_bool_set_selector_is_reversed() + and + bt_field_class_option_with_selector_field_bool_selector_is_reversed(). +
+
+
+ +
Option field class with an unsigned selector field
+
+ The linked selector field of an option field class's instance + (an option field) is an \bt_uint_field. + + Consequently, the option field class's selector field class is + an \bt_uint_fc. + + Create with + bt_field_class_option_with_selector_field_integer_unsigned_create(). + + Pass an \bt_uint_rs on creation to set which values of the selector + field can make the option field contain a field. + + An option field class with an unsigned integer selector field has + the following specific property: + +
+
+ \anchor api-tir-fc-opt-prop-uint-rs + Selector's unsigned integer ranges +
+
+ If the linked unsigned integer selector field of an option + field class's instance (an option field) has a value which + intersects with the selector's unsigned integer ranges, then + the option field contains a field. + + You cannot change the selector's unsigned integer ranges once + the option field class is created. + + Borrow the selector's unsigned integer ranges from an + option field class with an unsigned integer selector field with + bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const(). +
+
+
+ +
Option field class with a signed selector field
+
+ The linked selector field of an option field class's instance + (an option field) is a \bt_sint_field. + + Consequently, the option field class's selector field class is + a \bt_sint_fc. + + Create with + bt_field_class_option_with_selector_field_integer_signed_create(). + + Pass a \bt_sint_rs on creation to set which values of the selector + field can make the option field contain a field. + + An option field class with a signed integer selector field has + the following specific property: + +
+
+ \anchor api-tir-fc-opt-prop-sint-rs + Selector's signed integer ranges +
+
+ If the linked signed integer selector field of an option + field class's instance (an option field) has a value which + intersects with the selector's signed integer ranges, then + the option field contains a field. + + You cannot change the selector's signed integer ranges once + the option field class is created. + + Borrow the selector's signed integer ranges from an + option field class with a signed integer selector field with + bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const(). +
+
+
+
+ +Option field classes with a selector have the following common +property: + +
+
+ \anchor api-tir-fc-opt-prop-sel-fp + Selector field path +
+
+ Field path of the linked selector field class. + + Borrow such an option field class's selector field path with + bt_field_class_option_with_selector_field_borrow_selector_field_path_const(). +
+
+ +Option field classes have the following common property: + +
+
+ \anchor api-tir-fc-opt-prop-fc + Optional field class +
+
+ Class of the optional field of an instance (option field) of the + option field class. + + You cannot change the optional field class once the option field + class is created. + + Borrow an option field class's optional field class with + Use bt_field_class_option_borrow_field_class() and + bt_field_class_option_borrow_field_class_const(). +
+
+ +

\anchor api-tir-fc-var Variant field classes

+ +@image html fc-var.png + +Variant field classes are classes +of \bt_p_var_field. + +A variant field contains a field amongst one or more possible fields. + +Variant field classes contain one or more options. Each variant field +class option has a name, a field class, user attributes, and integer +ranges, depending on the exact type. + +A variant field class is an \em abstract field class: you cannot create +one. A variant field class either has a selector field (it's linked to a +selector field class; see +\ref api-tir-fc-link "Field classes with links to other field classes") +or none. Therefore, the concrete variant field classes are: + +
+
Variant field class without a selector field
+
+ Create with bt_field_class_variant_create(), passing \c NULL as + the selector field class. + + Append an option to such a variant field class with + bt_field_class_variant_without_selector_append_option(). + + A variant field class without a selector field has no specific + properties. +
+ +
Variant field class with an unsigned selector field
+
+ The linked selector field of a variant field class's instance + (a variant field) is an \bt_uint_field. + + Consequently, the variant field class's selector field class is + an \bt_uint_fc. + + @image html var-link.png "Variant field class with an unsigned integer selector field." + + Create with bt_field_class_variant_create(), passing an + unsigned integer field class as the selector field class. + + Append an option to such a variant field class with + bt_field_class_variant_with_selector_field_integer_unsigned_append_option(). + + Pass an \bt_uint_rs when you append an option to set which values of + the selector field can make the variant field have a given + current option. + + Borrow such a variant field class's option with + bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const() + and + bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(). +
+ +
Variant field class with a signed selector field
+
+ The linked selector field of a variant field class's instance + (a variant field) is a \bt_sint_field. + + Consequently, the variant field class's selector field class is + a \bt_sint_fc. + + Create with bt_field_class_variant_create(), passing a + signed integer field class as the selector field class. + + Append an option to such a variant field class with + bt_field_class_variant_with_selector_field_integer_signed_append_option(). + + Pass a \bt_sint_rs when you append an option to set which values of + the selector field can make the variant field have a given + current option. + + Borrow such a variant field class's option with + bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const() + and + bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const(). +
+
+ +Variant field classes with a selector have the following common +property: + +
+
+ \anchor api-tir-fc-var-prop-sel-fp + Selector field path +
+
+ Field path of the linked selector field class. + + Borrow such a variant field class's selector field path with + bt_field_class_variant_with_selector_field_borrow_selector_field_path_const(). +
+
+ +Variant field classes have the following common property: + +
+
+ \anchor api-tir-fc-var-prop-opts + Options +
+
+ Options of the variant field class. + + Each option has: + + - A name, unique amongst all the option names of the same + variant field class. + - A field class. + - User attributes. + + If the variant field class is linked to a selector field class, then + each option also has an \bt_int_rs. In that case, the ranges of a + given option cannot overlap any range of any other option. + + A variant field class must contain at least one option. + + Depending on whether or not the variant field class has a selector + field class, append an option to a variant field class + with bt_field_class_variant_without_selector_append_option(), + bt_field_class_variant_with_selector_field_integer_unsigned_append_option(), + or + bt_field_class_variant_with_selector_field_integer_signed_append_option(). + + Get the number of options contained in a variant field class + with bt_field_class_variant_get_option_count(). + + A variant field class option is a + \ref api-fund-unique-object "unique object": it + belongs to the variant field class which contains it. + + Borrow any variant field class's option with + bt_field_class_variant_borrow_option_by_index(), + bt_field_class_variant_borrow_option_by_name(), + bt_field_class_variant_borrow_option_by_index_const(), and + bt_field_class_variant_borrow_option_by_name_const(). + + Those functions return the common #bt_field_class_variant_option + type. Get the name of a variant field class option with + bt_field_class_variant_option_get_name(). Borrow a variant field + class option's field class with + bt_field_class_variant_option_borrow_field_class() and + bt_field_class_variant_option_borrow_field_class_const(). + + Borrow the option of a variant field classes with a selector field + class with + bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(), + bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(), + bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(), or + bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const(), + depending on the selector field class's type. + + Those functions return the + #bt_field_class_variant_with_selector_field_integer_unsigned_option or + #bt_field_class_variant_with_selector_field_integer_signed_option type. + \ref api-fund-c-typing "Upcast" those types to the + #bt_field_class_variant_option type with + bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const() + or + bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const(). + + Borrow the option's ranges from a variant field class with a + selector field class with + bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const() + or + bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const(). + + Set a variant field class option's user attributes with + bt_field_class_variant_option_set_user_attributes(). + + Borrow a variant field class option's user attributes with + bt_field_class_variant_option_borrow_user_attributes() and + bt_field_class_variant_option_borrow_user_attributes_const(). +
+
+ +

\anchor api-tir-fc-link Field classes with links to other field classes

+ +\bt_cp_darray_fc, \bt_p_opt_fc, and \bt_p_var_fc \em can have links to +other, preceding field classes. + +When a field class A has a link to another field class B, then +an instance (\bt_field) of A has a link to an instance of B. + +This feature exists so that the linked field can contain the value of a +dynamic property of the field. Those properties are: + +
+
\bt_c_darray_field
+
+ The linked field, a \bt_uint_field, contains the \b length of the + dynamic array field. +
+ +
\bt_c_opt_field
+
+ The linked field, either a \bt_bool_field or an \bt_int_field, + indicates whether or not the option field has a field. +
+ +
\bt_c_var_field
+
+ The linked field, an \bt_int_field, indicates the variant field's + current selected field. +
+
+ +Having a linked field class is optional: you always set the +field properties with a dedicated function anyway. For example, even if +a dynamic array field is linked to a preceding length field, you must +still set its length with bt_field_array_dynamic_set_length(). In that +case, the value of the length field must match what you pass to +bt_field_array_dynamic_set_length(). + +The purpose of this feature is to eventually save space when a +\bt_sink_comp writes trace files: if the trace format can convey that +a preceding, existing field represents the length of a dynamic array +field, then the sink component doesn't need to write the dynamic array +field's length twice. This is the case of the +Common Trace Format, for +example. + +@image html darray-link.png "A dynamic array field class linked to an unsigned integer field class." + +To link a field class A to a preceding field class B, pass +field class B when you create field class A. For example, pass +the \bt_uint_fc to bt_field_class_array_dynamic_create() to create a +\bt_darray_fc with a length field. + +When you call 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(), or +bt_event_class_set_payload_field_class() with a field class containing +a field class A with a linked field class B, the path to +B becomes available in A. The functions to borrow this field path are: + +- 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() +- bt_field_class_variant_with_selector_field_borrow_selector_field_path_const() + +A field path indicates how to reach a linked field from a given +root scope. The available scopes are: + +
+
#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT
+
+ Packet context field. + + See bt_packet_borrow_context_field_const(). +
+ +
#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT
+
+ Event common context field. + + See bt_event_borrow_common_context_field_const(). +
+ +
#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT
+
+ Event specific context field. + + See bt_event_borrow_specific_context_field_const(). +
+ +
#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD
+
+ Event payload field. + + See bt_event_borrow_payload_field_const(). +
+
+ +The rules regarding field class A vs. field class B (linked +field class) are: + +- If A is within a packet context field class, B must also be in the + same packet context field class. + + See bt_stream_class_set_packet_context_field_class(). + +- If A is within a event common context field class, B must be in one + of: + + - The same event common context field class. + - The packet context field class of the same \bt_stream_cls. + + See bt_stream_class_set_event_common_context_field_class(). + +- If A is within an event specific context field class, B must be in + one of: + + - The same event specific context field class. + - The event common context field class of the same stream class. + - The packet context field class of the same stream class. + + See bt_event_class_set_specific_context_field_class(). + +- If A is within an event payload field class, B must be in one of: + + - The same event payload field class. + - The event specific context field class of the same \bt_ev_cls. + - The event common context field class of the same stream class. + - The packet context field class of the same stream class. + + See bt_event_class_set_payload_field_class(). + +- If both A and B are in the same scope, then: + + - The lowest common ancestor field class of A and B must be a + \bt_struct_fc. + + - B must precede A. + + Considering that the members of a structure field class are ordered, + then B must be part of a member that's before the member which + contains A in their lowest common ancestor structure field class. + + - The path from the lowest common ancestor structure field class of A + and B to A and to B must only contain structure field classes. + +- If A is in a different scope than B, the path from the root scope of B + to B must only contain structure field classes. +*/ + +/*! @{ */ + +/*! +@name Type +@{ + +@typedef struct bt_field_class bt_field_class; + +@brief + Field class. + +@} +*/ + +/*! +@name Type query +@{ +*/ + +/*! +@brief + Field class type enumerators. +*/ +typedef enum bt_field_class_type { + /*! + @brief + \bt_c_bool_fc. + */ + BT_FIELD_CLASS_TYPE_BOOL = 1ULL << 0, + + /*! + @brief + \bt_c_ba_fc. + */ + BT_FIELD_CLASS_TYPE_BIT_ARRAY = 1ULL << 1, + + /*! + @brief + \bt_c_int_fc. + + No field class has this type: use it with + bt_field_class_type_is(). + */ + BT_FIELD_CLASS_TYPE_INTEGER = 1ULL << 2, + + /*! + @brief + \bt_c_uint_fc. + + This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER. + */ + BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER = (1ULL << 3) | BT_FIELD_CLASS_TYPE_INTEGER, + + /*! + @brief + \bt_c_sint_fc. + + This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER. + */ + BT_FIELD_CLASS_TYPE_SIGNED_INTEGER = (1ULL << 4) | BT_FIELD_CLASS_TYPE_INTEGER, + + /*! + @brief + \bt_c_enum_fc. + + This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER. + + No field class has this type: use it with + bt_field_class_type_is(). + */ + BT_FIELD_CLASS_TYPE_ENUMERATION = 1ULL << 5, + + /*! + @brief + \bt_c_uenum_fc. + + This type conceptually inherits #BT_FIELD_CLASS_TYPE_ENUMERATION + and #BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER. + */ + BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION = BT_FIELD_CLASS_TYPE_ENUMERATION | BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER, + + /*! + @brief + \bt_c_senum_fc. + + This type conceptually inherits #BT_FIELD_CLASS_TYPE_ENUMERATION + and #BT_FIELD_CLASS_TYPE_SIGNED_INTEGER. + */ + BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION = BT_FIELD_CLASS_TYPE_ENUMERATION | BT_FIELD_CLASS_TYPE_SIGNED_INTEGER, + + /*! + @brief + \bt_c_real_fc. + + No field class has this type: use it with + bt_field_class_type_is(). + */ + BT_FIELD_CLASS_TYPE_REAL = 1ULL << 6, + + /*! + @brief + Single-precision \bt_real_fc. + + This type conceptually inherits #BT_FIELD_CLASS_TYPE_REAL. + */ + BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL = (1ULL << 7) | BT_FIELD_CLASS_TYPE_REAL, + + /*! + @brief + Double-precision \bt_real_fc. + + This type conceptually inherits #BT_FIELD_CLASS_TYPE_REAL. + */ + BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL = (1ULL << 8) | BT_FIELD_CLASS_TYPE_REAL, + + /*! + @brief + \bt_c_string_fc.. + */ + BT_FIELD_CLASS_TYPE_STRING = 1ULL << 9, + + /*! + @brief + \bt_c_struct_fc. + */ + BT_FIELD_CLASS_TYPE_STRUCTURE = 1ULL << 10, + + /*! + @brief + \bt_c_array_fc. + + No field class has this type: use it with + bt_field_class_type_is(). + */ + BT_FIELD_CLASS_TYPE_ARRAY = 1ULL << 11, + + /*! + @brief + \bt_c_sarray_fc. + + This type conceptually inherits #BT_FIELD_CLASS_TYPE_ARRAY. + */ + BT_FIELD_CLASS_TYPE_STATIC_ARRAY = (1ULL << 12) | BT_FIELD_CLASS_TYPE_ARRAY, + + /*! + @brief + \bt_c_darray_fc. + + This type conceptually inherits #BT_FIELD_CLASS_TYPE_ARRAY. + + No field class has this type: use it with + bt_field_class_type_is(). + */ + BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY = (1ULL << 13) | BT_FIELD_CLASS_TYPE_ARRAY, + + /*! + @brief + \bt_c_darray_fc (without a length field). + + This type conceptually inherits + #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY. + */ + BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD = (1ULL << 14) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY, + + /*! + @brief + \bt_c_darray_fc (with a length field). + + This type conceptually inherits + #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY. + */ + BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD = (1ULL << 15) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY, + + /*! + @brief + \bt_c_opt_fc. + + No field class has this type: use it with + bt_field_class_type_is(). + */ + BT_FIELD_CLASS_TYPE_OPTION = 1ULL << 16, + + /*! + @brief + \bt_c_opt_fc (without a selector field). + */ + BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD = (1ULL << 17) | BT_FIELD_CLASS_TYPE_OPTION, + + /*! + @brief + \bt_c_opt_fc (with a selector field). + + This type conceptually inherits #BT_FIELD_CLASS_TYPE_OPTION. + + No field class has this type: use it with + bt_field_class_type_is(). + */ + BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD = (1ULL << 18) | BT_FIELD_CLASS_TYPE_OPTION, + + /*! + @brief + \bt_c_opt_fc (with a boolean selector field). + + This type conceptually inherits + #BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD. + */ + BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD = (1ULL << 19) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD, + + /*! + @brief + \bt_c_opt_fc (with an integer selector field). + + This type conceptually inherits + #BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD. + + No field class has this type: use it with + bt_field_class_type_is(). + */ + BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD = (1ULL << 20) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD, + + /*! + @brief + \bt_c_opt_fc (with an unsigned integer selector field). + + This type conceptually inherits + #BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD. + */ + BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD = (1ULL << 21) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD, + + /*! + @brief + \bt_c_opt_fc (with a signed integer selector field). + + This type conceptually inherits + #BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD. + */ + BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD = (1ULL << 22) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD, + + /*! + @brief + \bt_c_var_fc. + + No field class has this type: use it with + bt_field_class_type_is(). + */ + BT_FIELD_CLASS_TYPE_VARIANT = 1ULL << 23, + + /*! + @brief + \bt_c_var_fc (without a selector field). + */ + BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD = (1ULL << 24) | BT_FIELD_CLASS_TYPE_VARIANT, + + /*! + @brief + \bt_c_var_fc (with a selector field). + + This type conceptually inherits + #BT_FIELD_CLASS_TYPE_VARIANT. + + No field class has this type: use it with + bt_field_class_type_is(). + */ + BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD = (1ULL << 25) | BT_FIELD_CLASS_TYPE_VARIANT, + + /*! + @brief + \bt_c_var_fc (with an integer selector field). + + This type conceptually inherits + #BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD. + + No field class has this type: use it with + bt_field_class_type_is(). + */ + BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD = (1ULL << 26) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD, + + /*! + @brief + \bt_c_opt_fc (with an unsigned integer selector field). + + This type conceptually inherits + #BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD. + */ + BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD = (1ULL << 27) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD, + + /*! + @brief + \bt_c_opt_fc (with a signed integer selector field). + + This type conceptually inherits + #BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD. + */ + BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD = (1ULL << 28) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD, + + /* + * Make sure the enumeration type is a 64-bit integer in case + * the project needs field class types in the future. + * + * This is not part of the API. + */ + __BT_FIELD_CLASS_TYPE_BIG_VALUE = 1ULL << 62, +} bt_field_class_type; + +/*! +@brief + Returns the type enumerator of the field class \bt_p{field_class}. + +@param[in] field_class + Field class of which to get the type enumerator + +@returns + Type enumerator of \bt_p{field_class}. + +@bt_pre_not_null{field_class} + +@sa bt_field_class_type_is() — + Returns whether or not the type of a field class conceptually is a + given type. +*/ +extern bt_field_class_type bt_field_class_get_type( + const bt_field_class *field_class); + +/*! +@brief + Returns whether or not the field class type \bt_p{type} conceptually + \em is the field class type \bt_p{other_type}. + +For example, an \bt_uint_fc conceptually \em is an integer field class, +so + +@code +bt_field_class_type_is(BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER, BT_FIELD_CLASS_TYPE_INTEGER) +@endcode + +returns #BT_TRUE. + +@param[in] type + Field class type to check against \bt_p{other_type}. +@param[in] other_type + Field class type against which to check \bt_p{type}. + +@returns + #BT_TRUE if \bt_p{type} conceptually \em is \bt_p{other_type}. + +@sa bt_field_class_get_type() — + Returns the type enumerator of a field class. +*/ +static inline +bt_bool bt_field_class_type_is(const bt_field_class_type type, + const bt_field_class_type other_type) +{ + return (type & other_type) == other_type; +} + +/*! @} */ + +/*! +@name Common property +@{ +*/ + +/*! +@brief + Sets the user attributes of the field class \bt_p{field_class} to + \bt_p{user_attributes}. + +See the \ref api-tir-fc-prop-user-attrs "user attributes" property. + +@note + When you create a field class with one of the + bt_field_class_*_create() functions, the field class's + initial user attributes is an empty \bt_map_val. Therefore you can + borrow it with bt_field_class_borrow_user_attributes() and fill it + directly instead of setting a new one with this function. + +@param[in] field_class + Field class of which to set the user attributes to + \bt_p{user_attributes}. +@param[in] user_attributes + New user attributes of \bt_p{field_class}. + +@bt_pre_not_null{field_class} +@bt_pre_hot{field_class} +@bt_pre_not_null{user_attributes} +@bt_pre_is_map_val{user_attributes} + +@sa bt_field_class_borrow_user_attributes() — + Borrows the user attributes of a field class. +*/ extern void bt_field_class_set_user_attributes( bt_field_class *field_class, const bt_value *user_attributes); -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}. + +See the \ref api-tir-fc-prop-user-attrs "user attributes" property. + +@note + When you create a field class with one of the + bt_field_class_*_create() 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: + + + + +
Property + Value +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + +
Property + Value +
\ref api-tir-fc-ba-prop-len "Length" + \bt_p{length} +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + +
+
Unsigned integer field class
+
[0, 2N - 1]
+ +
Signed integer field class
+
[-2N, 2N - 1]
+
+ @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: + +
+
Unsigned integer field class
+
[0, 2N - 1]
+ +
Signed integer field class
+
[-2N, 2N - 1]
+
+ @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: + + + + + + +
Property + Value +
\ref api-tir-fc-int-prop-size "Field value range" + [0, 264 - 1] +
\ref api-tir-fc-int-prop-base "Preferred display base" + #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + + +
Property + Value +
\ref api-tir-fc-int-prop-size "Field value range" + [-263, 263 - 1] +
\ref api-tir-fc-int-prop-base "Preferred display base" + #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + +
Property + Value +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + +
Property + Value +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + + + +
Property + Value +
\ref api-tir-fc-int-prop-size "Field value range" + [0, 264 - 1] +
\ref api-tir-fc-int-prop-base "Preferred display base" + #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL +
\ref api-tir-fc-enum-prop-mappings "Mappings" + \em None +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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 + On success, \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 + On success, \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: + + + + + + + +
Property + Value +
\ref api-tir-fc-int-prop-size "Field value range" + [-263, 263 - 1] +
\ref api-tir-fc-int-prop-base "Preferred display base" + #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL +
\ref api-tir-fc-enum-prop-mappings "Mappings" + \em None +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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 + On success, \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 + On success, \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: + + + + +
Property + Value +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + + +
Property + Value +
\ref api-tir-fc-array-prop-elem-fc "Element field class" + \bt_p{element_field_class} +
\ref api-tir-fc-sarray-prop-len "Length" + \bt_p{length} +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + + +
Property + Value +
\ref api-tir-fc-array-prop-elem-fc "Element field class" + \bt_p{element_field_class} +
\ref api-tir-fc-darray-prop-len-fp "Length field path" + + \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) +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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 + If \bt_p{length_field_class} is not \c NULL, + \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: + + + + + +
Property + Value +
\ref api-tir-fc-struct-prop-members "Members" + \em None +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + +
Property + Value +
\ref api-tir-fc-opt-prop-fc "Optional field class" + \bt_p{optional_field_class} +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + + + +
Property + Value +
\ref api-tir-fc-opt-prop-fc "Optional field class" + \bt_p{optional_field_class} +
\ref api-tir-fc-opt-prop-sel-fp "Selector field path" + + \em None (this property becomes available when the returned field + class becomes part of an \bt_ev_cls or of a \bt_stream_cls) +
\ref api-tir-fc-opt-prop-sel-rev "Selector is reversed?" + #BT_FALSE +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + + + +
Property + Value +
\ref api-tir-fc-opt-prop-fc "Optional field class" + \bt_p{optional_field_class} +
\ref api-tir-fc-opt-prop-sel-fp "Selector field path" + + \em None (this property becomes available when the returned field + class becomes part of an \bt_ev_cls or of a \bt_stream_cls) +
\ref api-tir-fc-opt-prop-uint-rs "Selector's unsigned integer ranges" + \bt_p{ranges} +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + + + +
Property + Value +
\ref api-tir-fc-opt-prop-fc "Optional field class" + \bt_p{optional_field_class} +
\ref api-tir-fc-opt-prop-sel-fp "Selector field path" + + \em None (this property becomes available when the returned field + class becomes part of an \bt_ev_cls or of a \bt_stream_cls) +
\ref api-tir-fc-opt-prop-sint-rs "Selector's signed integer ranges" + \bt_p{ranges} +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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}. -extern bt_field_class *bt_field_class_bool_create( - bt_trace_class *trace_class); +See the +\ref api-tir-fc-opt-prop-sint-rs "selector's signed integer ranges" +property. -extern bt_field_class *bt_field_class_bit_array_create( - bt_trace_class *trace_class, uint64_t length); +@param[in] field_class + Option field class from which to borrow the signed integer ranges. -extern bt_field_class *bt_field_class_integer_unsigned_create( - bt_trace_class *trace_class); +@returns + Signed integer ranges of \bt_p{field_class}. -extern bt_field_class *bt_field_class_integer_signed_create( - bt_trace_class *trace_class); +@bt_pre_not_null{field_class} +@bt_pre_is_opt_wsis_fc{field_class} +*/ +extern const bt_integer_range_set_signed * +bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const( + const bt_field_class *field_class); -extern void bt_field_class_integer_set_field_value_range( - bt_field_class *field_class, uint64_t size); +/*! @} */ -extern void bt_field_class_integer_set_preferred_display_base( - bt_field_class *field_class, - bt_field_class_integer_preferred_display_base base); +/*! +@name Variant field class +@{ +*/ -extern bt_field_class *bt_field_class_real_single_precision_create( - bt_trace_class *trace_class); +/*! +@brief + Creates a \bt_var_fc from the trace class \bt_p{trace_class}. -extern bt_field_class *bt_field_class_real_double_precision_create( - bt_trace_class *trace_class); +If \bt_p{selector_field_class} is not \c NULL, then the created variant +field class has a linked selector field class. +See +\ref api-tir-fc-link "Field classes with links to other field classes" +to learn more. -extern bt_field_class *bt_field_class_enumeration_unsigned_create( - bt_trace_class *trace_class); +On success, the returned variant field class has the following +property values: -extern bt_field_class *bt_field_class_enumeration_signed_create( - bt_trace_class *trace_class); + + + + + +
Property + Value +
\ref api-tir-fc-var-prop-sel-fp "Selector field path" + + \em None (if \bt_p{selector_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) +
\ref api-tir-fc-var-prop-opts "Options" + \em None +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
-typedef enum bt_field_class_enumeration_add_mapping_status { - BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_field_class_enumeration_add_mapping_status; +@param[in] trace_class + Trace class from which to create a variant field class. +@param[in] selector_field_class + @parblock + Linked selector field class of the variant field class to create. -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 *range_set); + Can be \c NULL. + @endparblock -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 *range_set); +@returns + New variant field class reference, or \c NULL on memory error. -extern bt_field_class *bt_field_class_string_create( - bt_trace_class *trace_class); +@bt_pre_not_null{trace_class} +@pre + If \bt_p{selector_field_class} is not \c NULL, + \bt_p{selector_field_class} is an \bt_int_fc. -extern bt_field_class *bt_field_class_structure_create( - bt_trace_class *trace_class); +@bt_post_success_frozen{element_field_class} +@bt_post_success_frozen{selector_field_class} +*/ +extern bt_field_class *bt_field_class_variant_create( + bt_trace_class *trace_class, + bt_field_class *selector_field_class); -typedef enum bt_field_class_structure_append_member_status { - BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_field_class_structure_append_member_status; +/*! +@brief + Returns the number of options contained in the \bt_var_fc + \bt_p{field_class}. -extern bt_field_class_structure_append_member_status -bt_field_class_structure_append_member( - bt_field_class *struct_field_class, - const char *name, bt_field_class *field_class); +See the \ref api-tir-fc-var-prop-opts "options" property. -extern bt_field_class_structure_member * -bt_field_class_structure_borrow_member_by_index( +@param[in] field_class + Variant field class of which to get the number of contained + options. + +@returns + Number of contained options in \bt_p{field_class}. + +@bt_pre_not_null{field_class} +@bt_pre_is_var_fc{field_class} +*/ +extern uint64_t bt_field_class_variant_get_option_count( + const bt_field_class *field_class); + +/*! +@brief + Borrows the option at index \bt_p{index} from the + \bt_var_fc \bt_p{field_class}. + +See the \ref api-tir-fc-var-prop-opts "options" property. + +@param[in] field_class + Variant field class from which to borrow the option at + index \bt_p{index}. +@param[in] index + Index of the option to borrow from \bt_p{field_class}. + +@returns + @parblock + \em Borrowed reference of the option 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_var_fc{field_class} +@pre + \bt_p{index} is less than the number of options in + \bt_p{field_class} (as returned by + bt_field_class_variant_get_option_count()). + +@sa bt_field_class_variant_get_option_count() — + Returns the number of options contained in a variant field class. +@sa bt_field_class_variant_borrow_option_by_index_const() — + \c const version of this function. +*/ +extern bt_field_class_variant_option * +bt_field_class_variant_borrow_option_by_index( bt_field_class *field_class, uint64_t index); -extern bt_field_class_structure_member * -bt_field_class_structure_borrow_member_by_name( +/*! +@brief + Borrows the option at index \bt_p{index} from the + \bt_var_fc \bt_p{field_class} (\c const version). + +See bt_field_class_variant_borrow_option_by_index(). +*/ +extern const bt_field_class_variant_option * +bt_field_class_variant_borrow_option_by_index_const( + const bt_field_class *field_class, uint64_t index); + +/*! +@brief + Borrows the option having the name \bt_p{name} from the + \bt_var_fc \bt_p{field_class}. + +See the \ref api-tir-fc-var-prop-opts "options" property. + +If there's no option having the name \bt_p{name} in +\bt_p{field_class}, this function returns \c NULL. + +@param[in] field_class + Variant field class from which to borrow the option having the + name \bt_p{name}. +@param[in] name + Name of the option to borrow from \bt_p{field_class}. + +@returns + @parblock + \em Borrowed reference of the option 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_var_fc{field_class} +@bt_pre_not_null{name} + +@sa bt_field_class_variant_borrow_option_by_name_const() — + \c const version of this function. +*/ +extern bt_field_class_variant_option * +bt_field_class_variant_borrow_option_by_name( bt_field_class *field_class, const char *name); -extern bt_field_class * -bt_field_class_structure_member_borrow_field_class( - bt_field_class_structure_member *member); +/*! +@brief + Borrows the option having the name \bt_p{name} from the + \bt_var_fc \bt_p{field_class} (\c const version). -extern bt_value *bt_field_class_structure_member_borrow_user_attributes( - bt_field_class_structure_member *member); +See bt_field_class_variant_borrow_option_by_name(). +*/ +extern const bt_field_class_variant_option * +bt_field_class_variant_borrow_option_by_name_const( + const bt_field_class *field_class, const char *name); -extern void bt_field_class_structure_member_set_user_attributes( - bt_field_class_structure_member *member, +/*! @} */ + +/*! +@name Variant field class option +@{ +*/ + +/*! +@typedef struct bt_field_class_variant_option bt_field_class_variant_option; + +@brief + Variant field class option. +*/ + +/*! +@brief + Returns the name of the \bt_var_fc option \bt_p{option}. + +See the \ref api-tir-fc-var-prop-opts "options" property. + +@param[in] option + Variant field class option of which to get the name. + +@returns + @parblock + Name of \bt_p{option}. + + The returned pointer remains valid as long as \bt_p{option} exists. + @endparblock + +@bt_pre_not_null{option} +*/ +extern const char *bt_field_class_variant_option_get_name( + const bt_field_class_variant_option *option); + +/*! +@brief + Borrows the field class from the \bt_var_fc option + \bt_p{option}. + +See the \ref api-tir-fc-var-prop-opts "options" property. + +@param[in] option + Variant field class option from which to borrow the field class. + +@returns + Field class of \bt_p{option}. + +@bt_pre_not_null{option} + +@sa bt_field_class_variant_option_borrow_field_class_const() — + \c const version of this function. +*/ +extern bt_field_class *bt_field_class_variant_option_borrow_field_class( + bt_field_class_variant_option *option); + +/*! +@brief + Borrows the field class from the \bt_var_fc option + \bt_p{option} (\c const version). + +See bt_field_class_variant_option_borrow_field_class(). +*/ +extern const bt_field_class * +bt_field_class_variant_option_borrow_field_class_const( + const bt_field_class_variant_option *option); + +/*! +@brief + Sets the user attributes of the \bt_var_fc option \bt_p{option} + to \bt_p{user_attributes}. + +See the \ref api-tir-fc-var-prop-opts "options" property. + +@note + When you append an option to a variant field class with + bt_field_class_variant_without_selector_append_option(), + bt_field_class_variant_with_selector_field_integer_unsigned_append_option(), + or + bt_field_class_variant_with_selector_field_integer_signed_append_option(), + the option's initial user attributes is an empty \bt_map_val. + Therefore you can borrow it with + bt_field_class_variant_option_borrow_user_attributes() and fill it + directly instead of setting a new one with this function. + +@param[in] option + Variant field class option of which to set the user attributes to + \bt_p{user_attributes}. +@param[in] user_attributes + New user attributes of \bt_p{option}. + +@bt_pre_not_null{option} +@bt_pre_hot{option} +@bt_pre_not_null{user_attributes} +@bt_pre_is_map_val{user_attributes} + +@sa bt_field_class_variant_option_borrow_user_attributes() — + Borrows the user attributes of a variant field class option. +*/ +extern void bt_field_class_variant_option_set_user_attributes( + bt_field_class_variant_option *option, const bt_value *user_attributes); -extern bt_field_class *bt_field_class_array_static_create( - bt_trace_class *trace_class, - bt_field_class *elem_field_class, uint64_t length); +/*! +@brief + Borrows the user attributes of the \bt_var_fc option \bt_p{option}. -extern bt_field_class *bt_field_class_array_dynamic_create( - bt_trace_class *trace_class, - bt_field_class *elem_field_class, - bt_field_class *length_field_class); +See the \ref api-tir-fc-var-prop-opts "options" property. -extern bt_field_class *bt_field_class_array_borrow_element_field_class( - bt_field_class *field_class); +@note + When you append an option to a variant field class with + bt_field_class_variant_without_selector_append_option(), + bt_field_class_variant_with_selector_field_integer_unsigned_append_option(), + or + bt_field_class_variant_with_selector_field_integer_signed_append_option(), + the option's initial user attributes is an empty \bt_map_val. -extern bt_field_class *bt_field_class_option_without_selector_create( - bt_trace_class *trace_class, - bt_field_class *content_field_class); +@param[in] option + Variant field class option from which to borrow the user + attributes. -extern bt_field_class *bt_field_class_option_with_selector_field_bool_create( - bt_trace_class *trace_class, - bt_field_class *content_field_class, - bt_field_class *selector_field_class); +@returns + User attributes of \bt_p{option} (a \bt_map_val). -extern void bt_field_class_option_with_selector_field_bool_set_selector_is_reversed( - bt_field_class *field_class, bt_bool selector_is_reversed); +@bt_pre_not_null{option} -extern bt_field_class * -bt_field_class_option_with_selector_field_integer_unsigned_create( - bt_trace_class *trace_class, - bt_field_class *content_field_class, - bt_field_class *selector_field_class, - const bt_integer_range_set_unsigned *range_set); +@sa bt_field_class_variant_option_set_user_attributes() — + Sets the user attributes of a variant field class option. +@sa bt_field_class_variant_option_borrow_user_attributes_const() — + \c const version of this function. +*/ +extern bt_value *bt_field_class_variant_option_borrow_user_attributes( + bt_field_class_variant_option *option); -extern bt_field_class * -bt_field_class_option_with_selector_field_integer_signed_create( - bt_trace_class *trace_class, - bt_field_class *content_field_class, - bt_field_class *selector_field_class, - const bt_integer_range_set_signed *range_set); +/*! +@brief + Borrows the user attributes of the \bt_var_fc option \bt_p{option} + (\c const version). -extern bt_field_class *bt_field_class_option_borrow_field_class( - bt_field_class *field_class); +See bt_field_class_variant_option_borrow_user_attributes(). +*/ +extern const bt_value *bt_field_class_variant_option_borrow_user_attributes_const( + const bt_field_class_variant_option *option); -extern bt_field_class *bt_field_class_variant_create( - bt_trace_class *trace_class, - bt_field_class *selector_field_class); +/*! @} */ + +/*! +@name Variant field class without a selector field +@{ +*/ +/*! +@brief + Status codes for + bt_field_class_variant_without_selector_append_option(). +*/ typedef enum bt_field_class_variant_without_selector_append_option_status { - BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, + /*! + @brief + Success. + */ BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK = __BT_FUNC_STATUS_OK, + + /*! + @brief + Out of memory. + */ + BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, } bt_field_class_variant_without_selector_append_option_status; +/*! +@brief + Appends an option to the \bt_var_fc (without a selector field) + \bt_p{field_class} having the name \bt_p{name} and the + field class \bt_p{option_field_class}. + +See the \ref api-tir-fc-var-prop-opts "options" property. + +@param[in] field_class + Variant field class to which to append an option having + the name \bt_p{name} and the field class \bt_p{option_field_class}. +@param[in] name + Name of the option to append to \bt_p{field_class} (copied). +@param[in] option_field_class + Field class of the option to append to \bt_p{field_class}. + +@retval #BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK + Success. +@retval #BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{field_class} +@bt_pre_hot{field_class} +@bt_pre_is_var_wos_fc{field_class} +@pre + \bt_p{field_class} has no option with the name \bt_p{name}. +@bt_pre_not_null{name} +@bt_pre_not_null{option_field_class} +@bt_pre_fc_not_in_tc{option_field_class} + +@bt_post_success_frozen{option_field_class} +*/ extern bt_field_class_variant_without_selector_append_option_status bt_field_class_variant_without_selector_append_option( - bt_field_class *var_field_class, const char *name, - bt_field_class *field_class); + bt_field_class *field_class, const char *name, + bt_field_class *option_field_class); + +/*! @} */ +/*! +@name Variant field class with a selector field +@{ +*/ + +/*! +@brief + Status codes for + bt_field_class_variant_with_selector_field_integer_unsigned_append_option() + and + bt_field_class_variant_with_selector_field_integer_signed_append_option(). +*/ typedef enum bt_field_class_variant_with_selector_field_integer_append_option_status { - BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, + /*! + @brief + Success. + */ BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK = __BT_FUNC_STATUS_OK, + + /*! + @brief + Out of memory. + */ + BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, } bt_field_class_variant_with_selector_field_integer_append_option_status; +/*! +@brief + Borrows the selector field path from the \bt_var_fc (with a selector + field) \bt_p{field_class}. + +See the \ref api-tir-fc-var-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 + Variant 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_var_ws_fc{field_class} +*/ +extern const bt_field_path * +bt_field_class_variant_with_selector_field_borrow_selector_field_path_const( + const bt_field_class *field_class); + +/*! @} */ + +/*! +@name Variant field class with an unsigned integer selector field +@{ +*/ + +/*! +@brief + Appends an option to the \bt_var_fc (with an unsigned integer + selector field) \bt_p{field_class} having the name \bt_p{name}, + the field class \bt_p{option_field_class}, and the + \bt_p_uint_rg \bt_p{ranges}. + +See the \ref api-tir-fc-var-prop-opts "options" property. + +@param[in] field_class + Variant field class to which to append an option having + the name \bt_p{name}, the field class \bt_p{option_field_class}, + and the unsigned integer ranges \bt_p{ranges}. +@param[in] name + Name of the option to append to \bt_p{field_class} (copied). +@param[in] option_field_class + Field class of the option to append to \bt_p{field_class}. +@param[in] ranges + Unsigned integer ranges of the option to append to + \bt_p{field_class}. + +@retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK + Success. +@retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{field_class} +@bt_pre_hot{field_class} +@bt_pre_is_var_wuis_fc{field_class} +@pre + \bt_p{field_class} has no option with the name \bt_p{name}. +@bt_pre_not_null{name} +@bt_pre_not_null{option_field_class} +@bt_pre_fc_not_in_tc{option_field_class} +@bt_pre_not_null{ŗanges} +@pre + \bt_p{ranges} contains one or more unsigned integer ranges. +@pre + The unsigned integer ranges in \bt_p{ranges} do not overlap + any unsigned integer range of any existing option in + \bt_p{field_class}. + +@bt_post_success_frozen{option_field_class} +*/ extern bt_field_class_variant_with_selector_field_integer_append_option_status bt_field_class_variant_with_selector_field_integer_unsigned_append_option( - bt_field_class *var_field_class, const char *name, - bt_field_class *field_class, - const bt_integer_range_set_unsigned *range_set); + bt_field_class *field_class, const char *name, + bt_field_class *option_field_class, + const bt_integer_range_set_unsigned *ranges); + +/*! +@brief + Borrows the option at index \bt_p{index} from the + \bt_var_fc (with an unsigned integer selector field) + \bt_p{field_class}. + +See the \ref api-tir-fc-var-prop-opts "options" property. + +@param[in] field_class + Variant field class from which to borrow the option at + index \bt_p{index}. +@param[in] index + Index of the option to borrow from \bt_p{field_class}. + +@returns + @parblock + \em Borrowed reference of the option 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_var_wuis_fc{field_class} +@pre + \bt_p{index} is less than the number of options in + \bt_p{field_class} (as returned by + bt_field_class_variant_get_option_count()). + +@sa bt_field_class_variant_get_option_count() — + Returns the number of options contained in a variant field class. +*/ +extern const bt_field_class_variant_with_selector_field_integer_unsigned_option * +bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const( + const bt_field_class *field_class, uint64_t index); + +/*! +@brief + Borrows the option having the name \bt_p{name} from the + \bt_var_fc (with an unsigned integer selector field) + \bt_p{field_class}. + +See the \ref api-tir-fc-var-prop-opts "options" property. + +If there's no option having the name \bt_p{name} in +\bt_p{field_class}, this function returns \c NULL. + +@param[in] field_class + Variant field class from which to borrow the option having the + name \bt_p{name}. +@param[in] name + Name of the option to borrow from \bt_p{field_class}. + +@returns + @parblock + \em Borrowed reference of the option 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_var_wuis_fc{field_class} +@bt_pre_not_null{name} + +@sa bt_field_class_variant_borrow_option_by_name_const() — + Borrows an option by name from a variant field class. +*/ +extern const bt_field_class_variant_with_selector_field_integer_unsigned_option * +bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const( + const bt_field_class *field_class, const char *name); + +/*! @} */ + +/*! +@name Variant field class (with an unsigned integer selector field) option +@{ +*/ + +/*! +@typedef struct bt_field_class_variant_with_selector_field_integer_unsigned_option bt_field_class_variant_with_selector_field_integer_unsigned_option; + +@brief + Variant field class (with an unsigned integer selector field) option. +*/ + +/*! +@brief + Borrows the \bt_p_uint_rg from the \bt_var_fc (with an unsigned + integer selector field) option \bt_p{option}. + +See the \ref api-tir-fc-var-prop-opts "options" property. + +@param[in] option + Variant field class option from which to borrow the + unsigned integer ranges. + +@returns + Unsigned integer ranges of \bt_p{option}. + +@bt_pre_not_null{option} +*/ +extern const bt_integer_range_set_unsigned * +bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const( + const bt_field_class_variant_with_selector_field_integer_unsigned_option *option); + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the \bt_var_fc (with an + unsigned integer selector field) option \bt_p{option} to the + common #bt_field_class_variant_option type. + +See the \ref api-tir-fc-var-prop-opts "options" property. + +@param[in] option + @parblock + Variant field class option to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{option} as a common variant field class option. +*/ +static inline +const bt_field_class_variant_option * +bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const( + const bt_field_class_variant_with_selector_field_integer_unsigned_option *option) +{ + return __BT_UPCAST_CONST(bt_field_class_variant_option, option); +} + +/*! @} */ + +/*! +@name Variant field class with a signed integer selector field +@{ +*/ + +/*! +@brief + Appends an option to the \bt_var_fc (with a signed integer + selector field) \bt_p{field_class} having the name \bt_p{name}, + the field class \bt_p{option_field_class}, and the + \bt_p_sint_rg \bt_p{ranges}. + +See the \ref api-tir-fc-var-prop-opts "options" property. +@param[in] field_class + Variant field class to which to append an option having + the name \bt_p{name} and the field class \bt_p{option_field_class}, + and the signed integer ranges \bt_p{ranges}. +@param[in] name + Name of the option to append to \bt_p{field_class} (copied). +@param[in] option_field_class + Field class of the option to append to \bt_p{field_class}. +@param[in] ranges + Signed integer ranges of the option to append to + \bt_p{field_class}. + +@retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK + Success. +@retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{field_class} +@bt_pre_hot{field_class} +@bt_pre_is_var_wsis_fc{field_class} +@pre + \bt_p{field_class} has no option with the name \bt_p{name}. +@bt_pre_not_null{name} +@bt_pre_not_null{option_field_class} +@bt_pre_fc_not_in_tc{option_field_class} +@bt_pre_not_null{ŗanges} +@pre + \bt_p{ranges} contains one or more signed integer ranges. +@pre + The signed integer ranges in \bt_p{ranges} do not overlap with + any signed integer range of any existing option in + \bt_p{field_class}. + +@bt_post_success_frozen{option_field_class} +*/ extern bt_field_class_variant_with_selector_field_integer_append_option_status bt_field_class_variant_with_selector_field_integer_signed_append_option( - bt_field_class *var_field_class, const char *name, - bt_field_class *field_class, - const bt_integer_range_set_signed *range_set); + bt_field_class *field_class, const char *name, + bt_field_class *option_field_class, + const bt_integer_range_set_signed *ranges); -extern bt_field_class_variant_option * -bt_field_class_variant_borrow_option_by_index( - bt_field_class *field_class, uint64_t index); +/*! +@brief + Borrows the option at index \bt_p{index} from the + \bt_var_fc (with a signed integer selector field) + \bt_p{field_class}. -extern bt_field_class_variant_option * -bt_field_class_variant_borrow_option_by_name( - bt_field_class *field_class, const char *name); +See the \ref api-tir-fc-var-prop-opts "options" property. -extern bt_field_class *bt_field_class_variant_option_borrow_field_class( - bt_field_class_variant_option *option); +@param[in] field_class + Variant field class from which to borrow the option at + index \bt_p{index}. +@param[in] index + Index of the option to borrow from \bt_p{field_class}. -extern bt_value *bt_field_class_variant_option_borrow_user_attributes( - bt_field_class_variant_option *option); +@returns + @parblock + \em Borrowed reference of the option of + \bt_p{field_class} at index \bt_p{index}. -extern void bt_field_class_variant_option_set_user_attributes( - bt_field_class_variant_option *option, - const bt_value *user_attributes); + 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_var_wsis_fc{field_class} +@pre + \bt_p{index} is less than the number of options in + \bt_p{field_class} (as returned by + bt_field_class_variant_get_option_count()). + +@sa bt_field_class_variant_get_option_count() — + Returns the number of options contained in a variant field class. +*/ +extern const bt_field_class_variant_with_selector_field_integer_signed_option * +bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const( + const bt_field_class *field_class, uint64_t index); + +/*! +@brief + Borrows the option having the name \bt_p{name} from the + \bt_var_fc (with a signed integer selector field) + \bt_p{field_class}. + +See the \ref api-tir-fc-var-prop-opts "options" property. + +If there's no option having the name \bt_p{name} in +\bt_p{field_class}, this function returns \c NULL. + +@param[in] field_class + Variant field class from which to borrow the option having the + name \bt_p{name}. +@param[in] name + Name of the option to borrow from \bt_p{field_class}. + +@returns + @parblock + \em Borrowed reference of the option 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_var_wsis_fc{field_class} +@bt_pre_not_null{name} + +@sa bt_field_class_variant_borrow_option_by_name_const() — + Borrows an option by name from a variant field class. +*/ +extern const bt_field_class_variant_with_selector_field_integer_signed_option * +bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const( + const bt_field_class *field_class, const char *name); + +/*! @} */ + +/*! +@name Variant field class (with a signed integer selector field) option +@{ +*/ + +/*! +@typedef struct bt_field_class_variant_with_selector_field_integer_signed_option bt_field_class_variant_with_selector_field_integer_signed_option; + +@brief + Variant field class (with a signed integer selector field) option. +*/ + +/*! +@brief + Borrows the \bt_p_sint_rg from the \bt_var_fc (with a signed + integer selector field) option \bt_p{option}. + +See the \ref api-tir-fc-var-prop-opts "options" property. + +@param[in] option + Variant field class option from which to borrow the + signed integer ranges. + +@returns + Signed integer ranges of \bt_p{option}. + +@bt_pre_not_null{option} +*/ +extern const bt_integer_range_set_signed * +bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const( + const bt_field_class_variant_with_selector_field_integer_signed_option *option); + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the \bt_var_fc (with a signed + integer selector field) option \bt_p{option} to the + common #bt_field_class_variant_option type. + +See the \ref api-tir-fc-var-prop-opts "options" property. + +@param[in] option + @parblock + Variant field class option to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{option} as a common variant field class option. +*/ +static inline +const bt_field_class_variant_option * +bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const( + const bt_field_class_variant_with_selector_field_integer_signed_option *option) +{ + return __BT_UPCAST_CONST(bt_field_class_variant_option, option); +} + +/*! @} */ + +/*! +@name Reference count +@{ +*/ + +/*! +@brief + Increments the \ref api-fund-shared-object "reference count" of + the field class \bt_p{field_class}. + +@param[in] field_class + @parblock + Field class of which to increment the reference count. + + Can be \c NULL. + @endparblock + +@sa bt_field_class_put_ref() — + Decrements the reference count of a field class. +*/ +extern void bt_field_class_get_ref(const bt_field_class *field_class); + +/*! +@brief + Decrements the \ref api-fund-shared-object "reference count" of + the field class \bt_p{field_class}. + +@param[in] field_class + @parblock + Field class of which to decrement the reference count. + + Can be \c NULL. + @endparblock + +@sa bt_field_class_get_ref() — + Increments the reference count of a field class. +*/ +extern void bt_field_class_put_ref(const bt_field_class *field_class); + +/*! +@brief + Decrements the reference count of the field class + \bt_p{_field_class}, and then sets \bt_p{_field_class} to \c NULL. + +@param _field_class + @parblock + Field class of which to decrement the reference count. + + Can contain \c NULL. + @endparblock + +@bt_pre_assign_expr{_field_class} +*/ +#define BT_FIELD_CLASS_PUT_REF_AND_RESET(_field_class) \ + do { \ + bt_field_class_put_ref(_field_class); \ + (_field_class) = NULL; \ + } while (0) + +/*! +@brief + Decrements the reference count of the field class \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 class 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_CLASS_MOVE_REF(_dst, _src) \ + do { \ + bt_field_class_put_ref(_dst); \ + (_dst) = (_src); \ + (_src) = NULL; \ + } while (0) + +/*! @} */ + +/*! @} */ #ifdef __cplusplus }