From 5b7281bd41149f6d064b954a0071c25ed950154b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Camilla=20L=C3=B6wy?= <elmindreda@glfw.org>
Date: Sun, 23 Jul 2017 16:34:11 +0200
Subject: [PATCH] Add glfwGetJoystickGUID

This function completes the first round of support for
SDL_GameControllerDB.

Fixes #900.
---
 README.md            |  2 ++
 docs/news.dox        |  6 +++---
 include/GLFW/glfw3.h | 37 +++++++++++++++++++++++++++++++++++++
 src/input.c          | 25 +++++++++++++++++++++++++
 tests/joysticks.c    |  2 ++
 5 files changed, 69 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 0892b403..3353dacc 100644
--- a/README.md
+++ b/README.md
@@ -130,6 +130,8 @@ information on what to include when reporting a bug.
   SDL\_GameControllerDB format (#900)
 - Added `glfwJoystickIsGamepad` function for querying whether a joystick has
   a gamepad mapping (#900)
+- Added `glfwGetJoystickGUID` function for querying the SDL compatible GUID of
+  a joystick (#900)
 - Added `glfwGetGamepadName` function for querying the name provided by the
   gamepad mapping (#900)
 - Added `glfwGetGamepadState` function, `GLFW_GAMEPAD_*` and `GLFWgamepadstate`
diff --git a/docs/news.dox b/docs/news.dox
index 2d4b621d..d8bb23a5 100644
--- a/docs/news.dox
+++ b/docs/news.dox
@@ -16,9 +16,9 @@ human-readable description with @ref glfwGetError.
 @subsection news_33_gamepad SDL_GameControllerDB support and gamepad input
 
 GLFW now supports remapping of gamepads and controllers to a 360-like controller
-layout with @ref glfwJoystickIsGamepad, @ref glfwGetGamepadName, @ref
-glfwGetGamepadState and @ref glfwUpdateGamepadMappings, and the input state
-struct @ref GLFWgamepadstate.
+layout with @ref glfwJoystickIsGamepad, @ref glfwGetJoystickGUID, @ref
+glfwGetGamepadName, @ref glfwGetGamepadState and @ref glfwUpdateGamepadMappings,
+and the input state struct @ref GLFWgamepadstate.
 
 @sa @ref gamepad
 
diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h
index 83fad737..25326252 100644
--- a/include/GLFW/glfw3.h
+++ b/include/GLFW/glfw3.h
@@ -4381,6 +4381,43 @@ GLFWAPI const unsigned char* glfwGetJoystickHats(int jid, int* count);
  */
 GLFWAPI const char* glfwGetJoystickName(int jid);
 
+/*! @brief Returns the SDL comaptible GUID of the specified joystick.
+ *
+ *  This function returns the SDL compatible GUID, as a UTF-8 encoded
+ *  hexadecimal string, of the specified joystick.  The returned string is
+ *  allocated and freed by GLFW.  You should not free it yourself.
+ *
+ *  If the specified joystick is not present this function will return `NULL`
+ *  but will not generate an error.  Call @ref glfwJoystickPresent to check
+ *  device presence.
+ *
+ *  The GUID uses the format introduced in SDL 2.0.5.  This GUID tries to
+ *  uniquely identify the make and model of a joystick but does not identify
+ *  a specific unit, e.g. all wired Xbox 360 controllers will have the same
+ *  GUID on that platform.  The GUID for a unit may vary between platforms
+ *  depending on what hardware information the platform specific APIs provide.
+ *
+ *  @param[in] jid The [joystick](@ref joysticks) to query.
+ *  @return The UTF-8 encoded GUID of the joystick, or `NULL` if the joystick
+ *  is not present or an [error](@ref error_handling) occurred.
+ *
+ *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
+ *  GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
+ *
+ *  @pointer_lifetime The returned string is allocated and freed by GLFW.  You
+ *  should not free it yourself.  It is valid until the specified joystick is
+ *  disconnected or the library is terminated.
+ *
+ *  @thread_safety This function must only be called from the main thread.
+ *
+ *  @sa @ref gamepad
+ *
+ *  @since Added in version 3.3.
+ *
+ *  @ingroup input
+ */
+GLFWAPI const char* glfwGetJoystickGUID(int jid);
+
 /*! @brief Returns whether the specified joystick has a gamepad mapping.
  *
  *  This function returns whether the specified joystick is both present and has
diff --git a/src/input.c b/src/input.c
index 2a5dfef0..101b6859 100644
--- a/src/input.c
+++ b/src/input.c
@@ -896,6 +896,31 @@ GLFWAPI const char* glfwGetJoystickName(int jid)
     return js->name;
 }
 
+GLFWAPI const char* glfwGetJoystickGUID(int jid)
+{
+    _GLFWjoystick* js;
+
+    assert(jid >= GLFW_JOYSTICK_1);
+    assert(jid <= GLFW_JOYSTICK_LAST);
+
+    _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
+
+    if (jid < 0 || jid > GLFW_JOYSTICK_LAST)
+    {
+        _glfwInputError(GLFW_INVALID_ENUM, "Invalid joystick ID %i", jid);
+        return NULL;
+    }
+
+    js = _glfw.joysticks + jid;
+    if (!js->present)
+        return NULL;
+
+    if (!_glfwPlatformPollJoystick(js, _GLFW_POLL_PRESENCE))
+        return NULL;
+
+    return js->guid;
+}
+
 GLFWAPI GLFWjoystickfun glfwSetJoystickCallback(GLFWjoystickfun cbfun)
 {
     _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
diff --git a/tests/joysticks.c b/tests/joysticks.c
index 9425af78..88489d4e 100644
--- a/tests/joysticks.c
+++ b/tests/joysticks.c
@@ -228,6 +228,8 @@ int main(void)
                 GLFWgamepadstate state;
 
                 nk_layout_row_dynamic(nk, 30, 1);
+                nk_labelf(nk, NK_TEXT_LEFT, "Hardware GUID %s",
+                          glfwGetJoystickGUID(joysticks[i]));
                 nk_label(nk, "Joystick state", NK_TEXT_LEFT);
 
                 axes = glfwGetJoystickAxes(joysticks[i], &axis_count);