1 #ifndef _METADATA_DECODER_H
2 #define _METADATA_DECODER_H
5 * Copyright 2016-2017 - Philippe Proulx <pproulx@efficios.com>
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
21 #include <babeltrace2/babeltrace.h>
23 #include "common/macros.h"
24 #include "common/uuid.h"
26 struct ctf_trace_class
;
28 /* A CTF metadata decoder object */
29 struct ctf_metadata_decoder
;
31 /* CTF metadata decoder status */
32 enum ctf_metadata_decoder_status
{
33 CTF_METADATA_DECODER_STATUS_OK
= 0,
34 CTF_METADATA_DECODER_STATUS_NONE
= 1,
35 CTF_METADATA_DECODER_STATUS_ERROR
= -1,
36 CTF_METADATA_DECODER_STATUS_INCOMPLETE
= -2,
37 CTF_METADATA_DECODER_STATUS_INVAL_VERSION
= -3,
38 CTF_METADATA_DECODER_STATUS_IR_VISITOR_ERROR
= -4,
41 /* Decoding configuration */
42 struct ctf_metadata_decoder_config
{
43 /* Active log level to use */
44 bt_logging_level log_level
;
46 /* Component to use for logging (can be `NULL`); weak */
47 bt_self_component
*self_comp
;
49 /* Additional clock class offset to apply */
50 int64_t clock_class_offset_s
;
51 int64_t clock_class_offset_ns
;
53 /* True to create trace class objects */
54 bool create_trace_class
;
57 * True to keep the plain text when content is appended with
58 * ctf_metadata_decoder_append_content().
64 * Creates a CTF metadata decoder.
66 * Returns `NULL` on error.
69 struct ctf_metadata_decoder
*ctf_metadata_decoder_create(
70 const struct ctf_metadata_decoder_config
*config
);
73 * Destroys a CTF metadata decoder that you created with
74 * ctf_metadata_decoder_create().
77 void ctf_metadata_decoder_destroy(
78 struct ctf_metadata_decoder
*metadata_decoder
);
81 * Appends content to the metadata decoder.
83 * This function reads the metadata from the current position of `fp`
84 * until the end of this file stream.
86 * The metadata can be packetized or not.
88 * The metadata chunk needs to be complete and lexically scannable, that
89 * is, zero or more complete top-level blocks. If it's incomplete, this
90 * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`. If this
91 * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`, then you
92 * need to call it again with the _same_ metadata and more to make it
93 * complete. For example:
95 * First call: event { name = hell
96 * Second call: event { name = hello_world; ... };
98 * If everything goes as expected, this function returns
99 * `CTF_METADATA_DECODER_STATUS_OK`.
102 enum ctf_metadata_decoder_status
ctf_metadata_decoder_append_content(
103 struct ctf_metadata_decoder
*metadata_decoder
, FILE *fp
);
106 * Returns the trace IR trace class of this metadata decoder (new
109 * Returns `NULL` if there's none yet or if the metadata decoder is not
110 * configured to create trace classes.
113 bt_trace_class
*ctf_metadata_decoder_get_ir_trace_class(
114 struct ctf_metadata_decoder
*mdec
);
117 * Returns the CTF IR trace class of this metadata decoder.
119 * Returns `NULL` if there's none yet or if the metadata decoder is not
120 * configured to create trace classes.
123 struct ctf_trace_class
*ctf_metadata_decoder_borrow_ctf_trace_class(
124 struct ctf_metadata_decoder
*mdec
);
127 * Checks whether or not a given metadata file stream `fp` is
128 * packetized, setting `is_packetized` accordingly on success. On
129 * success, also sets `*byte_order` to the byte order of the first
132 * This function uses `log_level` and `self_comp` for logging purposes.
133 * `self_comp` can be `NULL` if not available.
136 int ctf_metadata_decoder_is_packetized(FILE *fp
, bool *is_packetized
,
137 int *byte_order
, bt_logging_level log_level
,
138 bt_self_component
*self_comp
);
141 * Returns the byte order of the decoder's metadata stream as set by the
142 * last call to ctf_metadata_decoder_append_content().
144 * Returns -1 if unknown (plain text content).
147 int ctf_metadata_decoder_get_byte_order(struct ctf_metadata_decoder
*mdec
);
150 * Returns the UUID of the decoder's metadata stream as set by the last
151 * call to ctf_metadata_decoder_append_content().
154 int ctf_metadata_decoder_get_uuid(
155 struct ctf_metadata_decoder
*mdec
, bt_uuid_t uuid
);
158 * Returns the UUID of the decoder's trace class, if available.
162 * * `CTF_METADATA_DECODER_STATUS_OK`: success.
163 * * `CTF_METADATA_DECODER_STATUS_NONE`: no UUID.
164 * * `CTF_METADATA_DECODER_STATUS_INCOMPLETE`: missing metadata content.
167 enum ctf_metadata_decoder_status
ctf_metadata_decoder_get_trace_class_uuid(
168 struct ctf_metadata_decoder
*mdec
, bt_uuid_t uuid
);
171 * Returns the metadata decoder's current metadata text.
174 const char *ctf_metadata_decoder_get_text(struct ctf_metadata_decoder
*mdec
);
177 bool ctf_metadata_decoder_is_packet_version_valid(unsigned int major
,
180 return major
== 1 && minor
== 8;
183 #endif /* _METADATA_DECODER_H */