WJWriter API

================= WJWriter Synopsis

The WARP JSON Writer provides the ability to easily write a JSON document to a stream. All data formatting is done automatically.

WJWriter Data Types

WJWriter is The WJWriter document, the library's primary structure

From wjwriter.h:

    typedef struct {
        XplBool                pretty;

        /*
            Base may be set to 8, 10 (default), or 16.  Using a base other than 10
            will result in a non standard JSON document which may not be read
            properly by all parsers.
        */
        int                    base;

        struct {
            void               *data;
            WJWriteCallback    cb;
        } write;

        struct {
            void               *data;
            void               (* freecb)(void *data);
        } user;
    } WJWriterPublic;
    typedef WJWriterPublic*    WJWriter;

WJWriteCallback - Generic data writer (to file, socket, encoder, etc.)

typedef size_t (* WJWriteCallback)(char *data, size_t size, void *writedata);

WJWriter Interfaces

Document/Writer Management

WJWOpenDocument - Open a stream that is ready to accept a JSON document.

WJWriter WJWOpenDocument(XplBool pretty, WJWriteCallback callback,
                         void *writeData);
WJWriter _WJWOpenDocument(XplBool pretty, WJWriteCallback callback,
                          void *writedata, size_t buffersize);

A callback function must be provided which will be used to write data as it is ready.

A buffersize of 0 will disable write buffering entirely. The write buffer used will be at least the size requested, but may be larger.

WJWOpenFILEDocument - helper to write to an open FILE *.

WJWriter WJWOpenFILEDocument(XplBool pretty, FILE *file);

An alternative method of opening a JSON document for writing, which will provide a proper callback for writing the data to an open FILE *.

WJWCloseDocument - Close a WJWriter document

XplBool WJWCloseDocument(WJWriter doc);

JSON Structures

WJWOpenArray - Open an array.

XplBool WJWOpenArray(char *name, WJWriter doc);

All objects that are direct children of the array MUST NOT be named. A value of NULL should be passed as name for any such values.

When all values of the array have been written it can be closed with WJWCloseArray().

WJWCloseArray - Close an array.

XplBool WJWCloseArray(WJWriter doc);

WJWOpenObject - Open an object.

XplBool WJWOpenObject(char *name, WJWriter doc);

Open an object. All objects that are direct children of the object MUST be named. A value of NULL should NOT be passed as name for any such values.

When all values of the object have been written it can be closed with WJWCloseObject().

WJWCloseObject - Close an object.

XplBool WJWCloseObject(WJWriter doc);

JSON Values

These WJWriter functions write a value to the document. If any values are written that are a direct child of an object then a non-NULL name MUST be provided. If any values are written that are a direct child of an array then a non-NULL name MUST NOT be provided.

A string value may be written in multiple pieces. A JSON string will be started with the first call to WJWString, or WJWStringN and the string will not be completed until the "done" argument is set to TRUE or there is a call to write a non-string type value.

XplBool WJWStringN(char *name, char *value, size_t length, XplBool done, WJWriter doc);
XplBool WJWString(char *name, char *value, XplBool done, WJWriter doc);
XplBool WJWBoolean(char *name, XplBool value, WJWriter doc);
XplBool WJWNull(char *name, WJWriter doc);

XplBool WJWInt32(char *name, int32 value, WJWriter doc);
XplBool WJWUInt32(char *name, uint32 value, WJWriter doc);
XplBool WJWInt64(char *name, int64 value, WJWriter doc);
XplBool WJWUInt64(char *name, uint64 value, WJWriter doc);
XplBool WJWDouble(char *name, double value, WJWriter doc);

WJWRawValue - Write a raw, pre-formatted value to the document.

XplBool WJWRawValue(char *name, char *value, XplBool done, WJWriter doc);

It is up to the caller to ensure that the data is properly formatted and complete.