JsonSerializer#

Fully qualified name: omni::structuredlog::JsonSerializer

Defined in omni/structuredlog/JsonSerializer.h

template<bool validate = false, bool prettyPrint = false, OnValidationErrorFunc onValidationError = ignoreJsonSerializerValidationError, bool consumeRaw = false, bool hashPseudonymized = false>
class JsonSerializer#

A utility that allows you to easily encode JSON data.

This class is specifically designed to operate on ABI-safe JSON tree structures required by omni.structuredlog. This is not designed to implement the JSON standard. This is just able to serialize JSON to the degree needed to support omni.structuredlog.

This class won’t allocate any memory unless you use an excessive number of scopes.

Note

Users requiring JSON serialization without needing to operate on ABI-safe JSON structures should use a standard JSON library like RapidJSON.

Note

This class is designed for the specific needs of omni.structuredlog and its interface may change as needed by omni.structuredlog.

Param validate:

If this is set to true, methods will return false when an invalid operation is performed. onValidationError is used for logging because this struct is used in the logging system, so OMNI_LOG_* cannot be directly called from within this class. If this is set to false, methods will assume that all calls will produce valid JSON data. Invalid calls will write out invalid JSON data. Methods will only return false if an unavoidable check failed.

Template Parameters:

  • prettyPrint – If this is set to true, the output will be pretty-printed. If this is set to false, the output will have no added white space.

  • onValidationError – This is a callback that gets executed when a validation error is triggered, so logging can be called.

  • consumeRaw – This can be set to false to specify that the consumer used will only ever consume JSON in text form. This will optimize out a virtual call per value written.

  • hashPseudonymized – If this is set to true, string properties marked with fFlagPseudonymize will be hashed to uint64_t values instead of being written as strings. If false, strings are written as-is.

Public Functions

inline JsonSerializer(
JsonConsumer *consumer,
size_t indentLen = 4,
) noexcept#

Constructor.

Parameters:

  • consumer – [in] The object that will consume the output JSON data. This may not be nullptr.

  • indentLen – [in] The number of spaces to indent by when pretty printing is enabled.

inline ~JsonSerializer()#
inline void reset()#

Reset the internal state back to where it was after construction.

inline bool writeKey(const char *key, size_t keyLen) noexcept#

Write out a JSON key for an object property.

Parameters:

  • key – [in] The string value for the key. This can be nullptr.

  • keyLen – [in] The length of key, excluding the null terminator.

Returns:

whether or not validation succeeded.

inline bool writeKey(const char *key) noexcept#

Write out a JSON key for an object property.

Parameters:

key – [in] The key name for this property. This may be nullptr.

Returns:

whether or not validation succeeded.

inline bool writeValueJson(const JsonNode *node) noexcept#

Write out a JSON null value with optional node metadata.

Parameters:

node – [in] The JsonNode describing this property (may be nullptr).

Returns:

whether or not validation succeeded.

inline bool writeValue() noexcept#

Write out a JSON null value.

Returns:

whether or not validation succeeded.

inline bool writeValueJson(const JsonNode *node, bool value) noexcept#

Write out a JSON boolean value with optional node metadata.

Parameters:

  • node – [in] The JsonNode describing this property (may be nullptr).

  • value – [in] The boolean value.

Returns:

whether or not validation succeeded.

inline bool writeValue(bool value) noexcept#

Write out a JSON boolean value.

Parameters:

value – [in] The boolean value.

Returns:

whether or not validation succeeded.

inline bool writeValueJson(
const JsonNode *node,
int32_t value,
) noexcept#

Write out a JSON integer value with optional node metadata.

Parameters:

  • node – [in] The JsonNode describing this property (may be nullptr).

  • value – [in] The integer value.

Returns:

whether or not validation succeeded.

inline bool writeValue(int32_t value) noexcept#

Write out a JSON integer value.

Parameters:

value – [in] The integer value.

Returns:

whether or not validation succeeded.

inline bool writeValueJson(
const JsonNode *node,
uint32_t value,
) noexcept#

Write out a JSON integer value with optional node metadata.

Parameters:

  • node – [in] The JsonNode describing this property (may be nullptr).

  • value – [in] The integer value.

Returns:

whether or not validation succeeded.

inline bool writeValue(uint32_t value) noexcept#

Write out a JSON integer value.

Parameters:

value – [in] The integer value.

Returns:

whether or not validation succeeded.

inline bool writeValueJson(
const JsonNode *node,
int64_t value,
) noexcept#

Write out a JSON integer value with optional node metadata.

Note

64 bit integers are stored as double precision floats in JavaScript’s JSON library, so a JSON library with BigInt support should be used instead when reading 64 bit numbers.

Parameters:

  • node – [in] The JsonNode describing this property (may be nullptr).

  • value – [in] The integer value.

Returns:

whether or not validation succeeded.

inline bool writeValue(int64_t value) noexcept#

Write out a JSON integer value.

