2 * SPDX-License-Identifier: MIT
4 * Copyright 2016-2017 Philippe Proulx <pproulx@efficios.com>
7 #ifndef _METADATA_DECODER_H
8 #define _METADATA_DECODER_H
14 #include <babeltrace2/babeltrace.h>
16 #include "common/macros.h"
17 #include "common/uuid.h"
19 struct ctf_trace_class;
21 /* A CTF metadata decoder object */
22 struct ctf_metadata_decoder;
24 /* CTF metadata decoder status */
25 enum ctf_metadata_decoder_status {
26 CTF_METADATA_DECODER_STATUS_OK = 0,
27 CTF_METADATA_DECODER_STATUS_NONE = 1,
28 CTF_METADATA_DECODER_STATUS_ERROR = -1,
29 CTF_METADATA_DECODER_STATUS_INCOMPLETE = -2,
30 CTF_METADATA_DECODER_STATUS_INVAL_VERSION = -3,
31 CTF_METADATA_DECODER_STATUS_IR_VISITOR_ERROR = -4,
34 /* Decoding configuration */
35 struct ctf_metadata_decoder_config {
36 /* Active log level to use */
37 bt_logging_level log_level;
40 * Component or component class to use for logging (exactly one of
41 * them must be non-`NULL`); weak
43 bt_self_component *self_comp;
44 bt_self_component_class *self_comp_class;
46 /* Additional clock class offset to apply */
47 int64_t clock_class_offset_s;
48 int64_t clock_class_offset_ns;
49 bool force_clock_class_origin_unix_epoch;
51 /* True to create trace class objects */
52 bool create_trace_class;
55 * True to keep the plain text when content is appended with
56 * ctf_metadata_decoder_append_content().
62 * Creates a CTF metadata decoder.
64 * Returns `NULL` on error.
67 struct ctf_metadata_decoder *ctf_metadata_decoder_create(
68 const struct ctf_metadata_decoder_config *config);
71 * Destroys a CTF metadata decoder that you created with
72 * ctf_metadata_decoder_create().
75 void ctf_metadata_decoder_destroy(
76 struct ctf_metadata_decoder *metadata_decoder);
79 * Appends content to the metadata decoder.
81 * This function reads the metadata from the current position of `fp`
82 * until the end of this file stream.
84 * The metadata can be packetized or not.
86 * The metadata chunk needs to be complete and lexically scannable, that
87 * is, zero or more complete top-level blocks. If it's incomplete, this
88 * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`. If this
89 * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`, then you
90 * need to call it again with the _same_ metadata and more to make it
91 * complete. For example:
93 * First call: event { name = hell
94 * Second call: event { name = hello_world; ... };
96 * If everything goes as expected, this function returns
97 * `CTF_METADATA_DECODER_STATUS_OK`.
100 enum ctf_metadata_decoder_status ctf_metadata_decoder_append_content(
101 struct ctf_metadata_decoder *metadata_decoder, FILE *fp);
104 * Returns the trace IR trace class of this metadata decoder (new
107 * Returns `NULL` if there's none yet or if the metadata decoder is not
108 * configured to create trace classes.
111 bt_trace_class *ctf_metadata_decoder_get_ir_trace_class(
112 struct ctf_metadata_decoder *mdec);
115 * Returns the CTF IR trace class of this metadata decoder.
117 * Returns `NULL` if there's none yet or if the metadata decoder is not
118 * configured to create trace classes.
121 struct ctf_trace_class *ctf_metadata_decoder_borrow_ctf_trace_class(
122 struct ctf_metadata_decoder *mdec);
125 * Checks whether or not a given metadata file stream `fp` is
126 * packetized, setting `is_packetized` accordingly on success. On
127 * success, also sets `*byte_order` to the byte order of the first
130 * This function uses `log_level` and `self_comp` for logging purposes.
131 * `self_comp` can be `NULL` if not available.
134 int ctf_metadata_decoder_is_packetized(FILE *fp, bool *is_packetized,
135 int *byte_order, bt_logging_level log_level,
136 bt_self_component *self_comp);
139 * Returns the byte order of the decoder's metadata stream as set by the
140 * last call to ctf_metadata_decoder_append_content().
142 * Returns -1 if unknown (plain text content).
145 int ctf_metadata_decoder_get_byte_order(struct ctf_metadata_decoder *mdec);
148 * Returns the UUID of the decoder's metadata stream as set by the last
149 * call to ctf_metadata_decoder_append_content().
152 int ctf_metadata_decoder_get_uuid(
153 struct ctf_metadata_decoder *mdec, bt_uuid_t uuid);
156 * Returns the UUID of the decoder's trace class, if available.
160 * * `CTF_METADATA_DECODER_STATUS_OK`: success.
161 * * `CTF_METADATA_DECODER_STATUS_NONE`: no UUID.
162 * * `CTF_METADATA_DECODER_STATUS_INCOMPLETE`: missing metadata content.
165 enum ctf_metadata_decoder_status ctf_metadata_decoder_get_trace_class_uuid(
166 struct ctf_metadata_decoder *mdec, bt_uuid_t uuid);
169 * Returns the metadata decoder's current metadata text.
172 const char *ctf_metadata_decoder_get_text(struct ctf_metadata_decoder *mdec);
175 bool ctf_metadata_decoder_is_packet_version_valid(unsigned int major,
178 return major == 1 && minor == 8;
181 #endif /* _METADATA_DECODER_H */