Add libusb_strerror() to get short error message in English from enum

[dsd: small tweaks]

diff --git a/AUTHORS b/AUTHORS
index 105f6b5..15b2049 100644 (file)
--- a/AUTHORS
+++ b/AUTHORS
@@ -10,6 +10,7 @@ Bastien Nocera
 David Engraf
 David Moore
 Felipe Balbi
+Francesco Montorsi
 Hans Ulrich Niedermann
 Ludovic Rousseau
 Martin Koegler

diff --git a/libusb/core.c b/libusb/core.c
index e1849af..efae9aa 100644 (file)
--- a/libusb/core.c
+++ b/libusb/core.c
@@ -1582,3 +1582,51 @@ void usbi_log(struct libusb_context *ctx, enum usbi_log_level level,
        fprintf(stream, "\n");
 }
 
+/** \ingroup misc
+ * Returns a constant NULL-terminated string with an English short description
+ * of the given error code. The caller should never free() the returned pointer
+ * since it points to a constant string.
+ * The returned string is encoded in ASCII form and always starts with a
+ * capital letter and ends without any punctuation.
+ * Future versions of libusb may return NULL if the library is compiled without
+ * these messages included (e.g. for embedded systems).
+ * This function is intended to be used for debugging purposes only.
+ *
+ * \param errcode the error code whose description is desired
+ * \returns a short description of the error code in English, or NULL if the
+ * error descriptions are unavailable
+ */
+API_EXPORTED const char *libusb_strerror(enum libusb_error errcode)
+{
+       switch (errcode) {
+       case LIBUSB_SUCCESS:
+               return "Success";
+       case LIBUSB_ERROR_IO:
+               return "Input/output error";
+       case LIBUSB_ERROR_INVALID_PARAM:
+               return "Invalid parameter";
+       case LIBUSB_ERROR_ACCESS:
+               return "Access denied (insufficient permissions)";
+       case LIBUSB_ERROR_NO_DEVICE:
+               return "No such device (it may have been disconnected)";
+       case LIBUSB_ERROR_NOT_FOUND:
+               return "Entity not found";
+       case LIBUSB_ERROR_BUSY:
+               return "Resource busy";
+       case LIBUSB_ERROR_TIMEOUT:
+               return "Operation timed out";
+       case LIBUSB_ERROR_OVERFLOW:
+               return "Overflow";
+       case LIBUSB_ERROR_PIPE:
+               return "Pipe error";
+       case LIBUSB_ERROR_INTERRUPTED:
+               return "System call interrupted (perhaps due to signal)";
+       case LIBUSB_ERROR_NO_MEM:
+               return "Insufficient memory";
+       case LIBUSB_ERROR_NOT_SUPPORTED:
+               return "Operation not supported or unimplemented on this platform";
+       case LIBUSB_ERROR_OTHER:
+               return "Other error";
+       }
+       return "Unknown error";
+}

diff --git a/libusb/libusb.h b/libusb/libusb.h
index 483d76a..f094a93 100644 (file)
--- a/libusb/libusb.h
+++ b/libusb/libusb.h
@@ -593,6 +593,8 @@ typedef struct libusb_device_handle libusb_device_handle;
 /** \ingroup misc
  * Error codes. Most libusb functions return 0 on success or one of these
  * codes on failure.
+ * You can use libusb_strerror() to retrieve a short string description of
+ * a libusb_error enumeration value.
  */
 enum libusb_error {
        /** Success (no error) */
@@ -636,6 +638,9 @@ enum libusb_error {
 
        /** Other error */
        LIBUSB_ERROR_OTHER = -99
+
+       /* IMPORTANT: when adding new values to this enum, remember to
+          update the libusb_strerror() function implementation! */
 };
 
 /** \ingroup asyncio
@@ -774,6 +779,7 @@ struct libusb_transfer {
 int libusb_init(libusb_context **ctx);
 void libusb_exit(libusb_context *ctx);
 void libusb_set_debug(libusb_context *ctx, int level);
+const char *libusb_strerror(enum libusb_error errcode);
 
 ssize_t libusb_get_device_list(libusb_context *ctx,
        libusb_device ***list);