forked from Telodendria/Telodendria
70 lines
2.1 KiB
Groff
70 lines
2.1 KiB
Groff
.Dd $Mdocdate: November 30 2022 $
|
|
.Dt CANONICALJSON 3
|
|
.Os Telodendria Project
|
|
.Sh NAME
|
|
.Nm CanonicalJson
|
|
.Nd An extension of JSON that produces the Matrix spec's "canonical" JSON.
|
|
.Sh SYNOPSIS
|
|
.In CanonicalJson.h
|
|
.Ft int
|
|
.Fn CanonicalJsonEncode "HashMap *" "FILE *"
|
|
.Ft char *
|
|
.Fn CanonicalJsonEncodeToString "HashMap *"
|
|
.Sh DESCRIPTION
|
|
.Pp
|
|
.Nm
|
|
is an extension of
|
|
.Xr Json 3
|
|
that is specifically designed to produce the Matrix specification's
|
|
"canonical" JSON.
|
|
.Pp
|
|
Canonical JSON is defined as JSON that:
|
|
.Bl -bullet -offset indent
|
|
.It
|
|
Does not have any unecessary whitespace.
|
|
.It
|
|
Has all object keys lexicographically sorted.
|
|
.It
|
|
Does not contain any floating point numerical values.
|
|
.El
|
|
.Pp
|
|
The regular JSON encoder has no such rules, because normally they are
|
|
not needed. However, Canonical JSON is needed to consistently sign JSON
|
|
objects.
|
|
.Pp
|
|
.Fn CanonicalJsonEncode
|
|
encodes a JSON object following the rules of Canonical Json. See the
|
|
documentation for
|
|
.Fn JsonEncode ,
|
|
documented in
|
|
.Xr Json 3
|
|
for more details on how JSON encoding operates. This function exists
|
|
as an alternative to
|
|
.Fn 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
|
|
.Fn JsonEncode
|
|
because it is much cheaper both in terms of memory and CPU time.
|
|
.Pp
|
|
.Fn CanonicalJsonEncodeToString
|
|
encodes a JSON object to a string.
|
|
.Xr 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.
|
|
.Sh RETURN VALUES
|
|
.Pp
|
|
.Fn 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.
|
|
.Pp
|
|
.Fn CanonicalJsonEncodeToString
|
|
returns a C string containing the canonical JSON representation of
|
|
the given object, or NULL if the encoding failed.
|
|
.Sh SEE ALSO
|
|
.Xr Json 3
|