homechevron_rightDocschevron_rightAPI Referencechevron_rightNotecard APIchevron_rightfile Requests - API Reference

file Requests

The file set of requests enable developers to work with all types of Notefiles.

The requests in this section are available on the Notecard API. Consult the Notehub Device API to manage inbound and DB Notefiles from Notehub.

file.changes CellCell+WiFiLoRaWiFi

Used to perform queries on a single or multiple files to determine if new Notes are available to read, or if there are unsynced Notes in local Notefiles.

Note: This request is a Notefile API request, only. .qo Notes in Notehub are automatically ingested and stored, or sent to applicable Routes.

Arguments

files

array of strings (optional)

One or more files to obtain change information from. Omit to return changes for all Notefiles.

tracker

string (optional)

Cell Cell+WiFi WiFi

ID of a change tracker to use to determine changes to Notefiles.

{
  "req": "file.changes",
  "tracker": "multi-file-tracker",
  "files": ["my-settings.db", "other-settings.db"]
}
J *req = NoteNewRequest("file.changes");
JAddStringToObject(req, "tracker", "multi-file-tracker");

J *files = JAddArrayToObject(req, "files");
JAddItemToArray(files, JCreateString("other-settings.db"));
JAddItemToArray(files, JCreateString("my-settings.db"));

NoteRequest(req);
req = {"req": "file.changes"}
req["tracker"] = "multi-file-tracker"
req["files"] = ["my-settings.db", "other-settings.db"]
rsp = card.Transaction(req)
Response Members

total

integer

The total of local Notes across all Notefiles. This includes Inbound Notes that have not been deleted, as well as outbound Notes that have yet to sync.

changes

integer

If a change tracker is used, the number of changes across all files.

info

JSON object

An object with a key for each Notefile that matched the request parameters, and value object with the changes and total for each file.

Example Response
{
  "changes": 5,
  "total": 5,
  "info": {
    "my-settings.db": { "changes": 3, "total": 3 },
    "other-settings.db": { "changes": 2, "total": 2 }
  }
}
More information:

file.changes.pending CellCell+WiFiLoRaWiFi

Returns info about file changes that are pending upload to Notehub.

Arguments
None
{
  "req": "file.changes.pending"
}
J *req = NoteNewRequest("file.changes.pending");

NoteRequest(req);
req = {"req": "file.changes.pending"}
rsp = card.Transaction(req)
Response Members

total

integer

The total of unsynced notes across all Notefiles.

changes

integer

The number of changes across all files.

pending

boolean

true if there are pending changes.

info

JSON object

An object with a key for each Notefile and value object with the changes and total for each file.

Example Response
{
  "total": 3,
  "changes": 3,
  "pending": true,
  "info": {
    "sensors.qo": { "changes": 3, "total": 3 }
  }
}

file.clear CellCell+WiFiWiFi

Used to clear the contents of a specified outbound (.qo/.qos) Notefile, deleting all pending Notes.

Arguments

file

string

The name of the Notefile whose Notes you wish to delete.

{
  "req": "file.clear",
  "file": "data.qo"
}
J *req = NoteNewRequest("file.clear");
JAddStringToObject(req, "file", "data.qo");

NoteRequest(req);
req = {"req": "file.clear"}
req["file"] = "data.qo"
rsp = card.Transaction(req)
Response Members
None: an empty object {} means success.

file.delete CellCell+WiFiLoRaWiFi

Deletes Notefiles and the Notes they contain.

Arguments

files

array of strings

One or more files to delete.

{
  "req": "file.delete",
  "files": ["my-settings.db", "other-settings.db"]
}
J *req = NoteNewRequest("file.delete");

J *files = JAddArrayToObject(req, "files");
JAddItemToArray(files, JCreateString("other-settings.db"));
JAddItemToArray(files, JCreateString("my-settings.db"));

NoteRequest(req);
req = {"req": "file.delete"}
req["files"] = ["my-settings.db", "other-settings.db"]
card.Transaction(req)
Response Members
None: an empty object {} means success.

file.stats CellCell+WiFiLoRaWiFi

Gets resource statistics about local Notefiles.

Arguments

file

string (optional)

Returns the stats for the specified Notefile only.

{
  "req": "file.stats"
}
J *req = NoteNewRequest("file.stats");

NoteRequest(req);
req = {"req": "file.stats"}
rsp = card.Transaction(req)
Response Members

total

integer

The total number of Notes across all Notefiles.

changes

integer

The number of Notes across all Notefiles pending sync.

sync

boolean

true if a sync is recommended based on the number of pending notes.

Example Response
{
  "total":   83,
  "changes": 78,
  "sync":    true
}