lib/ctf-ir/stream-class.c: add logging

[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 2111ca1f8af985edf86ecec35bf23500e5843350..e66ab7da8d235471ab1dfc05fc9d4e992a041814 100644 (file)
--- a/include/babeltrace/ctf-ir/stream-class.h
+++ b/include/babeltrace/ctf-ir/stream-class.h
@@ -110,7 +110,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 +143,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 +188,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);
 
@@ -274,13 +301,14 @@ of the trace class to which you eventually add \p stream_class.
 
 @prenotnull{stream_class}
 @prehot{stream_class}
+@pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
 @postrefcountsame{stream_class}
 
 @sa bt_ctf_stream_class_get_id(): Returns the numeric ID of a given
        stream class.
 */
 extern int bt_ctf_stream_class_set_id(
-               struct bt_ctf_stream_class *stream_class, uint32_t id);
+               struct bt_ctf_stream_class *stream_class, uint64_t id);
 
 /** @} */
 
@@ -474,7 +502,7 @@ extern int bt_ctf_stream_class_set_event_context_type(
 @prenotnull{stream_class}
 @postrefcountsame{stream_class}
 */
-extern int bt_ctf_stream_class_get_event_class_count(
+extern int64_t bt_ctf_stream_class_get_event_class_count(
                struct bt_ctf_stream_class *stream_class);
 
 /**
@@ -493,33 +521,11 @@ extern int bt_ctf_stream_class_get_event_class_count(
 @postrefcountsame{stream_class}
 @postsuccessrefcountretinc
 
-@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(
-               struct bt_ctf_stream_class *stream_class, int 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);
+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 with ID \c id found in the CTF IR stream
@@ -533,12 +539,9 @@ 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, uint32_t id);
+               struct bt_ctf_stream_class *stream_class, uint64_t id);
 
 /**
 @brief Adds the CTF IR event class \p event_class to the