Core: Make libusb_error_name also handle transfer status codes

[platform/upstream/libusb.git] / libusb / core.c

diff --git a/libusb/core.c b/libusb/core.c
index 17e2780..097870f 100644 (file)
--- a/libusb/core.c
+++ b/libusb/core.c
@@ -106,15 +106,18 @@ static struct timeval timestamp_origin = { 0, 0 };
  *
  * \section msglog Debug message logging
  *
- * libusbx does not log any messages by default. Your application is therefore
- * free to close stdout/stderr and those descriptors may be reused without
- * worry.
- *
- * The libusb_set_debug() function can be used to enable stderr logging of
- * certain messages. Under standard configuration, libusbx doesn't really
- * log much at all, so you are advised to use this function to enable all
- * error/warning/informational messages. It will help you debug problems with
- * your software.
+ * libusbx uses stderr for all logging. By default, logging is set to NONE,
+ * which means that no output will be produced. However, unless the library
+ * has been compiled with logging disabled, then any application calls to
+ * libusb_set_debug(), or the setting of the environmental variable
+ * LIBUSB_DEBUG outside of the application, can result in logging being
+ * produced. Your application should therefore not close stderr, but instead
+ * direct it to the null device if its output is undesireable.
+ *
+ * The libusb_set_debug() function can be used to enable logging of certain
+ * messages. Under standard configuration, libusbx doesn't really log much
+ * so you are advised to use this function to enable all error/warning/
+ * informational messages. It will help debug problems with your software.
  *
  * The logged messages are unstructured. There is no one-to-one correspondence
  * between messages being logged and success or failure return codes from
@@ -137,10 +140,10 @@ static struct timeval timestamp_origin = { 0, 0 };
  * systems. In this case, libusb_set_debug() and the LIBUSB_DEBUG environment
  * variable have no effects.
  *
- * libusbx can also be compiled with verbose debugging messages. When the
- * library is compiled in this way, all messages of all verbosities are always
- * logged.  libusb_set_debug() and the LIBUSB_DEBUG environment variable have
- * no effects.
+ * libusbx can also be compiled with verbose debugging messages always. When
+ * the library is compiled in this way, all messages of all verbosities are
+ * always logged. libusb_set_debug() and the LIBUSB_DEBUG environment variable
+ * have no effects.
  *
  * \section remarks Other remarks
  *
@@ -1512,6 +1515,10 @@ int API_EXPORTED libusb_kernel_driver_active(libusb_device_handle *dev,
  *
  * This functionality is not available on Darwin or Windows.
  *
+ * Note that libusbx itself also talks to the device through a special kernel
+ * driver, if this driver is already attached to the device, this call will
+ * not detach it and return LIBUSB_ERROR_NOT_FOUND.
+ *
  * \param dev a device handle
  * \param interface_number the interface to detach the driver from
  * \returns 0 on success
@@ -1874,17 +1881,17 @@ void usbi_log(struct libusb_context *ctx, enum libusb_log_level level,
 
 /** \ingroup misc
  * Returns a constant NULL-terminated string with the ASCII name of a libusb
- * error code. The caller must not free() the returned string.
+ * error or transfer status code. The caller must not free() the returned
+ * string.
  *
- * \param error_code The \ref libusb_error code to return the name of.
+ * \param error_code The \ref libusb_error or libusb_transfer_status code to
+ * return the name of.
  * \returns The error name, or the string **UNKNOWN** if the value of
- * error_code is not a known error code.
+ * error_code is not a known error / status code.
  */
 DEFAULT_VISIBILITY const char * LIBUSB_CALL libusb_error_name(int error_code)
 {
        switch (error_code) {
-       case LIBUSB_SUCCESS:
-               return "LIBUSB_SUCCESS";
        case LIBUSB_ERROR_IO:
                return "LIBUSB_ERROR_IO";
        case LIBUSB_ERROR_INVALID_PARAM:
@@ -1911,6 +1918,22 @@ DEFAULT_VISIBILITY const char * LIBUSB_CALL libusb_error_name(int error_code)
                return "LIBUSB_ERROR_NOT_SUPPORTED";
        case LIBUSB_ERROR_OTHER:
                return "LIBUSB_ERROR_OTHER";
+
+       case LIBUSB_TRANSFER_ERROR:
+               return "LIBUSB_TRANSFER_ERROR";
+       case LIBUSB_TRANSFER_TIMED_OUT:
+               return "LIBUSB_TRANSFER_TIMED_OUT";
+       case LIBUSB_TRANSFER_CANCELLED:
+               return "LIBUSB_TRANSFER_CANCELLED";
+       case LIBUSB_TRANSFER_STALL:
+               return "LIBUSB_TRANSFER_STALL";
+       case LIBUSB_TRANSFER_NO_DEVICE:
+               return "LIBUSB_TRANSFER_NO_DEVICE";
+       case LIBUSB_TRANSFER_OVERFLOW:
+               return "LIBUSB_TRANSFER_OVERFLOW";
+
+       case 0:
+               return "LIBUSB_SUCCESS / LIBUSB_TRANSFER_COMPLETED";
        default:
                return "**UNKNOWN**";
        }