Split CTF IR and CTF writer APIs and implementations

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

diff --git a/include/babeltrace/ctf-ir/stream.h b/include/babeltrace/ctf-ir/stream.h
index f1191bc6b0bd7081a938bc15ab6031d59f524322..4b4ac3cfe42d9859d283aa612764c2f25ae16d31 100644 (file)
--- a/include/babeltrace/ctf-ir/stream.h
+++ b/include/babeltrace/ctf-ir/stream.h
@@ -30,34 +30,40 @@
  * http://www.efficios.com/ctf
  */
 
-#include <babeltrace/ctf-ir/stream-class.h>
 #include <stdint.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+struct bt_stream_class;
+
 /**
 @defgroup ctfirstream CTF IR stream
 @ingroup ctfir
 @brief CTF IR stream.
 
+@code
+#include <babeltrace/ctf-ir/stream.h>
+@endcode
+
 @note
-See \ref ctfirwriterstream which documents additional CTF IR stream
-functions exclusive to the CTF IR writer mode.
+See \ref ctfwriterstream which documents additional CTF IR stream
+functions exclusive to the CTF writer mode.
 
 A CTF IR <strong><em>stream</em></strong> is an instance of a
 \link ctfirstreamclass CTF IR stream class\endlink.
 
 You can obtain a CTF IR stream object in two different modes:
 
-- <strong>Normal mode</strong>: use bt_ctf_stream_create() with a stream
-  class having a \link ctfirtraceclass CTF IR trace class\endlink parent
-  \em not created by a \link ctfirwriter CTF IR writer\endlink object to
+- <strong>Normal mode</strong>: use bt_stream_create() or
+  bt_stream_create_with_id() with a stream class having a
+  \link ctfirtraceclass CTF IR trace class\endlink parent
+  \em not created by a \link ctfwriter CTF writer\endlink object to
   create a default stream.
-- <strong>CTF IR writer mode</strong>: use bt_ctf_stream_create() with
-  a stream class having a trace class parent created by a CTF IR writer
-  object, or use bt_ctf_writer_create_stream().
+- <strong>CTF writer mode</strong>: use bt_stream_create() with
+  a stream class having a trace class parent created by a CTF writer
+  object, or use bt_writer_create_stream().
 
 A CTF IR stream object represents a CTF stream, that is, a sequence of
 packets containing events:
@@ -75,7 +81,7 @@ management of Babeltrace objects.
 
 @sa ctfirstreamclass
 @sa ctfirpacket
-@sa ctfirwriterstream
+@sa ctfwriterstream
 
 @file
 @brief CTF IR stream type and functions.
@@ -86,27 +92,23 @@ management of Babeltrace objects.
 */
 
 /**
-@struct bt_ctf_stream
+@struct bt_stream
 @brief A CTF IR stream.
 @sa ctfirstream
-@sa ctfirwriterstream
+@sa ctfwriterstream
 */
-struct bt_ctf_stream;
-struct bt_ctf_event;
+struct bt_stream;
+struct bt_event;
 
 /**
-@brief  Creates a default CTF IR stream named \p name from the CTF IR
-       stream class \p stream_class.
+@brief  Creates a default CTF IR stream named \p name with ID \p id
+       from the CTF IR stream class \p stream_class.
 
 \p stream_class \em must have a parent
 \link ctfirtraceclass CTF IR trace class\endlink.
 
-If the parent \link ctfirtraceclass trace class\endlink of
-\p stream_class was created by a \link ctfirwriter CTF IR writer\endlink
-object, then the stream object is created in CTF IR writer mode, and
-you can use the functions of \ref ctfirwriterstream on it.
-Otherwise it is created in normal mode: you should only use the
-functions documented in this module on it.
+\p id \em must be unique amongst the IDs of all the streams created
+from \p stream_class with bt_stream_create_with_id().
 
 \p name can be \c NULL to create an unnamed stream object.
 
@@ -114,15 +116,16 @@ functions documented in this module on it.
                        CTF IR stream.
 @param[in] name                Name of the stream object to create (copied on
                        success) or \c NULL to create an unnamed stream.
+@param[in] id          ID of the stream object to create.
 @returns               Created stream object, or \c NULL on error.
 
 @prenotnull{stream_class}
+@pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
 @pre \p stream_class has a parent trace class.
 @postsuccessrefcountret1
 */
-extern struct bt_ctf_stream *bt_ctf_stream_create(
-               struct bt_ctf_stream_class *stream_class,
-               const char *name);
+extern struct bt_stream *bt_stream_create(struct bt_stream_class *stream_class,
+               const char *name, uint64_t id);
 
 /**
 @brief Returns the name of the CTF IR stream \p stream.
@@ -136,7 +139,19 @@ On success, \p stream remains the sole owner of the returned string.
 @prenotnull{stream}
 @postrefcountsame{stream}
 */
-extern const char *bt_ctf_stream_get_name(struct bt_ctf_stream *stream);
+extern const char *bt_stream_get_name(struct bt_stream *stream);
+
+/**
+@brief Returns the numeric ID of the CTF IR stream \p stream.
+
+@param[in] stream      Stream of which to get the numeric ID.
+@returns               ID of stream \p stream, or a negative value
+                       on error.
+
+@prenotnull{stream}
+@postrefcountsame{stream}
+*/
+extern int64_t bt_stream_get_id(struct bt_stream *stream);
 
 /**
 @brief Returns the parent CTF IR stream class of the CTF IR
@@ -144,17 +159,18 @@ extern const char *bt_ctf_stream_get_name(struct bt_ctf_stream *stream);
 
 This function returns a reference to the stream class which was used
 to create the stream object in the first place with
-bt_ctf_stream_create().
+bt_stream_create().
 
 @param[in] stream      Stream of which to get the parent stream class.
 @returns               Parent stream class of \p stream,
                        or \c NULL on error.
 
 @prenotnull{stream}
+@postrefcountsame{stream}
 @postsuccessrefcountretinc
 */
-extern struct bt_ctf_stream_class *bt_ctf_stream_get_class(
-               struct bt_ctf_stream *stream);
+extern struct bt_stream_class *bt_stream_get_class(
+               struct bt_stream *stream);
 
 /** @} */