API Reference ¶

These pages cover the core functions and types that make up the note-c API.

Dynamic Memory and Timing Hooks ¶

Functions¶

void NoteSetFn(mallocFn mallocHook, freeFn freeHook, delayMsFn delayMsHook, getMsFn getMsHook)¶

Set the platform-specific memory and timing hooks.

Parameters:

mallocHook – The platform-specific memory allocation function (i.e. malloc).
freeHook – The platform-specific memory free function (i.e. free).
delayMsHook – The platform-specific millisecond delay function.
getMsHook – The platform-specific millisecond counter function.

Types¶

typedef void *(*mallocFn)(size_t size)¶

The type for the memory allocation hook.

Param size:: The number of bytes to allocate.
Return:: A pointer to the newly allocated memory or NULL on failure.

typedef void (*freeFn)(void *mem)¶

The type for the memory freeing hook.

Param mem:: Pointer to the memory to free.

typedef void (*delayMsFn)(uint32_t ms)¶

The type for the millisecond delay hook.

Param ms:: The number of milliseconds to delay for.

typedef uint32_t (*getMsFn)(void)¶

The type for the millisecond counter hook.

Return:: The value of the millisecond counter.

I/O Hooks ¶

Serial Hooks¶

Functions¶

void NoteSetFnSerial(serialResetFn resetFn, serialTransmitFn transmitFn, serialAvailableFn availFn, serialReceiveFn receiveFn)¶

Set the platform-specific hooks for communicating with the Notecard over serial.

Parameters:

resetFn – The platform-specific serial reset function.
transmitFn – The platform-specific serial transmit function.
availFn – The platform-specific serial available function.
receiveFn – The platform-specific serial receive function.

Types¶

typedef bool (*serialResetFn)(void)¶

The type for the serial reset hook.

This hook is used to reset the serial peripheral used to communicate with the Notecard.

Return:: true on success and false on failure.

typedef void (*serialTransmitFn)(uint8_t *txBuf, size_t txBufSize, bool flush)¶

The type for the serial transmit hook.

Param txBuf:: A buffer of bytes to transmit to the Notecard.
Param txBufSize:: The size, in bytes, of txBuf.
Param flush:: If true, flush the serial peripheral’s transmit buffer.

typedef bool (*serialAvailableFn)(void)¶

The type for the serial available hook.

Return:: true if there’s data to read and false otherwise.

typedef char (*serialReceiveFn)(void)¶

The type for the serial receive hook.

Return:: The received byte.

I2C¶

Functions¶

void NoteSetFnI2C(uint32_t notecardAddr, uint32_t maxTransmitSize, i2cResetFn resetFn, i2cTransmitFn transmitFn, i2cReceiveFn receiveFn)¶

Set the platform-specific hooks for communicating with the Notecard over I2C, as well as the I2C address of the Notecard and maximum transmission size.

Parameters:

notecardAddr – The I2C address of the Notecard. Pass 0 to use the default address.
maxTransmitSize – The max number of bytes to send to the Notecard in a single I2C segment. Pass 0 to use the default maximum transmission size.
resetFn – The platform-specific I2C reset function.
transmitFn – The platform-specific I2C transmit function.
receiveFn – The platform-specific I2C receive function.

Types¶

typedef bool (*i2cResetFn)(uint16_t address)¶

The type for the I2C reset hook.

This hook is used to reset the I2C peripheral used to communicate with the Notecard.

Param address:: The I2C address of the Notecard.

typedef const char *(*i2cTransmitFn)(uint16_t address, uint8_t *txBuf, uint16_t txBufSize)¶

The type for the I2C transmit hook.

This hook is used to send a buffer of bytes to the Notecard.

Param address:: The I2C address of the Notecard to transmit the data to.
Param txBuf:: A buffer of bytes to transmit to the Notecard.
Param txBufSize:: The size, in bytes, of txBuf.
Return:: NULL on success and an error string on failure.

typedef const char *(*i2cReceiveFn)(uint16_t address, uint8_t *rxBuf, uint16_t rxBufSize, uint32_t *available)¶

The type for the I2C receive hook.

This hook is used to receive a buffer of bytes from the Notecard.

