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