json_dumper.h File Reference

#include "ws_symbol_export.h"
#include <inttypes.h>
#include <stdbool.h>
#include <stdio.h>
#include <glib.h>

Go to the source code of this file.

Classes
struct	json_dumper
	State and configuration for incrementally writing JSON output to a file or string. More...

Macros
#define	JSON_DUMPER_MAX_DEPTH   1100
#define	JSON_DUMPER_FLAGS_PRETTY_PRINT   (1 << 0)
#define	JSON_DUMPER_DOT_TO_UNDERSCORE   (1 << 1)
#define	JSON_DUMPER_FLAGS_NO_DEBUG   (1 << 17)
#define	JD_BUF_SIZE   8192
#define	json_dumper_set_member_name_const(dumper, literal)
	Sets the member name of an object using a string literal.

Typedefs
typedef struct json_dumper	json_dumper
	State and configuration for incrementally writing JSON output to a file or string.

Functions
WS_DLL_PUBLIC void	json_dumper_begin_object (json_dumper *dumper)
	Begins a new JSON object.
WS_DLL_PUBLIC void	json_dumper_set_member_name (json_dumper *dumper, const char *name)
	Sets the name of the next member in a JSON object.
WS_DLL_PUBLIC void	json_dumper_set_member_name_noesc (json_dumper *dumper, const char *name, size_t len)
WS_DLL_PUBLIC void	json_dumper_end_object (json_dumper *dumper)
	Ends the current JSON object.
WS_DLL_PUBLIC void	json_dumper_begin_array (json_dumper *dumper)
	Begins a new JSON array.
WS_DLL_PUBLIC void	json_dumper_end_array (json_dumper *dumper)
	Ends the current JSON array.
WS_DLL_PUBLIC void	json_dumper_value_string (json_dumper *dumper, const char *value)
	Writes a string value to the JSON output.
WS_DLL_PUBLIC void	json_dumper_value_string_noesc (json_dumper *dumper, const char *value, size_t len)
	Writes a string value that is known to not require JSON escaping.
WS_DLL_PUBLIC void	json_dumper_value_double (json_dumper *dumper, double value)
	Writes a double-precision numeric value to the JSON output.
WS_DLL_PUBLIC void	json_dumper_value_anyf (json_dumper *dumper, const char *format,...)
	Writes a formatted literal value to the JSON output.
WS_DLL_PUBLIC void	json_dumper_value_va_list (json_dumper *dumper, const char *format, va_list ap)
	Writes a formatted literal value using a va_list.
WS_DLL_PUBLIC void	json_dumper_value_int (json_dumper *dumper, int64_t value)
	Writes a signed 64-bit integer value without printf overhead.
WS_DLL_PUBLIC void	json_dumper_value_uint (json_dumper *dumper, uint64_t value)
	Writes an unsigned 64-bit integer value without printf overhead.
WS_DLL_PUBLIC void	json_dumper_begin_base64 (json_dumper *dumper)
	Begins a base64-encoded data block.
WS_DLL_PUBLIC void	json_dumper_end_base64 (json_dumper *dumper)
	Ends a base64-encoded data block.
WS_DLL_PUBLIC void	json_dumper_write_base64 (json_dumper *dumper, const unsigned char *data, size_t len)
	Writes binary data in base64 format.
WS_DLL_PUBLIC bool	json_dumper_finish (json_dumper *dumper)
	Finalizes the JSON output.

Detailed Description

Routines for serializing data as JSON.

Copyright 2018, Peter Wu peter.nosp@m.@lek.nosp@m.enste.nosp@m.yn.n.nosp@m.l

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 1998 Gerald Combs

SPDX-License-Identifier: GPL-2.0-or-later

Macro Definition Documentation

JSON_DUMPER_DOT_TO_UNDERSCORE

#define JSON_DUMPER_DOT_TO_UNDERSCORE   (1 << 1)

Replace '.' with '_' in all object key names.

JSON_DUMPER_FLAGS_NO_DEBUG

#define JSON_DUMPER_FLAGS_NO_DEBUG   (1 << 17)

Suppress fatal ws_error messages on misuse; intended to improve fuzzing throughput.

JSON_DUMPER_FLAGS_PRETTY_PRINT

#define JSON_DUMPER_FLAGS_PRETTY_PRINT   (1 << 0)

Enable pretty-printed output with indentation and newlines.

JSON_DUMPER_MAX_DEPTH

#define JSON_DUMPER_MAX_DEPTH   1100

Example:

json_dumper dumper = { .output_file = stdout, // or .output_string = g_string_new(NULL) .flags = JSON_DUMPER_FLAGS_PRETTY_PRINT, }; json_dumper_begin_object(&dumper); json_dumper_set_member_name(&dumper, "key"); json_dumper_value_string(&dumper, "value"); json_dumper_set_member_name(&dumper, "array"); json_dumper_begin_array(&dumper); json_dumper_value_anyf(&dumper, "true"); json_dumper_value_double(&dumper, 1.0); json_dumper_begin_base64(&dumper); json_dumper_write_base64(&dumper, (const unsigned char *)"abcd", 4); json_dumper_write_base64(&dumper, (const unsigned char *)"1234", 4); json_dumper_end_base64(&dumper); json_dumper_begin_object(&dumper); json_dumper_end_object(&dumper); json_dumper_begin_array(&dumper); json_dumper_end_array(&dumper); json_dumper_end_array(&dumper); json_dumper_end_object(&dumper); json_dumper_finish(&dumper); Maximum object/array nesting depth.

json_dumper_set_member_name_const

#define json_dumper_set_member_name_const	(		dumper,
			literal )

Value:

    json_dumper_set_member_name_noesc(dumper, literal, sizeof(literal) - 1)

