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 #include <stdint.h>
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /**
  38 @defgroup ctfirpacket CTF IR packet
  39 @ingroup ctfir
  40 @brief CTF IR packet.
  41
  42 @code
  43 #include <babeltrace/ctf-ir/packet.h>
  44 @endcode
  45
  46 A CTF IR <strong><em>packet</em></strong> is a container of packet
  47 fields, that is, of the <strong>trace packet header</strong> and
  48 <strong>stream packet context</strong> fields.
  49
  50 As a reminder, here's the structure of a CTF packet:
  51
  52 @imgpacketstructure
  53
  54 You can create a CTF IR packet \em from a
  55 \link ctfirstream CTF IR stream\endlink with bt_ctf_packet_create(). The
  56 stream you use to create a packet object becomes its parent.
  57
  58 When you set the trace packet header and stream packet context fields of
  59 a packet with resp. bt_ctf_packet_set_header() and
  60 bt_ctf_packet_set_context(), their field type \em must be equivalent to
  61 the field types returned by resp. bt_ctf_trace_get_packet_header_type()
  62 and bt_ctf_stream_class_get_packet_context_type() for its parent trace
  63 class and stream class.
  64
  65 You can attach a packet object to a \link ctfirevent CTF IR
  66 event\endlink object with bt_ctf_event_set_packet().
  67
  68 As with any Babeltrace object, CTF IR packet objects have
  69 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
  70 counts</a>. See \ref refs to learn more about the reference counting
  71 management of Babeltrace objects.
  72
  73 bt_notification_event_create() \em freezes its event parameter on
  74 success, which in turns freezes the event's associated packet object.
  75 This is the only way that a CTF IR packet object can be frozen.
  76 You cannot modify a frozen packet: it is considered immutable,
  77 except for \link refs reference counting\endlink.
  78
  79 @sa ctfirstream
  80 @sa ctfirstreamclass
  81 @sa ctfirtraceclass
  82
  83 @file
  84 @brief CTF IR packet type and functions.
  85 @sa ctfirpacket
  86
  87 @addtogroup ctfirpacket
  88 @{
  89 */
  90
  91 /**
  92 @struct bt_ctf_packet
  93 @brief A CTF IR packet.
  94 @sa ctfirpacket
  95 */
  96 struct bt_ctf_packet;
  97 struct bt_ctf_stream;
  98
  99 /**
 100 @name Creation and parent access functions
 101 @{
 102 */
 103
 104 /**
 105 @brief  Creates a default CTF IR packet with \p stream as its parent
 106         CTF IR stream.
 107
 108 On success, the packet object's trace packet header and stream packet
 109 context fields are not set. You can set them with resp.
 110 bt_ctf_packet_set_header() and bt_ctf_packet_set_context().
 111
 112 @param[in] stream       Parent CTF IR stream of the packet to create.
 113 @returns                Created packet, or \c NULL on error.
 114
 115 @prenotnull{stream}
 116 @postsuccessrefcountret1
 117 */
 118 extern struct bt_ctf_packet *bt_ctf_packet_create(
 119                 struct bt_ctf_stream *stream);
 120
 121 /**
 122 @brief  Returns the parent CTF IR stream of the CTF IR packet \p packet.
 123
 124 This function returns a reference to the stream which was used to create
 125 the packet object in the first place with bt_ctf_packet_create().
 126
 127 @param[in] packet       Packet of which to get the parent stream.
 128 @returns                Parent stream of \p packet, or \c NULL on error.
 129
 130 @prenotnull{packet}
 131 @postrefcountsame{packet}
 132 @postsuccessrefcountretinc
 133 */
 134 extern struct bt_ctf_stream *bt_ctf_packet_get_stream(
 135                 struct bt_ctf_packet *packet);
 136
 137 /** @} */
 138
 139 /**
 140 @name Contained fields functions
 141 @{
 142 */
 143
 144 /**
 145 @brief  Returns the trace packet header field of the CTF IR packet
 146         \p packet.
 147
 148 @param[in] packet       Packet of which to get the trace packet header
 149                         field.
 150 @returns                Trace packet header field of \p packet,
 151                         or \c NULL if the trace packet header
 152                         field is not set or on error.
 153
 154 @prenotnull{packet}
 155 @postrefcountsame{packet}
 156 @postsuccessrefcountretinc
 157
 158 @sa bt_ctf_packet_set_header(): Sets the trace packet header
 159         field of a given packet.
 160 */
 161 extern struct bt_ctf_field *bt_ctf_packet_get_header(
 162                 struct bt_ctf_packet *packet);
 163
 164 /**
 165 @brief  Sets the trace packet header field of the CTF IR packet
 166         \p packet to \p header.
 167
 168 The field type of \p header, as returned by bt_ctf_field_get_type(),
 169 \em must be equivalent to the field type returned by
 170 bt_ctf_trace_get_packet_header_type() for the parent trace class
 171 of \p packet.
 172
 173 @param[in] packet       Packet of which to set the trace packet header
 174                         field.
 175 @param[in] header       Trace packet header field.
 176 @returns                0 on success, or a negative value on error.
 177
 178 @prenotnull{packet}
 179 @prenotnull{header}
 180 @prehot{packet}
 181 @pre \p header has a field type equivalent to the field type returned by
 182         bt_ctf_trace_get_packet_header_type() for the parent trace class
 183         of \p packet.
 184 @postrefcountsame{packet}
 185 @postsuccessrefcountinc{header}
 186
 187 @sa bt_ctf_packet_get_header(): Returns the trace packet header field
 188         of a given packet.
 189 */
 190 extern int bt_ctf_packet_set_header(
 191                 struct bt_ctf_packet *packet, struct bt_ctf_field *header);
 192
 193 /**
 194 @brief  Returns the stream packet context field of the CTF IR packet
 195         \p packet.
 196
 197 @param[in] packet       Packet of which to get the stream packet context
 198                         field.
 199 @returns                Stream packet context field of \p packet,
 200                         or \c NULL if the stream packet context
 201                         field is not set or on error.
 202
 203 @prenotnull{packet}
 204 @postrefcountsame{packet}
 205 @postsuccessrefcountretinc
 206
 207 @sa bt_ctf_packet_set_context(): Sets the stream packet context
 208         field of a given packet.
 209 */
 210 extern struct bt_ctf_field *bt_ctf_packet_get_context(
 211                 struct bt_ctf_packet *packet);
 212
 213 /**
 214 @brief  Sets the stream packet context field of the CTF IR packet
 215         \p packet to \p context.
 216
 217 The field type of \p context, as returned by bt_ctf_field_get_type(),
 218 \em must be equivalent to the field type returned by
 219 bt_ctf_stream_class_get_packet_context_type() for the parent stream
 220 class of \p packet.
 221
 222 @param[in] packet       Packet of which to set the stream packet context
 223                         field.
 224 @param[in] context      Stream packet context field.
 225 @returns                0 on success, or a negative value on error.
 226
 227 @prenotnull{packet}
 228 @prenotnull{context}
 229 @prehot{packet}
 230 @pre \p context has a field type equivalent to the field type returned
 231         by bt_ctf_stream_class_get_packet_context_type() for the parent
 232         stream class of \p packet.
 233 @postrefcountsame{packet}
 234 @postsuccessrefcountinc{context}
 235
 236 @sa bt_ctf_packet_get_context(): Returns the stream packet context field
 237         of a given packet.
 238 */
 239 extern int bt_ctf_packet_set_context(
 240                 struct bt_ctf_packet *packet, struct bt_ctf_field *context);
 241
 242 /** @} */
 243
 244 #ifdef __cplusplus
 245 }
 246 #endif
 247
 248 #endif /* BABELTRACE_CTF_IR_PACKET_H */