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: +
+trueon success andfalseon 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: +
+trueif there’s data to read andfalseotherwise.
+
-
+
-
+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¶
+ + +Types¶
+-
+
-
+typedef void (*mutexFn)(void)¶
The type for the various mutex (i.e. lock/unlock) hooks.
+
I2C Mutex¶
+Functions¶
+ + +Types¶
+See mutexFn.
Notecard API Calls¶
+Functions¶
+-
+
-
+J *NoteNewRequest(const char *request)¶
Create a new JSON request.
+Creates a dynamically allocated
+Jobject 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
+Jobject 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
+
+NoteResponseErrorto check the response for errors.
-
+
-
+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
+
+NoteResponseErrorto check the response for errors.
-
+
-
+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
+
+NoteRequestResponseif you need to work with the response.-
+
- Parameters: +
-
+
req – Pointer to a
Jrequest object.
+
+- Returns: +
+trueif successful andfalseif 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, atruereturn 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
+
+NoteRequestResponseWithRetryif you need to work with the response.-
+
- Parameters: +
-
+
req – Pointer to a
Jrequest object.
+timeoutSeconds – Time limit for retires, in seconds, if there is no response, or if the response contains an I/O error.
+
+- Returns: +
+trueif successful andfalseif 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: +
+trueif there’s an error andfalseif 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 aJobject. 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
+Jobject.-
+
- 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
+Jobject.-
+
- 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
+Jobject.-
+
- 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
+Jobject.-
+
- 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
+Jobject.-
+
- 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
+Jobject.To free the object, use
+JDelete.-
+
- Returns: +
A pointer to the newly-created 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
+JFreewhen it is no longer needed.++Note
+On error, the returned binary buffer and data length shall be set to
+NULLand 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
+Jobject representing it.-
+
- Parameters: +
-
+
value – The JSON object as a C-string.
+
+- Returns: +
A
+Jobject or NULL on error (e.g. the string was invalid JSON).
+
-
+
-
+char *JPrintUnformatted(const J *item)¶
Get the unformatted string representation of a
+Jobject.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:
+100For example, if you have a JSON object that contains multiple, nested objects like this
+ And the nesting level exceeds+{ + "x": + { + "x:" + { + . + . + . + } + } +} +
N_CJSON_NESTING_LIMIT, then callingJParseon aJ *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.
+