Sets the member name of an object using a string literal.

The length is computed at compile time via sizeof. The literal must not contain characters that require JSON escaping (backslash, double-quote, or control characters). Only use with string literal arguments.

Function Documentation

json_dumper_begin_array()

WS_DLL_PUBLIC void json_dumper_begin_array

(

json_dumper *

dumper

)

Begins a new JSON array.

Starts a JSON array context. Must be paired with a call to json_dumper_end_array().

Parameters

dumper

The JSON dumper context.

json_dumper_begin_base64()

WS_DLL_PUBLIC void json_dumper_begin_base64

(

json_dumper *

dumper

)

Begins a base64-encoded data block.

Starts a base64 encoding context for binary data. Must be paired with json_dumper_end_base64().

Parameters

dumper

The JSON dumper context.

json_dumper_begin_object()

WS_DLL_PUBLIC void json_dumper_begin_object

(

json_dumper *

dumper

)

Begins a new JSON object.

Starts a JSON object context. Must be paired with a call to json_dumper_end_object().

Parameters

dumper

The JSON dumper context.

json_dumper_end_array()

WS_DLL_PUBLIC void json_dumper_end_array

(

json_dumper *

dumper

)

Ends the current JSON array.

Closes the current array context started by json_dumper_begin_array().

Parameters

dumper

The JSON dumper context.

json_dumper_end_base64()

WS_DLL_PUBLIC void json_dumper_end_base64

(

json_dumper *

dumper

)

Ends a base64-encoded data block.

Closes the base64 encoding context started by json_dumper_begin_base64().

Parameters

dumper

The JSON dumper context.

json_dumper_end_object()

WS_DLL_PUBLIC void json_dumper_end_object

(

json_dumper *

dumper

)

Ends the current JSON object.

Closes the current object context started by json_dumper_begin_object().

Parameters

dumper

The JSON dumper context.

json_dumper_finish()

WS_DLL_PUBLIC bool json_dumper_finish

(

json_dumper *

dumper

)

Finalizes the JSON output.

Completes the JSON dump and checks for structural correctness (e.g., matching open/close calls).

Parameters

dumper

The JSON dumper context.

Returns

true if the output is valid and complete, false if errors occurred.

json_dumper_set_member_name()

WS_DLL_PUBLIC void json_dumper_set_member_name	(	json_dumper *	dumper,
		const char *	name )

Sets the name of the next member in a JSON object.

Specifies the key for the next value to be written inside an open JSON object.

Parameters

dumper	The JSON dumper context.
name	The name of the member key.

< Replace '.' with '_' in all object key names.

< Enable pretty-printed output with indentation and newlines.

json_dumper_set_member_name_noesc()

WS_DLL_PUBLIC void json_dumper_set_member_name_noesc	(	json_dumper *	dumper,
		const char *	name,
		size_t	len )

< Enable pretty-printed output with indentation and newlines.

json_dumper_value_anyf()

WS_DLL_PUBLIC void json_dumper_value_anyf	(	json_dumper *	dumper,
		const char *	format,
			... )

Writes a formatted literal value to the JSON output.

Dumps a literal value such as a number, "true", "false", or "null" using printf-style formatting.

Parameters

dumper	The JSON dumper context.
format	The format string for the value.
...	Additional arguments for formatting.

json_dumper_value_double()

WS_DLL_PUBLIC void json_dumper_value_double	(	json_dumper *	dumper,
		double	value )

Writes a double-precision numeric value to the JSON output.

Adds a floating-point number to the current object or array.

Parameters

dumper	The JSON dumper context.
value	The double value to write.

json_dumper_value_int()

WS_DLL_PUBLIC void json_dumper_value_int	(	json_dumper *	dumper,
		int64_t	value )

Writes a signed 64-bit integer value without printf overhead.

Parameters

dumper	The JSON dumper context.
value	The integer value to write.

json_dumper_value_string()

WS_DLL_PUBLIC void json_dumper_value_string	(	json_dumper *	dumper,
		const char *	value )

Writes a string value to the JSON output.

Adds a properly escaped string value to the current object or array.

Parameters

dumper	The JSON dumper context.
value	The string value to write.

json_dumper_value_string_noesc()

WS_DLL_PUBLIC void json_dumper_value_string_noesc	(	json_dumper *	dumper,
		const char *	value,
		size_t	len )

Writes a string value that is known to not require JSON escaping.

Skips the escape-scanning overhead. The caller guarantees the string contains no characters that need escaping (no control chars, backslash, or quotes).

Parameters

dumper	The JSON dumper context.
value	The pre-validated string value.
len	Length of the string.

json_dumper_value_uint()

WS_DLL_PUBLIC void json_dumper_value_uint	(	json_dumper *	dumper,
		uint64_t	value )

Writes an unsigned 64-bit integer value without printf overhead.

Parameters

dumper	The JSON dumper context.
value	The integer value to write.

json_dumper_value_va_list()

WS_DLL_PUBLIC void json_dumper_value_va_list	(	json_dumper *	dumper,
		const char *	format,
		va_list	ap )

Writes a formatted literal value using a va_list.

Similar to json_dumper_value_anyf(), but accepts a va_list for formatting. String values must be properly quoted and escaped by the caller. Not safe for untrusted input.

Parameters

dumper	The JSON dumper context.
format	The format string for the value.
ap	The va_list of arguments.

json_dumper_write_base64()

WS_DLL_PUBLIC void json_dumper_write_base64	(	json_dumper *	dumper,
		const unsigned char *	data,
		size_t	len )

Writes binary data in base64 format.

Encodes and writes the given binary data as base64 within an active base64 context.

Parameters

dumper	The JSON dumper context.
data	Pointer to the binary data.
len	Length of the binary data in bytes.