+/*!
+@defgroup api-tir-stream-cls Stream class
+@ingroup api-tir
+
+@brief
+ Class of \bt_p_stream.
+
+A <strong><em>stream class</em></strong> is the class of \bt_p_stream:
+
+@image html trace-structure.png
+
+In the illustration above, notice that:
+
+- A \bt_stream is a conceptual \ref api-msg-seq "sequence of messages".
+
+ The sequence always starts with a \bt_sb_msg and ends with a
+ \bt_se_msg.
+
+- A stream is an instance of a stream class.
+
+A stream class is a \ref api-tir "trace IR" metadata object.
+
+A stream class is a \ref api-fund-shared-object "shared object": get a
+new reference with bt_stream_class_get_ref() and put an existing
+reference with bt_stream_class_put_ref().
+
+Some library functions \ref api-fund-freezing "freeze" stream classes on
+success. The documentation of those functions indicate this
+postcondition. You can still create and add an \bt_p_ev_cls to a frozen
+stream class with bt_event_class_create() or
+bt_event_class_create_with_id().
+
+The type of a stream class is #bt_stream_class.
+
+A \bt_trace_cls contains stream classes. All the stream classes of a
+given trace class have unique
+\ref api-tir-stream-cls-prop-id "numeric IDs". Borrow the trace class
+which contains a stream class with bt_stream_class_borrow_trace_class()
+or bt_stream_class_borrow_trace_class_const().
+
+A stream class contains \bt_p_ev_cls. All the event classes of a given
+stream class have unique \ref api-tir-ev-cls-prop-id "numeric IDs". Get
+the number of event classes in a stream class with
+bt_stream_class_get_event_class_count(). Borrow a specific event class
+from a stream class with bt_stream_class_borrow_event_class_by_index(),
+bt_stream_class_borrow_event_class_by_index_const(),
+bt_stream_class_borrow_event_class_by_id(), and
+bt_stream_class_borrow_event_class_by_id_const().
+
+A stream class controls what its instances (\bt_p_stream) support:
+
+<dl>
+ <dt>Default clock</dt>
+ <dd>
+ By default, a stream class's streams do not have default clocks.
+
+ Set the default \bt_clock_cls of a stream class with
+ bt_stream_class_set_default_clock_class(). This makes all its
+ streams have their own default clock.
+ </dd>
+
+ <dt>\anchor api-tir-stream-cls-pkt-support Packets</dt>
+ <dd>
+ By default, a stream class's streams do not support \bt_p_pkt.
+
+ In other words, you cannot create a packet for such a stream,
+ therefore you cannot create \bt_p_pb_msg and \bt_p_pe_msg for this
+ stream either.
+
+ Enable packet support for a stream class's streams with
+ bt_stream_class_set_supports_packets().
+
+ bt_stream_class_set_supports_packets() also configures whether or
+ not the packets of the stream class's instances have beginning
+ and/or end default \bt_p_cs.
+ </dd>
+
+ <dt>Discarded events</dt>
+ <dd>
+ By default, a stream class's streams do not support discarded
+ events.
+
+ In other words, you cannot create \bt_p_disc_ev_msg for such a
+ stream.
+
+ Enable discarded events support for a stream class's streams with
+ bt_stream_class_set_supports_discarded_events().
+
+ bt_stream_class_set_supports_discarded_events() also configures
+ whether or not the discarded events messages of the stream class's
+ instances have beginning and end default \bt_p_cs to indicate the
+ discarded events time range.
+ </dd>
+
+ <dt>Discarded packets</dt>
+ <dd>
+ By default, a stream class's streams do not support discarded
+ packets.
+
+ In other words, you cannot create \bt_p_disc_pkt_msg for such a
+ stream.
+
+ Enable discarded packets support for a stream class's streams with
+ bt_stream_class_set_supports_discarded_packets(). This also implies
+ that you must enable packet support with
+ bt_stream_class_set_supports_packets().
+
+ bt_stream_class_set_supports_discarded_packets() also configures
+ whether or not the discarded packets messages of the stream class's
+ instances have beginning and end \bt_p_cs to indicate the
+ discarded packets time range.
+ </dd>
+</dl>
+
+Set whether or not the \bt_p_ev_cls and \bt_p_stream you create for a
+stream class get automatic numeric IDs with
+bt_stream_class_set_assigns_automatic_event_class_id() and
+bt_stream_class_set_assigns_automatic_stream_id().
+
+To create a default stream class:
+
+<dl>
+ <dt>
+ If bt_trace_class_assigns_automatic_stream_class_id() returns
+ #BT_TRUE (the default) for the trace class to use
+ </dt>
+ <dd>Use bt_stream_class_create().</dd>
+
+ <dt>
+ If bt_trace_class_assigns_automatic_stream_class_id() returns
+ #BT_FALSE for the trace class to use
+ </dt>
+ <dd>Use bt_stream_class_create_with_id().</dd>
+</dl>
+
+<h1>Properties</h1>
+
+A stream class has the following properties:
+
+<dl>
+ <dt>\anchor api-tir-stream-cls-prop-id Numeric ID</dt>
+ <dd>
+ Numeric ID, unique amongst the numeric IDs of the stream class's
+ \bt_trace_cls's stream classes.
+
+ Depending on whether or not the stream class's trace class
+ automatically assigns \bt_ev_cls IDs
+ (see bt_trace_class_assigns_automatic_stream_class_id()),
+ set the stream class's numeric ID on creation with
+ bt_stream_class_create() or bt_stream_class_create_with_id().
+
+ You cannot change the numeric ID once the stream class is created.
+
+ Get a stream class's numeric ID with bt_stream_class_get_id().
+ </dd>
+
+ <dt>\anchor api-tir-stream-cls-prop-name \bt_dt_opt Name</dt>
+ <dd>
+ Name of the stream class.
+
+ Use bt_stream_class_set_name() and bt_stream_class_get_name().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-def-clock-cls
+ \bt_dt_opt Default clock class
+ </dt>
+ <dd>
+ Default \bt_clock_cls of the stream class.
+
+ As of \bt_name_version_min_maj, a stream class either has a default
+ clock class or none: it cannot have more than one clock class.
+
+ When a stream class has a default clock class, then all its
+ instances (\bt_p_stream) have a default clock which is an instance
+ of the stream class's default clock class.
+
+ Use bt_stream_class_set_default_clock_class(),
+ bt_stream_class_borrow_default_clock_class(), and
+ bt_stream_class_borrow_default_clock_class_const().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-pc-fc
+ \bt_dt_opt Packet context field class
+ </dt>
+ <dd>
+ \bt_c_pkt context \bt_fc of the stream class.
+
+ This property is only relevant if the stream class
+ \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
+
+ The context of a \bt_pkt contains data which is common to all the
+ packet's \bt_p_ev.
+
+ Use bt_stream_class_set_packet_context_field_class()
+ bt_stream_class_borrow_packet_context_field_class(),
+ and bt_stream_class_borrow_packet_context_field_class_const().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-ecc-fc
+ \bt_dt_opt Event common context field class
+ </dt>
+ <dd>
+ \bt_c_ev common context \bt_fc of the stream class.
+
+ The common context of an \bt_ev contains contextual data of which
+ the layout is common to all the stream class's \bt_p_ev_cls.
+
+ Use bt_stream_class_set_event_common_context_field_class()
+ bt_stream_class_borrow_event_common_context_field_class(),
+ and bt_stream_class_borrow_event_common_context_field_class_const().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-auto-ec-id
+ Assigns automatic event class IDs?
+ </dt>
+ <dd>
+ Whether or not the \bt_p_ev_cls you create and add to the stream
+ class get \ref api-tir-ev-cls-prop-id "numeric IDs" automatically.
+
+ Depending on the value of this property, to create an event class
+ and add it to the stream class:
+
+ <dl>
+ <dt>#BT_TRUE</dt>
+ <dd>
+ Use bt_event_class_create().
+ </dd>
+
+ <dt>#BT_FALSE</dt>
+ <dd>
+ Use bt_event_class_create_with_id().
+ </dd>
+ </dl>
+
+ Use bt_stream_class_set_assigns_automatic_event_class_id()
+ and bt_stream_class_assigns_automatic_event_class_id().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-auto-stream-id
+ Assigns automatic stream IDs?
+ </dt>
+ <dd>
+ Whether or not the streams you create from the stream class
+ get \ref api-tir-stream-prop-id "numeric IDs" automatically.
+
+ Depending on the value of this property, to create a stream
+ from the stream class:
+
+ <dl>
+ <dt>#BT_TRUE</dt>
+ <dd>
+ Use bt_stream_create().
+ </dd>
+
+ <dt>#BT_FALSE</dt>
+ <dd>
+ Use bt_stream_create_with_id().
+ </dd>
+ </dl>
+
+ Use bt_stream_class_set_assigns_automatic_stream_id()
+ and bt_stream_class_assigns_automatic_stream_id().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-supports-pkt
+ Supports packets?
+ </dt>
+ <dd>
+ Whether or not the streams you create from the stream class
+ have \bt_p_pkt.
+
+ If a stream has packets, then all the stream's \bt_p_ev are
+ conceptually contained within packets, which means you must
+ create \bt_p_ev_msg for such streams with
+ bt_message_event_create_with_packet() or
+ bt_message_event_create_with_packet_and_default_clock_snapshot()
+ instead of bt_message_event_create() or
+ bt_message_event_create_with_default_clock_snapshot().
+
+ It also means you must create \bt_p_pb_msg and \bt_p_pe_msg to
+ indicate where packets begin and end within the stream's
+ \ref api-msg-seq "message sequence".
+
+ Use bt_stream_class_set_supports_packets() and
+ bt_stream_class_supports_packets().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-pkt-beg-cs
+ Packets have a beginning default clock snapshot?
+ </dt>
+ <dd>
+ Whether or not the \bt_p_pkt of the streams you create from the
+ stream class have beginning default \bt_p_cs.
+
+ This property is only relevant if the stream class
+ \ref api-tir-stream-cls-prop-supports-pkt "supports packets" and
+ has a
+ \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+ If the stream packets have a beginning default clock snapshot, then
+ you must create \bt_p_pb_msg with
+ bt_message_packet_beginning_create_with_default_clock_snapshot()
+ instead of bt_message_packet_beginning_create().
+
+ Use bt_stream_class_set_supports_packets() and
+ bt_stream_class_packets_have_beginning_default_clock_snapshot().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-pkt-end-cs
+ Packets have an end default clock snapshot?
+ </dt>
+ <dd>
+ Whether or not the \bt_p_pkt of the streams you create from the
+ stream class have end default \bt_p_cs.
+
+ This property is only relevant if the stream class
+ \ref api-tir-stream-cls-prop-supports-pkt "supports packets" and
+ has a
+ \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+ If the stream packets have an end default clock snapshot, then you
+ must create \bt_p_pe_msg with
+ bt_message_packet_end_create_with_default_clock_snapshot() instead
+ of bt_message_packet_end_create().
+
+ Use bt_stream_class_set_supports_packets() and
+ bt_stream_class_packets_have_end_default_clock_snapshot().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-supports-disc-ev
+ Supports discarded events?
+ </dt>
+ <dd>
+ Whether or not the streams you create from the stream class can have
+ discarded events.
+
+ If the stream class supports discarded events, then you can create
+ \bt_p_disc_ev_msg for this stream.
+
+ Use bt_stream_class_set_supports_discarded_events()
+ and bt_stream_class_supports_discarded_events().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-disc-ev-cs
+ Discarded events have default clock snapshots?
+ </dt>
+ <dd>
+ Whether or not the stream's \bt_p_disc_ev_msg have
+ default beginning and end \bt_p_cs to indicate the discarded events
+ time range.
+
+ This property is only relevant if the stream class
+ \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events"
+ and has a
+ \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+ If the stream's discarded events messages have beginning and end
+ default clock snapshots, then you must create them with
+ bt_message_discarded_events_create_with_default_clock_snapshots()
+ instead of bt_message_discarded_events_create().
+
+ Use bt_stream_class_set_supports_discarded_events()
+ and bt_stream_class_discarded_events_have_default_clock_snapshots().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-supports-disc-pkt
+ Supports discarded packets?
+ </dt>
+ <dd>
+ Whether or not the streams you create from the stream class can have
+ discarded packets.
+
+ This property is only relevant if the stream class
+ \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
+
+ If the stream class supports discarded packets, then you can create
+ \bt_p_disc_pkt_msg for this stream.
+
+ Use bt_stream_class_set_supports_discarded_packets()
+ and bt_stream_class_supports_discarded_packets().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-disc-pkt-cs
+ Discarded packets have default clock snapshots?
+ </dt>
+ <dd>
+ Whether or not the stream's \bt_p_disc_pkt_msg have
+ default beginning and end \bt_p_cs to indicate the discarded
+ packets time range.
+
+ This property is only relevant if the stream class
+ \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets"
+ and has a
+ \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+ If the stream's discarded packets messages have default clock
+ snapshots, then you must create them with
+ bt_message_discarded_packets_create_with_default_clock_snapshots()
+ instead of bt_message_discarded_packets_create().
+
+ Use bt_stream_class_set_supports_discarded_packets()
+ and bt_stream_class_discarded_packets_have_default_clock_snapshots().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-user-attrs
+ \bt_dt_opt User attributes
+ </dt>
+ <dd>
+ User attributes of the stream class.
+
+ User attributes are custom attributes attached to a stream class.
+
+ Use bt_stream_class_set_user_attributes(),
+ bt_stream_class_borrow_user_attributes(), and
+ bt_stream_class_borrow_user_attributes_const().
+ </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_stream_class bt_stream_class;
+
+@brief
+ Stream class.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+ Creates a default stream class and adds it to the \bt_trace_cls
+ \bt_p{trace_class}.
+
+@attention
+ @parblock
+ Only use this function if
+
+ @code
+ bt_trace_class_assigns_automatic_stream_class_id(trace_class)
+ @endcode
+
+ returns #BT_TRUE.
+
+ Otherwise, use bt_stream_class_create_with_id().
+ @endparblock
+
+On success, the returned stream class has the following property values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-id "Numeric ID"
+ <td>Automatically assigned by \bt_p{trace_class}
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-name "Name"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-pc-fc "Packet context field class"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?"
+ <td>Yes
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?"
+ <td>Yes
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class to add the created stream class to.
+
+@returns
+ New stream class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@pre
+ <code>bt_trace_class_assigns_automatic_stream_class_id(trace_class)</code>
+ returns #BT_TRUE.
+
+@bt_post_success_frozen{trace_class}
+
+@sa bt_stream_class_create_with_id() —
+ Creates a stream class with a specific numeric ID and adds it to a
+ trace class.
+*/