Avoid unnecessary inclusions in public headers

[babeltrace.git] / include / babeltrace / ctf-ir / stream-class.h

diff --git a/include/babeltrace/ctf-ir/stream-class.h b/include/babeltrace/ctf-ir/stream-class.h
index 6a0e2e135f11fa1df2d961e2a1f0affedb4aa4e9..96a2dee7cea698cea561a89842022a472a1fae36 100644 (file)
--- a/include/babeltrace/ctf-ir/stream-class.h
+++ b/include/babeltrace/ctf-ir/stream-class.h
@@ -31,6 +31,8 @@
  */
 
 #include <stdint.h>
+
+/* For bt_ctf_visitor */
 #include <babeltrace/ctf-ir/visitor.h>
 
 #ifdef __cplusplus
@@ -110,7 +112,10 @@ You cannot modify a frozen stream class: it is considered immutable,
 except for:
 
 - Adding an event class to it with
-  bt_ctf_stream_class_add_event_class().
+  bt_ctf_stream_class_add_event_class(). If the stream class's parent
+  \link ctfirtraceclass trace class\endlink is static, however,
+  you cannot call bt_ctf_stream_class_add_event_class()
+  (see bt_ctf_trace_is_static() and bt_ctf_trace_set_is_static()).
 - \link refs Reference counting\endlink.
 
 @sa ctfirstream
@@ -140,6 +145,28 @@ struct bt_ctf_clock;
 @{
 */
 
+/**
+@brief Creates an empty CTF IR stream class named \p name, or an
+       unnamed empty stream class if \p name is \c NULL.
+
+On success, the packet context, event header, and event context field
+types are empty structure field types. You can modify those default
+field types after the stream class is created with
+bt_ctf_stream_class_set_packet_context_type(),
+bt_ctf_stream_class_set_event_header_type(), and
+bt_ctf_stream_class_set_event_context_type().
+
+@param[in] name        Name of the stream class to create (copied on success),
+               or \c NULL to create an unnamed stream class.
+@returns       Created empty stream class, or \c NULL on error.
+
+@postsuccessrefcountret1
+
+@sa bt_ctf_stream_class_create(): Creates a default stream class.
+*/
+extern struct bt_ctf_stream_class *bt_ctf_stream_class_create_empty(
+               const char *name);
+
 /**
 @brief Creates a default CTF IR stream class named \p name­, or a
        default unnamed stream class if \p name is \c NULL.
@@ -163,11 +190,13 @@ You can modify those default field types after the stream class is
 created with bt_ctf_stream_class_set_packet_context_type() and
 bt_ctf_stream_class_set_event_header_type().
 
-@param[in] name        Name of the stream class to create (can be \c NULL to
-               create an unnamed stream class).
-@returns       Created stream class, or \c NULL on error.
+@param[in] name        Name of the stream class to create (copied on success),
+               or \c NULL to create an unnamed stream class.
+@returns       Created default stream class, or \c NULL on error.
 
 @postsuccessrefcountret1
+
+@sa bt_ctf_stream_class_create_empty(): Creates an empty stream class.
 */
 extern struct bt_ctf_stream_class *bt_ctf_stream_class_create(const char *name);
 
@@ -225,17 +254,20 @@ extern const char *bt_ctf_stream_class_get_name(
 
 /**
 @brief Sets the name of the CTF IR stream class
-       \p stream_class to \p name.
+       \p stream_class to \p name, or resets the name of
+       \p stream_class.
 
-\p name must be unique amongst the names of all the stream classes
-of the trace class to which you eventually add \p stream_class.
+If \p name is not \c NULL, it must be unique amongst the names of all
+the stream classes of the trace class to which you eventually add
+\p stream_class.
 
 @param[in] stream_class        Stream class of which to set the name.
-@param[in] name                Name of the stream class (copied on success).
+@param[in] name                Name of the stream class (copied on success), or
+                       \c NULL to reset the name of \p stream_class
+                       (make it unnamed).
 @returns               0 on success, or a negative value on error.
 
 @prenotnull{stream_class}
-@prenotnull{name}
 @prehot{stream_class}
 @postrefcountsame{stream_class}
 
@@ -496,32 +528,10 @@ extern int64_t bt_ctf_stream_class_get_event_class_count(
 
 @sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class
        by ID.
-@sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class
-       by name.
 */
 extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_index(
                struct bt_ctf_stream_class *stream_class, uint64_t index);
 
-/**
-@brief  Returns the event class named \c name found in the CTF IR stream
-       class \p stream_class.
-
-@param[in] stream_class        Stream class of which to get the event class.
-@param[in] name                Name of the event class to find.
-@returns               Event class named \p name, or \c NULL
-                       on error.
-
-@prenotnull{stream_class}
-@prenotnull{name}
-@postrefcountsame{stream_class}
-@postsuccessrefcountretinc
-
-@sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class
-       by ID.
-*/
-extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_name(
-               struct bt_ctf_stream_class *stream_class, const char *name);
-
 /**
 @brief  Returns the event class with ID \c id found in the CTF IR stream
        class \p stream_class.
@@ -534,9 +544,6 @@ extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_name(
 @prenotnull{stream_class}
 @postrefcountsame{stream_class}
 @postsuccessrefcountretinc
-
-@sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class
-       by name.
 */
 extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_id(
                struct bt_ctf_stream_class *stream_class, uint64_t id);