wsutil/json_dumper.h

   1 /** @file
   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
  18 #include <inttypes.h>
  19 #include <stdbool.h>
  20 #include <stdio.h>
  21
  22 #include <glib.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29  * Example:
  30  *
  31  *  json_dumper dumper = {
  32  *      .output_file = stdout, // or .output_string = g_string_new(NULL)
  33  *      .flags = JSON_DUMPER_FLAGS_PRETTY_PRINT,
  34  *  };
  35  *  json_dumper_begin_object(&dumper);
  36  *  json_dumper_set_member_name(&dumper, "key");
  37  *  json_dumper_value_string(&dumper, "value");
  38  *  json_dumper_set_member_name(&dumper, "array");
  39  *  json_dumper_begin_array(&dumper);
  40  *  json_dumper_value_anyf(&dumper, "true");
  41  *  json_dumper_value_double(&dumper, 1.0);
  42  *  json_dumper_begin_base64(&dumper);
  43  *  json_dumper_write_base64(&dumper, (const unsigned char *)"abcd", 4);
  44  *  json_dumper_write_base64(&dumper, (const unsigned char *)"1234", 4);
  45  *  json_dumper_end_base64(&dumper);
  46  *  json_dumper_begin_object(&dumper);
  47  *  json_dumper_end_object(&dumper);
  48  *  json_dumper_begin_array(&dumper);
  49  *  json_dumper_end_array(&dumper);
  50  *  json_dumper_end_array(&dumper);
  51  *  json_dumper_end_object(&dumper);
  52  *  json_dumper_finish(&dumper);
  53  */
  54
  55 /** Maximum object/array nesting depth. */
  56 #define JSON_DUMPER_MAX_DEPTH   1100
  57 typedef struct json_dumper {
  58     FILE    *output_file;    /**< Output file. If it is not NULL, JSON will be dumped in the file. */
  59     GString *output_string;  /**< Output GLib strings. If it is not NULL, JSON will be dumped in the string. */
  60 #define JSON_DUMPER_FLAGS_PRETTY_PRINT  (1 << 0)    /* Enable pretty printing. */
  61 #define JSON_DUMPER_DOT_TO_UNDERSCORE   (1 << 1)    /* Convert dots to underscores in keys */
  62 #define JSON_DUMPER_FLAGS_NO_DEBUG      (1 << 17)   /* Disable fatal ws_error messages on error(intended for speeding up fuzzing). */
  63     int     flags;
  64     /* for internal use, initialize with zeroes. */
  65     unsigned   current_depth;
  66     int     base64_state;
  67     int     base64_save;
  68     uint8_t state[JSON_DUMPER_MAX_DEPTH];
  69 } json_dumper;
  70
  71 WS_DLL_PUBLIC void
  72 json_dumper_begin_object(json_dumper *dumper);
  73
  74 WS_DLL_PUBLIC void
  75 json_dumper_set_member_name(json_dumper *dumper, const char *name);
  76
  77 WS_DLL_PUBLIC void
  78 json_dumper_end_object(json_dumper *dumper);
  79
  80 WS_DLL_PUBLIC void
  81 json_dumper_begin_array(json_dumper *dumper);
  82
  83 WS_DLL_PUBLIC void
  84 json_dumper_end_array(json_dumper *dumper);
  85
  86 WS_DLL_PUBLIC void
  87 json_dumper_value_string(json_dumper *dumper, const char *value);
  88
  89 WS_DLL_PUBLIC void
  90 json_dumper_value_double(json_dumper *dumper, double value);
  91
  92 /**
  93  * Dump number, "true", "false" or "null" values.
  94  */
  95 WS_DLL_PUBLIC void
  96 json_dumper_value_anyf(json_dumper *dumper, const char *format, ...)
  97 G_GNUC_PRINTF(2, 3);
  98
  99 /**
 100  * Dump literal values (like json_dumper_value_anyf), but taking a va_list
 101  * as parameter. String values MUST be properly quoted by the caller, no
 102  * escaping occurs. Do not use with untrusted data.
 103  */
 104 WS_DLL_PUBLIC void
 105 json_dumper_value_va_list(json_dumper *dumper, const char *format, va_list ap);
 106
 107 WS_DLL_PUBLIC void
 108 json_dumper_begin_base64(json_dumper *dumper);
 109
 110 WS_DLL_PUBLIC void
 111 json_dumper_end_base64(json_dumper *dumper);
 112
 113 WS_DLL_PUBLIC void
 114 json_dumper_write_base64(json_dumper *dumper, const unsigned char *data, size_t len);
 115
 116 /**
 117  * Finishes dumping data. Returns true if everything is okay and false if
 118  * something went wrong (open/close mismatch, missing values, etc.).
 119  */
 120 WS_DLL_PUBLIC bool
 121 json_dumper_finish(json_dumper *dumper);
 122
 123 #ifdef __cplusplus
 124 }
 125 #endif
 126
 127 #endif /* __JSON_DUMPER_H__ */
 128
 129 /*
 130  * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
 131  *
 132  * Local variables:
 133  * c-basic-offset: 4
 134  * tab-width: 8
 135  * indent-tabs-mode: nil
 136  * End:
 137  *
 138  * vi: set shiftwidth=4 tabstop=8 expandtab:
 139  * :indentSize=4:tabSize=8:noTabs=true:
 140  */