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
;
39 * Component or component class to use for logging (exactly one of
40 * them must be non-`NULL`); weak
42 bt_self_component
*self_comp
;
43 bt_self_component_class
*self_comp_class
;
45 /* Additional clock class offset to apply */
46 int64_t clock_class_offset_s
;
47 int64_t clock_class_offset_ns
;
48 bool force_clock_class_origin_unix_epoch
;
50 /* True to create trace class objects */
51 bool create_trace_class
;
54 * True to keep the plain text when content is appended with
55 * ctf_metadata_decoder_append_content().
61 * Creates a CTF metadata decoder.
63 * Returns `NULL` on error.
66 struct ctf_metadata_decoder
*ctf_metadata_decoder_create(
67 const struct ctf_metadata_decoder_config
*config
);
70 * Destroys a CTF metadata decoder that you created with
71 * ctf_metadata_decoder_create().
74 void ctf_metadata_decoder_destroy(
75 struct ctf_metadata_decoder
*metadata_decoder
);
78 * Appends content to the metadata decoder.
80 * This function reads the metadata from the current position of `fp`
81 * until the end of this file stream.
83 * The metadata can be packetized or not.
85 * The metadata chunk needs to be complete and lexically scannable, that
86 * is, zero or more complete top-level blocks. If it's incomplete, this
87 * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`. If this
88 * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`, then you
89 * need to call it again with the _same_ metadata and more to make it
90 * complete. For example:
92 * First call: event { name = hell
93 * Second call: event { name = hello_world; ... };
95 * If everything goes as expected, this function returns
96 * `CTF_METADATA_DECODER_STATUS_OK`.
99 enum ctf_metadata_decoder_status
ctf_metadata_decoder_append_content(
100 struct ctf_metadata_decoder
*metadata_decoder
, FILE *fp
);
103 * Returns the trace IR trace class of this metadata decoder (new
106 * Returns `NULL` if there's none yet or if the metadata decoder is not
107 * configured to create trace classes.
110 bt_trace_class
*ctf_metadata_decoder_get_ir_trace_class(
111 struct ctf_metadata_decoder
*mdec
);
114 * Returns the CTF IR trace class of this metadata decoder.
116 * Returns `NULL` if there's none yet or if the metadata decoder is not
117 * configured to create trace classes.
120 struct ctf_trace_class
*ctf_metadata_decoder_borrow_ctf_trace_class(
121 struct ctf_metadata_decoder
*mdec
);
124 * Checks whether or not a given metadata file stream `fp` is
125 * packetized, setting `is_packetized` accordingly on success. On
126 * success, also sets `*byte_order` to the byte order of the first
129 * This function uses `log_level` and `self_comp` for logging purposes.
130 * `self_comp` can be `NULL` if not available.
133 int ctf_metadata_decoder_is_packetized(FILE *fp
, bool *is_packetized
,
134 int *byte_order
, bt_logging_level log_level
,
135 bt_self_component
*self_comp
);
138 * Returns the byte order of the decoder's metadata stream as set by the
139 * last call to ctf_metadata_decoder_append_content().
141 * Returns -1 if unknown (plain text content).
144 int ctf_metadata_decoder_get_byte_order(struct ctf_metadata_decoder
*mdec
);
147 * Returns the UUID of the decoder's metadata stream as set by the last
148 * call to ctf_metadata_decoder_append_content().
151 int ctf_metadata_decoder_get_uuid(
152 struct ctf_metadata_decoder
*mdec
, bt_uuid_t uuid
);
155 * Returns the UUID of the decoder's trace class, if available.
159 * * `CTF_METADATA_DECODER_STATUS_OK`: success.
160 * * `CTF_METADATA_DECODER_STATUS_NONE`: no UUID.
161 * * `CTF_METADATA_DECODER_STATUS_INCOMPLETE`: missing metadata content.
164 enum ctf_metadata_decoder_status
ctf_metadata_decoder_get_trace_class_uuid(
165 struct ctf_metadata_decoder
*mdec
, bt_uuid_t uuid
);
168 * Returns the metadata decoder's current metadata text.
171 const char *ctf_metadata_decoder_get_text(struct ctf_metadata_decoder
*mdec
);
174 bool ctf_metadata_decoder_is_packet_version_valid(unsigned int major
,
177 return major
== 1 && minor
== 8;
180 #endif /* _METADATA_DECODER_H */