X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ffields.h;h=a6250ed7ab7f1b10b3ede5ae0cdd1276a5fe0cc8;hb=53d65c1d23e2098901c411d670d87d40509c0f9f;hp=536a88f57da3e08a5dd4e6523cb7f7093621bd36;hpb=91f379cba8cebdfab3791c93d95c45c450e8a818;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/fields.h b/include/babeltrace/ctf-ir/fields.h index 536a88f5..a6250ed7 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,6 +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_enumeration_mapping_iterator; /** @name Creation and parent field type access functions @@ -183,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 @@ -206,14 +216,33 @@ 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); + + +extern bt_bool bt_ctf_field_is_set(struct bt_ctf_field *field); + +extern int bt_ctf_field_reset(struct bt_ctf_field *field); + +/* + * bt_ctf_field_signed_integer_get_value: get a signed integer field's value + * + * Get a signed integer field's value. + * + * @param integer Signed integer field instance. + * @param value Pointer to a signed integer where the value will be stored. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_signed_integer_get_value(struct bt_ctf_field *integer, + int64_t *value); /** @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} @@ -222,14 +251,14 @@ extern enum bt_ctf_type_id bt_ctf_field_get_type_id(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_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} @@ -238,14 +267,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} @@ -254,14 +283,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} @@ -270,14 +299,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} @@ -286,14 +315,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} @@ -302,14 +331,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} @@ -318,14 +347,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} @@ -334,7 +363,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); /** @} */ @@ -593,9 +622,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 @@ -625,27 +654,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); /** @} */ @@ -801,8 +838,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 @@ -832,10 +871,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. @@ -854,11 +898,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 it may +either be replaced by \p field and its reference count is decremented, +or \p field's value is assigned to 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, the field in \p struct_field named \p name + may either be replaced by \p field or have the same value as \p field. +@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); /** @} */