@endcode
@note
-See \ref ctfirwriterstreamclass which documents additional CTF IR stream
-class functions exclusive to the CTF IR writer mode.
+See \ref ctfwriterstreamclass which documents additional CTF IR stream
+class functions exclusive to the CTF writer mode.
A CTF IR <strong><em>stream class</em></strong> is a template that you
can use to create concrete \link ctfirstream CTF IR streams\endlink.
- bt_ctf_trace_add_stream_class()
- bt_ctf_event_create()
- bt_ctf_writer_create_stream()
- (\link ctfirwriter CTF IR writer\endlink mode only)
+ (\link ctfwriter CTF writer\endlink mode only)
You cannot modify a frozen stream class: it is considered immutable,
except for:
@sa ctfirstream
@sa ctfireventclass
@sa ctfirtraceclass
-@sa ctfirwriterstreamclass
+@sa ctfwriterstreamclass
@file
@brief CTF IR stream class type and functions.
@param[in] stream_class Stream class of which to get the packet
context field type.
@returns Packet context field type of \p stream_class,
- or \c NULL on error.
+ or \c NULL if \p stream_class has no packet context
+ field type or on error.
@prenotnull{stream_class}
@postrefcountsame{stream_class}
-@postsuccessrefcountretinc
+@post <strong>On success, if the return value is a field type</strong>, its
+ reference count is incremented.
@sa bt_ctf_stream_class_set_packet_context_type(): Sets the packet
context field type of a given stream class.
/**
@brief Sets the packet context field type of the CTF IR stream class
- \p stream_class to \p packet_context_type.
+ \p stream_class to \p packet_context_type, or unsets the current packet
+ context field type from \p stream_class.
+
+If \p packet_context_type is \c NULL, then this function unsets the current
+packet context field type from \p stream_class, effectively making
+\p stream_class a stream class without a packet context field type.
-As of Babeltrace \btversion, \p packet_context_type \em must be a
-CTF IR structure field type object.
+As of Babeltrace \btversion, if \p packet_context_type is not \c NULL,
+\p packet_context_type \em must be a CTF IR structure field type object.
@param[in] stream_class Stream class of which to set the packet
context field type.
-@param[in] packet_context_type Packet context field type.
+@param[in] packet_context_type Packet context field type, or \c NULL to unset
+ the current packet context field type.
@returns 0 on success, or a negative value on error.
@prenotnull{stream_class}
-@prenotnull{packet_context_type}
@prehot{stream_class}
-@preisstructft{packet_context_type}
+@pre <strong>\p packet_context_type, if not \c NULL</strong>, is a CTF IR
+ structure field type.
@postrefcountsame{stream_class}
-@postsuccessrefcountinc{packet_context_type}
+@post <strong>On success, if \p packet_context_type is not \c NULL</strong>,
+ the reference count of \p packet_context_type is incremented.
@sa bt_ctf_stream_class_get_packet_context_type(): Returns the packet
context field type of a given stream class.
@param[in] stream_class Stream class of which to get the event header
field type.
@returns Event header field type of \p stream_class,
- or \c NULL on error.
+ or \c NULL if \p stream_class has no event header field
+ type or on error.
@prenotnull{stream_class}
@postrefcountsame{stream_class}
-@postsuccessrefcountretinc
+@post <strong>On success, if the return value is a field type</strong>, its
+ reference count is incremented.
@sa bt_ctf_stream_class_set_event_header_type(): Sets the event
header field type of a given stream class.
/**
@brief Sets the event header field type of the CTF IR stream class
- \p stream_class to \p event_header_type.
+ \p stream_class to \p event_header_type, or unsets the current event
+ header field type from \p stream_class.
+
+If \p event_header_type is \c NULL, then this function unsets the current
+event header field type from \p stream_class, effectively making \p stream_class
+a stream class without a event header field type.
-As of Babeltrace \btversion, \p event_header_type \em must be a
-CTF IR structure field type object.
+As of Babeltrace \btversion, if \p event_header_type is not \c NULL,
+\p event_header_type \em must be a CTF IR structure field type object.
-@param[in] stream_class Stream class of which to set the event
+@param[in] trace_class Trace class of which to set the packet
header field type.
-@param[in] event_header_type Event header field type.
+@param[in] event_header_type Event header field type, or \c NULL to unset
+ the current event header field type.
@returns 0 on success, or a negative value on error.
@prenotnull{stream_class}
-@prenotnull{event_header_type}
@prehot{stream_class}
-@preisstructft{event_header_type}
+@pre <strong>\p event_header_type, if not \c NULL</strong>, is a CTF IR
+ structure field type.
@postrefcountsame{stream_class}
-@postsuccessrefcountinc{event_header_type}
+@post <strong>On success, if \p event_header_type is not \c NULL</strong>,
+ the reference count of \p event_header_type is incremented.
-@sa bt_ctf_stream_class_get_event_header_type(): Returns the event
- header field type of a given stream class.
+@sa bt_ctf_trace_get_packet_header_type(): Returns the packet
+ header field type of a given trace class.
*/
extern int bt_ctf_stream_class_set_event_header_type(
struct bt_ctf_stream_class *stream_class,
struct bt_ctf_field_type *event_header_type);
/**
-@brief Returns the per-stream class event context field type of the
- CTF IR stream class \p stream_class.
+@brief Returns the event context field type of the CTF IR stream class
+ \p stream_class.
-@param[in] stream_class Stream class of which to get the per-stream
- class event context field type.
-@returns Per-stream class event context field type of
- \p stream_class, or \c NULL on error.
+@param[in] stream_class Stream class of which to get the event context
+ field type.
+@returns Event context field type of \p stream_class,
+ or \c NULL if \p stream_class has no event context field
+ type or on error.
@prenotnull{stream_class}
@postrefcountsame{stream_class}
-@postsuccessrefcountretinc
+@post <strong>On success, if the return value is a field type</strong>,
+ its reference count is incremented.
+
-@sa bt_ctf_stream_class_set_event_context_type(): Sets the per-stream
- class event context field type of a given stream class.
+@sa bt_ctf_stream_class_set_event_context_type(): Sets the event
+ context field type of a given stream class.
*/
extern struct bt_ctf_field_type *
bt_ctf_stream_class_get_event_context_type(
struct bt_ctf_stream_class *stream_class);
/**
-@brief Sets the per-stream class event context field type of the CTF
- IR stream class \p stream_class to \p event_context_type.
+@brief Sets the event context field type of the CTF IR stream class
+ \p stream_class to \p event_context_type, or unsets the current event
+ context field type from \p stream_class.
+
+If \p event_context_type is \c NULL, then this function unsets the current
+event context field type from \p stream_class, effectively making \p
+stream_class a stream class without a event context field type.
-As of Babeltrace \btversion, \p event_context_type \em must be a
-CTF IR structure field type object.
+As of Babeltrace \btversion, if \p event_context_type is not \c NULL,
+\p event_context_type \em must be a CTF IR structure field type object.
-@param[in] stream_class Stream class of which to set the
- per-stream class event context
- field type.
-@param[in] event_context_type Per-stream class event context context
- field type.
+@param[in] stream_class Stream class of which to set the packet
+ context field type.
+@param[in] event_context_type Event context field type, or \c NULL to unset
+ the current event context field type.
@returns 0 on success, or a negative value on error.
@prenotnull{stream_class}
-@prenotnull{event_context_type}
@prehot{stream_class}
-@preisstructft{event_context_type}
+@pre <strong>\p event_context_type, if not \c NULL</strong>, is a CTF IR
+ structure field type.
@postrefcountsame{stream_class}
-@postsuccessrefcountinc{event_context_type}
+@post <strong>On success, if \p event_context_type is not \c NULL</strong>,
+ the reference count of \p event_context_type is incremented.
-@sa bt_ctf_stream_class_get_event_context_type(): Returns the per-stream
- class event context field type of a given stream class.
+@sa bt_ctf_stream_class_get_event_context_type(): Returns the event context
+ field type of a given stream class.
*/
extern int bt_ctf_stream_class_set_event_context_type(
struct bt_ctf_stream_class *stream_class,
event classes is the only operation that is permitted
on a frozen stream class.
+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. If any automatic resolving fails:
+
+- If the needed field type should be found in one of the root field
+ types of \p event_class or \p stream_class, this function fails.
+- If \p stream_class is the child of a
+ \link ctfirtraceclass CTF IR trace class\endlink (it was added
+ with bt_ctf_trace_add_stream_class()), this function fails.
+- If \p stream_class is not the child of a trace class yet, the
+ automatic resolving is reported to the next call to
+ bt_ctf_trace_add_stream_class() with \p stream_class.
+
@param[in] stream_class Stream class to which to add \p event_class.
@param[in] event_class Event class to add to \p stream_class.
@returns 0 on success, or a negative value on error.
/** @} */
-// TODO: document for writer
+// TODO: document for CTF writer
extern struct bt_ctf_clock *bt_ctf_stream_class_get_clock(
struct bt_ctf_stream_class *stream_class);
projects / babeltrace.git / blobdiff