Calling the Notecard API¶

The Notecard API is JSON-based. note-c uses a modified version of the cJSON library for working with JSON. The core JSON struct used in note-c is J. You should treat this type as opaque; you will only ever need to work with J * when using note-c.

To make a Notecard API call, first create a JSON request:

J *req = NoteNewRequest("note.add");

When req is serialized to a string, it looks like this:

{"req": "note.add"}

To add fields to the request, there are a number of JAdd* functions:

For example, to add the field "file": "data.qo" to req, use JAddStringToObject():

JAddStringToObject(req, "file", "data.qo")

Now, when req is serialized, it will have the "file" field:

{"req": "note.add", "file": "data.qo"}

Once the request has been prepared, send it to the Notecard with NoteRequestResponse():

J *rsp = NoteRequestResponse(req);

rsp holds the JSON response from the Notecard. Use NoteResponseError() to check the response for errors:

if (rsp == NULL || NoteResponseError(rsp)) {
   // handle error
}

NoteRequestResponse will take care of freeing the passed in request object, but you must free the response with NoteDeleteResponse():

NoteDeleteResponse(rsp);

The function NoteRequest() is useful when you don’t care about the details of the Notecard’s response, just whether the API call was successful or not. It returns true if the API call was successful and false if there was an error sending the request or if there was an error in the response (i.e. it calls NoteResponseError() internally):

if (NoteRequest(req)) {
   // success
}
else {
   // handle error
}

NoteRequest() frees the request object for you.

Note

To use plain C-strings as the JSON interface into note-c, rather than J *, check out NoteRequestResponseJSON()

Examples¶

For examples of real applications calling the Notecard API with note-c, check out some of the Zephyr-based Blues App Accelerators: