KCGIJSON(3)

NAME
kcgijson, kjson_open, kjson_close, kjson_putbool, kjson_putboolp, kjson_putint, kjson_putintp, kjson_putdouble, kjson_putdoublep, kjson_putnull, kjson_putnullp, kjson_putstring, kjson_putstringp, kjson_obj_open, kjson_objp_open, kjson_obj_close, kjson_array_open, kjson_arrayp_open, kjson_array_close, kjson_string_open, kjson_stringp_open, kjson_string_close, kjson_string_putdouble, kjson_string_putint, kjson_string_puts, kjson_string_write - JSON handling functions for kcgi

LIBRARY
libkcgijson

SYNOPSIS
#include <sys/types.h>
#include <stdarg.h>
#include <stddef.h>
#include <stdint.h>
#include <kcgi.h>
#include <kcgijson.h>
void
kjson_open(struct kjsonreq *r, struct kreq *req);
int
kjson_close(struct kjsonreq *r);
int
kjson_putbool(struct kjsonreq *r, int val);
int
kjson_putboolp(struct kjsonreq *r, const char *key, int val);
int
kjson_putdouble(struct kjsonreq *r, double val);
int
kjson_putdoublep(struct kjsonreq *r, const char *key, double val);
int
kjson_putint(struct kjsonreq *r, int64_t val);
int
kjson_putintp(struct kjsonreq *r, const char *key, int64_t val);
int
kjson_putnull(struct kjsonreq *r);
int
kjson_putnullp(struct kjsonreq *r, const char *key);
int
kjson_putstring(struct kjsonreq *r, const char *val);
int
kjson_putstringp(struct kjsonreq *r, const char *key, const char *val);
int
kjson_obj_open(struct kjsonreq *r);
int
kjson_objp_open(struct kjsonreq *r, const char *key);
int
kjson_obj_close(struct kjsonreq *r);
int
kjson_array_open(struct kjsonreq *r);
int
kjson_arrayp_open(struct kjsonreq *r, const char *key);
int
kjson_array_close(struct kjsonreq *r);
int
kjson_string_open(struct kjsonreq *r);
int
kjson_stringp_open(struct kjsonreq *r, const char *key);
int
kjson_string_close(struct kjsonreq *r);
int
kjson_string_putint(struct kjsonreq *r, int64_t val);
int
kjson_string_puts(struct kjsonreq *r, const char *cp);
int
kjson_string_write(const char *cp, size_t sz, void *arg);

DESCRIPTION
The kcgijson functions extend kcgi(3) output with JSON objects and arrays for contexts allocated with khttp_parse(3). None of these functions may be called before khttp_body(3).

All kcgijson sequences begin and end with kjson_open and kjson_close, respectively. These enclose a standalone-type array or object context, kjson_array_open or kjson_obj_open, respectively, each with its own pair-type or standalone-type children.

In general, kcgijson functions follow the convention of writing either pair-type (ending in "p") or standalone-type data. Standalone values are used in arrays; key-value pairs are used in objects. Passing a NULL value as the key for any key-value pair function is the same as calling the standalone version.

To use these functions, you must include the <kcgijson.h> header and compile with kcgijson, for example,

    % cc -I/usr/local/include -c -o sample.o sample.c
    % cc -L/usr/local/lib -o sample -lkcgijson -lkcgi -lz

kjson_open()
    Initialise a JSON context.

kjson_close()
    Close a JSON context as opened with kjson_open(). This will also close any open arrays, strings, or objects. You should not use the object after invoking this function.

kjson_arrayp_open()
    This and kjson_array_open() start an array context with or without a name.

kjson_array_close()
    Close an array context with or without a name.

kjson_string_open()
    This and kjson_stringp_open() start a string context with or without a name. This is usually used for complex values, or those create dynamically with khttp_template(3). The kjson_string_putdouble(), kjson_string_putint(), kjson_string_puts(), and kjson_string_write() functions may be used for serialising value data.

kjson_string_close()
    Close a string context with or without a name.

kjson_obj_open()
    This and kjson_objp_open() start an object context with or without a name.

kjson_obj_close()
    Close an object context with or without a name.

kjson_putstringp()
    This and kjson_putstring() emit a string value with or without a name. Note that it is not checked for character encoding, only character legality.

kjson_putboolp()
    This and kjson_putbool() emit a Boolean value with or without a name. In the usual way, 0 evalutes to FALSE, non-zero to TRUE.

kjson_putnullp()
    This and kjson_putnull() emit a null value with or without a name.

kjson_putintp()
    This and kjson_putint() emit a 64-bit signed integer value with or without a name.

kjson_putdoublep()
    This and kjson_putdouble() emit a double-precision floating point value with or without a name. This is formatted as with the %g argument to printf(3).

RETURN VALUES
Functions returning an int indicate zero on failure and non-zero on success.

Failure for “open”, “write” and “put” functions occurs if the request occurs out of context, for example, emitting a key-value pair in an array context (or the root context), or emitting a standalone value in an object.

For “close” functions, failure occurs when trying to close a different type, for example, closing an array when an object is open. Failure also occurs if there is nothing open to close. For either of these, failure means that the requested operation was ignored.

For kcgijson_close(), failure only means that there are open scopes when the function was invoked: all scopes are still closed.

STANDARDS
The kcgijson functions conform to the ECMA-404 The JSON Data Interchange Standard.

AUTHORS
The kcgijson library was written by Kristaps Dzonsons <kristaps@bsd.lv>.

CAVEATS
The current hard-coded limit of nested objects is 128 levels. When this is reached, the system will assert(3).