added get_device_topology optional API call

* Windows only, unsupported on other platforms

6 files changed, 71 insertions, 0 deletions

diff --git a/libusb/core.c b/libusb/core.c
index 46c2b9c..5ad5809 100644
--- a/libusb/core.c
+++ b/libusb/core.c
@@ -1454,6 +1454,28 @@ int API_EXPORTED libusb_attach_kernel_driver(libusb_device_handle *dev,
 		return LIBUSB_ERROR_NOT_SUPPORTED;
 }
 
+/** \ingroup dev
+ * Returns topology information for a device
+ *
+ * \param dev the device to get topology properties from
+ * \param topology the libusb_device_topology structure to be populated.
+ * \returns 0 on success
+ * \returns LIBUSB_ERROR_INVALID_PARAM if dev or topology are invalid
+ * \returns LIBUSB_ERROR_NOT_SUPPORTED on platforms where the functionality
+ * is not available
+ * \returns another LIBUSB_ERROR code on other failure
+ */
+
+int API_EXPORTED libusb_get_device_topology(libusb_device *dev,
+	struct libusb_device_topology* topology)
+{
+	usbi_dbg("");
+	if (dev == NULL || topology == NULL) {
+		return LIBUSB_ERROR_INVALID_PARAM;
+	}
+	return usbi_backend->get_device_topology(dev, topology);
+}
+
 /** \ingroup lib
  * Set message verbosity.
  *  - Level 0: no messages ever printed by the library (default)
diff --git a/libusb/libusb.h b/libusb/libusb.h
index b57fe1a..a89e326 100644
--- a/libusb/libusb.h
+++ b/libusb/libusb.h
@@ -675,6 +675,20 @@ typedef struct libusb_device libusb_device;
  */
 typedef struct libusb_device_handle libusb_device_handle;
 
+/** \ingroup dev
+ * Structure representing the topology of an USB device.
+ */
+struct libusb_device_topology {
+	/** Opaque device handle to the USB parent (a Hub or a HCD) */
+	libusb_device* parent_dev;
+	/** Bus number to which the device is connected, as seen by the OS */
+	uint8_t bus;
+	/** Depth to HCD for this bus (0 depth means the HCD device) */
+	uint8_t depth;
+	/** Hub port onto which the device is plugged in, as seen by the OS */
+	uint8_t port;
+};
+
 /** \ingroup misc
  * Error codes. Most libusb functions return 0 on success or one of these
  * codes on failure.
@@ -920,6 +934,9 @@ int LIBUSB_CALL libusb_detach_kernel_driver(libusb_device_handle *dev,
 int LIBUSB_CALL libusb_attach_kernel_driver(libusb_device_handle *dev,
 	int interface_number);
 
+int LIBUSB_CALL libusb_get_device_topology(struct libusb_device *dev,
+	struct libusb_device_topology *topology);
+
 /* async I/O */
 
 /** \ingroup asyncio
diff --git a/libusb/libusbi.h b/libusb/libusbi.h
index 99bf6ac..28c5b0e 100644
--- a/libusb/libusbi.h
+++ b/libusb/libusbi.h
@@ -755,6 +755,14 @@ struct usbi_os_backend {
 	int (*attach_kernel_driver)(struct libusb_device_handle *handle,
 		int interface_number);
 
+	/* Return device topology. Optional.
+	 *
+	 * This function is called to populate a libusb_device_topology structure,
+	 * that allows to uniquely identify the location of a device on the system.
+	 */
+	int (*get_device_topology)(struct libusb_device *dev,
+		struct libusb_device_topology* topology);
+
 	/* Destroy a device. Optional.
 	 *
 	 * This function is called when the last reference to a device is
diff --git a/libusb/os/darwin_usb.c b/libusb/os/darwin_usb.c
index 646c938..4c19592 100644
--- a/libusb/os/darwin_usb.c
+++ b/libusb/os/darwin_usb.c
@@ -1097,6 +1097,10 @@ static int darwin_detach_kernel_driver (struct libusb_device_handle *dev_handle,
   return LIBUSB_ERROR_NOT_SUPPORTED;
 }
 
+static int darwin_get_device_topology(struct libusb_device *dev, struct libusb_device_topology* topology) {
+  return LIBUSB_ERROR_NOT_SUPPORTED;
+}
+
 static void darwin_destroy_device(struct libusb_device *dev) {
 }
 
@@ -1527,6 +1531,7 @@ const struct usbi_os_backend darwin_backend = {
 	.detach_kernel_driver = darwin_detach_kernel_driver,
 	.attach_kernel_driver = darwin_attach_kernel_driver,
 
+	.get_device_topology = darwin_get_device_topology,
 	.destroy_device = darwin_destroy_device,
 
 	.submit_transfer = darwin_submit_transfer,
diff --git a/libusb/os/linux_usbfs.c b/libusb/os/linux_usbfs.c
index 5c2a6e8..b7d9066 100644
--- a/libusb/os/linux_usbfs.c
+++ b/libusb/os/linux_usbfs.c
@@ -1310,6 +1310,12 @@ static int op_attach_kernel_driver(struct libusb_device_handle *handle,
 	return 0;
 }
 
+static int op_get_device_topology(struct libusb_device *dev,
+	struct libusb_device_topology* topology)
+{
+	return LIBUSB_ERROR_NOT_SUPPORTED;
+}
+
 static void op_destroy_device(struct libusb_device *dev)
 {
 	struct linux_device_priv *priv = __device_priv(dev);
@@ -2198,6 +2204,7 @@ const struct usbi_os_backend linux_usbfs_backend = {
 	.detach_kernel_driver = op_detach_kernel_driver,
 	.attach_kernel_driver = op_attach_kernel_driver,
 
+	.get_device_topology = op_get_device_topology,
 	.destroy_device = op_destroy_device,
 
 	.submit_transfer = op_submit_transfer,
diff --git a/libusb/os/windows_usb.c b/libusb/os/windows_usb.c
index 1979200..2a70969 100644
--- a/libusb/os/windows_usb.c
+++ b/libusb/os/windows_usb.c
@@ -1845,6 +1845,17 @@ static void windows_destroy_device(struct libusb_device *dev)
 	windows_device_priv_release(dev);
 }
 
+static int windows_get_device_topology(struct libusb_device *dev, struct libusb_device_topology* topology)
+{
+	struct windows_device_priv *priv = __device_priv(dev);
+
+	topology->bus = dev->bus_number;
+	topology->depth = priv->depth;
+	topology->parent_dev = priv->parent_dev;
+	topology->port = priv->port;
+	return LIBUSB_SUCCESS;
+}
+
 static void windows_clear_transfer_priv(struct usbi_transfer *itransfer)
 {
 	struct windows_transfer_priv *transfer_priv = (struct windows_transfer_priv*)usbi_transfer_get_os_priv(itransfer);
@@ -2236,6 +2247,7 @@ const struct usbi_os_backend windows_backend = {
 	windows_detach_kernel_driver,
 	windows_attach_kernel_driver,
 
+	windows_get_device_topology,
 	windows_destroy_device,
 
 	windows_submit_transfer,