Param address:: The I2C address of the Notecard sending the data to receive.
Param rxBuf:: A buffer to hold the data received from the Notecard.
Param rxBufSize:: The size, in bytes, of rxBuf.
Param available:: The number of bytes remaining to be received, if any.
Return:: NULL on success and an error string on failure.

Macros¶

NOTE_I2C_ADDR_DEFAULT¶: The default I2C address of the Notecard.

NOTE_I2C_MAX_DEFAULT¶: The maximum number of bytes to request from or transmit to the Notecard in a single chunk.

Mutex Hooks ¶

Notecard Mutex¶

Functions¶

void NoteSetFnNoteMutex(mutexFn lockFn, mutexFn unlockFn)¶

Set the platform-specific mutex functions for the Notecard.

Parameters:

lockFn – The platform-specific Notecard lock function.
unlockFn – The platform-specific Notecard unlock function.

Types¶

typedef void (*mutexFn)(void)¶: The type for the various mutex (i.e. lock/unlock) hooks.

I2C Mutex¶

Functions¶

void NoteSetFnI2CMutex(mutexFn lockI2Cfn, mutexFn unlockI2Cfn)¶

Set the platform-specific mutex functions for I2C.

Parameters:

lockI2Cfn – The platform-specific I2C lock function.
unlockI2Cfn – The platform-specific I2C unlock function.

Types¶

See mutexFn.

Notecard API Calls ¶

Functions¶

J *NoteNewRequest(const char *request)¶

Create a new JSON request.

Creates a dynamically allocated J object with one field "req" whose value is the passed in request string.

Parameters:

request – The name of the request, for example hub.set.

Returns:

A J object with the “req” field populated.

J *NoteRequestResponse(J *req)¶

Send a request to the Notecard and return the response.

The passed in request object is always freed, regardless of if the request was successful or not.

See also

NoteResponseError to check the response for errors.

Parameters:

req – Pointer to a J request object.

Returns:

A J object with the response or NULL if there was an error sending the request.

J *NoteRequestResponseWithRetry(J *req, uint32_t timeoutSeconds)¶

Send a request to the Notecard, retrying it until it succeeds or it times out, and return the response.

The passed in request object is always freed, regardless of if the request was successful or not.

See also

NoteResponseError to check the response for errors.

Parameters:

req – Pointer to a J request object.
timeoutSeconds – Time limit for retires, in seconds, if there is no response, or if the response contains an I/O error.

Returns:

A J object with the response or NULL if there was an error sending the request.

bool NoteRequest(J *req)¶

Send a request to the Notecard.

The passed in request object is always freed, regardless of if the request was successful or not. The response from the Notecard, if any, is freed and not returned to the caller.

See also

NoteRequestResponse if you need to work with the response.

Parameters:

req – Pointer to a J request object.

Returns:

true if successful and false if an error occurs (e.g. out of memory or the response from the Notecard has an “err” field). If req is a command rather than a request, a true return value indicates that the command was sent without error. However, since the Notecard sends no response to commands, it does not guarantee that the command was received and processed by the Notecard.

bool NoteRequestWithRetry(J *req, uint32_t timeoutSeconds)¶

Send a request to the Notecard, retrying it until it succeeds or it times out.

The passed in request object is always freed, regardless of if the request was successful or not. The response from the Notecard, if any, is freed and not returned to the caller.

See also

NoteRequestResponseWithRetry if you need to work with the response.

Parameters:

req – Pointer to a J request object.
timeoutSeconds – Time limit for retires, in seconds, if there is no response, or if the response contains an I/O error.

Returns:

true if successful and false if an error occurs (e.g. out of memory or the response from the Notecard has an “err” field).

NoteResponseError(rsp)¶

Check if the Notecard response contains an error.

Parameters:

rsp – The response to check.

Returns:

true if there’s an error and false if there’s not.

NoteDeleteResponse(rsp)¶

Free a response from the Notecard.

Parameters:

rsp – The response to free.

char *NoteRequestResponseJSON(const char *reqJSON)¶

Send a request to the Notecard and return the response.

