add rc_client_get_user_agent_clause (#307)

include/rc_client.h

@@ -136,6 +136,11 @@ RC_EXPORT void RC_CCONV rc_client_set_get_time_millisecs_function(rc_client_t* c
  */
 RC_EXPORT void RC_CCONV rc_client_abort_async(rc_client_t* client, rc_client_async_handle_t* async_handle);
 
+/**
+ * Gets a clause that can be added to the User-Agent to identify the version of rcheevos being used.
+ */
+RC_EXPORT size_t RC_CCONV rc_client_get_user_agent_clause(rc_client_t* client, char buffer[], size_t buffer_size);
+
 /*****************************************************************************\
 | Logging                                                                     |
 \*****************************************************************************/

src/rc_client.c

@@ -5,6 +5,7 @@
 #include "rc_api_user.h"
 #include "rc_consoles.h"
 #include "rc_hash.h"
+#include "rc_version.h"
 
 #include "rapi/rc_api_common.h"
 
@@ -5592,3 +5593,28 @@ void rc_client_set_host(const rc_client_t* client, const char* hostname)
     client->state.external_client->set_host(hostname);
 #endif
 }
+
+size_t rc_client_get_user_agent_clause(rc_client_t* client, char buffer[], size_t buffer_size)
+{
+  size_t result;
+
+#ifdef RC_CLIENT_SUPPORTS_EXTERNAL
+  if (client && client->state.external_client && client->state.external_client->get_user_agent_clause) {
+    result = client->state.external_client->get_user_agent_clause(buffer, buffer_size);
+    if (result > 0) {
+      result += snprintf(buffer + result, buffer_size - result, " rc_client/" RCHEEVOS_VERSION_STRING);
+      buffer[buffer_size - 1] = '\0';
+      return result;
+    }
+  }
+#else
+  (void)client;
+#endif
+
+  result = snprintf(buffer, buffer_size, "rcheevos/" RCHEEVOS_VERSION_STRING);
+
+  /* some implementations of snprintf will fill the buffer without null terminating.
+   * make sure the buffer is null terminated */
+  buffer[buffer_size - 1] = '\0';
+  return result;
+}

src/rc_client_external.h

@@ -73,6 +73,7 @@ typedef struct rc_client_external_t
   rc_client_external_set_read_memory_func_t set_read_memory;
   rc_client_external_set_get_time_millisecs_func_t set_get_time_millisecs;
   rc_client_external_set_string_func_t set_host;
+  rc_client_external_copy_string_func_t get_user_agent_clause;
 
   rc_client_external_set_int_func_t set_hardcore_enabled;
   rc_client_external_get_int_func_t get_hardcore_enabled;

test/test_rc_client.c

@@ -8414,6 +8414,23 @@ static void test_set_encore_mode_disable(void)
   rc_client_destroy(g_client);
 }
 
+static void test_get_user_agent_clause(void)
+{
+  char expected_clause[] = "rcheevos/" RCHEEVOS_VERSION_STRING;
+  char buffer[64];
+
+  g_client = mock_client_not_logged_in();
+  ASSERT_NUM_EQUALS(rc_client_get_user_agent_clause(g_client, buffer, sizeof(buffer)), sizeof(expected_clause) - 1);
+  ASSERT_STR_EQUALS(buffer, expected_clause);
+
+  /* snprintf will return the number of characters it wants, even if the buffer is too small,
+   * but will only fill as much of the buffer is available */
+  ASSERT_NUM_EQUALS(rc_client_get_user_agent_clause(g_client, buffer, 8), sizeof(expected_clause) - 1);
+  ASSERT_STR_EQUALS(buffer, "rcheevo");
+
+  rc_client_destroy(g_client);
+}
+
 /* ----- harness ----- */
 
 void test_client(void) {
@@ -8618,5 +8635,7 @@ void test_client(void) {
   TEST(test_set_encore_mode_enable);
   TEST(test_set_encore_mode_disable);
 
+  TEST(test_get_user_agent_clause);
+
   TEST_SUITE_END();
 }

test/test_rc_client_external.c

@@ -1,6 +1,7 @@
 #include "rc_client.h"
 
 #include "../src/rc_client_internal.h"
+#include "../src/rc_version.h"
 #include "rc_consoles.h"
 #include "rhash/data.h"
 
@@ -267,6 +268,33 @@ static void test_set_host(void)
   rc_client_destroy(g_client);
 }
 
+static size_t rc_client_external_get_user_agent_clause(char buffer[], size_t buffer_size)
+{
+  return snprintf(buffer, buffer_size, "external/2.1");
+}
+
+static void test_get_user_agent_clause(void)
+{
+  char expected_clause[] = "external/2.1 rc_client/" RCHEEVOS_VERSION_STRING;
+  char buffer[64];
+
+  g_client = mock_client_with_external();
+  g_client->state.external_client->get_user_agent_clause = rc_client_external_get_user_agent_clause;
+
+  ASSERT_NUM_EQUALS(rc_client_get_user_agent_clause(g_client, buffer, sizeof(buffer)), sizeof(expected_clause) - 1);
+  ASSERT_STR_EQUALS(buffer, expected_clause);
+
+  /* snprintf will return the number of characters it wants, even if the buffer is too small,
+   * but will only fill as much of the buffer is available */
+  ASSERT_NUM_EQUALS(rc_client_get_user_agent_clause(g_client, buffer, 8), sizeof(expected_clause) - 1);
+  ASSERT_STR_EQUALS(buffer, "externa");
+
+  ASSERT_NUM_EQUALS(rc_client_get_user_agent_clause(g_client, buffer, 20), sizeof(expected_clause) - 1);
+  ASSERT_STR_EQUALS(buffer, "external/2.1 rc_cli");
+
+  rc_client_destroy(g_client);
+}
+
 /* ----- login ----- */
 
 typedef struct v1_rc_client_user_t {
@@ -1176,6 +1204,7 @@ void test_client_external(void) {
   TEST(test_read_memory);
   TEST(test_get_time_millisecs);
   TEST(test_set_host);
+  TEST(test_get_user_agent_clause);
 
   /* login */
   TEST(test_login_with_password);