Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: 8a18e62c96
Fetching contributors…

Cannot retrieve contributors at this time

209 lines (199 sloc) 5.932 kb
<html>
<head>
<title>WJElement Documentation: wjreader</title>
</head>
<body>
<a href="index.html">Index</a>
<h1>WJReader Synopsis</h1>
<p>
The WARP JSON Reader provides the ability to parse a JSON document as a
stream. All parsing is done with a portion of the document loaded into a
buffer, and the buffer is reloaded as needed.
</p>
<p>
This allows the parser to be very fast, but does require that data in the
document is accessed in the order of the document.
</p>
<h1>WJReader Data Types</h1>
<p>
<strong>WJReader</strong>
is The WJReader document, the library's primary structure
</p>
<p>
From wjreader.h:
<blockquote><pre>
typedef struct {
uint32 depth;
uint32 maxdepth;
void *userdata;
} WJReaderPublic;
typedef WJReaderPublic * WJReader;
</pre></blockquote>
</p>
<p>
<strong>WJRType</strong>
specifies the type of a value being read.
</p>
<p>
From wjreader.h:
<blockquote><pre>
typedef enum {
WJR_TYPE_OBJECT = 'O',
WJR_TYPE_ARRAY = 'A',
WJR_TYPE_STRING = 'S',
WJR_TYPE_NUMBER = 'N',
WJR_TYPE_BOOL = 'B',
WJR_TYPE_TRUE = 'T',
WJR_TYPE_FALSE = 'F',
WJR_TYPE_NULL = '0',
WJR_TYPE_UNKNOWN = '?'
} WJRType;
</pre></blockquote>
</p>
<p>
<strong>WJReadCallback</strong>
- Generic data reader (from file, socket, decoder, etc.)
</p>
<p>
<blockquote><pre>
typedef size_t (* WJReadCallback)(char *data, size_t length, size_t seen, void *userdata);
</pre></blockquote>
</p>
<h1>WJReader Interfaces</h1>
<h2>Document/Reader Management</h2>
<p>
<strong>WJROpenDocument</strong>
- Open a JSON document and prepare to parse.
</p>
<p>
<blockquote><pre>
WJReader WJROpenDocument(WJReadCallback callback, void *userdata, char *buffer,
size_t buffersize);
WJReader _WJROpenDocument(WJReadCallback callback, void *userdata, char *buffer,
size_t buffersize, uint32 maxdepth);
</pre></blockquote>
</p>
<p>
A callback function must be
provided which will be used to read data as it is needed. The callback is
expected to load data into the provided buffer and return the number of
bytes that where loaded. If the number of bytes loaded is less than the
requested length then it is assumed that the end of the document has been
reached.
</p>
<p>
If a buffer is provided to WJROpenDocument() then that buffer will be used,
rather than allocating a new buffer. The size of the buffer must be
provided as buffersize. If a buffer is not provided then one will be
allocated of size buffersize.
</p>
<p>
If a buffersize of 0 is passed to WJROpenDocument then the default size will
be used (4KB). Some data is kept in the buffer while parsing, such as
element names and values. If the buffer is not large enough for these then
the document will fail to be parsed and will be aborted.
</p>
<p>
<strong>WJROpenFILEDocument</strong>
- helper to read from an open FILE *.
</p>
<p>
<blockquote><pre>
WJReader WJROpenFILEDocument(FILE *jsonfile, char *buffer, size_t buffersize);
</pre></blockquote>
</p>
<p>
An alternative method of opening a JSON document, which will provide a
proper callback for reading the data from an open FILE *.
</p>
<p>
As with the standard WJROpenDocument() a buffersize of 0 will use the
default buffer size.
</p>
<p>
<strong>WJROpenMemDocument</strong>
- helper to read from memory.
</p>
<p>
<blockquote><pre>
WJReader WJROpenMemDocument(char *json, char *buffer, size_t buffersize);
</pre></blockquote>
</p>
<p>
An alternative method of opening a JSON document, which will provide a
proper callback for reading from a pre-allocated buffer in memory.
</p>
<p>
As with the standard WJROpenDocument() a buffersize of 0 will use the
default buffer size.
</p>
<p>
<strong>WJRCloseDocument</strong>
- Close a WJReader document.
</p>
<p>
<blockquote><pre>
XplBool WJRCloseDocument(WJReader doc);
</pre></blockquote>
</p>
<h2>JSON Values</h2>
<p>
<strong>WJRNext</strong>
- Get the type and name of the next element in 'doc'.
</p>
<p>
<blockquote><pre>
char * WJRNext(char *parent, size_t maxnamelen, WJReader doc);
</pre></blockquote>
</p>
<p>
Returns a string, which contains the name of the next element of the
specified parent, prefixed by a single character that represents the type.
The pointer returned may be used as the parent argument in future calls to
WJRNext() in order to return the children of the current object.
</p>
<p>
If the object's name is larger than the maxnamelen argument then it will be
truncated.
</p>
<p>
These WJReader functions
Return the value of the last object returned by WJRNext(). The calling
application is expected to know the type of the value, and call the
appropriate function. When possible the value will be converted if it does
not match the requested type.
</p>
<p>
If the buffer is not large enough to contain the entire value then the
WJRString() function may return a partial value. It may be called multiple
times until a NULL is returned to ensure that the entire value has been
read.
</p>
<p>
<blockquote><pre>
char * WJRString(XplBool *complete, WJReader doc);
char * WJRStringEx(XplBool *complete, size_t *length, WJReader doc);
XplBool WJRBoolean(WJReader doc);
int32 WJRInt32(WJReader doc);
uint32 WJRUInt32(WJReader doc);
int64 WJRInt64(WJReader doc);
uint64 WJRUInt64(WJReader doc);
double WJRDouble(WJReader doc);
</pre></blockquote>
</p>
<p>
<strong>WJRNegative</strong>
- Check whether the current WJR_TYPE_NUMBER value is negative
</p>
<p>
<blockquote><pre>
XplBool WJRNegative(WJReader doc);
</pre></blockquote>
</p>
<p>
If the current element is a WJR_TYPE_NUMBER then this function can be used
to determine if the value is negative or positive. If negative then TRUE
will be returned.
</p>
</body>
</html>
Jump to Line
Something went wrong with that request. Please try again.