X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ffield-types.h;h=69a89e5c8f00de0bd92f1be487d921d159e27214;hb=9d408fcae74602e3591f66623ceb85f482d948ed;hp=e9b5f25393bbd9e2eeeb4ef6deb070934fcf5cc2;hpb=9643611120f9bf174684cb0a06ec9ed418e3341e;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/field-types.h b/include/babeltrace/ctf-ir/field-types.h index e9b5f253..69a89e5c 100644 --- a/include/babeltrace/ctf-ir/field-types.h +++ b/include/babeltrace/ctf-ir/field-types.h @@ -30,7 +30,11 @@ * http://www.efficios.com/ctf */ +/* For bt_bool */ +#include + #include +#include #ifdef __cplusplus extern "C" { @@ -96,49 +100,49 @@ The standard CTF field types are: CTF IR field which you can create from this field type - #BT_CTF_TYPE_ID_INTEGER + #BT_CTF_FIELD_TYPE_ID_INTEGER \ref ctfirintfieldtype \ref ctfirintfield - #BT_CTF_TYPE_ID_FLOAT + #BT_CTF_FIELD_TYPE_ID_FLOAT \ref ctfirfloatfieldtype \ref ctfirfloatfield - #BT_CTF_TYPE_ID_ENUM + #BT_CTF_FIELD_TYPE_ID_ENUM \ref ctfirenumfieldtype \ref ctfirenumfield - #BT_CTF_TYPE_ID_STRING + #BT_CTF_FIELD_TYPE_ID_STRING \ref ctfirstringfieldtype \ref ctfirstringfield - #BT_CTF_TYPE_ID_STRUCT + #BT_CTF_FIELD_TYPE_ID_STRUCT \ref ctfirstructfieldtype \ref ctfirstructfield - #BT_CTF_TYPE_ID_ARRAY + #BT_CTF_FIELD_TYPE_ID_ARRAY \ref ctfirarrayfieldtype \ref ctfirarrayfield - #BT_CTF_TYPE_ID_SEQUENCE + #BT_CTF_FIELD_TYPE_ID_SEQUENCE \ref ctfirseqfieldtype \ref ctfirseqfield - #BT_CTF_TYPE_ID_VARIANT + #BT_CTF_FIELD_TYPE_ID_VARIANT \ref ctfirvarfieldtype \ref ctfirvarfield Each field type has its own type ID (see -#bt_ctf_type_id). You get the type ID of a field type object +#bt_ctf_field_type_id). You get the type ID of a field type object with bt_ctf_field_type_get_type_id(). You can get a deep copy of a field type with bt_ctf_field_type_copy(). @@ -198,27 +202,28 @@ struct bt_ctf_event_class; struct bt_ctf_event; struct bt_ctf_field; struct bt_ctf_field_path; +struct bt_ctf_field_type_enumeration_mapping_iterator; /** @cond DOCUMENT */ /* * Babeltrace 1.x enumerations that were also used in CTF writer's API. * They are left here for backward compatibility reasons, but - * enum bt_ctf_type_id and enum bt_ctf_string_encoding should be used + * enum bt_ctf_field_type_id and enum bt_ctf_string_encoding should be used * in new code. Both new enumerations are compatible with their legacy * counterpart. */ enum ctf_type_id { - CTF_TYPE_UNKNOWN = 0, - CTF_TYPE_INTEGER, - CTF_TYPE_FLOAT, - CTF_TYPE_ENUM, - CTF_TYPE_STRING, - CTF_TYPE_STRUCT, - CTF_TYPE_UNTAGGED_VARIANT, - CTF_TYPE_VARIANT, - CTF_TYPE_ARRAY, - CTF_TYPE_SEQUENCE, + CTF_TYPE_UNKNOWN = -1, + CTF_TYPE_INTEGER = 0, + CTF_TYPE_FLOAT = 1, + CTF_TYPE_ENUM = 2, + CTF_TYPE_STRING = 3, + CTF_TYPE_STRUCT = 4, + CTF_TYPE_UNTAGGED_VARIANT = 5, + CTF_TYPE_VARIANT = 5, + CTF_TYPE_ARRAY = 6, + CTF_TYPE_SEQUENCE = 7, NR_CTF_TYPES, }; @@ -273,37 +278,33 @@ enum bt_ctf_scope { /** @brief Type ID of a @ft. */ -enum bt_ctf_type_id { +enum bt_ctf_field_type_id { /// Unknown, used for errors. - BT_CTF_TYPE_ID_UNKNOWN = CTF_TYPE_UNKNOWN, + BT_CTF_FIELD_TYPE_ID_UNKNOWN = CTF_TYPE_UNKNOWN, /// \ref ctfirintfieldtype - BT_CTF_TYPE_ID_INTEGER = CTF_TYPE_INTEGER, + BT_CTF_FIELD_TYPE_ID_INTEGER = CTF_TYPE_INTEGER, /// \ref ctfirfloatfieldtype - BT_CTF_TYPE_ID_FLOAT = CTF_TYPE_FLOAT, + BT_CTF_FIELD_TYPE_ID_FLOAT = CTF_TYPE_FLOAT, /// \ref ctfirenumfieldtype - BT_CTF_TYPE_ID_ENUM = CTF_TYPE_ENUM, + BT_CTF_FIELD_TYPE_ID_ENUM = CTF_TYPE_ENUM, /// \ref ctfirstringfieldtype - BT_CTF_TYPE_ID_STRING = CTF_TYPE_STRING, + BT_CTF_FIELD_TYPE_ID_STRING = CTF_TYPE_STRING, /// \ref ctfirstructfieldtype - BT_CTF_TYPE_ID_STRUCT = CTF_TYPE_STRUCT, - - /// @cond DOCUMENT - BT_CTF_TYPE_ID_UNTAGGED_VARIANT = CTF_TYPE_UNTAGGED_VARIANT, - /// @endcond + BT_CTF_FIELD_TYPE_ID_STRUCT = CTF_TYPE_STRUCT, /// \ref ctfirarrayfieldtype - BT_CTF_TYPE_ID_ARRAY = CTF_TYPE_ARRAY, + BT_CTF_FIELD_TYPE_ID_ARRAY = CTF_TYPE_ARRAY, /// \ref ctfirseqfieldtype - BT_CTF_TYPE_ID_SEQUENCE = CTF_TYPE_SEQUENCE, + BT_CTF_FIELD_TYPE_ID_SEQUENCE = CTF_TYPE_SEQUENCE, /// \ref ctfirvarfieldtype - BT_CTF_TYPE_ID_VARIANT = CTF_TYPE_VARIANT, + BT_CTF_FIELD_TYPE_ID_VARIANT = CTF_TYPE_VARIANT, /// Number of enumeration entries. BT_CTF_NR_TYPE_IDS = NR_CTF_TYPES, @@ -314,12 +315,12 @@ enum bt_ctf_type_id { @param[in] field_type Field type of which to get the type ID. @returns Type ID of \p field_type, - or #BT_CTF_TYPE_ID_UNKNOWN on error. + or #BT_CTF_FIELD_TYPE_ID_UNKNOWN on error. @prenotnull{field_type} @postrefcountsame{field_type} -@sa #bt_ctf_type_id: CTF IR field type ID. +@sa #bt_ctf_field_type_id: CTF IR field type ID. @sa bt_ctf_field_type_is_integer(): Returns whether or not a given field type is a @intft. @sa bt_ctf_field_type_is_floating_point(): Returns whether or not a @@ -337,15 +338,15 @@ enum bt_ctf_type_id { @sa bt_ctf_field_type_is_variant(): Returns whether or not a given field type is a @varft. */ -extern enum bt_ctf_type_id bt_ctf_field_type_get_type_id( +extern enum bt_ctf_field_type_id bt_ctf_field_type_get_type_id( struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @intft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is an integer field type, - or 0 otherwise (including if \p field_type is +@returns #BT_TRUE if \p field_type is an integer field type, + or #BT_FALSE otherwise (including if \p field_type is \c NULL). @prenotnull{field_type} @@ -354,14 +355,15 @@ extern enum bt_ctf_type_id bt_ctf_field_type_get_type_id( @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_integer(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_integer( + struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @floatft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is a floating point - number field type, +@returns #BT_TRUE if \p field_type is a floating point + #BT_FALSE field type, or 0 otherwise (including if \p field_type is \c NULL). @@ -370,14 +372,15 @@ extern int bt_ctf_field_type_is_integer(struct bt_ctf_field_type *field_type); @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_floating_point(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_floating_point( + struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @enumft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is an enumeration field type, - or 0 otherwise (including if \p field_type is +@returns #BT_TRUE if \p field_type is an enumeration field type, + or #BT_FALSE otherwise (including if \p field_type is \c NULL). @postrefcountsame{field_type} @@ -385,14 +388,15 @@ extern int bt_ctf_field_type_is_floating_point(struct bt_ctf_field_type *field_t @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_enumeration(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_enumeration( + struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @stringft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is a string field type, - or 0 otherwise (including if \p field_type is +@returns #BT_TRUE if \p field_type is a string field type, + or #BT_FALSE otherwise (including if \p field_type is \c NULL). @postrefcountsame{field_type} @@ -400,14 +404,15 @@ extern int bt_ctf_field_type_is_enumeration(struct bt_ctf_field_type *field_type @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_string(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_string( + struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @structft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is a structure field type, - or 0 otherwise (including if \p field_type is +@returns #BT_TRUE if \p field_type is a structure field type, + or #BT_FALSE otherwise (including if \p field_type is \c NULL). @postrefcountsame{field_type} @@ -415,14 +420,15 @@ extern int bt_ctf_field_type_is_string(struct bt_ctf_field_type *field_type); @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_structure(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_structure( + struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @arrayft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is an array field type, - or 0 otherwise (including if \p field_type is +@returns #BT_TRUE if \p field_type is an array field type, + or #BT_FALSE otherwise (including if \p field_type is \c NULL). @postrefcountsame{field_type} @@ -430,14 +436,15 @@ extern int bt_ctf_field_type_is_structure(struct bt_ctf_field_type *field_type); @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_array(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_array( + struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @seqft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is a sequence field type, - or 0 otherwise (including if \p field_type is +@returns #BT_TRUE if \p field_type is a sequence field type, + or #BT_FALSE otherwise (including if \p field_type is \c NULL). @postrefcountsame{field_type} @@ -445,14 +452,15 @@ extern int bt_ctf_field_type_is_array(struct bt_ctf_field_type *field_type); @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_sequence(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_sequence( + struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @varft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is a variant field type, - or 0 otherwise (including if \p field_type is +@returns #BT_TRUE if \p field_type is a variant field type, + or #BT_FALSE otherwise (including if \p field_type is \c NULL). @postrefcountsame{field_type} @@ -460,7 +468,8 @@ extern int bt_ctf_field_type_is_sequence(struct bt_ctf_field_type *field_type); @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_variant(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_variant( + struct bt_ctf_field_type *field_type); /** @} */ @@ -485,6 +494,12 @@ enum bt_ctf_byte_order { /// Native (default) byte order. BT_CTF_BYTE_ORDER_NATIVE = 0, + /** + Unspecified byte order; the initial native byte order of a + \link ctfirtraceclass CTF IR trace class\endlink. + */ + BT_CTF_BYTE_ORDER_UNSPECIFIED, + /// Little-endian. BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, @@ -701,13 +716,13 @@ An integer field type has the following properties: integer fields Specified at creation bt_ctf_field_type_integer_get_size() - None: specified at creation (bt_ctf_field_type_integer_create()) + bt_ctf_field_type_integer_set_size() Signedness of the described integer fields Unsigned - bt_ctf_field_type_integer_get_signed() - bt_ctf_field_type_integer_set_signed() + bt_ctf_field_type_integer_is_signed() + bt_ctf_field_type_integer_set_is_signed() Preferred display base of the described @@ -746,6 +761,9 @@ enum bt_ctf_integer_base { /// Unknown, used for errors. BT_CTF_INTEGER_BASE_UNKNOWN = -1, + /// Unspecified by the tracer. + BT_CTF_INTEGER_BASE_UNSPECIFIED = 0, + /// Binary. BT_CTF_INTEGER_BASE_BINARY = 2, @@ -763,6 +781,10 @@ enum bt_ctf_integer_base { @brief Creates a default @intft with \p size bits as the storage size of the @intfields it describes. +You can change the storage size of the integer fields described by +the created integer field type later with +bt_ctf_field_type_integer_set_size(). + @param[in] size Storage size (bits) of the described integer fields. @returns Created integer field type, or \c NULL on error. @@ -786,10 +808,36 @@ extern struct bt_ctf_field_type *bt_ctf_field_type_integer_create( @prenotnull{int_field_type} @preisintft{int_field_type} @postrefcountsame{int_field_type} + +@sa bt_ctf_field_type_integer_set_size(): Sets the storage size of the + integer fields described by a given integer field type. */ extern int bt_ctf_field_type_integer_get_size( struct bt_ctf_field_type *int_field_type); +/** +@brief Sets the storage size, in bits, of the @intfields described by + the @intft \p int_field_type. + +@param[in] int_field_type Integer field type which describes the + integer fields of which to set the + storage size. +@param[in] size Storage size (bits) of the integer fields + described by \p int_field_type. +@returns 0 on success, or a negative value on error. + +@prenotnull{int_field_type} +@preisintft{int_field_type} +@prehot{int_field_type} +@pre \p size is greater than 0 and lesser than or equal to 64. +@postrefcountsame{int_field_type} + +@sa bt_ctf_field_type_integer_get_size(): Returns the storage size of + the integer fields described by a given integer field type. +*/ +extern int bt_ctf_field_type_integer_set_size( + struct bt_ctf_field_type *int_field_type, unsigned int size); + /** @brief Returns whether or not the @intfields described by the @intft \p int_field_type are signed. @@ -797,21 +845,27 @@ extern int bt_ctf_field_type_integer_get_size( @param[in] int_field_type Integer field type which describes the integer fields of which to get the signedness. -@returns 1 if the integer fields described by - \p int_field_type are signed, 0 if they - are unsigned, or a negative value on - error. +@returns #BT_TRUE if the integer fields described by + \p int_field_type are signed, #BT_FALSE if they + are unsigned. @prenotnull{int_field_type} @preisintft{int_field_type} @postrefcountsame{int_field_type} -@sa bt_ctf_field_type_integer_set_signed(): Sets the signedness of the +@sa bt_ctf_field_type_integer_set_is_signed(): Sets the signedness of the integer fields described by a given integer field type. */ +extern bt_bool bt_ctf_field_type_integer_is_signed( + struct bt_ctf_field_type *int_field_type); + +/** @cond DOCUMENT */ + extern int bt_ctf_field_type_integer_get_signed( struct bt_ctf_field_type *int_field_type); +/** @endcond */ + /** @brief Sets whether or not the @intfields described by the @intft \p int_field_type are signed. @@ -820,21 +874,23 @@ extern int bt_ctf_field_type_integer_get_signed( integer fields of which to set the signedness. @param[in] is_signed Signedness of the integer fields - described by \p int_field_type; 0 means - \em unsigned, 1 means \em signed. + described by \p int_field_type; #BT_FALSE means + \em unsigned, #BT_TRUE means \em signed. @returns 0 on success, or a negative value on error. @prenotnull{int_field_type} @preisintft{int_field_type} @prehot{int_field_type} -@pre \p is_signed is 0 or 1. -@postrefcountsame{event_class} +@postrefcountsame{int_field_type} -@sa bt_ctf_field_type_integer_get_signed(): Returns the signedness of +@sa bt_ctf_field_type_integer_is_signed(): Returns the signedness of the integer fields described by a given integer field type. */ -extern int bt_ctf_field_type_integer_set_signed( - struct bt_ctf_field_type *int_field_type, int is_signed); +extern int bt_ctf_field_type_integer_set_is_signed( + struct bt_ctf_field_type *int_field_type, bt_bool is_signed); + +/* Pre-2.0 CTF writer compatibility */ +#define bt_ctf_field_type_integer_set_signed bt_ctf_field_type_integer_set_is_signed /** @brief Returns the preferred display base (radix) of the @intfields @@ -845,8 +901,9 @@ extern int bt_ctf_field_type_integer_set_signed( preferred display base. @returns Preferred display base of the integer fields described by \p int_field_type, - or #BT_CTF_INTEGER_BASE_UNKNOWN on - error. + #BT_CTF_INTEGER_BASE_UNSPECIFIED if + not specified, or + #BT_CTF_INTEGER_BASE_UNKNOWN on error. @prenotnull{int_field_type} @preisintft{int_field_type} @@ -873,9 +930,9 @@ extern enum bt_ctf_integer_base bt_ctf_field_type_integer_get_base( @prenotnull{int_field_type} @preisintft{int_field_type} @prehot{int_field_type} -@pre \p base is #BT_CTF_INTEGER_BASE_BINARY, #BT_CTF_INTEGER_BASE_OCTAL, - #BT_CTF_INTEGER_BASE_DECIMAL, or - #BT_CTF_INTEGER_BASE_HEXADECIMAL. +@pre \p base is #BT_CTF_INTEGER_BASE_UNSPECIFIED, + #BT_CTF_INTEGER_BASE_BINARY, #BT_CTF_INTEGER_BASE_OCTAL, + #BT_CTF_INTEGER_BASE_DECIMAL, or #BT_CTF_INTEGER_BASE_HEXADECIMAL. @postrefcountsame{int_field_type} @sa bt_ctf_field_type_integer_get_base(): Returns the preferred display @@ -1176,36 +1233,6 @@ extern int bt_ctf_field_type_floating_point_set_mantissa_digits( /** @} */ -struct bt_ctf_field_type_enumeration_mapping_iterator * - bt_ctf_field_type_enumeration_find_mappings_by_name( - struct bt_ctf_field_type *type, - const char *name); - -struct bt_ctf_field_type_enumeration_mapping_iterator * - bt_ctf_field_type_enumeration_find_mappings_by_signed_value( - struct bt_ctf_field_type *type, - int64_t value); - -struct bt_ctf_field_type_enumeration_mapping_iterator * - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value( - struct bt_ctf_field_type *type, - uint64_t value); - -int bt_ctf_field_type_enumeration_mapping_iterator_get_name( - struct bt_ctf_field_type_enumeration_mapping_iterator *iter, - const char **mapping_name); - -int bt_ctf_field_type_enumeration_mapping_iterator_get_signed( - struct bt_ctf_field_type_enumeration_mapping_iterator *iter, - const char **mapping_name, int64_t *lower, int64_t *upper); - -int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned( - struct bt_ctf_field_type_enumeration_mapping_iterator *iter, - const char **mapping_name, uint64_t *lower, uint64_t *upper); - -int bt_ctf_field_type_enumeration_mapping_iterator_next( - struct bt_ctf_field_type_enumeration_mapping_iterator *iter); - /** @defgroup ctfirenumfieldtype CTF IR enumeration field type @ingroup ctfirfieldtypes @@ -1231,10 +1258,24 @@ An enumeration mapping has: value, both included in the range. You can add a mapping to an enumeration field type with -bt_ctf_field_type_enumeration_add_mapping() or +bt_ctf_field_type_enumeration_add_mapping_signed() or bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the signedness of the wrapped @intft. +You can find mappings by name or by value with the following find +operations: + +- bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the + mappings with a given name. +- bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): + Finds the mappings which contain a given unsigned value in their + range. +- bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): + Finds the mappings which contain a given signed value in their range. + +Those functions return a @enumftiter on the result set of the find +operation. + Many mappings can share the same name, and the ranges of a given enumeration field type are allowed to overlap. For example, this is a valid set of mappings: @@ -1258,6 +1299,7 @@ APPLE -> [ 30, 55] Here, the range of the second \c APPLE mapping overlaps the range of the \c CHERRY mapping. +@sa ctfirenumftmappingiter @sa ctfirenumfield @sa ctfirfieldtypes @@ -1313,7 +1355,7 @@ struct bt_ctf_field_type *bt_ctf_field_type_enumeration_get_container_type( @preisenumft{enum_field_type} @postrefcountsame{enum_field_type} */ -extern int bt_ctf_field_type_enumeration_get_mapping_count( +extern int64_t bt_ctf_field_type_enumeration_get_mapping_count( struct bt_ctf_field_type *enum_field_type); /** @@ -1328,7 +1370,7 @@ On success, \p enum_field_type remains the sole owner of \p *name. @param[in] enum_field_type Enumeration field type of which to get the mapping at index \p index. -­@param[in] index Index of the mapping to get from +@param[in] index Index of the mapping to get from \p enum_field_type. @param[out] name Returned name of the mapping at index \p index. @@ -1350,12 +1392,12 @@ On success, \p enum_field_type remains the sole owner of \p *name. bt_ctf_field_type_enumeration_get_mapping_count()). @postrefcountsame{enum_field_type} -@sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the - signed mapping contained by a given enumeration field type +@sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the + unsigned mapping contained by a given enumeration field type at a given index. */ extern int bt_ctf_field_type_enumeration_get_mapping_signed( - struct bt_ctf_field_type *enum_field_type, int index, + struct bt_ctf_field_type *enum_field_type, uint64_t index, const char **name, int64_t *range_begin, int64_t *range_end); /** @@ -1370,7 +1412,7 @@ On success, \p enum_field_type remains the sole owner of \p *name. @param[in] enum_field_type Enumeration field type of which to get the mapping at index \p index. -­@param[in] index Index of the mapping to get from +@param[in] index Index of the mapping to get from \p enum_field_type. @param[out] name Returned name of the mapping at index \p index. @@ -1392,15 +1434,122 @@ On success, \p enum_field_type remains the sole owner of \p *name. bt_ctf_field_type_enumeration_get_mapping_count()). @postrefcountsame{enum_field_type} -@sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the - unsigned mapping contained by a given enumeration field type +@sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the + signed mapping contained by a given enumeration field type at a given index. */ extern int bt_ctf_field_type_enumeration_get_mapping_unsigned( - struct bt_ctf_field_type *enum_field_type, int index, + struct bt_ctf_field_type *enum_field_type, uint64_t index, const char **name, uint64_t *range_begin, uint64_t *range_end); +/** +@brief Finds the mappings of the @enumft \p enum_field_type which + are named \p name. + +This function returns an iterator on the result set of this find +operation. See \ref ctfirenumftmappingiter for more details. + +@param[in] enum_field_type Enumeration field type of which to find + the mappings named \p name. +@param[in] name Name of the mappings to find in + \p enum_field_type. +@returns @enumftiter on the set of mappings named + \p name in \p enum_field_type, or + \c NULL if no mappings were found or + on error. + +@prenotnull{enum_field_type} +@prenotnull{name} +@preisenumft{enum_field_type} +@postrefcountsame{enum_field_type} +@postsuccessrefcountret1 +@post On success, the returned @enumftiter can iterate + on at least one mapping. + +@sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds + the mappings of a given enumeration field type which contain + a given signed value in their range. +@sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds + the mappings of a given enumeration field type which contain + a given unsigned value in their range. +*/ +extern struct bt_ctf_field_type_enumeration_mapping_iterator * +bt_ctf_field_type_enumeration_find_mappings_by_name( + struct bt_ctf_field_type *enum_field_type, + const char *name); + +/** +@brief Finds the mappings of the @enumft \p enum_field_type which + contain the signed value \p value in their range. + +This function returns an iterator on the result set of this find +operation. See \ref ctfirenumftmappingiter for more details. + +@param[in] enum_field_type Enumeration field type of which to find + the mappings which contain \p value. +@param[in] value Value to find in the ranges of the + mappings of \p enum_field_type. +@returns @enumftiter on the set of mappings of + \p enum_field_type which contain + \p value in their range, or \c NULL if + no mappings were found or on error. + +@prenotnull{enum_field_type} +@preisenumft{enum_field_type} +@postrefcountsame{enum_field_type} +@postsuccessrefcountret1 +@post On success, the returned @enumftiter can iterate + on at least one mapping. + +@sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the + mappings of a given enumeration field type which have a given + name. +@sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds + the mappings of a given enumeration field type which contain + a given unsigned value in their range. +*/ +extern struct bt_ctf_field_type_enumeration_mapping_iterator * +bt_ctf_field_type_enumeration_find_mappings_by_signed_value( + struct bt_ctf_field_type *enum_field_type, + int64_t value); + +/** +@brief Finds the mappings of the @enumft \p enum_field_type which + contain the unsigned value \p value in their range. + +This function returns an iterator on the result set of this find +operation. See \ref ctfirenumftmappingiter for more details. + +@param[in] enum_field_type Enumeration field type of which to find + the mappings which contain \p value. +@param[in] value Value to find in the ranges of the + mappings of \p enum_field_type. +@returns @enumftiter on the set of mappings of + \p enum_field_type which contain + \p value in their range, or \c NULL + if no mappings were found or + on error. + +@prenotnull{enum_field_type} +@preisenumft{enum_field_type} +@postrefcountsame{enum_field_type} +@postsuccessrefcountret1 +@post On success, the returned @enumftiter can iterate + on at least one mapping. + +@sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the + mappings of a given enumeration field type which have a given + name. +@sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds + the mappings of a given enumeration field type which contain + a given unsigned value in their range. +*/ +extern struct bt_ctf_field_type_enumeration_mapping_iterator * +bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value( + struct bt_ctf_field_type *enum_field_type, + uint64_t value); + /** @brief Adds a mapping to the @enumft \p enum_field_type which maps the name \p name to the signed range \p range_begin (included) to @@ -1427,6 +1576,7 @@ A mapping in \p enum_field_type can exist with the name \p name. @prenotnull{enum_field_type} @prenotnull{name} +@prehot{enum_field_type} @preisenumft{enum_field_type} @pre The wrapped @intft of \p enum_field_type is signed. @pre \p range_end is greater than or equal to \p range_begin. @@ -1435,10 +1585,13 @@ A mapping in \p enum_field_type can exist with the name \p name. @sa bt_ctf_field_type_enumeration_add_mapping_unsigned(): Adds an unsigned mapping to a given enumeration field type. */ -extern int bt_ctf_field_type_enumeration_add_mapping( +extern int bt_ctf_field_type_enumeration_add_mapping_signed( struct bt_ctf_field_type *enum_field_type, const char *name, int64_t range_begin, int64_t range_end); +/* Pre-2.0 CTF writer compatibility */ +#define bt_ctf_field_type_enumeration_add_mapping bt_ctf_field_type_enumeration_add_mapping_signed + /** @brief Adds a mapping to the @enumft \p enum_field_type which maps the name \p name to the unsigned @@ -1465,12 +1618,13 @@ A mapping in \p enum_field_type can exist with the name \p name. @prenotnull{enum_field_type} @prenotnull{name} +@prehot{enum_field_type} @preisenumft{enum_field_type} @pre The wrapped @intft of \p enum_field_type is unsigned. @pre \p range_end is greater than or equal to \p range_begin. @postrefcountsame{enum_field_type} -@sa bt_ctf_field_type_enumeration_add_mapping(): Adds a signed +@sa bt_ctf_field_type_enumeration_add_mapping_signed(): Adds a signed mapping to a given enumeration field type. */ extern int bt_ctf_field_type_enumeration_add_mapping_unsigned( @@ -1479,6 +1633,167 @@ extern int bt_ctf_field_type_enumeration_add_mapping_unsigned( /** @} */ +/** +@defgroup ctfirenumftmappingiter CTF IR enumeration field type mapping iterator +@ingroup ctfirenumfieldtype +@brief CTF IR enumeration field type mapping iterator. + +@code +#include +@endcode + +A CTF IR enumeration field type mapping +iterator is an iterator on @enumft mappings. + +You can get an enumeration mapping iterator from one of the following +functions: + +- Find operations of an @enumft object: + - bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the + mappings with a given name. + - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): + Finds the mappings which contain a given unsigned value in their + range. + - bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): + Finds the mappings which contain a given signed value in their range. +- bt_ctf_field_enumeration_get_mappings(): Finds the mappings in the + @enumft of an @enumfield containing its current integral value in + their range. + +Those functions guarantee that the returned iterator can iterate on +at least one mapping. Otherwise, they return \c NULL. + +You can get the name and the range of a mapping iterator's current +mapping with +bt_ctf_field_type_enumeration_mapping_iterator_get_signed() +or +bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(), +depending on the signedness of the @intft wrapped by the +@enumft. If you only need the name of the current mapping, you can +use any of the two functions and set the \p range_begin and \p range_end +parameters to \c NULL. + +You can advance an enumeration field type mapping iterator to the next +mapping with +bt_ctf_field_type_enumeration_mapping_iterator_next(). This +function returns a negative value when you reach the end of the +result set. + +As with any Babeltrace object, CTF IR enumeration field type mapping +iterator objects have reference +counts. See \ref refs to learn more about the reference counting +management of Babeltrace objects. + +@sa ctfirenumfieldtype + +@addtogroup ctfirenumftmappingiter +@{ +*/ + +/** +@struct bt_ctf_field_type_enumeration_mapping_iterator +@brief A CTF IR enumeration field type mapping iterator. +@sa ctfirenumftmappingiter +*/ + +/** +@brief Returns the name and the range of the current (signed) mapping + of the @enumftiter \p iter. + +If one of \p range_begin or \p range_end is not \c NULL, the @intft +wrapped by the @enumft from which \p iter was obtained, as returned by +bt_ctf_field_type_enumeration_get_container_type(), must be +\b signed to use this function. Otherwise, if you only need to get the +name of the current mapping, set \p range_begin and \p range_end to +\c NULL. + +On success, if \p name is not \c NULL, \p *name remains valid as long +as \p iter exists and +bt_ctf_field_type_enumeration_mapping_iterator_next() is +\em not called on \p iter. + +@param[in] iter Enumeration field type mapping iterator + of which to get the range of the current + mapping. +@param[out] name Returned name of the current mapping of + \p iter (can be \c NULL to ignore). +@param[out] range_begin Returned beginning of the range + (included) of the current mapping of + \p iter (can be \c NULL to ignore). +@param[out] range_end Returned end of the range + (included) of the current mapping of + \p iter (can be \c NULL to ignore). +@returns 0 on success, or a negative value on error. + +@prenotnull{iter} +@postrefcountsame{iter} + +@sa bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(): + Returns the name and the unsigned range of the current mapping + of a given enumeration field type mapping iterator. +*/ +extern int bt_ctf_field_type_enumeration_mapping_iterator_get_signed( + struct bt_ctf_field_type_enumeration_mapping_iterator *iter, + const char **name, int64_t *range_begin, int64_t *range_end); + +/** +@brief Returns the name and the range of the current (unsigned) mapping + of the @enumftiter \p iter. + +If one of \p range_begin or \p range_end is not \c NULL, the @intft +wrapped by the @enumft from which \p iter was obtained, as returned by +bt_ctf_field_type_enumeration_get_container_type(), must be +\b unsigned to use this function. Otherwise, if you only need to get the +name of the current mapping, set \p range_begin and \p range_end to +\c NULL. + +On success, if \p name is not \c NULL, \p *name remains valid as long +as \p iter exists and +bt_ctf_field_type_enumeration_mapping_iterator_next() is +\em not called on \p iter. + +@param[in] iter Enumeration field type mapping iterator + of which to get the range of the current + mapping. +@param[out] name Returned name of the current mapping of + \p iter (can be \c NULL to ignore). +@param[out] range_begin Returned beginning of the range + (included) of the current mapping of + \p iter (can be \c NULL to ignore). +@param[out] range_end Returned end of the range + (included) of the current mapping of + \p iter (can be \c NULL to ignore). +@returns 0 on success, or a negative value on error. + +@prenotnull{iter} +@postrefcountsame{iter} + +@sa + bt_ctf_field_type_enumeration_mapping_iterator_get_signed(): + Returns the name and the signed range of the current mapping of + a given enumeration field type mapping iterator. +*/ +extern int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned( + struct bt_ctf_field_type_enumeration_mapping_iterator *iter, + const char **name, uint64_t *range_begin, uint64_t *range_end); + +/** +@brief Advances the @enumftiter \p iter to the next mapping. + +@param[in] iter Enumeration field type mapping iterator to + advance. +@returns 0 on success, or a negative value on error or + when you reach the end of the set. + +@prenotnull{iter} +@postrefcountsame{iter} +*/ +extern int bt_ctf_field_type_enumeration_mapping_iterator_next( + struct bt_ctf_field_type_enumeration_mapping_iterator *iter); + +/** @} */ + /** @defgroup ctfirstringfieldtype CTF IR string field type @ingroup ctfirfieldtypes @@ -1628,7 +1943,7 @@ extern struct bt_ctf_field_type *bt_ctf_field_type_structure_create(void); @preisstructft{struct_field_type} @postrefcountsame{struct_field_type} */ -extern int bt_ctf_field_type_structure_get_field_count( +extern int64_t bt_ctf_field_type_structure_get_field_count( struct bt_ctf_field_type *struct_field_type); /** @@ -1662,10 +1977,13 @@ On success, the field's type is placed in \p *field_type if @sa bt_ctf_field_type_structure_get_field_type_by_name(): Finds a structure field type's field by name. */ -extern int bt_ctf_field_type_structure_get_field( +extern int bt_ctf_field_type_structure_get_field_by_index( struct bt_ctf_field_type *struct_field_type, const char **field_name, struct bt_ctf_field_type **field_type, - int index); + uint64_t index); + +/* Pre-2.0 CTF writer compatibility */ +#define bt_ctf_field_type_structure_get_field bt_ctf_field_type_structure_get_field_by_index /** @brief Returns the type of the field named \p field_name found in @@ -1684,7 +2002,7 @@ extern int bt_ctf_field_type_structure_get_field( @postrefcountsame{struct_field_type} @postsuccessrefcountretinc -@sa bt_ctf_field_type_structure_get_field(): Finds a +@sa bt_ctf_field_type_structure_get_field_by_index(): Finds a structure field type's field by index. */ extern @@ -2107,7 +2425,7 @@ extern struct bt_ctf_field_path *bt_ctf_field_type_variant_get_tag_field_path( @preisvarft{variant_field_type} @postrefcountsame{variant_field_type} */ -extern int bt_ctf_field_type_variant_get_field_count( +extern int64_t bt_ctf_field_type_variant_get_field_count( struct bt_ctf_field_type *variant_field_type); /** @@ -2143,10 +2461,13 @@ On success, the field's type is placed in \p *field_type if @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant field type's field by current tag value. */ -extern int bt_ctf_field_type_variant_get_field( +extern int bt_ctf_field_type_variant_get_field_by_index( struct bt_ctf_field_type *variant_field_type, const char **field_name, - struct bt_ctf_field_type **field_type, int index); + struct bt_ctf_field_type **field_type, uint64_t index); + +/* Pre-2.0 CTF writer compatibility */ +#define bt_ctf_field_type_variant_get_field bt_ctf_field_type_variant_get_field_by_index /** @brief Returns the type of the field (choice) named \p field_name @@ -2165,7 +2486,7 @@ extern int bt_ctf_field_type_variant_get_field( @postrefcountsame{variant_field_type} @postsuccessrefcountretinc -@sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's +@sa bt_ctf_field_type_variant_get_field_by_index(): Finds a variant field type's field by index. @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant field type's field by current tag value. @@ -2201,7 +2522,7 @@ bt_ctf_field_type_variant_get_tag_type() for \p variant_field_type. @postrefcountsame{tag_field} @postsuccessrefcountretinc -@sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's +@sa bt_ctf_field_type_variant_get_field_by_index(): Finds a variant field type's field by index. @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant field type's field by name.