include/babeltrace/ctf-ir/field-path.h

   1 #ifndef BABELTRACE_CTF_IR_FIELD_PATH
   2 #define BABELTRACE_CTF_IR_FIELD_PATH
   3
   4 /*
   5  * BabelTrace - CTF IR: Field path
   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 #include <babeltrace/ctf-ir/field-types.h>
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /**
  39 @defgroup ctfirfieldpath CTF IR field path
  40 @ingroup ctfir
  41 @brief CTF IR field path.
  42
  43 @code
  44 #include <babeltrace/ctf-ir/field-path.h>
  45 @endcode
  46
  47 A CTF IR <strong><em>field path</em></strong> represents an absolute
  48 path to a field in the hierarchy of a
  49 \link ctfirtraceclass CTF IR trace class\endlink, of a
  50 \link ctfirstreamclass CTF IR stream class\endlink, or of a
  51 \link ctfireventclass CTF IR event class\endlink.
  52
  53 As a reminder, here's the structure of a CTF packet:
  54
  55 @imgpacketstructure
  56
  57 Sequence and variant \link ctfirfieldtypes CTF IR field types\endlink
  58 can return a field path to resp. their length field and tag field
  59 with resp. bt_ctf_field_type_sequence_get_length_field_path() and
  60 bt_ctf_field_type_variant_get_tag_field_path().
  61
  62 A field path has a <em>root scope</em> which indicates from which of the
  63 six CTF scopes to begin. It also has a list of structure field <em>path
  64 indexes</em> which indicate the path to take to reach the destination
  65 field. A path index set to -1 means that you need to continue the lookup
  66 within the current element of an array or sequence field.
  67
  68 As with any Babeltrace object, CTF IR field path 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 @file
  74 @brief CTF IR field path type and functions.
  75 @sa ctfirfieldpath
  76
  77 @addtogroup ctfirfieldpath
  78 @{
  79 */
  80
  81 /**
  82 @struct bt_ctf_field_path
  83 @brief A CTF IR field path.
  84 @sa ctfirfieldpath
  85 */
  86 struct bt_ctf_field_path;
  87
  88 /**
  89 @brief  Returns the root scope of the CTF IR field path \p field_path.
  90
  91 @param[in] field_path   Field path of which to get the root scope.
  92 @returns                Root scope of \p field_path, or
  93                         #BT_CTF_SCOPE_UNKNOWN on error.
  94
  95 @prenotnull{field_path}
  96 @postrefcountsame{field_path}
  97 */
  98 extern enum bt_ctf_scope bt_ctf_field_path_get_root_scope(
  99                 const struct bt_ctf_field_path *field_path);
 100
 101 /**
 102 @brief  Returns the number of path indexes contained in the CTF IR field
 103         path \p field_path.
 104
 105 @param[in] field_path   Field path of which to get the number of
 106                         path indexes.
 107 @returns                Number of path indexes contained in
 108                         \p field_path, or a negative value on error.
 109
 110 @prenotnull{field_path}
 111 @postrefcountsame{field_path}
 112 */
 113 extern int64_t bt_ctf_field_path_get_index_count(
 114                 const struct bt_ctf_field_path *field_path);
 115
 116 /**
 117 @brief  Returns the path index contained in the CTF IR field
 118         path \p field_path at index \p index.
 119
 120 @param[in] field_path   Field path of which to get the path index
 121                         at index \p index.
 122 @param[in] index        Index of path index to get.
 123 @returns                Path index of \p field_path at index \p index,
 124                         or \c INT_MIN on error.
 125
 126 @prenotnull{field_path}
 127 @pre \p index is lesser than the number of path indexes contained in the
 128         field path \p field_path (see
 129         bt_ctf_field_path_get_index_count()).
 130 @postrefcountsame{field_path}
 131 */
 132 extern int bt_ctf_field_path_get_index(
 133                 const struct bt_ctf_field_path *field_path,
 134                 int index);
 135
 136 /** @} */
 137
 138 #ifdef __cplusplus
 139 }
 140 #endif
 141
 142 #endif /* BABELTRACE_CTF_IR_FIELD_PATH */