include/babeltrace/ctf-ir/packet.h

   1 #ifndef BABELTRACE_CTF_IR_PACKET_H
   2 #define BABELTRACE_CTF_IR_PACKET_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Stream packet
   6  *
   7  * Copyright 2016 Philippe Proulx <pproulx@efficios.com>
   8  *
   9  * Permission is hereby granted, free of charge, to any person obtaining a copy
  10  * of this software and associated documentation files (the "Software"), to deal
  11  * in the Software without restriction, including without limitation the rights
  12  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  13  * copies of the Software, and to permit persons to whom the Software is
  14  * furnished to do so, subject to the following conditions:
  15  *
  16  * The above copyright notice and this permission notice shall be included in
  17  * all copies or substantial portions of the Software.
  18  *
  19  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  20  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  21  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  22  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  23  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  24  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  25  * SOFTWARE.
  26  *
  27  * The Common Trace Format (CTF) Specification is available at
  28  * http://www.efficios.com/ctf
  29  */
  30
  31 /* For bt_get() */
  32 #include <babeltrace/ref.h>
  33
  34 #include <stdint.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /**
  41 @defgroup ctfirpacket CTF IR packet
  42 @ingroup ctfir
  43 @brief CTF IR packet.
  44
  45 @code
  46 #include <babeltrace/ctf-ir/packet.h>
  47 @endcode
  48
  49 A CTF IR <strong><em>packet</em></strong> is a container of packet
  50 fields, that is, of the <strong>trace packet header</strong> and
  51 <strong>stream packet context</strong> fields.
  52
  53 As a reminder, here's the structure of a CTF packet:
  54
  55 @imgpacketstructure
  56
  57 You can create a CTF IR packet \em from a
  58 \link ctfirstream CTF IR stream\endlink with bt_packet_create(). The
  59 stream you use to create a packet object becomes its parent.
  60
  61 When you set the trace packet header and stream packet context fields of
  62 a packet with resp. bt_packet_set_header() and
  63 bt_packet_set_context(), their field type \em must be equivalent to
  64 the field types returned by resp. bt_trace_get_packet_header_type()
  65 and bt_stream_class_get_packet_context_type() for its parent trace
  66 class and stream class.
  67
  68 You can attach a packet object to a \link ctfirevent CTF IR
  69 event\endlink object with bt_event_set_packet().
  70
  71 As with any Babeltrace object, CTF IR packet 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 bt_notification_event_create() \em freezes its event parameter on
  77 success, which in turns freezes the event's associated packet object.
  78 This is the only way that a CTF IR packet object can be frozen.
  79 You cannot modify a frozen packet: it is considered immutable,
  80 except for \link refs reference counting\endlink.
  81
  82 @sa ctfirstream
  83 @sa ctfirstreamclass
  84 @sa ctfirtraceclass
  85
  86 @file
  87 @brief CTF IR packet type and functions.
  88 @sa ctfirpacket
  89
  90 @addtogroup ctfirpacket
  91 @{
  92 */
  93
  94 /**
  95 @struct bt_packet
  96 @brief A CTF IR packet.
  97 @sa ctfirpacket
  98 */
  99 struct bt_packet;
 100 struct bt_stream;
 101
 102 /**
 103 @name Creation and parent access functions
 104 @{
 105 */
 106
 107 /**
 108 @brief  Creates a default CTF IR packet with \p stream as its parent
 109         CTF IR stream.
 110
 111 On success, the packet object's trace packet header and stream packet
 112 context fields are not set. You can set them with resp.
 113 bt_packet_set_header() and bt_packet_set_context().
 114
 115 @param[in] stream       Parent CTF IR stream of the packet to create.
 116 @returns                Created packet, or \c NULL on error.
 117
 118 @prenotnull{stream}
 119 @postsuccessrefcountret1
 120 */
 121 extern struct bt_packet *bt_packet_create(
 122                 struct bt_stream *stream);
 123
 124 extern struct bt_stream *bt_packet_borrow_stream(
 125                 struct bt_packet *packet);
 126
 127 /**
 128 @brief  Returns the parent CTF IR stream of the CTF IR packet \p packet.
 129
 130 This function returns a reference to the stream which was used to create
 131 the packet object in the first place with bt_packet_create().
 132
 133 @param[in] packet       Packet of which to get the parent stream.
 134 @returns                Parent stream of \p packet, or \c NULL on error.
 135
 136 @prenotnull{packet}
 137 @postrefcountsame{packet}
 138 @postsuccessrefcountretinc
 139 */
 140 static inline
 141 struct bt_stream *bt_packet_get_stream(
 142                 struct bt_packet *packet)
 143 {
 144         return bt_get(bt_packet_borrow_stream(packet));
 145 }
 146
 147 /** @} */
 148
 149 /**
 150 @name Contained fields functions
 151 @{
 152 */
 153
 154 extern
 155 struct bt_field *bt_packet_borrow_header(struct bt_packet *packet);
 156
 157 /**
 158 @brief  Returns the trace packet header field of the CTF IR packet
 159         \p packet.
 160
 161 @param[in] packet       Packet of which to get the trace packet header
 162                         field.
 163 @returns                Trace packet header field of \p packet,
 164                         or \c NULL if the trace packet header
 165                         field is not set or on error.
 166
 167 @prenotnull{packet}
 168 @postrefcountsame{packet}
 169 @postsuccessrefcountretinc
 170
 171 @sa bt_packet_set_header(): Sets the trace packet header
 172         field of a given packet.
 173 */
 174 static inline
 175 struct bt_field *bt_packet_get_header(struct bt_packet *packet)
 176 {
 177         return bt_get(bt_packet_borrow_header(packet));
 178 }
 179
 180 /**
 181 @brief  Sets the trace packet header field of the CTF IR packet \p packet to
 182         \p header, or unsets the current trace packet header field from
 183         \p packet.
 184
 185 If \p header is not \c NULL, the field type of \p header, as returned by
 186 bt_field_get_type(), \em must be equivalent to the field type returned by
 187 bt_trace_get_packet_header_type() for the parent trace class of
 188 \p packet.
 189
 190 @param[in] packet       Packet of which to set the trace packet header field.
 191 @param[in] header       Trace packet header field.
 192 @returns                0 on success, or a negative value on error.
 193
 194 @prenotnull{packet}
 195 @prehot{packet}
 196 @pre <strong>\p header, if not \c NULL</strong>, has a field type equivalent to
 197         the field type returned by bt_trace_get_packet_header_type() for the
 198         parent trace class of \p packet.
 199 @postrefcountsame{event}
 200 @post <strong>On success, if \p header is not \c NULL</strong>, the reference
 201         count of \p header is incremented.
 202
 203 @sa bt_packet_get_header(): Returns the trace packet header field of a given
 204         packet.
 205 */
 206 extern int bt_packet_set_header(struct bt_packet *packet,
 207                 struct bt_field *header);
 208
 209 extern struct bt_field *bt_packet_borrow_context(
 210                 struct bt_packet *packet);
 211
 212 /**
 213 @brief  Returns the stream packet context field of the CTF IR packet
 214         \p packet.
 215
 216 @param[in] packet       Packet of which to get the stream packet context
 217                         field.
 218 @returns                Stream packet context field of \p packet,
 219                         or \c NULL if the stream packet context
 220                         field is not set or on error.
 221
 222 @prenotnull{packet}
 223 @postrefcountsame{packet}
 224 @postsuccessrefcountretinc
 225
 226 @sa bt_packet_set_context(): Sets the stream packet context
 227         field of a given packet.
 228 */
 229 static inline
 230 struct bt_field *bt_packet_get_context(struct bt_packet *packet)
 231 {
 232         return bt_get(bt_packet_borrow_context(packet));
 233 }
 234
 235 /**
 236 @brief  Sets the stream packet context field of the CTF IR packet \p packet to
 237         \p context, or unsets the current packet context field from \p packet.
 238
 239 If \p context is not \c NULL, the field type of \p context, as returned by
 240 bt_field_get_type(), \em must be equivalent to the field type returned by
 241 bt_stream_class_get_packet_context_type() for the parent stream class of
 242 \p packet.
 243
 244 @param[in] packet       Packet of which to set the stream packet context field.
 245 @param[in] context      Stream packet context field.
 246 @returns                0 on success, or a negative value on error.
 247
 248 @prenotnull{packet}
 249 @prehot{packet}
 250 @pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
 251         the field type returned by bt_stream_class_get_packet_context_type()
 252         for the parent stream class of \p packet.
 253 @postrefcountsame{packet}
 254 @post <strong>On success, if \p context is not \c NULL</strong>, the reference
 255         count of \p context is incremented.
 256
 257 @sa bt_packet_get_context(): Returns the stream packet context field of a
 258         given packet.
 259 */
 260 extern int bt_packet_set_context(
 261                 struct bt_packet *packet, struct bt_field *context);
 262
 263 /** @} */
 264
 265 /** @} */
 266
 267 #ifdef __cplusplus
 268 }
 269 #endif
 270
 271 #endif /* BABELTRACE_CTF_IR_PACKET_H */