b0f179be71857072c913c5ef7030918bb4db65c7
[babeltrace.git] / src / plugins / ctf / common / metadata / decoder.h
1 #ifndef _METADATA_DECODER_H
2 #define _METADATA_DECODER_H
3
4 /*
5 * Copyright 2016-2017 - Philippe Proulx <pproulx@efficios.com>
6 *
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:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 */
17
18 #include <stdint.h>
19 #include <stdbool.h>
20
21 #include <babeltrace2/babeltrace.h>
22
23 /* A CTF metadata decoder object */
24 struct ctf_metadata_decoder;
25
26 /* CTF metadata decoder status */
27 enum ctf_metadata_decoder_status {
28 CTF_METADATA_DECODER_STATUS_OK = 0,
29 CTF_METADATA_DECODER_STATUS_ERROR = -1,
30 CTF_METADATA_DECODER_STATUS_INCOMPLETE = -2,
31 CTF_METADATA_DECODER_STATUS_INVAL_VERSION = -3,
32 CTF_METADATA_DECODER_STATUS_IR_VISITOR_ERROR = -4,
33 };
34
35 /* Decoding configuration */
36 struct ctf_metadata_decoder_config {
37 int64_t clock_class_offset_s;
38 int64_t clock_class_offset_ns;
39 };
40
41 /*
42 * Creates a CTF metadata decoder.
43 *
44 * Returns `NULL` on error.
45 */
46 BT_HIDDEN
47 struct ctf_metadata_decoder *ctf_metadata_decoder_create(
48 bt_self_component_source *self_comp,
49 const struct ctf_metadata_decoder_config *config);
50
51 /*
52 * Destroys a CTF metadata decoder that you created with
53 * ctf_metadata_decoder_create().
54 */
55 BT_HIDDEN
56 void ctf_metadata_decoder_destroy(
57 struct ctf_metadata_decoder *metadata_decoder);
58
59 /*
60 * Decodes a new chunk of CTF metadata.
61 *
62 * This function reads the metadata from the current position of `fp`
63 * until the end of this file stream. If it finds new information (new
64 * event class, new stream class, or new clock class), it appends this
65 * information to the decoder's trace object (as returned by
66 * ctf_metadata_decoder_get_ir_trace_class()), or it creates this trace.
67 *
68 * The metadata can be packetized or not.
69 *
70 * The metadata chunk needs to be complete and scannable, that is,
71 * zero or more complete top-level blocks. If it's incomplete, this
72 * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`. If this
73 * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`, then you
74 * need to call it again with the same metadata and more to make it
75 * complete. For example:
76 *
77 * First call: event { name = hell
78 * Second call: event { name = hello_world; ... };
79 *
80 * If the conversion from the metadata text to CTF IR objects fails,
81 * this function returns `CTF_METADATA_DECODER_STATUS_IR_VISITOR_ERROR`.
82 *
83 * If everything goes as expected, this function returns
84 * `CTF_METADATA_DECODER_STATUS_OK`.
85 */
86 BT_HIDDEN
87 enum ctf_metadata_decoder_status ctf_metadata_decoder_decode(
88 struct ctf_metadata_decoder *metadata_decoder, FILE *fp);
89
90 BT_HIDDEN
91 bt_trace_class *ctf_metadata_decoder_get_ir_trace_class(
92 struct ctf_metadata_decoder *mdec);
93
94 BT_HIDDEN
95 struct ctf_trace_class *ctf_metadata_decoder_borrow_ctf_trace_class(
96 struct ctf_metadata_decoder *mdec);
97
98 /*
99 * Checks whether or not a given metadata file stream is packetized, and
100 * if so, sets `*byte_order` to the byte order of the first packet.
101 */
102 BT_HIDDEN
103 bool ctf_metadata_decoder_is_packetized(FILE *fp, int *byte_order);
104
105 /*
106 * Decodes a packetized metadata file stream to a NULL-terminated
107 * text buffer using the given byte order.
108 */
109 BT_HIDDEN
110 int ctf_metadata_decoder_packetized_file_stream_to_buf(
111 FILE *fp, char **buf, int byte_order);
112
113 #endif /* _METADATA_DECODER_H */
This page took 0.03111 seconds and 3 git commands to generate.