dlite-json#

Provides built-in support for JSON in dlite.

A set of utility function for serialising and deserialising dlite instances to/from JSON.

Iterator

typedef struct _DLiteJsonIter DLiteJsonIter#: Opaque iterator struct

DLiteJsonIter *dlite_json_iter_create(const char *src, int length, const char *metaid)#

Creates and returns a new iterator used by dlite_json_next().

Arguments

src: input JSON string to search.
length: length of src. If zero or negative, all of src will be used.
metaid: limit the search to instances of metadata with this id.

The source should be a JSON object with keys being instance UUIDs and values being the JSON representation of the individual instances.

Returns a new iterator or NULL on error.

void dlite_json_iter_free(DLiteJsonIter *iter)#: Free’s iterator created with dlite_json_iter_create().

const char *dlite_json_next(DLiteJsonIter *iter, int *length)#

Search for instances in the JSON document provided to dlite_json_iter_create() and returns a pointer to instance UUIDs.

iter should be an iterator created with dlite_json_iter_create().

If length is given, it is set to the length of the returned identifier.

Returns a pointer to the next matching UUID or NULL if there are no more matches left.

JSON store

typedef struct _DLiteJStoreIter DLiteJStoreIter#: Opaque iterator struct

DLiteJsonFormat dlite_jstore_loads(JStore *js, const char *src, int len)#

Load content of json string src to json store js. len is the length of src.

Returns json format or -1 on error.

DLiteJsonFormat dlite_jstore_loadf(JStore *js, const char *filename)#

Read content of filename to json store js.

Returns json format or -1 on error.

int dlite_jstore_add(JStore *js, const DLiteInstance *inst, DLiteJsonFlag flags)#

Add json representation of inst to json store js.

Returns non-zero on error.

int dlite_jstore_remove(JStore *js, const char *id)#

Removes instance with given id from json store js.

Returns non-zero on error.

DLiteJStoreIter *dlite_jstore_iter_create(JStore *js, const char *metaid)#

Initiate iterator init from json store js. If metaid is provided, the iterator will only iterate over instances of this metadata.

Returns a new iterator or NULL on error.

int dlite_jstore_iter_free(DLiteJStoreIter *iter)#

Deinitialises iterater.

Return non-zero on error.

const char *dlite_jstore_iter_next(DLiteJStoreIter *iter)#: Return the id of the next instance in the json store or NULL if the iterator is exausted.

Serilisation

int dlite_json_sprint(char *dest, size_t size, const DLiteInstance *inst, int indent, DLiteJsonFlag flags)#

Serialise instance inst to dest, formatted as JSON.

No more than size bytes are written to dest (incl. the terminating NUL).

Returns number of bytes written to dest. If the output is truncated because it exceeds size, the number of bytes that would have been written if size was large enough is returned. On error, a negative value is returned.

int dlite_json_asprint(char **dest, size_t *size, size_t pos, const DLiteInstance *inst, int indent, DLiteJsonFlag flags)#

Like dlite_json_sprint(), but prints to allocated buffer.

Prints to position pos in *dest, which should point to a buffer of size *size. Bytes at position less than pos are not changed.

If *dest is NULL or *size is less than needed, *dest is reallocated and *size updated to the new buffer size.

If pos is larger than *size the bytes at index i are initialized to space (’ ‘), where *size <= i < pos.

Returns number or bytes written (not including terminating NUL) or a negative number on error.

char *dlite_json_aprint(const DLiteInstance *inst, int indent, DLiteJsonFlag flags)#: Like dlite_sprint(), but returns allocated buffer with serialised instance.

int dlite_json_fprint(FILE *fp, const DLiteInstance *inst, int indent, DLiteJsonFlag flags)#

Like dlite_sprint(), but prints to stream fp.

Returns number or bytes printed or a negative number on error.

int dlite_json_print(const DLiteInstance *inst)#

Prints json representation of inst to standard output.

Returns number or bytes printed or a negative number on error.

int dlite_json_printfile(const char *filename, const DLiteInstance *inst, DLiteJsonFlag flags)#

Like dlite_json_sprint(), but prints the output to file filename.

Returns number or bytes printed or a negative number on error.

int dlite_json_append(char **s, size_t *size, const DLiteInstance *inst, DLiteJsonFlag flags)#

Appends json representation of inst to json string pointed to by *s.

On input, *s should be a malloc’ed string representation of a json object. It will be reallocated as needed.

*size if the allocated size of *s. It will be updated when *s is realocated.

Returns number or bytes inserted or a negative number on error.

Deserialisation

DLiteInstance *dlite_json_sscan(const char *src, const char *id, const char *metaid)#

Returns a new instance scanned from src.

id is the uri or uuid of the instance to load. If src only contain one instance (of the required metadata), id may be NULL.

If metaid is not NULL, it should be the URI or UUID of the metadata of the returned instance. It is an error if no such instance exists in the source.

Returns the instance or NULL on error.

DLiteInstance *dlite_json_fscan(FILE *fp, const char *id, const char *metaid)#

Like dlite_sscan(), but scans instance id from stream fp instead of a string.

Returns the instance or NULL on error.

DLiteInstance *dlite_json_scanfile(const char *filename, const char *id, const char *metaid)#

Like dlite_json_sscan(), but scans instance id from file filename instead of a string.

Returns the instance or NULL on error.

Checking

DLiteJsonFormat dlite_json_check(const char *src, const jsmntok_t *tokens, const char *id, DLiteJsonFlag *flags)#

Check format of a parsed JSON string.

src is the JSON string to check.

tokens should be a parsed set of JSMN tokens corresponding to src.

If id is not NULL, it is used to select what instance in a multi-entity formatted JSON string that will be used to assign flags. If NULL, the first instance will be used.

If flags is not NULL, the formatting (of the first entry in case of multi-entity format) will be investigated and flags set accordingly.

Return the format of src or -1 on error.

DLiteJsonFormat dlite_json_scheck(const char *src, size_t len, const char *id, DLiteJsonFlag *flags)#

Like dlite_json_check(), but checks string src with length len.

Return the json format or -1 on error.

DLiteJsonFormat dlite_json_fcheck(FILE *fp, const char *id, DLiteJsonFlag *flags)#

Like dlite_json_scheck(), but checks the content of stream fp instead.

Return the json format or -1 on error.

DLiteJsonFormat dlite_json_checkfile(const char *filename, const char *id, DLiteJsonFlag *flags)#

Like dlite_json_scheck(), but checks the file filename instead.

Return the json format or -1 on error.

Enums

enum DLiteJsonFlag#

Flags for controlling serialisation

Values:

enumerator dliteJsonSingle#: Single-entity format

enumerator dliteJsonUriKey#: Use uri (if it exists) as json key in multi- entity format.

enumerator dliteJsonWithUuid#: Include uuid in output

enumerator dliteJsonWithMeta#: Always include “meta” (even for metadata)

enumerator dliteJsonArrays#: Write metadata dimension and properties as json arrays (old format)

enumerator dliteJsonNoParent#: Do not write transaction parent info

enumerator dliteJsonCompactRel#: Write relations with no newlines

enum DLiteJsonFormat#

Enum indicating whether a JSON string is formatted as data and metadata.

Values:

enumerator dliteJsonUnknownFormat#: Unknown format

enumerator dliteJsonDataFormat#: Data format

enumerator dliteJsonMetaFormat#: Metadata format