X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ffields.h;h=f881e24a59341f1ef0fef13d0ee3233abb6fad6b;hb=9d408fcae74602e3591f66623ceb85f482d948ed;hp=e9f59fb303bf20cad66f32cdb1d1cc7f644246b0;hpb=96e8f959f3f895366c26f945c418a006e6ea397c;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/fields.h b/include/babeltrace/ctf-ir/fields.h index e9f59fb3..f881e24a 100644 --- a/include/babeltrace/ctf-ir/fields.h +++ b/include/babeltrace/ctf-ir/fields.h @@ -33,10 +33,15 @@ #include #include +/* For bt_bool */ +#include + #ifdef __cplusplus extern "C" { #endif +struct bt_ctf_field_type; + /** @defgroup ctfirfields CTF IR fields @ingroup ctfir @@ -83,14 +88,18 @@ contained fields with the following getters if such fields do not exist yet: - bt_ctf_field_enumeration_get_container() -- bt_ctf_field_structure_get_field() +- bt_ctf_field_structure_get_field_by_name() - bt_ctf_field_array_get_field() - bt_ctf_field_sequence_get_field() - bt_ctf_field_variant_get_field() +If you already have a field object, you can also assign it to a specific +name within a @structfield with +bt_ctf_field_structure_set_field_by_name(). + You can get a reference to the @ft which was used to create a field with bt_ctf_field_get_type(). You can get the -\link #bt_ctf_type_id type ID\endlink of this field type directly with +\link #bt_ctf_field_type_id type ID\endlink of this field type directly with bt_ctf_field_get_type_id(). You can get a deep copy of a field with bt_ctf_field_copy(). The field @@ -126,7 +135,7 @@ struct bt_ctf_field; struct bt_ctf_event_class; struct bt_ctf_event; struct bt_ctf_field_type; -struct bt_ctf_field_type_enum_iter; +struct bt_ctf_field_type_enumeration_mapping_iterator; /** @name Creation and parent field type access functions @@ -184,12 +193,12 @@ extern struct bt_ctf_field_type *bt_ctf_field_get_type( @param[in] field Field of which to get the type ID of its parent field type.. @returns Type ID of the parent field type of \p field, - or #BT_CTF_TYPE_ID_UNKNOWN on error. + or #BT_CTF_FIELD_TYPE_ID_UNKNOWN on error. @prenotnull{field} @postrefcountsame{field} -@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_is_integer(): Returns whether or not a given field is a @intfield. @sa bt_ctf_field_is_floating_point(): Returns whether or not a given @@ -207,7 +216,7 @@ extern struct bt_ctf_field_type *bt_ctf_field_get_type( @sa bt_ctf_field_is_variant(): Returns whether or not a given field is a @varfield. */ -extern enum bt_ctf_type_id bt_ctf_field_get_type_id(struct bt_ctf_field *field); +extern enum bt_ctf_field_type_id bt_ctf_field_get_type_id(struct bt_ctf_field *field); /* * bt_ctf_field_signed_integer_get_value: get a signed integer field's value @@ -226,8 +235,8 @@ extern int bt_ctf_field_signed_integer_get_value(struct bt_ctf_field *integer, @brief Returns whether or not the @field \p field is a @intfield. @param[in] field Field to check (can be \c NULL). -@returns 1 if \p field is an integer field, or 0 - otherwise (including if \p field is +@returns #BT_TRUE if \p field is an integer field, or + #BT_FALSE otherwise (including if \p field is \c NULL). @prenotnull{field} @@ -236,14 +245,14 @@ extern int bt_ctf_field_signed_integer_get_value(struct bt_ctf_field *integer, @sa bt_ctf_field_get_type_id(): Returns the type ID of a given field's type. */ -extern int bt_ctf_field_is_integer(struct bt_ctf_field *field); +extern bt_bool bt_ctf_field_is_integer(struct bt_ctf_field *field); /** @brief Returns whether or not the @field \p field is a @floatfield. @param[in] field Field to check (can be \c NULL). -@returns 1 if \p field is a floating point number field, - or 0 otherwise (including if \p field is +@returns #BT_TRUE if \p field is a floating point number fiel + #BT_FALSE or 0 otherwise (including if \p field is \c NULL). @prenotnull{field} @@ -252,14 +261,14 @@ extern int bt_ctf_field_is_integer(struct bt_ctf_field *field); @sa bt_ctf_field_get_type_id(): Returns the type ID of a given field's type. */ -extern int bt_ctf_field_is_floating_point(struct bt_ctf_field *field); +extern bt_bool bt_ctf_field_is_floating_point(struct bt_ctf_field *field); /** @brief Returns whether or not the @field \p field is a @enumfield. @param[in] field Field to check (can be \c NULL). -@returns 1 if \p field is an enumeration field, or 0 - otherwise (including if \p field is +@returns #BT_TRUE if \p field is an enumeration field, or + #BT_FALSE otherwise (including if \p field is \c NULL). @prenotnull{field} @@ -268,14 +277,14 @@ extern int bt_ctf_field_is_floating_point(struct bt_ctf_field *field); @sa bt_ctf_field_get_type_id(): Returns the type ID of a given field's type. */ -extern int bt_ctf_field_is_enumeration(struct bt_ctf_field *field); +extern bt_bool bt_ctf_field_is_enumeration(struct bt_ctf_field *field); /** @brief Returns whether or not the @field \p field is a @stringfield. @param[in] field Field to check (can be \c NULL). -@returns 1 if \p field is a string field, or 0 - otherwise (including if \p field is +@returns #BT_TRUE if \p field is a string field, or + #BT_FALSE otherwise (including if \p field is \c NULL). @prenotnull{field} @@ -284,14 +293,14 @@ extern int bt_ctf_field_is_enumeration(struct bt_ctf_field *field); @sa bt_ctf_field_get_type_id(): Returns the type ID of a given field's type. */ -extern int bt_ctf_field_is_string(struct bt_ctf_field *field); +extern bt_bool bt_ctf_field_is_string(struct bt_ctf_field *field); /** @brief Returns whether or not the @field \p field is a @structfield. @param[in] field Field to check (can be \c NULL). -@returns 1 if \p field is a structure field, or 0 - otherwise (including if \p field is +@returns #BT_TRUE if \p field is a structure field, or + #BT_FALSE otherwise (including if \p field is \c NULL). @prenotnull{field} @@ -300,14 +309,14 @@ extern int bt_ctf_field_is_string(struct bt_ctf_field *field); @sa bt_ctf_field_get_type_id(): Returns the type ID of a given field's type. */ -extern int bt_ctf_field_is_structure(struct bt_ctf_field *field); +extern bt_bool bt_ctf_field_is_structure(struct bt_ctf_field *field); /** @brief Returns whether or not the @field \p field is a @arrayfield. @param[in] field Field to check (can be \c NULL). -@returns 1 if \p field is an array field, or 0 - otherwise (including if \p field is +@returns #BT_TRUE if \p field is an array field, or + #BT_FALSE otherwise (including if \p field is \c NULL). @prenotnull{field} @@ -316,14 +325,14 @@ extern int bt_ctf_field_is_structure(struct bt_ctf_field *field); @sa bt_ctf_field_get_type_id(): Returns the type ID of a given field's type. */ -extern int bt_ctf_field_is_array(struct bt_ctf_field *field); +extern bt_bool bt_ctf_field_is_array(struct bt_ctf_field *field); /** @brief Returns whether or not the @field \p field is a @seqfield. @param[in] field Field to check (can be \c NULL). -@returns 1 if \p field is a sequence field, or 0 - otherwise (including if \p field is +@returns #BT_TRUE if \p field is a sequence field, or + #BT_FALSE otherwise (including if \p field is \c NULL). @prenotnull{field} @@ -332,14 +341,14 @@ extern int bt_ctf_field_is_array(struct bt_ctf_field *field); @sa bt_ctf_field_get_type_id(): Returns the type ID of a given field's type. */ -extern int bt_ctf_field_is_sequence(struct bt_ctf_field *field); +extern bt_bool bt_ctf_field_is_sequence(struct bt_ctf_field *field); /** @brief Returns whether or not the @field \p field is a @varfield. @param[in] field Field to check (can be \c NULL). -@returns 1 if \p field is a variant field, or 0 - otherwise (including if \p field is +@returns #BT_TRUE if \p field is a variant field, or + #BT_FALSE otherwise (including if \p field is \c NULL). @prenotnull{field} @@ -348,7 +357,7 @@ extern int bt_ctf_field_is_sequence(struct bt_ctf_field *field); @sa bt_ctf_field_get_type_id(): Returns the type ID of a given field's type. */ -extern int bt_ctf_field_is_variant(struct bt_ctf_field *field); +extern bt_bool bt_ctf_field_is_variant(struct bt_ctf_field *field); /** @} */ @@ -607,9 +616,9 @@ bt_ctf_field_signed_integer_set_value() or bt_ctf_field_unsigned_integer_set_value(). Once you set the integral value of an enumeration field by following the -previous paragraph, you can get the name of the mapping containing this -value in the enumeration field with -bt_ctf_field_enumeration_get_mapping_name(). +previous paragraph, you can get the mappings containing this value in +their range with bt_ctf_field_enumeration_get_mappings(). This function +returns a @enumftiter. @sa ctfirenumfieldtype @sa ctfirfields @@ -639,27 +648,35 @@ extern struct bt_ctf_field *bt_ctf_field_enumeration_get_container( struct bt_ctf_field *enum_field); /** -@brief Returns the name of the mapping selected by the current integral - value of the @enumfield \p enum_field. - -On success, \p enum_field remains the sole owner of the returned -value. - -@param[in] enum_field Enumeration field of which to get the name of - mapping associated to its current integral - value. -@returns Name of the mapping associated to the current - integral value of \p enum_field, or \c NULL - on error. +@brief Returns a @enumftiter on all the mappings of the field type of + \p enum_field which contain the current integral value of the + @enumfield \p enum_field in their range. + +This function is the equivalent of using +bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value() or +bt_ctf_field_type_enumeration_find_mappings_by_signed_value() with the +current integral value of \p enum_field. + +@param[in] enum_field Enumeration field of which to get the mappings + containing the current integral value of \p + enum_field in their range. +@returns @enumftiter on the set of mappings of the field + type of \p enum_field which contain the current + integral value of \p enum_field in their range, + or \c NULL if no mappings were found or on + error. @prenotnull{enum_field} @preisenumfield{enum_field} @pre The wrapped integer field of \p enum_field contains an integral value. @postrefcountsame{enum_field} +@postsuccessrefcountret1 +@post On success, the returned @enumftiter can iterate + on at least one mapping. */ -extern const char *bt_ctf_field_enumeration_get_mapping_name( - struct bt_ctf_field *enum_field); +extern struct bt_ctf_field_type_enumeration_mapping_iterator * +bt_ctf_field_enumeration_get_mappings(struct bt_ctf_field *enum_field); /** @} */ @@ -815,8 +832,10 @@ contains an ordered list of zero or more named @fields which can be different @fts, and which is described by a @structft. To set the value of a specific field of a structure field, you need to -first get the field with bt_ctf_field_structure_get_field() or -bt_ctf_field_structure_get_field_by_index(). +first get the field with bt_ctf_field_structure_get_field_by_name() or +bt_ctf_field_structure_get_field_by_index(). If you already have a +field object, you can assign it to a specific name within a structure +field with bt_ctf_field_structure_set_field_by_name(). @sa ctfirstructfieldtype @sa ctfirfields @@ -846,10 +865,15 @@ exist. @sa bt_ctf_field_structure_get_field_by_index(): Returns the field of a given structure field by index. +@sa bt_ctf_field_structure_set_field_by_name(): Sets the field of a + given structure field by name. */ -extern struct bt_ctf_field *bt_ctf_field_structure_get_field( +extern struct bt_ctf_field *bt_ctf_field_structure_get_field_by_name( struct bt_ctf_field *struct_field, const char *name); +/* Pre-2.0 CTF writer compatibility */ +#define bt_ctf_field_structure_get_field bt_ctf_field_structure_get_field_by_name + /** @brief Returns the @field at index \p index in the @structfield \p struct_field. @@ -868,11 +892,57 @@ extern struct bt_ctf_field *bt_ctf_field_structure_get_field( @postrefcountsame{struct_field} @postsuccessrefcountretinc -@sa bt_ctf_field_structure_get_field(): Returns the field of a +@sa bt_ctf_field_structure_get_field_by_name(): Returns the field of a + given structure field by name. +@sa bt_ctf_field_structure_set_field_by_name(): Sets the field of a given structure field by name. */ extern struct bt_ctf_field *bt_ctf_field_structure_get_field_by_index( - struct bt_ctf_field *struct_field, int index); + struct bt_ctf_field *struct_field, uint64_t index); + +/** +@brief Sets the field of the @structfield \p struct_field named \p name + to the @field \p field. + +If \p struct_field already contains a field named \p name, then its +reference count is decremented, and \p field replaces it. + +The field type of \p field, as returned by bt_ctf_field_get_type(), +\em must be equivalent to the field type returned by +bt_ctf_field_type_structure_get_field_type_by_name() with the field +type of \p struct_field and the same name, \p name. + +bt_ctf_trace_get_packet_header_type() for the parent trace class of +\p packet. + +@param[in] struct_field Structure field of which to set the field + named \p name. +@param[in] name Name of the field to set in \p struct_field. +@param[in] field Field named \p name to set in \p struct_field. +@returns 0 on success, or -1 on error. + +@prenotnull{struct_field} +@prenotnull{name} +@prenotnull{field} +@prehot{struct_field} +@preisstructfield{struct_field} +@pre \p field has a field type equivalent to the field type returned by + bt_ctf_field_type_structure_get_field_type_by_name() for the + field type of \p struct_field with the name \p name. +@postrefcountsame{struct_field} +@post On success, if there's an existing field in + \p struct_field named \p name, its reference count is + decremented. +@postsuccessrefcountinc{field} + +@sa bt_ctf_field_structure_get_field_by_index(): Returns the field of a + given structure field by index. +@sa bt_ctf_field_structure_get_field_by_name(): Returns the field of a + given structure field by name. +*/ +extern int bt_ctf_field_structure_set_field_by_name( + struct bt_ctf_field *struct_field, + const char *name, struct bt_ctf_field *field); /** @} */ @@ -1125,9 +1195,6 @@ extern struct bt_ctf_field *bt_ctf_field_variant_get_tag( /** @} */ -const char *bt_ctf_field_enumeration_get_single_mapping_name( - struct bt_ctf_field *field); - #ifdef __cplusplus } #endif