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 system hook functions (memory allocation, delay, timing).

Note

This function overrides any previously set system functions.

Note

This operation will lock Notecard access while in progress, if Notecard mutex functions have been set.

Parameters:

  • mallocHook – The platform-specific function for memory allocation.

  • freeHook – The platform-specific function for memory deallocation.

  • delayMsHook – The platform-specific function for millisecond delays.

  • getMsHook – The platform-specific function to get millisecond counter.

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 serial communication hook functions.

Note

This function overrides any previously set serial functions.

Note

This operation will set the active interface to serial.

Note

This operation will lock Notecard access while in progress, if Notecard mutex functions have been set.

Parameters:

  • resetFn – The platform-specific function to reset the serial peripheral.

  • transmitFn – The platform-specific function to transmit data via serial.

  • availFn – The platform-specific function to check if serial data is available.

  • receiveFn – The platform-specific function to receive serial data.

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 I2C communication hook functions, address and MTU.

Note

This function overrides any previously set I2C functions.

Note

This operation will set the active interface to I2C.

Note

This operation will lock Notecard access while in progress, if Notecard mutex functions have been set.

Parameters:

  • notecardAddr – I2C address of the Notecard (0 for default).

  • maxTransmitSize – Maximum number of bytes to transmit in a single I2C segment (0 for default).

  • resetFn – The platform-specific function to reset the I2C peripheral.

  • transmitFn – The platform-specific function to transmit data via I2C.

  • receiveFn – The platform-specific function to receive data via I2C.

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 Notecard mutex functions.

Parameters:

  • lockFn – Function to lock Notecard access.

  • unlockFn – Function to unlock Notecard access.

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 I2C mutex functions.

Parameters:

  • lockI2Cfn – Function to lock I2C access.

  • unlockI2Cfn – Function to unlock I2C access.

Types

See mutexFn.

Notecard API Calls

Functions

J *NoteNewRequest(const char *request)

Create a new request JSON object.

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

Parameters:

  • request – The name of the Notecard API request (e.g., “card.version”).

Returns:

A pointer to a newly allocated JSON object with the “req” field populated, or NULL on failure.

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 until it succeeds or times out, then 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.

Note

Timeouts may occur when either there is no response, or if the response contains an I/O error.

Parameters:

  • req – Pointer to a J request object.

  • timeoutSeconds – Time limit for retries, in seconds.

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 until it succeeds or 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 retries, 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 as JSON string.

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 is newline-terminated, just like the request. 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, since commands do not have a response.

Note

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

Note

Unlike the NoteRequest* functions, this function does not automatically free the request JSON string. It is not possible to know if the parameter is a string literal. As such, it is the caller’s responsibility to manage the memory associated with the request string.

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 to a JSON object as a base64-encoded string.

Parameters:

  • json – The JSON object to modify.

  • fieldName – The field name to add.

  • 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 an array object from a JSON object field.

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 to query.

  • field – The field name to retrieve.

Returns:

Pointer to the JSON array (J *), or NULL if the field doesn’t exist or isn’t an array.

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 to query.

  • fieldName – The field name to retrieve.

  • retBinaryData – A pointer to a pointer used to store the decoded binary data (caller must free).

  • retBinaryDataLen – A pointer to an unsigned integer used to store the length of the decoded binary data.

Returns:

true if the binary data was successfully decoded, false otherwise.

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 to query.

  • field – The field name to retrieve.

Returns:

The boolean value, or false if the field doesn’t exist or isn’t a boolean.

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 to query.

  • field – The field name to retrieve.

Returns:

The integer value, or 0 if the field doesn’t exist or isn’t a number.

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

Get the 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 to query.

  • field – The field name to retrieve.

Returns:

The numeric value, or 0.0f if the field doesn’t exist or isn’t a number.

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

Get a JSON object from a JSON object field.

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 to query.

  • field – The field name to retrieve.

Returns:

Pointer to the nested JSON object, or NULL if the field doesn’t exist or isn’t an object.

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

Get a string value from a JSON object field.

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 to query.

  • field – The field name to retrieve.

Returns:

Pointer to the string value, or an empty string (“”) if the field doesn’t exist or isn’t a string.

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

Check if a field is present in a JSON object.

Parameters:

  • json – The JSON object to check.

  • field – The field name to look for.

Returns:

true if the field is present, false otherwise.

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 

{
    "x":
    {
        "x:"
        {
            .
            .
            .
        }
    }
}
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.

Logging

Hooks

Functions

void NoteGetFnDebugOutput(debugOutputFn *fn)

Get the currently set debug output function hook.

Parameters:

  • fn – Pointer to store the current debug output function pointer.

void NoteSetFnDebugOutput(debugOutputFn fn)

Set the debug output function hook.

Note

This operation will lock Notecard access while in progress, if Notecard mutex functions have been set.

Parameters:

  • fn – Pointer to the debug output function.

Types

typedef size_t (*debugOutputFn)(const char *text)

The type for the debug output hook.

Param text:

The debug text to output.

Return:

Number of characters written, or 0 on failure.

Control

Functions

void NoteSetLogLevel(int level)

Set the current log level for debug output filtering.

Parameters:

  • level – The log level to set:

    • NOTE_C_LOG_LEVEL_ERROR

    • NOTE_C_LOG_LEVEL_WARN

    • NOTE_C_LOG_LEVEL_INFO

    • NOTE_C_LOG_LEVEL_DEBUG

bool NoteDebugSyncStatus(int pollFrequencyMs, int maxLevel)

Enable debug output for sync status monitoring.

Parameters:

  • pollFrequencyMs – How often to poll for sync status, in milliseconds.

  • maxLevel – Maximum detail level for sync status output.

Returns:

true if debugging was enabled successfully, false otherwise.

Macros

NOTE_C_LOG_LEVEL_ERROR
NOTE_C_LOG_LEVEL_WARN
NOTE_C_LOG_LEVEL_INFO
NOTE_C_LOG_LEVEL_DEBUG
SYNCSTATUS_LEVEL_MAJOR
SYNCSTATUS_LEVEL_MINOR
SYNCSTATUS_LEVEL_DETAILED
SYNCSTATUS_LEVEL_ALGORITHMIC
SYNCSTATUS_LEVEL_ALL