From 6b783f49d30fd41d5cace9b72730281b8b7d97fd Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=A9mie=20Galarneau?= Date: Fri, 25 Nov 2016 16:11:50 -0500 Subject: [PATCH] Docs: allow NULL packet, stream and event headers, contexts and payloads MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Jérémie Galarneau --- include/babeltrace/ctf-ir/event-class.h | 94 +++++++++-------- include/babeltrace/ctf-ir/event.h | 125 +++++++++++------------ include/babeltrace/ctf-ir/packet.h | 63 ++++++------ include/babeltrace/ctf-ir/stream-class.h | 114 +++++++++++++-------- include/babeltrace/ctf-ir/trace.h | 27 +++-- 5 files changed, 232 insertions(+), 191 deletions(-) diff --git a/include/babeltrace/ctf-ir/event-class.h b/include/babeltrace/ctf-ir/event-class.h index 12e31fcb..16fbcfb3 100644 --- a/include/babeltrace/ctf-ir/event-class.h +++ b/include/babeltrace/ctf-ir/event-class.h @@ -364,42 +364,49 @@ extern int bt_ctf_event_class_set_attribute( @brief Returns the context field type of the CTF IR event class \p event_class. -@param[in] event_class Event class of which to get the - context field type. -@returns Context field type of \p event_class, - or \c NULL on error. +@param[in] event_class Event class of which to get the context field type. +@returns Context field type of \p event_class, or \c NULL if + \p event_class has no context field type or on error. @prenotnull{event_class} @postrefcountsame{event_class} -@postsuccessrefcountretinc +@post On success, if the return value is a field type, its + reference count is incremented. -@sa bt_ctf_event_class_set_context_type(): Sets the context field - type of a given event class. +@sa bt_ctf_event_class_set_context_type(): Sets the context field type of a + given event class. */ extern struct bt_ctf_field_type *bt_ctf_event_class_get_context_type( struct bt_ctf_event_class *event_class); /** -@brief Sets the context field type of the CTF IR event class - \p event_class to \p context_type. +@brief Sets the context field type of the CTF IR event class \p event_class to + \p context_type, or unsets the current context field type from + \p event_class. -As of Babeltrace \btversion, \p context_type \em must be a -CTF IR structure field type object. +If \p context_type is \c NULL, then this function unsets the current context +field type from \p event_class, effectively making \p event_class an event class +without a context field type. -@param[in] event_class Event class of which to set the context - field type. -@param[in] context_type Context field type. -@returns 0 on success, or a negative value on error. +As of Babeltrace \btversion, if \p context_type is not \c NULL, +\p context_type \em must be a CTF IR structure field type object. + +@param[in] event_class Event class of which to set the context field + type. +@param[in] context_type Context field type, or \c NULL to unset the + current context field type. +@returns 0 on success, or a negative value on error. @prenotnull{event_class} -@prenotnull{context_type} @prehot{event_class} -@preisstructft{context_type} +@pre If \p context_type is not \c NULL, \p context_type is a + CTF IR structure field type. @postrefcountsame{event_class} -@postsuccessrefcountinc{context_type} +@post On success, if \p context_type is not \c NULL, + the reference count of \p context_type is incremented. -@sa bt_ctf_event_class_get_context_type(): Returns the context field - type of a given event class. +@sa bt_ctf_event_class_get_context_type(): Returns the context field type of a + given event class. */ extern int bt_ctf_event_class_set_context_type( struct bt_ctf_event_class *event_class, @@ -409,42 +416,49 @@ extern int bt_ctf_event_class_set_context_type( @brief Returns the payload field type of the CTF IR event class \p event_class. -@param[in] event_class Event class of which to get the - payload field type. -@returns Payload field type of \p event_class, - or \c NULL on error. +@param[in] event_class Event class of which to get the payload field type. +@returns Payload field type of \p event_class, or \c NULL if + \p event_class has no payload field type or on error. @prenotnull{event_class} @postrefcountsame{event_class} -@postsuccessrefcountretinc +@post On success, if the return value is a field type, its + reference count is incremented. -@sa bt_ctf_event_class_set_payload_type(): Sets the payload field - type of a given event class. +@sa bt_ctf_event_class_set_payload_type(): Sets the payload field type of a + given event class. */ extern struct bt_ctf_field_type *bt_ctf_event_class_get_payload_type( struct bt_ctf_event_class *event_class); /** -@brief Sets the payload field type of the CTF IR event class - \p event_class to \p payload_type. +@brief Sets the payload field type of the CTF IR event class \p event_class to + \p payload_type, or unsets the current payload field type from + \p event_class. -As of Babeltrace \btversion, \p payload_type \em must be a -CTF IR structure field type object. +If \p payload_type is \c NULL, then this function unsets the current payload +field type from \p event_class, effectively making \p event_class an event class +without a payload field type. -@param[in] event_class Event class of which to set the payload - field type. -@param[in] payload_type Payload field type. -@returns 0 on success, or a negative value on error. +As of Babeltrace \btversion, if \p payload_type is not \c NULL, +\p payload_type \em must be a CTF IR structure field type object. + +@param[in] event_class Event class of which to set the payload field + type. +@param[in] payload_type Payload field type, or \c NULL to unset the + current payload field type. +@returns 0 on success, or a negative value on error. @prenotnull{event_class} -@prenotnull{payload_type} @prehot{event_class} -@preisstructft{payload_type} +@pre If \p payload_type is not \c NULL, \p payload_type is a + CTF IR structure field type. @postrefcountsame{event_class} -@postsuccessrefcountinc{payload_type} +@post On success, if \p payload_type is not \c NULL, + the reference count of \p payload_type is incremented. -@sa bt_ctf_event_class_get_payload_type(): Returns the payload field - type of a given event class. +@sa bt_ctf_event_class_get_payload_type(): Returns the payload field type of a + given event class. */ extern int bt_ctf_event_class_set_payload_type( struct bt_ctf_event_class *event_class, diff --git a/include/babeltrace/ctf-ir/event.h b/include/babeltrace/ctf-ir/event.h index 64cd68f2..1f73b267 100644 --- a/include/babeltrace/ctf-ir/event.h +++ b/include/babeltrace/ctf-ir/event.h @@ -279,10 +279,11 @@ extern struct bt_ctf_field *bt_ctf_event_get_header( /** @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. @@ -292,13 +293,13 @@ 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 \p header, if not \c NULL, 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 On success, if \p header is not \c NULL, + the reference count of \p header is incremented. @sa bt_ctf_event_get_header(): Returns the stream event header field of a given event. @@ -320,131 +321,123 @@ extern int bt_ctf_event_set_header(struct bt_ctf_event *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 \p context, if not \c NULL, 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 On success, if \p context is not \c NULL, 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 \p context, if not \c NULL, 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 On success, if \p context is not \c NULL, 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_payload_field(): Sets the payload field of a given + event. */ extern struct bt_ctf_field *bt_ctf_event_get_payload_field( 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 \p payload, if not \c NULL, 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 On success, if \p payload is not \c NULL, 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, struct bt_ctf_field *payload); diff --git a/include/babeltrace/ctf-ir/packet.h b/include/babeltrace/ctf-ir/packet.h index 81ca4c20..72f5068a 100644 --- a/include/babeltrace/ctf-ir/packet.h +++ b/include/babeltrace/ctf-ir/packet.h @@ -162,30 +162,30 @@ extern struct bt_ctf_field *bt_ctf_packet_get_header( struct bt_ctf_packet *packet); /** -@brief Sets the trace packet header field of the CTF IR packet - \p packet to \p header. +@brief Sets the trace packet header field of the CTF IR packet \p packet to + \p header, or unsets the current trace packet header field from + \p packet. -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_trace_get_packet_header_type() for the parent trace class -of \p packet. +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_trace_get_packet_header_type() for the parent trace class of +\p packet. -@param[in] packet Packet of which to set the trace packet header - field. +@param[in] packet Packet of which to set the trace packet header field. @param[in] header Trace packet header field. @returns 0 on success, or a negative value on error. @prenotnull{packet} -@prenotnull{header} @prehot{packet} -@pre \p header has a field type equivalent to the field type returned by - bt_ctf_trace_get_packet_header_type() for the parent trace class - of \p packet. -@postrefcountsame{packet} -@postsuccessrefcountinc{header} - -@sa bt_ctf_packet_get_header(): Returns the trace packet header field - of a given packet. +@pre \p header, if not \c NULL, has a field type equivalent to + the field type returned by bt_ctf_trace_get_packet_header_type() for the + parent trace class of \p packet. +@postrefcountsame{event} +@post On success, if \p header is not \c NULL, the reference + count of \p header is incremented. + +@sa bt_ctf_packet_get_header(): Returns the trace packet header field of a given + packet. */ extern int bt_ctf_packet_set_header( struct bt_ctf_packet *packet, struct bt_ctf_field *header); @@ -211,30 +211,29 @@ extern struct bt_ctf_field *bt_ctf_packet_get_context( struct bt_ctf_packet *packet); /** -@brief Sets the stream packet context field of the CTF IR packet - \p packet to \p context. +@brief Sets the stream packet context field of the CTF IR packet \p packet to + \p context, or unsets the current packet context field from \p packet. -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_packet_context_type() for the parent stream -class of \p packet. +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_packet_context_type() for the parent stream class of +\p packet. -@param[in] packet Packet of which to set the stream packet context - field. +@param[in] packet Packet of which to set the stream packet context field. @param[in] context Stream packet context field. @returns 0 on success, or a negative value on error. @prenotnull{packet} -@prenotnull{context} @prehot{packet} -@pre \p context has a field type equivalent to the field type returned - by bt_ctf_stream_class_get_packet_context_type() for the parent - stream class of \p packet. +@pre \p context, if not \c NULL, has a field type equivalent to + the field type returned by bt_ctf_stream_class_get_packet_context_type() + for the parent stream class of \p packet. @postrefcountsame{packet} -@postsuccessrefcountinc{context} +@post On success, if \p context is not \c NULL, the reference + count of \p context is incremented. -@sa bt_ctf_packet_get_context(): Returns the stream packet context field - of a given packet. +@sa bt_ctf_packet_get_context(): Returns the stream packet context field of a + given packet. */ extern int bt_ctf_packet_set_context( struct bt_ctf_packet *packet, struct bt_ctf_field *context); diff --git a/include/babeltrace/ctf-ir/stream-class.h b/include/babeltrace/ctf-ir/stream-class.h index d2b16ded..ed82b848 100644 --- a/include/babeltrace/ctf-ir/stream-class.h +++ b/include/babeltrace/ctf-ir/stream-class.h @@ -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. -As of Babeltrace \btversion, \p event_context_type \em must be a -CTF IR structure field type object. +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. -@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. +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 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, diff --git a/include/babeltrace/ctf-ir/trace.h b/include/babeltrace/ctf-ir/trace.h index 840ebf37..ba6b28cd 100644 --- a/include/babeltrace/ctf-ir/trace.h +++ b/include/babeltrace/ctf-ir/trace.h @@ -478,11 +478,13 @@ extern int bt_ctf_trace_set_environment_field_string( @param[in] trace_class Trace class of which to get the packet header field type. @returns Packet header field type of \p trace_class, - or \c NULL on error. + or \c NULL if \p trace_class has no packet header field + type or on error. @prenotnull{trace_class} @postrefcountsame{trace_class} -@postsuccessrefcountretinc +@post On success, if the return value is a field type, its + reference count is incremented. @sa bt_ctf_trace_set_packet_header_type(): Sets the packet header field type of a given trace class. @@ -492,22 +494,29 @@ extern struct bt_ctf_field_type *bt_ctf_trace_get_packet_header_type( /** @brief Sets the packet header field type of the CTF IR trace class - \p trace_class to \p packet_context_type. + \p trace_class to \p packet_header_type, or unsets the current packet + header field type from \p trace_class. + +If \p packet_header_type is \c NULL, then this function unsets the current +packet header field type from \p trace_class, effectively making \p trace_class +a trace without a packet header 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_header_type is not \c NULL, +\p packet_header_type \em must be a CTF IR structure field type object. @param[in] trace_class Trace class of which to set the packet header field type. -@param[in] packet_header_type Packet header field type. +@param[in] packet_header_type Packet header field type, or \c NULL to unset + the current packet header field type. @returns 0 on success, or a negative value on error. @prenotnull{trace_class} -@prenotnull{packet_header_type} @prehot{trace_class} -@preisstructft{packet_header_type} +@pre \p packet_header_type, if not \c NULL, is a CTF IR + structure field type. @postrefcountsame{trace_class} -@postsuccessrefcountinc{packet_header_type} +@post On success, if \p packet_header_type is not \c NULL, + the reference count of \p packet_header_type is incremented. @sa bt_ctf_trace_get_packet_header_type(): Returns the packet header field type of a given trace class. -- 2.34.1