X-Git-Url: http://developer.intra2net.com/git/?a=blobdiff_plain;f=src%2Fftdi.c;h=096a03d50a0acf928c56b9ad51cd2527d05e27a2;hb=d77b0e94a0a6c7cbd09ecb5bd768bcb525befa21;hp=0b8b2696239fe1347532d1ff5817190f0df2215c;hpb=9bec2387b04ac85385ff019fa1a4cf7bbe9491cf;p=libftdi

diff --git a/src/ftdi.c b/src/ftdi.c
index 0b8b269..096a03d 100644
--- a/src/ftdi.c
+++ b/src/ftdi.c
@@ -14,6 +14,20 @@
  *                                                                         *
  ***************************************************************************/
 
+/**
+    \mainpage libftdi API documentation
+
+    Library to talk to FTDI chips. You find the latest versions of libftdi at
+    http://www.intra2net.com/de/produkte/opensource/ftdi/
+
+    The library is easy to use. Have a look at this short example:
+    \include simple.c
+
+    More examples can be found in the "examples" directory.
+*/
+/** \addtogroup libftdi */
+/* @{ */
+
 #include <usb.h>
 #include <string.h>
 #include <errno.h>
@@ -144,6 +158,7 @@ int ftdi_usb_find_all(struct ftdi_context *ftdi, struct ftdi_device_list **devli
         ftdi_error_return(-2, "usb_find_devices() failed");
 
     curdev = devlist;
+    *curdev = NULL;
     for (bus = usb_busses; bus; bus = bus->next) {
         for (dev = bus->devices; dev; dev = dev->next) {
             if (dev->descriptor.idVendor == vendor
@@ -172,13 +187,77 @@ int ftdi_usb_find_all(struct ftdi_context *ftdi, struct ftdi_device_list **devli
 */
 void ftdi_list_free(struct ftdi_device_list **devlist)
 {
-    struct ftdi_device_list **curdev;
-    for (; *devlist == NULL; devlist = curdev) {
-        curdev = &(*devlist)->next;
-        free(*devlist);
+    struct ftdi_device_list *curdev, *next;
+
+    for (curdev = *devlist; curdev != NULL;) {
+        next = curdev->next;
+        free(curdev);
+        curdev = next;
+    }
+
+    *devlist = NULL;
+}
+
+/**
+    Return device ID strings from the usb device.
+
+    The parameters manufacturer, description and serial may be NULL
+    or pointer to buffers to store the fetched strings.
+
+    \note Use this function only in combination with ftdi_usb_find_all()
+          as it closes the internal "usb_dev" after use.
+
+    \param ftdi pointer to ftdi_context
+    \param dev libusb usb_dev to use
+    \param manufacturer Store manufacturer string here if not NULL
+    \param mnf_len Buffer size of manufacturer string
+    \param description Store product description string here if not NULL
+    \param desc_len Buffer size of product description string
+    \param serial Store serial string here if not NULL
+    \param serial_len Buffer size of serial string
+
+    \retval   0: all fine
+    \retval  -1: wrong arguments
+    \retval  -4: unable to open device
+    \retval  -7: get product manufacturer failed
+    \retval  -8: get product description failed
+    \retval  -9: get serial number failed
+    \retval -10: unable to close device
+*/
+int ftdi_usb_get_strings(struct ftdi_context * ftdi, struct usb_device * dev,
+        char * manufacturer, int mnf_len, char * description, int desc_len, char * serial, int serial_len)
+{
+    if ((ftdi==NULL) || (dev==NULL))
+        return -1;
+
+    if (!(ftdi->usb_dev = usb_open(dev)))
+        ftdi_error_return(-4, usb_strerror());
+
+    if (manufacturer != NULL) {
+        if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iManufacturer, manufacturer, mnf_len) <= 0) {
+            usb_close (ftdi->usb_dev);
+            ftdi_error_return(-7, usb_strerror());
+        }
+    }
+
+    if (description != NULL) {
+        if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iProduct, description, desc_len) <= 0) {
+            usb_close (ftdi->usb_dev);
+            ftdi_error_return(-8, usb_strerror());
+        }
+    }
+
+    if (serial != NULL) {
+        if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iSerialNumber, serial, serial_len) <= 0) {
+            usb_close (ftdi->usb_dev);
+            ftdi_error_return(-9, usb_strerror());
+        }
     }
 
-    devlist = NULL;
+    if (usb_close (ftdi->usb_dev) != 0)
+        ftdi_error_return(-10, usb_strerror());
+
+    return 0;
 }
 
 /**
@@ -402,6 +481,7 @@ int ftdi_usb_close(struct ftdi_context *ftdi)
 /*
     ftdi_convert_baudrate returns nearest supported baud rate to that requested.
     Function is only used internally
+    \internal
 */
 static int ftdi_convert_baudrate(int baudrate, struct ftdi_context *ftdi,
                                  unsigned short *value, unsigned short *index)
@@ -661,6 +741,7 @@ int ftdi_write_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunk
     \param size Size of the buffer
 
     \retval <0: error code from usb_bulk_read()
+    \retval  0: no data was available
     \retval >0: number of bytes read
 
     \remark This function is not useful in bitbang mode.
@@ -1273,3 +1354,5 @@ int ftdi_setrts(struct ftdi_context *ftdi, int state)
 
     return 0;
 }
+
+/* @} end of doxygen libftdi group */