Unlike NoteRequestResponse, this function expects the request to be a valid JSON C-string, rather than a J object. The string is expected to be newline-terminated, otherwise the call produces undefined behavior. The response is returned as a dynamically allocated JSON C-string. The response string is verbatim what was sent by the Notecard, which IS newline-terminated. The caller is responsible for freeing the response string. If the request was a command (i.e. it uses “cmd” instead of “req”), this function returns NULL, because the Notecard does not send a response to commands.

Note

When a “cmd” is sent, it is not possible to determine if an error occurred.

Parameters:

reqJSON – A valid newline-terminated JSON C-string containing the request.

Returns:

A newline-terminated JSON C-string with the response, or NULL if there was no response or if there was an error.

JSON Manipulation ¶

Functions¶

bool JAddBinaryToObject(J *json, const char *fieldName, const void *binaryData, uint32_t binaryDataLen)¶

Add binary data as a Base64-encoded string field to a JSON object.

Parameters:

json – The JSON object.
fieldName – The name to use for the field.
binaryData – A buffer of binary data to encode.
binaryDataLen – The length of the binary data in bytes.

Returns:

True if the string was successfully encoded and added to the object, otherwise false.

J *JAddBoolToObject(J *const object, const char *const name, const Jbool boolean)¶

Add a boolean field to a J object.

Parameters:

object – The object to add the field to.
name – The name of the field.
boolean – The value of the field.

Returns:

A pointer to the newly-added boolean field or NULL on error.

J *JAddNumberToObject(J *const object, const char *const name, const JNUMBER number)¶

Add a number field to a J object.

Parameters:

object – The object to add the field to.
name – The name of the field.
number – The value of the field.

Returns:

A pointer to the newly-added number field or NULL on error.

J *JAddStringToObject(J *const object, const char *const name, const char *const string)¶

Add a string field to a J object.

Parameters:

object – The object to add the field to.
name – The name of the field.
string – The value of the field.

Returns:

A pointer to the newly-added string field or NULL on error.

J *JAddObjectToObject(J *const object, const char *const name)¶

Add an object field to another J object.

Parameters:

object – The object to add the field to.
name – The name of the field.

Returns:

A pointer to the newly-added object field or NULL on error.

J *JAddArrayToObject(J *const object, const char *const name)¶

Add an array field to a J object.

Parameters:

object – The object to add the field to.
name – The name of the field.

Returns:

A pointer to the newly-added array field or NULL on error.

J *JCreateObject(void)¶

Create a new J object.

To free the object, use JDelete.

Returns:: A pointer to the newly-created object.

void JDelete(J *c)¶

Free a J object.

Parameters:

item – A pointer to the object.

void JFree(void *object)¶

Free a block of dynamically allocated memory.

This is simply a wrapper around the memory free function provided by the user via NoteSetFn.

Parameters:

p – A pointer to the block of memory to free.

J *JGetArray(J *json, const char *field)¶

Get the value of an array field from a JSON object.

Note

The returned JSON object is a pointer to the array contained in the parent JSON object. It is not a copy, so once the parent JSON object is freed, the pointer is no longer valid.

Parameters:

json – The JSON object.
field – The array field to query.

Returns:

A pointer to the array, which is itself a JSON object (J *), if the field exists and is an array, otherwise NULL.

bool JGetBinaryFromObject(J *json, const char *fieldName, uint8_t **retBinaryData, uint32_t *retBinaryDataLen)¶

Decode a Base64-encoded string field in a JSON object and return the decoded bytes.

Note

The returned binary buffer must be freed by the user with JFree when it is no longer needed.

Note

On error, the returned binary buffer and data length shall be set to NULL and zero (0), respectively.

Parameters:

json – The JSON object.
fieldName – The name of the field.
retBinaryData – A pointer to a pointer, used to hold the pointer to the decoded bytes.
retBinaryDataLen – A pointer to an unsigned integer, used to hold the length of the decoded bytes.

Returns:

True if the string was successfully decoded and returned, otherwise false.

bool JGetBool(J *json, const char *field)¶

Get the value of a boolean field from a JSON object.

See also

JGetInt

See also

JGetNumber

Parameters:

json – The JSON object.
field – The boolean field to query.

Returns:

The value of the boolean field if it exists and is a boolean, otherwise false.

