Add functions to query information about TCP/IP devices

Signed-off-by: Marc Schink <jaylink-dev@marcschink.de>

3 files changed, 178 insertions, 4 deletions

diff --git a/libjaylink/device.c b/libjaylink/device.c
index 010c0a0..a02585c 100644
--- a/libjaylink/device.c
+++ b/libjaylink/device.c
@@ -275,6 +275,169 @@ JAYLINK_API int jaylink_device_get_usb_address(
 }
 
 /**
+ * Get the IPv4 address string of a device.
+ *
+ * @param[in] dev Device instance.
+ * @param[out] address IPv4 address string in quad-dotted decimal format of the
+ *                     device on success and undefined on failure.
+ *
+ * @retval JAYLINK_OK Success.
+ * @retval JAYLINK_ERR_ARG Invalid arguments.
+ * @retval JAYLINK_ERR_NOT_SUPPORTED Supported for devices with host interface
+ *                                   #JAYLINK_HIF_TCP only.
+ *
+ * @since 0.2.0
+ */
+JAYLINK_API int jaylink_device_get_ipv4_address(
+		const struct jaylink_device *dev, char *address)
+{
+	if (!dev || !address)
+		return JAYLINK_ERR_ARG;
+
+	if (dev->interface != JAYLINK_HIF_TCP)
+		return JAYLINK_ERR_NOT_SUPPORTED;
+
+	memcpy(address, dev->ipv4_address, sizeof(dev->ipv4_address));
+
+	return JAYLINK_OK;
+}
+
+/**
+ * Get the MAC address of a device.
+ *
+ * @param[in] dev Device instance.
+ * @param[out] address MAC address of the device on success and undefined on
+ *                     failure. The length of the MAC address is
+ *                     #JAYLINK_MAC_ADDRESS_LENGTH bytes.
+ *
+ * @retval JAYLINK_OK Success.
+ * @retval JAYLINK_ERR_ARG Invalid arguments.
+ * @retval JAYLINK_ERR_NOT_SUPPORTED Supported for devices with host interface
+ *                                   #JAYLINK_HIF_TCP only.
+ * @retval JAYLINK_ERR_NOT_AVAILABLE MAC address is not available.
+ *
+ * @since 0.2.0
+ */
+JAYLINK_API int jaylink_device_get_mac_address(
+		const struct jaylink_device *dev, uint8_t *address)
+{
+	if (!dev || !address)
+		return JAYLINK_ERR_ARG;
+
+	if (dev->interface != JAYLINK_HIF_TCP)
+		return JAYLINK_ERR_NOT_SUPPORTED;
+
+	if (!dev->has_mac_address)
+		return JAYLINK_ERR_NOT_AVAILABLE;
+
+	memcpy(address, dev->mac_address, sizeof(dev->mac_address));
+
+	return JAYLINK_OK;
+}
+
+/**
+ * Get the hardware version of a device.
+ *
+ * @note The hardware type can not be obtained by this function, use
+ *       jaylink_get_hardware_version() instead.
+ *
+ * @param[in] dev Device instance.
+ * @param[out] version Hardware version of the device on success and undefined
+ *                     on failure.
+ *
+ * @retval JAYLINK_OK Success.
+ * @retval JAYLINK_ERR_ARG Invalid arguments.
+ * @retval JAYLINK_ERR_NOT_SUPPORTED Supported for devices with host interface
+ *                                   #JAYLINK_HIF_TCP only.
+ * @retval JAYLINK_ERR_NOT_AVAILABLE Hardware version is not available.
+ *
+ * @since 0.2.0
+ */
+JAYLINK_API int jaylink_device_get_hardware_version(
+		const struct jaylink_device *dev,
+		struct jaylink_hardware_version *version)
+{
+	if (!dev || !version)
+		return JAYLINK_ERR_ARG;
+
+	if (dev->interface != JAYLINK_HIF_TCP)
+		return JAYLINK_ERR_NOT_SUPPORTED;
+
+	if (!dev->has_hw_version)
+		return JAYLINK_ERR_NOT_AVAILABLE;
+
+	*version = dev->hw_version;
+
+	return JAYLINK_OK;
+}
+
+/**
+ * Get the product name of a device.
+ *
+ * @param[in] dev Device instance.
+ * @param[out] name Product name of the device on success and undefined on
+ *                  failure. The maximum length of the product name is
+ *                  #JAYLINK_PRODUCT_NAME_MAX_LENGTH bytes.
+ *
+ * @retval JAYLINK_OK Success.
+ * @retval JAYLINK_ERR_ARG Invalid arguments.
+ * @retval JAYLINK_ERR_NOT_SUPPORTED Supported for devices with host interface
+ *                                   #JAYLINK_HIF_TCP only.
+ * @retval JAYLINK_ERR_NOT_AVAILABLE Product name is not available.
+ *
+ * @since 0.2.0
+ */
+JAYLINK_API int jaylink_device_get_product_name(
+		const struct jaylink_device *dev, char *name)
+{
+	if (!dev || !name)
+		return JAYLINK_ERR_ARG;
+
+	if (dev->interface != JAYLINK_HIF_TCP)
+		return JAYLINK_ERR_NOT_SUPPORTED;
+
+	if (!dev->has_product_name)
+		return JAYLINK_ERR_NOT_AVAILABLE;
+
+	memcpy(name, dev->product_name, sizeof(dev->product_name));
+
+	return JAYLINK_OK;
+}
+
+/**
+ * Get the nickname of a device.
+ *
+ * @param[in] dev Device instance.
+ * @param[out] nickname Nickname of the device on success and undefined on
+ *                      failure. The maximum length of the nickname is
+ *                      #JAYLINK_NICKNAME_MAX_LENGTH bytes.
+ *
+ * @retval JAYLINK_OK Success.
+ * @retval JAYLINK_ERR_ARG Invalid arguments.
+ * @retval JAYLINK_ERR_NOT_SUPPORTED Supported for devices with host interface
+ *                                   #JAYLINK_HIF_TCP only.
+ * @retval JAYLINK_ERR_NOT_AVAILABLE Nickname is not available.
+ *
+ * @since 0.2.0
+ */
+JAYLINK_API int jaylink_device_get_nickname(const struct jaylink_device *dev,
+		char *nickname)
+{
+	if (!dev || !nickname)
+		return JAYLINK_ERR_ARG;
+
+	if (dev->interface != JAYLINK_HIF_TCP)
+		return JAYLINK_ERR_NOT_SUPPORTED;
+
+	if (!dev->has_nickname)
+		return JAYLINK_ERR_NOT_AVAILABLE;
+
+	memcpy(nickname, dev->nickname, sizeof(dev->nickname));
+
+	return JAYLINK_OK;
+}
+
+/**
  * Increment the reference count of a device.
  *
  * @param[in,out] dev Device instance.
diff --git a/libjaylink/libjaylink-internal.h b/libjaylink/libjaylink-internal.h
index 5da37dc..96a9a2a 100644
--- a/libjaylink/libjaylink-internal.h
+++ b/libjaylink/libjaylink-internal.h
@@ -51,9 +51,6 @@
 /** Calculate the minimum of two numeric values. */
 #define MIN(a, b) (((a) < (b)) ? (a) : (b))
 
