chore: Add helper for length

n_helpers.c

@@ -86,6 +86,48 @@ NOTE_C_STATIC int ytodays(int year);
 
 static const char BINARY_EOP = '\n';
 
+//**************************************************************************/
+/*!
+  @brief  Get the length of the data stored on the Notecard. If there's no data
+          stored on the Notecard, then `*len` will return 0.
+  @param  len [out] the length of the decoded contents of the Notecard's binary
+          data store.
+  @returns An error string on error and NULL on success.
+*/
+/**************************************************************************/
+const char * NoteBinaryDataLength(size_t *len)
+{
+    // Validate parameter(s)
+    if (!len) {
+        NOTE_C_LOG_ERROR("len cannot be NULL");
+        return ERRSTR("len cannot be NULL", c_err);
+    }
+
+    // Issue a "card.binary" request.
+    J *rsp = NoteRequestResponse(NoteNewRequest("card.binary"));
+    if (!rsp) {
+        NOTE_C_LOG_ERROR("unable to issue binary request");
+        return ERRSTR("unable to issue binary request", c_err);
+    }
+
+    // Ensure the transaction doesn't return an error and confirm the binary
+    // feature is available.
+    if (NoteResponseError(rsp)) {
+        const char *err = JGetString(rsp, "err");
+        NOTE_C_LOG_ERROR(err);
+        JDelete(rsp);
+        NOTE_C_LOG_ERROR("unexpected error received during handshake");
+        return ERRSTR("unexpected error received during handshake", c_bad);
+    }
+
+    // Examine "length" from the response to evaluate the length of the decoded
+    // data residing on the Notecard.
+    *len = JGetInt(rsp, "length");
+    JDelete(rsp);
+
+    return NULL;
+}
+
 //**************************************************************************/
 /*!
   @brief  Decode a binary payload received from the Notecard.
@@ -98,7 +140,7 @@ static const char BINARY_EOP = '\n';
   @returns  NULL on success, else an error string pointer.
 */
 /**************************************************************************/
-const char *NoteBinaryDecode(const uint8_t *inBuf, uint32_t inLen,
+const char * NoteBinaryDecode(const uint8_t *inBuf, uint32_t inLen,
                              uint8_t *outBuf, uint32_t *outLen)
 {
     if (inBuf == NULL || outBuf == NULL || outLen == NULL) {
@@ -128,7 +170,7 @@ const char *NoteBinaryDecode(const uint8_t *inBuf, uint32_t inLen,
   @returns  NULL on success, else an error string pointer.
 */
 /**************************************************************************/
-const char *NoteBinaryEncode(const uint8_t *inBuf, uint32_t inLen,
+const char * NoteBinaryEncode(const uint8_t *inBuf, uint32_t inLen,
                              uint8_t *outBuf, uint32_t *outLen)
 {
     if (inBuf == NULL || outBuf == NULL || outLen == NULL) {
@@ -310,10 +352,10 @@ size_t NoteBinaryRequiredBuffer(size_t dataLen)
 //**************************************************************************/
 /*!
   @brief  Get the required buffer size to receive the entire binary object
-          stored on the Notecard. If there's no data to stored on the Notecard,
-          *size will return 0.
-  @param  size [out] size required to hold the entire contents of the
-           Notecard's binary store.
+          stored on the Notecard. If there's no data stored on the Notecard,
+          then `*size` will return 0.
+  @param  size [out] the size required to hold the entire contents of the
+           Notecard's binary data store.
   @returns An error string on error and NULL on success.
 */
 /**************************************************************************/
@@ -343,7 +385,7 @@ const char * NoteBinaryRequiredRxMaxBuffer(size_t *size)
     }
 
     // Examine "cobs" from the response to evaluate the space required to hold
-    // the COBS-encoded data received from the Notecard.
+    // the COBS-encoded data to be received from the Notecard.
     long int cobs = JGetInt(rsp, "cobs");
     JDelete(rsp);
     if (!cobs) {

note.h

@@ -318,19 +318,20 @@ void NoteMD5HashToString(unsigned char *hash, char *strbuf, unsigned long buflen
 // High-level helper functions that are both useful and serve to show developers
 // how to call the API
 #define NOTE_C_BINARY_RX_ALL 0
+const char * NoteBinaryDataLength(size_t *len);
+const char * NoteBinaryDecode(const uint8_t *inBuf, uint32_t inLen,
+                             uint8_t *outBuf, uint32_t *outLen);
+const char * NoteBinaryEncode(const uint8_t *inBuf, uint32_t inLen,
+                             uint8_t *outBuf, uint32_t *outLen);
+uint32_t NoteBinaryEncodedLength(const uint8_t *buf, uint32_t len);
+uint32_t NoteBinaryEncodedMaxLength(uint32_t len);
 const char * NoteBinaryReceive(uint8_t *buffer, size_t bufLen,
                                size_t offset, size_t *dataLen);
-const char * NoteBinaryRequiredRxMaxBuffer(size_t *size);
 size_t NoteBinaryRequiredBuffer(size_t dataLen);
+const char * NoteBinaryRequiredRxMaxBuffer(size_t *size);
 const char * NoteBinaryReset(void);
 const char * NoteBinaryTransmit(uint8_t *data, size_t dataLen,
                                 size_t bufLen, size_t offset);
-const char *NoteBinaryDecode(const uint8_t *inBuf, uint32_t inLen,
-                             uint8_t *outBuf, uint32_t *outLen);
-const char *NoteBinaryEncode(const uint8_t *inBuf, uint32_t inLen,
-                             uint8_t *outBuf, uint32_t *outLen);
-uint32_t NoteBinaryEncodedLength(const uint8_t *buf, uint32_t len);
-uint32_t NoteBinaryEncodedMaxLength(uint32_t len);
 uint32_t NoteSetSTSecs(uint32_t secs);
 bool NoteTimeValid(void);
 bool NoteTimeValidST(void);