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  */