wmem: allow wmem_destroy_list to ignore a NULL list.
[metze/wireshark/wip.git] / wsutil / json_dumper.h
1 /* wsjson.h
2  * Routines for serializing data as JSON.
3  *
4  * Copyright 2018, Peter Wu <peter@lekensteyn.nl>
5  *
6  * Wireshark - Network traffic analyzer
7  * By Gerald Combs <gerald@wireshark.org>
8  * Copyright 1998 Gerald Combs
9  *
10  * SPDX-License-Identifier: GPL-2.0-or-later
11  */
12
13 #ifndef __JSON_DUMPER_H__
14 #define __JSON_DUMPER_H__
15
16 #include "ws_symbol_export.h"
17 #include <glib.h>
18 #include <stdio.h>
19
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23
24 /**
25  * Example:
26  *
27  *  json_dumper dumper = {
28  *      .output_file = stdout,
29  *      .flags = JSON_DUMPER_FLAGS_PRETTY_PRINT,
30  *  };
31  *  json_dumper_begin_object(&dumper);
32  *  json_dumper_set_member_name(&dumper, "key");
33  *  json_dumper_value_string(&dumper, "value");
34  *  json_dumper_set_member_name(&dumper, "array");
35  *  json_dumper_begin_array(&dumper);
36  *  json_dumper_value_anyf(&dumper, "true");
37  *  json_dumper_value_anyf(&dumper, "1.0");
38  *  json_dumper_begin_base64(&dumper);
39  *  json_dumper_write_base64(&dumper, (const guchar *)"abcd", 4);
40  *  json_dumper_write_base64(&dumper, (const guchar *)"1234", 4);
41  *  json_dumper_end_base64(&dumper);
42  *  json_dumper_begin_object(&dumper);
43  *  json_dumper_end_object(&dumper);
44  *  json_dumper_begin_array(&dumper);
45  *  json_dumper_end_array(&dumper);
46  *  json_dumper_end_array(&dumper);
47  *  json_dumper_end_object(&dumper);
48  *  json_dumper_finish(&dumper);
49  */
50
51 /** Maximum object/array nesting depth. */
52 #define JSON_DUMPER_MAX_DEPTH   1100
53 typedef struct json_dumper {
54     FILE   *output_file;    /**< Output file, must be set. */
55 #define JSON_DUMPER_FLAGS_PRETTY_PRINT  (1 << 0)    /* Enable pretty printing. */
56 #define JSON_DUMPER_DOT_TO_UNDERSCORE   (1 << 1)    /* Convert dots to underscores in keys */
57     int     flags;
58     /* for internal use, initialize with zeroes. */
59     int     current_depth;
60     gint    base64_state;
61     gint    base64_save;
62     guint8  state[JSON_DUMPER_MAX_DEPTH];
63 } json_dumper;
64
65 WS_DLL_PUBLIC void
66 json_dumper_begin_object(json_dumper *dumper);
67
68 WS_DLL_PUBLIC void
69 json_dumper_set_member_name(json_dumper *dumper, const char *name);
70
71 WS_DLL_PUBLIC void
72 json_dumper_end_object(json_dumper *dumper);
73
74 WS_DLL_PUBLIC void
75 json_dumper_begin_array(json_dumper *dumper);
76
77 WS_DLL_PUBLIC void
78 json_dumper_end_array(json_dumper *dumper);
79
80 WS_DLL_PUBLIC void
81 json_dumper_value_string(json_dumper *dumper, const char *value);
82
83 /**
84  * Dump number, "true", "false" or "null" values.
85  */
86 WS_DLL_PUBLIC void
87 json_dumper_value_anyf(json_dumper *dumper, const char *format, ...)
88 G_GNUC_PRINTF(2, 3);
89
90 /**
91  * Dump literal values (like json_dumper_value_anyf), but taking a va_list
92  * as parameter. String values MUST be properly quoted by the caller, no
93  * escaping occurs. Do not use with untrusted data.
94  */
95 WS_DLL_PUBLIC void
96 json_dumper_value_va_list(json_dumper *dumper, const char *format, va_list ap);
97
98 WS_DLL_PUBLIC void
99 json_dumper_begin_base64(json_dumper *dumper);
100
101 WS_DLL_PUBLIC void
102 json_dumper_end_base64(json_dumper *dumper);
103
104 WS_DLL_PUBLIC void
105 json_dumper_write_base64(json_dumper *dumper, const guchar *data, size_t len);
106
107 /**
108  * Finishes dumping data. Returns TRUE if everything is okay and FALSE if
109  * something went wrong (open/close mismatch, missing values, etc.).
110  */
111 WS_DLL_PUBLIC gboolean
112 json_dumper_finish(json_dumper *dumper);
113
114 #ifdef __cplusplus
115 }
116 #endif
117
118 #endif /* __JSON_DUMPER_H__ */
119
120 /*
121  * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
122  *
123  * Local variables:
124  * c-basic-offset: 4
125  * tab-width: 8
126  * indent-tabs-mode: nil
127  * End:
128  *
129  * vi: set shiftwidth=4 tabstop=8 expandtab:
130  * :indentSize=4:tabSize=8:noTabs=true:
131  */