| JSON |
| ==== |
| |
| JSON is a data interchange format. The description of this format can be |
| found from IETF RFC 4627. |
| |
| .. contents:: |
| :local: |
| :depth: 2 |
| |
| Description |
| ----------- |
| |
| This package helps in converting between C data types and JSON data |
| objects. It supports both encoding and decoding. |
| |
| Data structures |
| --------------- |
| |
| Encoding |
| ~~~~~~~~ |
| |
| .. code:: c |
| |
| /* Encoding functions */ |
| typedef int (*json_write_func_t)(void *buf, char *data, |
| int len); |
| |
| struct json_encoder { |
| json_write_func_t je_write; |
| void *je_arg; |
| int je_wr_commas:1; |
| char je_encode_buf[64]; |
| }; |
| |
| Here's the data structure encoder funtions use, and it must be |
| initialized by the caller. The key element is *je\_write*, which is a |
| function pointer which gets called whenever encoding routine is ready |
| with encoded data. The element *je\_arg* is passed to *je\_write* as the |
| first argument. The rest of the structure contents are for internal |
| state management. This function should collect all the data encoder |
| function generates. It can collect this data to a flat buffer, chain of |
| mbufs or even stream through. |
| |
| .. code:: c |
| |
| /** |
| * For encode. The contents of a JSON value to encode. |
| */ |
| struct json_value { |
| uint8_t jv_pad1; |
| uint8_t jv_type; |
| uint16_t jv_len; |
| |
| union { |
| uint64_t u; |
| float fl; |
| char *str; |
| struct { |
| char **keys; |
| struct json_value **values; |
| } composite; |
| } jv_val; |
| }; |
| |
| This data structure is filled with data to be encoded. It is best to |
| fill this using the macros *JSON\_VALUE\_STRING()* or |
| *JSON\_VALUE\_STRINGN()* when value is string, *JSON\_VALUE\_INT()* when |
| value is an integer, and so forth. |
| |
| Decoding |
| ~~~~~~~~ |
| |
| .. code:: c |
| |
| /* when you implement a json buffer, you must implement these functions */ |
| |
| /* returns the next character in the buffer or '\0'*/ |
| typedef char (*json_buffer_read_next_byte_t)(struct json_buffer *); |
| /* returns the previous character in the buffer or '\0' */ |
| typedef char (*json_buffer_read_prev_byte_t)(struct json_buffer *); |
| /* returns the number of characters read or zero */ |
| typedef int (*json_buffer_readn_t)(struct json_buffer *, char *buf, int n); |
| |
| struct json_buffer { |
| json_buffer_readn_t jb_readn; |
| json_buffer_read_next_byte_t jb_read_next; |
| json_buffer_read_prev_byte_t jb_read_prev; |
| }; |
| |
| Function pointers within this structure are used by decoder when it is |
| reading in more data to decode. |
| |
| .. code:: c |
| |
| struct json_attr_t { |
| char *attribute; |
| json_type type; |
| union { |
| int *integer; |
| unsigned int *uinteger; |
| double *real; |
| char *string; |
| bool *boolean; |
| char *character; |
| struct json_array_t array; |
| size_t offset; |
| } addr; |
| union { |
| int integer; |
| unsigned int uinteger; |
| double real; |
| bool boolean; |
| char character; |
| char *check; |
| } dflt; |
| size_t len; |
| const struct json_enum_t *map; |
| bool nodefault; |
| }; |
| |
| This structure tells the decoder about a particular name/value pair. |
| Structure must be filled in before calling the decoder routine |
| *json\_read\_object()*. |
| |
| +-------------+-------------------------------------------------------+ |
| | Element | Description | |
| +=============+=======================================================+ |
| | attribute | Name of the value | |
| +-------------+-------------------------------------------------------+ |
| | type | The type of the variable; see enum json\_type | |
| +-------------+-------------------------------------------------------+ |
| | addr | Contains the address where value should be stored | |
| +-------------+-------------------------------------------------------+ |
| | dflt | Default value to fill in, if this name is not found | |
| +-------------+-------------------------------------------------------+ |
| | len | Max number of bytes to read in for value | |
| +-------------+-------------------------------------------------------+ |
| | nodefault | If set, default value is not copied name | |
| +-------------+-------------------------------------------------------+ |
| |
| API |
| --- |
| |
| .. doxygenfile:: json/include/json/json.h |