NAME
CanonicalJson —
An extension of JSON that produces the
Matrix spec's canonical JSON.
SYNOPSIS
#include
<CanonicalJson.h>
int
CanonicalJsonEncode(HashMap
*, FILE *);
char *
CanonicalJsonEncodeToString(HashMap
*);
DESCRIPTION
CanonicalJson is an extension of
Json(3) that is specifically designed to produce the Matrix
specification's "canonical" JSON.
Canonical JSON is defined as JSON that:
- Does not have any unecessary whitespace.
- Has all object keys lexicographically sorted.
- Does not contain any floating point numerical values.
The regular JSON encoder has no such rules, because normally they are not needed. However, Canonical JSON is needed to consistently sign JSON objects.
CanonicalJsonEncode()
encodes a JSON object following the rules of Canonical Json. See the
documentation for
JsonEncode(),
documented in Json(3) for more details on how JSON encoding operates. This
function exists as an alternative to JsonEncode(),
but should not be preferred to it in most circumstances. It is a lot more
costly, as it must lexicographically sort all keys and strip out float
values. If at all possible, use JsonEncode() because
it is much cheaper both in terms of memory and CPU time.
CanonicalJsonEncodeToString()
encodes a JSON object to a string.
Json(3) doesn't have any way to send JSON to a string, because
there's absolutely no reason to handle JSON strings in most cases. However,
the sole reason Canonical JSON exists is so that JSON objects can be signed
in a consistent way. Thus, you need a string to pass to the signing
function.
RETURN VALUES
CanonicalJsonEncode() returns whether or
not the JSON encoding operation was sucessful. This function will fail only
if NULL was given for any parameter. Otherwise, if an invalid pointer is
given, undefined behavior results.
CanonicalJsonEncodeToString() returns a C
string containing the canonical JSON representation of the given object, or
NULL if the encoding failed.