include/babeltrace/ctf-ir/stream.h

   1 #ifndef BABELTRACE_CTF_IR_STREAM_H
   2 #define BABELTRACE_CTF_IR_STREAM_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Stream
   6  *
   7  * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   8  *
   9  * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  10  *
  11  * Permission is hereby granted, free of charge, to any person obtaining a copy
  12  * of this software and associated documentation files (the "Software"), to deal
  13  * in the Software without restriction, including without limitation the rights
  14  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  15  * copies of the Software, and to permit persons to whom the Software is
  16  * furnished to do so, subject to the following conditions:
  17  *
  18  * The above copyright notice and this permission notice shall be included in
  19  * all copies or substantial portions of the Software.
  20  *
  21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  22  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  23  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  24  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  25  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  26  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  27  * SOFTWARE.
  28  *
  29  * The Common Trace Format (CTF) Specification is available at
  30  * http://www.efficios.com/ctf
  31  */
  32
  33 #include <babeltrace/ctf-ir/stream-class.h>
  34 #include <stdint.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /**
  41 @defgroup ctfirstream CTF IR stream
  42 @ingroup ctfir
  43 @brief CTF IR stream.
  44
  45 @note
  46 See \ref ctfirwriterstream which documents additional CTF IR stream
  47 functions exclusive to the CTF IR writer mode.
  48
  49 A CTF IR <strong><em>stream</em></strong> is an instance of a
  50 \link ctfirstreamclass CTF IR stream class\endlink.
  51
  52 You can obtain a CTF IR stream object in two different modes:
  53
  54 - <strong>Normal mode</strong>: use bt_ctf_stream_create() with a stream
  55   class having a \link ctfirtraceclass CTF IR trace class\endlink parent
  56   \em not created by a \link ctfirwriter CTF IR writer\endlink object to
  57   create a default stream.
  58 - <strong>CTF IR writer mode</strong>: use bt_ctf_stream_create() with
  59   a stream class having a trace class parent created by a CTF IR writer
  60   object, or use bt_ctf_writer_create_stream().
  61
  62 A CTF IR stream object represents a CTF stream, that is, a sequence of
  63 packets containing events:
  64
  65 @imgtracestructure
  66
  67 A CTF IR stream does not contain, however, actual \link ctfirpacket CTF
  68 IR packet\endlink objects: it only acts as a common parent to identify
  69 the original CTF stream of packet objects.
  70
  71 As with any Babeltrace object, CTF IR stream objects have
  72 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
  73 counts</a>. See \ref refs to learn more about the reference counting
  74 management of Babeltrace objects.
  75
  76 @sa ctfirstreamclass
  77 @sa ctfirpacket
  78 @sa ctfirwriterstream
  79
  80 @file
  81 @brief CTF IR stream type and functions.
  82 @sa ctfirstream
  83
  84 @addtogroup ctfirstream
  85 @{
  86 */
  87
  88 struct bt_ctf_stream;
  89 struct bt_ctf_event;
  90
  91 /**
  92 @brief  Creates a default CTF IR stream named \p name from the CTF IR
  93         stream class \p stream_class.
  94
  95 \p stream_class \em must have a parent
  96 \link ctfirtraceclass CTF IR trace class\endlink.
  97
  98 If the parent \link ctfirtraceclass trace class\endlink of
  99 \p stream_class was created by a \link ctfirwriter CTF IR writer\endlink
 100 object, then the stream object is created in CTF IR writer mode, and
 101 you can use the functions of \ref ctfirwriterstream on it.
 102 Otherwise it is created in normal mode: you should only use the
 103 functions documented in this module on it.
 104
 105 \p name can be \c NULL to create an unnamed stream object.
 106
 107 @param[in] stream_class CTF IR stream class to use to create the
 108                         CTF IR stream.
 109 @param[in] name         Name of the stream object to create (copied on
 110                         success) or \c NULL to create an unnamed stream.
 111 @returns                Created stream object, or \c NULL on error.
 112
 113 @prenotnull{stream_class}
 114 @pre \p stream_class has a parent trace class.
 115 @postsuccessrefcountret1
 116 */
 117 extern struct bt_ctf_stream *bt_ctf_stream_create(
 118                 struct bt_ctf_stream_class *stream_class,
 119                 const char *name);
 120
 121 /**
 122 @brief  Returns the name of the CTF IR stream \p stream.
 123
 124 On success, \p stream remains the sole owner of the returned string.
 125
 126 @param[in] stream       Stream object of which to get the name.
 127 @returns                Name of stream \p stream, or \c NULL if
 128                         \p stream is unnamed or on error.
 129
 130 @prenotnull{stream}
 131 @postrefcountsame{stream}
 132 */
 133 extern const char *bt_ctf_stream_get_name(struct bt_ctf_stream *stream);
 134
 135 /**
 136 @brief  Returns the parent CTF IR stream class of the CTF IR
 137         stream \p stream.
 138
 139 This function returns a reference to the stream class which was used
 140 to create the stream object in the first place with
 141 bt_ctf_stream_create().
 142
 143 @param[in] stream       Stream of which to get the parent stream class.
 144 @returns                Parent stream class of \p stream,
 145                         or \c NULL on error.
 146
 147 @prenotnull{stream}
 148 @postsuccessrefcountretinc
 149 */
 150 extern struct bt_ctf_stream_class *bt_ctf_stream_get_class(
 151                 struct bt_ctf_stream *stream);
 152
 153 /** @} */
 154
 155 #ifdef __cplusplus
 156 }
 157 #endif
 158
 159 #endif /* BABELTRACE_CTF_IR_STREAM_H */