libbladeRF: add bladerf_get_serial_struct function

Adds a bladerf_get_serial_struct function, which is similar
in functionality to bladerf_get_serial, but instead of requiring
a user-supplied buffer of at least BLADERF_SERIAL_LENGTH bytes,
it expects a pointer to a struct bladerf_serial which itself has
a buffer of BLADERF_SERIAL_LENGTH bytes as a member.

This turns BLADERF_SERIAL_LENGTH into an API-internal value,
instead of something that API users have to be intently aware of.

Fixes Nuand#382

Author: rtucker

host/libraries/libbladeRF/include/libbladeRF.h

@@ -372,6 +372,13 @@ struct bladerf_range {
     float scale;  /**< Unit scale */
 };
 
+/**
+ * Serial number structure
+ */
+struct bladerf_serial {
+    char serial[BLADERF_SERIAL_LENGTH]; /**< Device serial number string */
+};
+
 /**
  * Version structure for FPGA, firmware, libbladeRF, and associated utilities
  */
@@ -408,7 +415,7 @@ typedef enum {
 } bladerf_dev_speed;
 
 /**
- * Query a device's serial number
+ * Query a device's serial number (deprecated)
  *
  * @param       dev     Device handle
  * @param[out]  serial  This user-supplied buffer, which <b>must be at least
@@ -417,11 +424,39 @@ typedef enum {
  *                      error occurs (as indicated by a non-zero return value),
  *                      no data will be written to this buffer.
  *
+ * @deprecated New code should use ::bladerf_get_serial_struct instead.
+ *
  * @return 0 on success, value from \ref RETCODES list on failure
  */
 API_EXPORT
 int CALL_CONV bladerf_get_serial(struct bladerf *dev, char *serial);
 
+/**
+ * Query a device's serial number
+ *
+ * @param       dev     Device handle
+ * @param[out]  serial  Pointer to a bladerf_serial structure, which will be
+ *                      populated with a `serial` string on success.
+ *
+ * Example code:
+ *
+ * @code
+ *   struct bladerf_serial sn;
+ *
+ *   status = bladerf_get_serial_struct(dev, &sn);
+ *   if (status < 0) {
+ *       // error handling here
+ *   }
+ *
+ *   printf("Serial number: %s\n", sn.serial);
+ * @endcode
+ *
+ * @return 0 on success, value from \ref RETCODES list on failure
+ */
+API_EXPORT
+int CALL_CONV bladerf_get_serial_struct(struct bladerf *dev,
+                                        struct bladerf_serial *serial);
+
 /**
  * Query a device's FPGA size
  *

host/libraries/libbladeRF/src/bladerf.c

@@ -331,12 +331,32 @@ int bladerf_get_serial(struct bladerf *dev, char *serial)
     int status;
     MUTEX_LOCK(&dev->lock);
 
+    /** TODO: add deprecation warning */
+
     status = dev->board->get_serial(dev, serial);
 
     MUTEX_UNLOCK(&dev->lock);
     return status;
 }
 
+int bladerf_get_serial_struct(struct bladerf *dev,
+                              struct bladerf_serial *serial)
+{
+    int status;
+    MUTEX_LOCK(&dev->lock);
+
+    char serialstr[BLADERF_SERIAL_LENGTH];
+
+    status = dev->board->get_serial(dev, serialstr);
+
+    if (status >= 0) {
+        strncpy(serial->serial, serialstr, BLADERF_SERIAL_LENGTH - 1);
+    }
+
+    MUTEX_UNLOCK(&dev->lock);
+    return status;
+}
+
 int bladerf_get_fpga_size(struct bladerf *dev, bladerf_fpga_size *size)
 {
     int status;