X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Fstream-class.h;h=3d570eaa6c9ea0881d60cb8e97d1b8ffd3d362b7;hb=dfeca116599b64d433239305d43800103eba48c7;hp=40dbf819992259903b54676297d57953511364b4;hpb=c2f29fb98a1e9088434fe8872d68695afd8e9dd3;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/stream-class.h b/include/babeltrace/ctf-ir/stream-class.h index 40dbf819..3d570eaa 100644 --- a/include/babeltrace/ctf-ir/stream-class.h +++ b/include/babeltrace/ctf-ir/stream-class.h @@ -47,8 +47,8 @@ extern "C" { @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 stream class is a template that you can use to create concrete \link ctfirstream CTF IR streams\endlink. @@ -104,7 +104,7 @@ success: - 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: @@ -116,7 +116,7 @@ except for: @sa ctfirstream @sa ctfireventclass @sa ctfirtraceclass -@sa ctfirwriterstreamclass +@sa ctfwriterstreamclass @file @brief CTF IR stream class type and functions. @@ -296,11 +296,13 @@ extern int bt_ctf_stream_class_set_id( @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 On success, if the return value is a field type, 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. @@ -310,22 +312,29 @@ extern struct bt_ctf_field_type *bt_ctf_stream_class_get_packet_context_type( /** @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 \p packet_context_type, if not \c NULL, is a CTF IR + structure field type. @postrefcountsame{stream_class} -@postsuccessrefcountinc{packet_context_type} +@post On success, if \p packet_context_type is not \c NULL, + 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. @@ -341,11 +350,13 @@ extern int bt_ctf_stream_class_set_packet_context_type( @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 On success, if the return value is a field type, 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. @@ -356,73 +367,88 @@ bt_ctf_stream_class_get_event_header_type( /** @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 \p event_header_type, if not \c NULL, is a CTF IR + structure field type. @postrefcountsame{stream_class} -@postsuccessrefcountinc{event_header_type} +@post On success, if \p event_header_type is not \c NULL, + 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 On success, if the return value is a field type, + 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 \p event_context_type, if not \c NULL, is a CTF IR + structure field type. @postrefcountsame{stream_class} -@postsuccessrefcountinc{event_context_type} +@post On success, if \p event_context_type is not \c NULL, + 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, @@ -526,6 +552,20 @@ You can call this function even if \p stream_class is frozen. Adding 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. @@ -573,7 +613,7 @@ extern int bt_ctf_stream_class_visit(struct bt_ctf_stream_class *stream_class, /** @} */ -// 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);