#include <stdint.h>
#include <stddef.h>
-#include <babeltrace/values.h>
#ifdef __cplusplus
extern "C" {
#endif
+struct bt_value;
+struct bt_ctf_clock_class;
+
/**
@defgroup ctfirevent CTF IR event
@ingroup ctfir
If the \link ctfirtraceclass CTF IR trace class\endlink of an event
object (parent of its \link ctfirstreamclass CTF IR stream class\endlink,
which is the parent of its event class) was created by a
-\link ctfirwriter CTF IR writer\endlink object, then the only possible
+\link ctfwriter CTF writer\endlink object, then the only possible
action you can do with this event object is to append it to a
\link ctfirstream CTF IR stream\endlink with
bt_ctf_stream_append_event(). Otherwise, you can create an event
On success, the four fields of the created event object are not set. You
can set them with bt_ctf_event_set_header(),
bt_ctf_event_set_stream_event_context(),
-bt_ctf_event_set_event_context(), and bt_ctf_event_set_payload_field().
+bt_ctf_event_set_event_context(), and bt_ctf_event_set_event_payload().
+
+This function tries to resolve the needed
+\link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
+types that are found anywhere in the context or payload field
+types of \p event_class and in the root field types of the
+parent stream class of \p event_class. If any automatic resolving fails,
+this function fails. This means that, if any dynamic field type need
+a field type which should be found in the trace packet header root
+field type, and if the parent stream class of \p event_class was not
+added to a \link ctfirtraceclass CTF IR trace class\endlink yet
+with bt_ctf_trace_add_stream_class(), then this function fails.
@param[in] event_class CTF IR event class to use to create the
CTF IR event.
\p event to the parent stream of \p packet.
@param[in] event Event to which to associate \p packet.
+@param[in] packet Packet to associate to \p event.
@returns 0 on success, or a negative value on error.
@prenotnull{event}
/**
@brief Sets the stream event header field of the CTF IR event
- \p event to \p header.
+ \p event to \p header, or unsets the current stream event header field
+ from \p event.
-The field type of \p header, as returned by bt_ctf_field_get_type(),
-\em must be equivalent to the field type returned by
+If \p header is not \c NULL, the field type of \p header, as returned by
+bt_ctf_field_get_type(), \em must be equivalent to the field type returned by
bt_ctf_stream_class_get_event_header_type() for the parent stream class
of \p event.
@returns 0 on success, or a negative value on error.
@prenotnull{event}
-@prenotnull{header}
@prehot{event}
-@pre \p header has a field type equivalent to the field type returned by
- bt_ctf_stream_class_get_event_header_type() for the parent
- stream class of \p event.
+@pre <strong>\p header, if not \c NULL</strong>, has a field type equivalent to
+ the field type returned by bt_ctf_stream_class_get_event_header_type()
+ for the parent stream class of \p event.
@postrefcountsame{event}
-@postsuccessrefcountinc{header}
+@post <strong>On success, if \p header is not \c NULL</strong>,
+ the reference count of \p header is incremented.
@sa bt_ctf_event_get_header(): Returns the stream event header field
of a given event.
@postrefcountsame{event}
@postsuccessrefcountretinc
-@sa bt_ctf_event_set_stream_event_context(): Sets the stream event
- context field of a given event.
+@sa bt_ctf_event_set_stream_event_context(): Sets the stream event context
+ field of a given event.
*/
extern struct bt_ctf_field *bt_ctf_event_get_stream_event_context(
struct bt_ctf_event *event);
/**
@brief Sets the stream event context field of the CTF IR event
- \p event to \p context.
+ \p event to \p context, or unsets the current stream event context field
+ from \p event.
-The field type of \p context, as returned by bt_ctf_field_get_type(),
-\em must be equivalent to the field type returned by
+If \p context is not \c NULL, the field type of \p context, as returned by
+bt_ctf_field_get_type(), \em must be equivalent to the field type returned by
bt_ctf_stream_class_get_event_context_type() for the parent stream class
of \p event.
-@param[in] event Event of which to set the stream event context
- field.
+@param[in] event Event of which to set the stream event context field.
@param[in] context Stream event context field.
@returns 0 on success, or a negative value on error.
@prenotnull{event}
-@prenotnull{context}
@prehot{event}
-@pre \p context has a field type equivalent to the field type returned
- by bt_ctf_stream_class_get_event_context_type() for the parent
- stream class of \p event.
+@pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
+ the field type returned by bt_ctf_stream_class_get_event_context_type()
+ for the parent stream class of \p event.
@postrefcountsame{event}
-@postsuccessrefcountinc{context}
+@post <strong>On success, if \p context is not \c NULL</strong>, the reference
+ count of \p context is incremented.
-@sa bt_ctf_event_get_stream_event_context(): Returns the stream event
- context field of a given event.
+@sa bt_ctf_event_get_stream_event_context(): Returns the stream event context
+ field of a given event.
*/
extern int bt_ctf_event_set_stream_event_context(struct bt_ctf_event *event,
struct bt_ctf_field *context);
/**
-@brief Returns the event context field of the CTF IR event
- \p event.
+@brief Returns the event context field of the CTF IR event \p event.
-@param[in] event Event of which to get the event context
- field.
-@returns Event context field of \p event, or \c NULL if
- the event context field is not set or on error.
+@param[in] event Event of which to get the context field.
+@returns Event context field of \p event, or \c NULL if the
+ event context field is not set or on error.
@prenotnull{event}
@postrefcountsame{event}
@postsuccessrefcountretinc
-@sa bt_ctf_event_set_event_context(): Sets the event context field of a
- given event.
+@sa bt_ctf_event_set_event_context(): Sets the event context field of a given
+ event.
*/
extern struct bt_ctf_field *bt_ctf_event_get_event_context(
struct bt_ctf_event *event);
/**
-@brief Sets the event context field of the CTF IR event
- \p event to \p context.
+@brief Sets the event context field of the CTF IR event \p event to \p context,
+ or unsets the current event context field from \p event.
-The field type of \p context, as returned by bt_ctf_field_get_type(),
-\em must be equivalent to the field type returned by
-bt_ctf_event_class_get_context_type() for the parent event class
-of \p event.
+If \p context is not \c NULL, the field type of \p context, as returned by
+bt_ctf_field_get_type(), \em must be equivalent to the field type returned by
+bt_ctf_event_class_get_context_type() for the parent class of \p event.
-@param[in] event Event of which to set the event context field.
+@param[in] event Event of which to set the context field.
@param[in] context Event context field.
@returns 0 on success, or a negative value on error.
@prenotnull{event}
-@prenotnull{context}
@prehot{event}
-@pre \p context has a field type equivalent to the field type returned
- by bt_ctf_event_class_get_context_type() for the parent
- event class of \p event.
+@pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
+ the field type returned by bt_ctf_event_class_get_context_type() for the
+ parent class of \p event.
@postrefcountsame{event}
-@postsuccessrefcountinc{context}
+@post <strong>On success, if \p context is not \c NULL</strong>, the reference
+ count of \p context is incremented.
-@sa bt_ctf_event_get_event_context(): Returns the event context field of
- a given event.
+@sa bt_ctf_event_get_context(): Returns the context field of a given event.
*/
extern int bt_ctf_event_set_event_context(struct bt_ctf_event *event,
struct bt_ctf_field *context);
/**
-@brief Returns the event payload field of the CTF IR event
- \p event.
+@brief Returns the payload field of the CTF IR event \p event.
-@param[in] event Event of which to get the event payload
- field.
-@returns Event payload field of \p event, or \c NULL if
- the event payload field is not set or on error.
+@param[in] event Event of which to get the payload field.
+@returns Payload field of \p event, or \c NULL if the payload
+ field is not set or on error.
@prenotnull{event}
@postrefcountsame{event}
@postsuccessrefcountretinc
-@sa bt_ctf_event_set_payload_field(): Sets the event payload field of a
- given event.
+@sa bt_ctf_event_set_event_payload(): Sets the payload field of a given
+ event.
*/
-extern struct bt_ctf_field *bt_ctf_event_get_payload_field(
+extern struct bt_ctf_field *bt_ctf_event_get_event_payload(
struct bt_ctf_event *event);
/**
-@brief Sets the event payload field of the CTF IR event
- \p event to \p payload.
+@brief Sets the payload field of the CTF IR event \p event to \p payload,
+ or unsets the current event payload field from \p event.
-The field type of \p payload, as returned by bt_ctf_field_get_type(),
-\em must be equivalent to the field type returned by
-bt_ctf_event_class_get_payload_type() for the parent event class
-of \p event.
+If \p payload is not \c NULL, the field type of \p payload, as returned by
+bt_ctf_field_get_type(), \em must be equivalent to the field type returned by
+bt_ctf_event_class_get_payload_type() for the parent class of \p event.
-@param[in] event Event of which to set the event payload field.
+@param[in] event Event of which to set the payload field.
@param[in] payload Event payload field.
@returns 0 on success, or a negative value on error.
@prenotnull{event}
-@prenotnull{payload}
@prehot{event}
-@pre \p payload has a field type equivalent to the field type returned
- by bt_ctf_event_class_get_payload_type() for the parent
- event class of \p event.
+@pre <strong>\p payload, if not \c NULL</strong>, has a field type equivalent to
+ the field typereturned by bt_ctf_event_class_get_payload_type() for the
+ parent class of \p event.
@postrefcountsame{event}
-@postsuccessrefcountinc{payload}
+@post <strong>On success, if \p payload is not \c NULL</strong>, the reference
+ count of \p payload is incremented.
-@sa bt_ctf_event_get_payload_field(): Returns the event payload field of
- a given event.
+@sa bt_ctf_event_get_payload(): Returns the payload field of a given event.
*/
-extern int bt_ctf_event_set_payload_field(struct bt_ctf_event *event,
+extern int bt_ctf_event_set_event_payload(struct bt_ctf_event *event,
struct bt_ctf_field *payload);
-/**
-@cond DOCUMENT
-*/
+/** @cond DOCUMENT */
/*
* TODO: Doxygenize.
* Note: Will return an error if the payload's type is not a structure.
*/
extern struct bt_ctf_field *bt_ctf_event_get_payload_by_index(
- struct bt_ctf_event *event, int index);
+ struct bt_ctf_event *event, uint64_t index);
/*
* TODO: Doxygenize.
const char *name,
struct bt_ctf_field *value);
-/**
-@endcond
-*/
+/** @endcond */
/** @} */
@sa bt_ctf_event_set_clock_value(): Sets the clock value of a given event.
*/
extern struct bt_ctf_clock_value *bt_ctf_event_get_clock_value(
- struct bt_ctf_event *event, struct bt_ctf_clock *clock_class);
+ struct bt_ctf_event *event,
+ struct bt_ctf_clock_class *clock_class);
/**
@brief Sets the value, as of the CTF IR event \p event, of the
- clock described by the
- \link ctfirclockclass CTF IR clock class\endlink \p clock_class.
+ clock described by its \link ctfirclockclass CTF IR
+ clock class\endlink.
@param[in] event Event of which to set the value of the clock
- described by \p clock_class.
-@param[in] clock_class Class of the clock of which to set the value
- for \p event.
-@param[in] clock_value Value of the clock described by \p clock_class
+ described by the clock class of \p clock_value.
+@param[in] clock_value Value of the clock described by its clock class
as of \p event.
@returns 0 on success, or a negative value on error.
@prenotnull{event}
-@prenotnull{clock_class}
@prenotnull{clock_value}
@prehot{event}
@postrefcountsame{event}
-@postrefcountsame{clock_class}
@sa bt_ctf_event_get_clock_value(): Returns the clock value of
a given event.
*/
extern int bt_ctf_event_set_clock_value(
- struct bt_ctf_event *event, struct bt_ctf_clock *clock_class,
+ struct bt_ctf_event *event,
struct bt_ctf_clock_value *clock_value);
/** @} */
projects / babeltrace.git / blobdiff