-/** Media Access Control (MAC) address length in bytes. */
-#define MAC_ADDRESS_LENGTH	6
-
 struct jaylink_context {
 	/** libusb context. */
 	struct libusb_context *usb_ctx;
@@ -110,7 +107,7 @@ struct jaylink_device {
 	 * This field is used for devices with host interface #JAYLINK_HIF_TCP
 	 * only.
 	 */
-	uint8_t mac_address[MAC_ADDRESS_LENGTH];
+	uint8_t mac_address[JAYLINK_MAC_ADDRESS_LENGTH];
 	/** Indicates whether the MAC address is available. */
 	bool has_mac_address;
 	/**
diff --git a/libjaylink/libjaylink.h b/libjaylink/libjaylink.h
index 20ecbb6..ef00f76 100644
--- a/libjaylink/libjaylink.h
+++ b/libjaylink/libjaylink.h
@@ -327,6 +327,9 @@ struct jaylink_connection {
 /** Maximum number of connections that can be registered on a device. */
 #define JAYLINK_MAX_CONNECTIONS			16
 
+/** Media Access Control (MAC) address length in bytes. */
+#define JAYLINK_MAC_ADDRESS_LENGTH		6
+
 /**
  * Maximum length of a device's nickname including trailing null-terminator in
  * bytes.
@@ -425,6 +428,17 @@ JAYLINK_API int jaylink_device_get_serial_number(
 JAYLINK_API int jaylink_device_get_usb_address(
 		const struct jaylink_device *dev,
 		enum jaylink_usb_address *address);
+JAYLINK_API int jaylink_device_get_ipv4_address(
+		const struct jaylink_device *dev, char *address);
+JAYLINK_API int jaylink_device_get_mac_address(
+		const struct jaylink_device *dev, uint8_t *address);
+JAYLINK_API int jaylink_device_get_hardware_version(
+		const struct jaylink_device *dev,
+		struct jaylink_hardware_version *version);
+JAYLINK_API int jaylink_device_get_product_name(
+		const struct jaylink_device *dev, char *name);
+JAYLINK_API int jaylink_device_get_nickname(const struct jaylink_device *dev,
+		char *nickname);
 JAYLINK_API struct jaylink_device *jaylink_ref_device(
 		struct jaylink_device *dev);
 JAYLINK_API void jaylink_unref_device(struct jaylink_device *dev);