Note

64 bit integers are stored as double precision floats in JavaScript’s JSON library, so a JSON library with BigInt support should be used instead when reading 64 bit numbers.

Parameters:

value – [in] The integer value.

Returns:

whether or not validation succeeded.

inline bool writeValueJson(
const JsonNode *node,
uint64_t value,
) noexcept#

Write out a JSON integer value with optional node metadata.

Note

64 bit integers are stored as double precision floats in JavaScript’s JSON library, so a JSON library with BigInt support should be used instead when reading 64 bit numbers.

Parameters:

  • node – [in] The JsonNode describing this property (may be nullptr).

  • value – [in] The integer value.

Returns:

whether or not validation succeeded.

inline bool writeValue(uint64_t value) noexcept#

Write out a JSON integer value.

Note

64 bit integers are stored as double precision floats in JavaScript’s JSON library, so a JSON library with BigInt support should be used instead when reading 64 bit numbers.

Parameters:

value – [in] The integer value.

Returns:

whether or not validation succeeded.

inline bool writeValueJson(
const JsonNode *node,
double value,
) noexcept#

Write out a JSON double (aka number) value with optional node metadata.

Parameters:

  • node – [in] The JsonNode describing this property (may be nullptr).

  • value – [in] The double value.

Returns:

whether or not validation succeeded.

inline bool writeValue(double value) noexcept#

Write out a JSON double (aka number) value.

Parameters:

value – [in] The double value.

Returns:

whether or not validation succeeded.

inline bool writeValueJson(
const JsonNode *node,
float value,
) noexcept#

Write out a JSON float (aka number) value with optional node metadata.

Parameters:

  • node – [in] The JsonNode describing this property (may be nullptr).

  • value – [in] The float value.

Returns:

whether or not validation succeeded.

inline bool writeValue(float value) noexcept#

Write out a JSON float (aka number) value.

Parameters:

value – [in] The float value.

Returns:

whether or not validation succeeded.

inline bool writeValueJson(
const JsonNode *node,
const char *value,
size_t len,
) noexcept#

Write out a JSON string value, with optional pseudonymization based on node flags.

Parameters:

  • node – [in] The JsonNode describing this property (may be nullptr). If non-null and has fFlagPseudonymize set, the string will be hashed when hashPseudonymized template parameter is true.

  • value – [in] The string value. This can be nullptr if len is 0.

  • len – [in] The length of value, excluding the null terminator.

Returns:

whether or not validation succeeded.

inline bool writeValue(const char *value, size_t len) noexcept#

Write out a JSON string value.

Parameters:

  • value – [in] The string value. This can be nullptr if len is 0.

  • len – [in] The length of value, excluding the null terminator.

Returns:

whether or not validation succeeded.

inline bool writeValueJson(
const JsonNode *node,
const char *value,
) noexcept#

Write out a JSON string value, with optional pseudonymization based on node flags.

Parameters:

  • node – [in] The JsonNode describing this property (may be nullptr). If non-null and has fFlagPseudonymize set, the string will be hashed when hashPseudonymized template parameter is true.

  • value – [in] The string value. This can be nullptr.

Returns:

whether or not validation succeeded.

inline bool writeValue(const char *value) noexcept#

Write out a JSON string value.

Parameters:

value – [in] The string value. This can be nullptr.

Returns:

whether or not validation succeeded.

inline bool writeValueWithBase64EncodingJson(
const JsonNode *node,
const void *value_,
size_t size,
)#

Write a binary blob into the output JSON as a base64 encoded string.

Remark

This will take the input string and encode it in base64, then store that as base64 data in a string.

Parameters:

  • node – [in] The JsonNode describing this property (may be nullptr).

  • value_ – [in] The binary blob to write in.

  • size – [in] The number of bytes of data in value_.

Returns:

whether or not validation succeeded.

inline bool writeValueWithBase64Encoding(
const void *value_,
size_t size,
)#

Write a binary blob into the output JSON as a base64 encoded string.

Remark

This will take the input string and encode it in base64, then store that as base64 data in a string.

Parameters:

  • value_ – [in] The binary blob to write in.

  • size – [in] The number of bytes of data in value_.

Returns:

whether or not validation succeeded.

inline bool openArray() noexcept#

Begin a JSON array.

Returns:

whether or not validation succeeded.

Returns:

false if a memory allocation failed.

inline bool closeArray() noexcept#

Finish writing a JSON array.

Returns:

whether or not validation succeeded.

inline bool openObject() noexcept#

Begin a JSON object.

Returns:

whether or not validation succeeded.

Returns:

false if a memory allocation failed.

inline bool closeObject() noexcept#

Finish writing a JSON object.

Returns:

whether or not validation succeeded.

inline bool finish() noexcept#

Finish writing your JSON.

Returns:

whether or not validation succeeded.

Public Members

OnValidationErrorFunc m_onValidationError = onValidationError#

The function that will be called when a validation error occurs.