JINTEGER JGetInt(J *json, const char *field)¶

Get the integer value of a number field from a JSON object.

See also

JGetBool

See also

JGetNumber

Note

The returned value is the integer representation of the number.

Parameters:

json – The JSON object.
field – The number field to query.

Returns:

The value of the number field if the field exists and is a number, otherwise 0.

JNUMBER JGetNumber(J *json, const char *field)¶

Get the floating point value of a number field from a JSON object.

See also

JGetInt

See also

JGetBool

Note

The returned value is the floating point representation of the number.

Parameters:

json – The JSON object.
field – The number field to query.

Returns:

The value of the number field if the field exists and is a number, otherwise 0.0.

J *JGetObject(J *json, const char *field)¶

Get the value of an object field from a JSON object.

Note

The returned JSON object is a pointer to the object contained in the parent JSON object. It is not a copy, so once the parent JSON object is freed, the pointer is no longer valid.

Parameters:

json – The JSON object.
field – The object field to query.

Returns:

A pointer to the object, which is itself a JSON object (J *), if the field exists and is an object, otherwise NULL.

char *JGetString(J *json, const char *field)¶

Get the value of a string field from a JSON object.

Note

The returned string is a pointer to the string contained in the JSON object. It is not a copy of the string, so once the JSON object is freed, the pointer is no longer valid.

Parameters:

json – The JSON object.
field – The string field to query.

Returns:

A pointer to the string if the field exists and is a string, otherwise the empty string (“”).

bool JIsPresent(J *json, const char *field)¶

Determine if a field is present in a JSON object.

Parameters:

json – The JSON object.
field – The field to find.

Returns:

True if the field is present, or false if the field is not present or the JSON object is NULL.

void *JMalloc(size_t size)¶

Dynamically allocate a block of memory of the given size.

This is simply a wrapper around the memory allocation function provided by the user via NoteSetFn.

Parameters:

size – The number of bytes to allocate.

Returns:

A pointer to the first byte of the allocated memory or NULL on error.

J *JParse(const char *value)¶

Parse the passed in C-string as JSON and return a J object representing it.

Parameters:

value – The JSON object as a C-string.

Returns:

A J object or NULL on error (e.g. the string was invalid JSON).

char *JPrintUnformatted(const J *item)¶

Get the unformatted string representation of a J object.

The string returned by this function is dynamically allocated and MUST be freed by the caller with JFree. Unformatted means that the minimum JSON string is produced, without any additional whitespace.

Parameters:

item – The JSON object to get the unformatted string representation of.

Returns:

The string or NULL on error.

Types¶

struct J¶

The core JSON object type used by note-c.

When using note-c, treat this struct as opaque. You should never have to work directly with its members.

typedef double JNUMBER¶: The floating point type used for JSON handling in note-c.

typedef int64_t JINTEGER¶: The signed integer type used for JSON handling in note-c.

typedef uint64_t JUINTEGER¶: The unsigned integer type used for JSON handling in note-c.

Macros¶

N_CJSON_NESTING_LIMIT¶

The maximum nesting level for JSON objects before a parsing error.

Default value: 100

For example, if you have a JSON object that contains multiple, nested objects like this

And the nesting level exceeds N_CJSON_NESTING_LIMIT, then calling JParse on a J * representing this object will return an error (NULL).

This exists to prevent the cJSON parser from causing a stack overflow. The user may override this macro at build time (e.g. -DN_CJSON_NESTING_LIMIT=200) to increase or reduce the limit.

API Reference¶

Dynamic Memory and Timing Hooks¶

Functions¶

Types¶

I/O Hooks¶

Serial Hooks¶

Functions¶

Types¶

I2C¶

Functions¶

Types¶

Macros¶

Mutex Hooks¶

Notecard Mutex¶

Functions¶

Types¶

I2C Mutex¶

Functions¶

Types¶

Notecard API Calls¶

Functions¶

JSON Manipulation¶

Functions¶

Types¶

Macros¶

API Reference ¶

Dynamic Memory and Timing Hooks ¶

I/O Hooks ¶

Mutex Hooks ¶

Notecard API Calls ¶

JSON Manipulation ¶