Draft iphone_get_specific_device() API, fix documentation for iphone_get_device()

1 files changed, 72 insertions, 34 deletions

diff --git a/src/iphone.c b/src/iphone.c
index 81d6870..c14d61b 100644
--- a/src/iphone.c
+++ b/src/iphone.c
@@ -29,19 +29,31 @@
 
 extern int debug;
 
-/** Gets a handle to an iPhone
- * 
- * @return A structure with data on the first iPhone it finds.  (Or NULL, on
- *         error)
+/**
+ * Given a USB bus and device number, returns a device handle to the iPhone on
+ * that bus. To aid compatibility with future devices, this function does not
+ * check the vendor and device IDs! To do that, you should use
+ * iphone_get_device() or a system-specific API (e.g. HAL).
+ *
+ * @param bus_n The USB bus number.
+ * @param dev_n The USB device number.
+ * @param device A pointer to a iphone_device_t, which must be set to NULL upon
+ *      calling iphone_get_specific_device, which will be filled with a device
+ *      descriptor on return. 
+ * @return IPHONE_E_SUCCESS if ok, otherwise an error code.
  */
-iphone_error_t iphone_get_device(iphone_device_t * device)
+iphone_error_t iphone_get_specific_device(int bus_n, int dev_n,
+        iphone_device_t *device)
 {
+        struct usb_bus *bus, *busses;
+        struct usb_device *dev;
+        usbmux_version_header *version;
+        int bytes = 0;
+
         //check we can actually write in device
         if (!device || (device && *device))
                 return IPHONE_E_INVALID_ARG;
 
-        struct usb_bus *bus, *busses;
-        struct usb_device *dev;
         iphone_device_t phone = (iphone_device_t) malloc(sizeof(struct iphone_device_int));
 
         // Initialize the struct
@@ -55,36 +67,26 @@ iphone_error_t iphone_get_device(iphone_device_t * device)
         usb_find_devices();
         busses = usb_get_busses();
 
-
         // Set the device configuration
-        for (bus = busses; bus; bus = bus->next) {
-                for (dev = bus->devices; dev; dev = dev->next) {
-                        if (dev->descriptor.idVendor == 0x05ac &&
-                                (dev->descriptor.idProduct == 0x1290 ||
-                                 dev->descriptor.idProduct == 0x1291 || dev->descriptor.idProduct == 0x1292
-                                 || dev->descriptor.idProduct == 0x1293)
-                                ) {
-                                phone->__device = dev;
-                                phone->device = usb_open(phone->__device);
-                                usb_set_configuration(phone->device, 3);
-                                usb_claim_interface(phone->device, 1);
-                                break;
-                        }
-                }
-                if (phone->__device && phone->device)
-                        break;
-        }
+        for (bus = busses; bus; bus = bus->next)
+        if (bus->location == bus_n)
+            for (dev = bus->devices; dev != NULL; dev = dev->next)
+                if (dev->devnum == dev_n) {
+                    phone->__device = dev;
+                    phone->device = usb_open(phone->__device);
+                    usb_set_configuration(phone->device, 3);
+                    usb_claim_interface(phone->device, 1);
+                    goto found;
+                }
 
-        // Check to see if we are connected
-        if (!phone->device || !phone->__device) {
-                iphone_free_device(phone);
-                if (debug)
-                        fprintf(stderr, "get_iPhone(): iPhone not found\n");
-                return IPHONE_E_NO_DEVICE;
-        }
+    iphone_free_device(phone);
+    if (debug)
+        fprintf(stderr, "iphone_get_specific_device: iPhone not found\n");
+    return IPHONE_E_NO_DEVICE;
+
+found:
         // Send the version command to the phone
-        int bytes = 0;
-        usbmux_version_header *version = version_header();
+    version = version_header();
         bytes = usb_bulk_write(phone->device, BULKOUT, (char *) version, sizeof(*version), 800);
         if (bytes < 20 && debug) {
                 fprintf(stderr, "get_iPhone(): libusb did NOT send enough!\n");
@@ -131,6 +133,42 @@ iphone_error_t iphone_get_device(iphone_device_t * device)
         return IPHONE_E_UNKNOWN_ERROR;  // if it got to this point it's gotta be bad
 }
 
+/**
+ * Scans all USB busses and devices for a known AFC-compatible device and
+ * returns a handle to the first such device it finds. Known devices include
+ * those with vendor ID 0x05ac and product ID between 0x1290 and 0x1293
+ * inclusive.
+ *
+ * This function is convenient, but on systems where higher-level abstractions
+ * (such as HAL) are available it may be preferable to use
+ * iphone_get_specific_device instead, because it can deal with multiple
+ * connected devices as well as devices not known to libiphone.
+ * 
+ * @param device Upon calling this function, a pointer to a location of type
+ *  iphone_device_t, which must have the value NULL. On return, this location
+ *  will be filled with a handle to the device.
+ * @return IPHONE_E_SUCCESS if ok, otherwise an error code.
+ */
+iphone_error_t iphone_get_device(iphone_device_t *device)
+{
+    struct usb_bus *bus, *busses;
+    struct usb_device *dev;
+
+    usb_init();
+    usb_find_busses();
+    usb_find_devices();
+
+    for (bus = usb_get_busses(); bus != NULL; bus = bus->next)
+        for (dev = bus->devices; dev != NULL; dev = dev->next)
+            if (dev->descriptor.idVendor == 0x05ac
+                    && dev->descriptor.idProduct >= 0x1290
+                    && dev->descriptor.idProduct <= 0x1293)
+                return iphone_get_specific_device(bus->location, dev->devnum,
+                        device);
+
+    return IPHONE_E_NO_DEVICE;
+}
+
 /** Cleans up an iPhone structure, then frees the structure itself.  
  * This is a library-level function; deals directly with the iPhone to tear
  *  down relations, but otherwise is mostly internal.