2 * SPDX-License-Identifier: MIT
4 * Copyright 2016-2017 Philippe Proulx <pproulx@efficios.com>
7 #ifndef _METADATA_DECODER_H
8 #define _METADATA_DECODER_H
13 #include <babeltrace2/babeltrace.h>
15 #include "common/macros.h"
16 #include "common/uuid.h"
18 struct ctf_trace_class
;
20 /* A CTF metadata decoder object */
21 struct ctf_metadata_decoder
;
23 /* CTF metadata decoder status */
24 enum ctf_metadata_decoder_status
{
25 CTF_METADATA_DECODER_STATUS_OK
= 0,
26 CTF_METADATA_DECODER_STATUS_NONE
= 1,
27 CTF_METADATA_DECODER_STATUS_ERROR
= -1,
28 CTF_METADATA_DECODER_STATUS_INCOMPLETE
= -2,
29 CTF_METADATA_DECODER_STATUS_INVAL_VERSION
= -3,
30 CTF_METADATA_DECODER_STATUS_IR_VISITOR_ERROR
= -4,
33 /* Decoding configuration */
34 struct ctf_metadata_decoder_config
{
35 /* Active log level to use */
36 bt_logging_level log_level
;
38 /* Component to use for logging (can be `NULL`); weak */
39 bt_self_component
*self_comp
;
41 /* Additional clock class offset to apply */
42 int64_t clock_class_offset_s
;
43 int64_t clock_class_offset_ns
;
44 bool force_clock_class_origin_unix_epoch
;
46 /* True to create trace class objects */
47 bool create_trace_class
;
50 * True to keep the plain text when content is appended with
51 * ctf_metadata_decoder_append_content().
57 * Creates a CTF metadata decoder.
59 * Returns `NULL` on error.
62 struct ctf_metadata_decoder
*ctf_metadata_decoder_create(
63 const struct ctf_metadata_decoder_config
*config
);
66 * Destroys a CTF metadata decoder that you created with
67 * ctf_metadata_decoder_create().
70 void ctf_metadata_decoder_destroy(
71 struct ctf_metadata_decoder
*metadata_decoder
);
74 * Appends content to the metadata decoder.
76 * This function reads the metadata from the current position of `fp`
77 * until the end of this file stream.
79 * The metadata can be packetized or not.
81 * The metadata chunk needs to be complete and lexically scannable, that
82 * is, zero or more complete top-level blocks. If it's incomplete, this
83 * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`. If this
84 * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`, then you
85 * need to call it again with the _same_ metadata and more to make it
86 * complete. For example:
88 * First call: event { name = hell
89 * Second call: event { name = hello_world; ... };
91 * If everything goes as expected, this function returns
92 * `CTF_METADATA_DECODER_STATUS_OK`.
95 enum ctf_metadata_decoder_status
ctf_metadata_decoder_append_content(
96 struct ctf_metadata_decoder
*metadata_decoder
, FILE *fp
);
99 * Returns the trace IR trace class of this metadata decoder (new
102 * Returns `NULL` if there's none yet or if the metadata decoder is not
103 * configured to create trace classes.
106 bt_trace_class
*ctf_metadata_decoder_get_ir_trace_class(
107 struct ctf_metadata_decoder
*mdec
);
110 * Returns the CTF IR trace class of this metadata decoder.
112 * Returns `NULL` if there's none yet or if the metadata decoder is not
113 * configured to create trace classes.
116 struct ctf_trace_class
*ctf_metadata_decoder_borrow_ctf_trace_class(
117 struct ctf_metadata_decoder
*mdec
);
120 * Checks whether or not a given metadata file stream `fp` is
121 * packetized, setting `is_packetized` accordingly on success. On
122 * success, also sets `*byte_order` to the byte order of the first
125 * This function uses `log_level` and `self_comp` for logging purposes.
126 * `self_comp` can be `NULL` if not available.
129 int ctf_metadata_decoder_is_packetized(FILE *fp
, bool *is_packetized
,
130 int *byte_order
, bt_logging_level log_level
,
131 bt_self_component
*self_comp
);
134 * Returns the byte order of the decoder's metadata stream as set by the
135 * last call to ctf_metadata_decoder_append_content().
137 * Returns -1 if unknown (plain text content).
140 int ctf_metadata_decoder_get_byte_order(struct ctf_metadata_decoder
*mdec
);
143 * Returns the UUID of the decoder's metadata stream as set by the last
144 * call to ctf_metadata_decoder_append_content().
147 int ctf_metadata_decoder_get_uuid(
148 struct ctf_metadata_decoder
*mdec
, bt_uuid_t uuid
);
151 * Returns the UUID of the decoder's trace class, if available.
155 * * `CTF_METADATA_DECODER_STATUS_OK`: success.
156 * * `CTF_METADATA_DECODER_STATUS_NONE`: no UUID.
157 * * `CTF_METADATA_DECODER_STATUS_INCOMPLETE`: missing metadata content.
160 enum ctf_metadata_decoder_status
ctf_metadata_decoder_get_trace_class_uuid(
161 struct ctf_metadata_decoder
*mdec
, bt_uuid_t uuid
);
164 * Returns the metadata decoder's current metadata text.
167 const char *ctf_metadata_decoder_get_text(struct ctf_metadata_decoder
*mdec
);
170 bool ctf_metadata_decoder_is_packet_version_valid(unsigned int major
,
173 return major
== 1 && minor
== 8;
176 #endif /* _METADATA_DECODER_H */