1
#ifndef RC_CLIENT_H
2
#define RC_CLIENT_H
3

4
#include "rc_api_request.h"
5
#include "rc_error.h"
6

7
#include <stddef.h>
8
#include <stdint.h>
9
#include <time.h>
10

11
RC_BEGIN_C_DECLS
12

13
/* implementation abstracted in rc_client_internal.h */
14
typedef struct rc_client_t rc_client_t;
15
typedef struct rc_client_async_handle_t rc_client_async_handle_t;
16

17
/*****************************************************************************\
18
| Callbacks                                                                   |
19
\*****************************************************************************/
20

21
/**
22
 * Callback used to read num_bytes bytes from memory starting at address into buffer.
23
 * Returns the number of bytes read. A return value of 0 indicates the address was invalid.
24
 */
25
typedef uint32_t (RC_CCONV *rc_client_read_memory_func_t)(uint32_t address, uint8_t* buffer, uint32_t num_bytes, rc_client_t* client);
26

27
/**
28
 * Internal method passed to rc_client_server_call_t to process the server response.
29
 */
30
typedef void (RC_CCONV *rc_client_server_callback_t)(const rc_api_server_response_t* server_response, void* callback_data);
31

32
/**
33
 * Callback used to issue a request to the server.
34
 */
35
typedef void (RC_CCONV *rc_client_server_call_t)(const rc_api_request_t* request, rc_client_server_callback_t callback, void* callback_data, rc_client_t* client);
36

37
/**
38
 * Generic callback for asynchronous eventing.
39
 */
40
typedef void (RC_CCONV *rc_client_callback_t)(int result, const char* error_message, rc_client_t* client, void* userdata);
41

42
/**
43
 * Callback for logging or displaying a message.
44
 */
45
typedef void (RC_CCONV *rc_client_message_callback_t)(const char* message, const rc_client_t* client);
46

47
/*****************************************************************************\
48
| Runtime                                                                     |
49
\*****************************************************************************/
50

51
/**
52
 * Creates a new rc_client_t object.
53
 */
54
RC_EXPORT rc_client_t* RC_CCONV rc_client_create(rc_client_read_memory_func_t read_memory_function, rc_client_server_call_t server_call_function);
55

56
/**
57
 * Releases resources associated to a rc_client_t object.
58
 * Pointer will no longer be valid after making this call.
59
 */
60
RC_EXPORT void RC_CCONV rc_client_destroy(rc_client_t* client);
61

62
/**
63
 * Sets whether hardcore is enabled (on by default).
64
 * Can be called with a game loaded.
65
 * Enabling hardcore with a game loaded will raise an RC_CLIENT_EVENT_RESET
66
 * event. Processing will be disabled until rc_client_reset is called.
67
 */
68
RC_EXPORT void RC_CCONV rc_client_set_hardcore_enabled(rc_client_t* client, int enabled);
69

70
/**
71
 * Gets whether hardcore is enabled (on by default).
72
 */
73
RC_EXPORT int RC_CCONV rc_client_get_hardcore_enabled(const rc_client_t* client);
74

75
/**
76
 * Sets whether encore mode is enabled (off by default).
77
 * Evaluated when loading a game. Has no effect while a game is loaded.
78
 */
79
RC_EXPORT void RC_CCONV rc_client_set_encore_mode_enabled(rc_client_t* client, int enabled);
80

81
/**
82
 * Gets whether encore mode is enabled (off by default).
83
 */
84
RC_EXPORT int RC_CCONV rc_client_get_encore_mode_enabled(const rc_client_t* client);
85

86
/**
87
 * Sets whether unofficial achievements should be loaded.
88
 * Evaluated when loading a game. Has no effect while a game is loaded.
89
 */
90
RC_EXPORT void RC_CCONV rc_client_set_unofficial_enabled(rc_client_t* client, int enabled);
91

92
/**
93
 * Gets whether unofficial achievements should be loaded.
94
 */
95
RC_EXPORT int RC_CCONV rc_client_get_unofficial_enabled(const rc_client_t* client);
96

97
/**
98
 * Sets whether spectator mode is enabled (off by default).
99
 * If enabled, events for achievement unlocks and leaderboard submissions will be
100
 * raised, but server calls to actually perform the unlock/submit will not occur.
101
 * Can be modified while a game is loaded. Evaluated at unlock/submit time.
102
 * Cannot be modified if disabled before a game is loaded.
103
 */
104
RC_EXPORT void RC_CCONV rc_client_set_spectator_mode_enabled(rc_client_t* client, int enabled);
105

106
/**
107
 * Gets whether spectator mode is enabled (off by default).
108
 */
109
RC_EXPORT int RC_CCONV rc_client_get_spectator_mode_enabled(const rc_client_t* client);
110

111
/**
112
 * Attaches client-specific data to the runtime.
113
 */
114
RC_EXPORT void RC_CCONV rc_client_set_userdata(rc_client_t* client, void* userdata);
115

116
/**
117
 * Gets the client-specific data attached to the runtime.
118
 */
119
RC_EXPORT void* RC_CCONV rc_client_get_userdata(const rc_client_t* client);
120

121
/**
122
 * Sets the name of the server to use.
123
 */
124
RC_EXPORT void RC_CCONV rc_client_set_host(rc_client_t* client, const char* hostname);
125

126
typedef uint64_t rc_clock_t;
127
typedef rc_clock_t (RC_CCONV *rc_get_time_millisecs_func_t)(const rc_client_t* client);
128

129
/**
130
 * Specifies a function that returns a value that increases once per millisecond.
131
 */
132
RC_EXPORT void RC_CCONV rc_client_set_get_time_millisecs_function(rc_client_t* client, rc_get_time_millisecs_func_t handler);
133

134
/**
135
 * Marks an async process as aborted. The associated callback will not be called.
136
 */
137
RC_EXPORT void RC_CCONV rc_client_abort_async(rc_client_t* client, rc_client_async_handle_t* async_handle);
138

139
/**
140
 * Gets a clause that can be added to the User-Agent to identify the version of rcheevos being used.
141
 */
142
RC_EXPORT size_t RC_CCONV rc_client_get_user_agent_clause(rc_client_t* client, char buffer[], size_t buffer_size);
143

144
/**
145
 * Returns true if any achievement submissions have failed and are currently pending.
146
 */
147
RC_EXPORT int RC_CCONV rc_client_is_disconnected(rc_client_t* client);
148

149
/*****************************************************************************\
150
| Logging                                                                     |
151
\*****************************************************************************/
152

153
/**
154
 * Sets the logging level and provides a callback to be called to do the logging.
155
 */
156
RC_EXPORT void RC_CCONV rc_client_enable_logging(rc_client_t* client, int level, rc_client_message_callback_t callback);
157
enum {
158
  RC_CLIENT_LOG_LEVEL_NONE = 0,
159
  RC_CLIENT_LOG_LEVEL_ERROR = 1,
160
  RC_CLIENT_LOG_LEVEL_WARN = 2,
161
  RC_CLIENT_LOG_LEVEL_INFO = 3,
162
  RC_CLIENT_LOG_LEVEL_VERBOSE = 4,
163
  NUM_RC_CLIENT_LOG_LEVELS = 5
164
};
165

166
/*****************************************************************************\
167
| User                                                                        |
168
\*****************************************************************************/
169

170
/**
171
 * Attempt to login a user.
172
 */
173
RC_EXPORT rc_client_async_handle_t* RC_CCONV rc_client_begin_login_with_password(rc_client_t* client,
174
    const char* username, const char* password,
175
    rc_client_callback_t callback, void* callback_userdata);
176

177
/**
178
 * Attempt to login a user.
179
 */
180
RC_EXPORT rc_client_async_handle_t* RC_CCONV rc_client_begin_login_with_token(rc_client_t* client,
181
    const char* username, const char* token,
182
    rc_client_callback_t callback, void* callback_userdata);
183

184
/**
185
 * Logout the user.
186
 */
187
RC_EXPORT void RC_CCONV rc_client_logout(rc_client_t* client);
188

189
typedef struct rc_client_user_t {
190
  const char* display_name;
191
  const char* username;
192
  const char* token;
193
  uint32_t score;
194
  uint32_t score_softcore;
195
  uint32_t num_unread_messages;
196
  /* minimum version: 12.0 */
197
  const char* avatar_url;
198
} rc_client_user_t;
199

200
/**
201
 * Gets information about the logged in user. Will return NULL if the user is not logged in.
202
 */
203
RC_EXPORT const rc_client_user_t* RC_CCONV rc_client_get_user_info(const rc_client_t* client);
204

205
/**
206
 * Gets the URL for the user's profile picture.
207
 * Returns RC_OK on success.
208
 */
209
RC_EXPORT int RC_CCONV rc_client_user_get_image_url(const rc_client_user_t* user, char buffer[], size_t buffer_size);
210

211
typedef struct rc_client_user_game_summary_t {
212
  uint32_t num_core_achievements;
213
  uint32_t num_unofficial_achievements;
214
  uint32_t num_unlocked_achievements;
215
  uint32_t num_unsupported_achievements;
216

217
  uint32_t points_core;
218
  uint32_t points_unlocked;
219

220
  /* minimum version: 12.1 */
221
  time_t beaten_time;
222
  time_t completed_time;
223
} rc_client_user_game_summary_t;
224

225
/**
226
 * Gets a breakdown of the number of achievements in the game, and how many the user has unlocked.
227
 * Used for the "You have unlocked X of Y achievements" message shown when the game starts.
228
 */
229
RC_EXPORT void RC_CCONV rc_client_get_user_game_summary(const rc_client_t* client, rc_client_user_game_summary_t* summary);
230

231
typedef struct rc_client_all_user_progress_entry_t {
232
  uint32_t game_id;
233
  uint32_t num_achievements;
234
  uint32_t num_unlocked_achievements;
235
  uint32_t num_unlocked_achievements_hardcore;
236
} rc_client_all_user_progress_entry_t;
237

238
typedef struct rc_client_all_user_progress_t {
239
  rc_client_all_user_progress_entry_t* entries;
240
  uint32_t num_entries;
241
} rc_client_all_user_progress_t;
242

243
/**
244
 * Callback that is fired when an all progress query completes. list may be null if the query failed.
245
 */
246
typedef void(RC_CCONV* rc_client_fetch_all_user_progress_callback_t)(int result, const char* error_message,
247
                                                                     rc_client_all_user_progress_t* list,
248
                                                                     rc_client_t* client, void* callback_userdata);
249

250
/**
251
 * Starts an asynchronous request for all progress for the given console.
252
 * This query returns the total number of achievements for all games tracked by this console, as well as
253
 * the user's achievement unlock count for both softcore and hardcore modes.
254
 */
255
RC_EXPORT rc_client_async_handle_t* RC_CCONV
256
rc_client_begin_fetch_all_user_progress(rc_client_t* client, uint32_t console_id,
257
                                        rc_client_fetch_all_user_progress_callback_t callback, void* callback_userdata);
258

259
/**
260
 * Destroys a previously-allocated result from the rc_client_begin_fetch_all_progress_list() callback.
261
 */
262
RC_EXPORT void RC_CCONV rc_client_destroy_all_user_progress(rc_client_all_user_progress_t* list);
263

264
/*****************************************************************************\
265
| Game                                                                        |
266
\*****************************************************************************/
267

268
#ifdef RC_CLIENT_SUPPORTS_HASH
269
/**
270
 * Start loading an unidentified game.
271
 */
272
RC_EXPORT rc_client_async_handle_t* RC_CCONV rc_client_begin_identify_and_load_game(rc_client_t* client,
273
    uint32_t console_id, const char* file_path,
274
    const uint8_t* data, size_t data_size,
275
    rc_client_callback_t callback, void* callback_userdata);
276

277
struct rc_hash_callbacks;
278
/**
279
 * Provide callback functions for interacting with the file system and processing disc-based files when generating hashes.
280
 */
281
RC_EXPORT void rc_client_set_hash_callbacks(rc_client_t* client, const struct rc_hash_callbacks* callbacks);
282
#endif
283

284
/**
285
 * Start loading a game.
286
 */
287
RC_EXPORT rc_client_async_handle_t* RC_CCONV rc_client_begin_load_game(rc_client_t* client, const char* hash,
288
    rc_client_callback_t callback, void* callback_userdata);
289

290
/**
291
 * Gets the current progress of the asynchronous load game process.
292
 */
293
RC_EXPORT int RC_CCONV rc_client_get_load_game_state(const rc_client_t* client);
294
enum {
295
  RC_CLIENT_LOAD_GAME_STATE_NONE,
296
  RC_CLIENT_LOAD_GAME_STATE_AWAIT_LOGIN,
297
  RC_CLIENT_LOAD_GAME_STATE_IDENTIFYING_GAME,
298
  RC_CLIENT_LOAD_GAME_STATE_FETCHING_GAME_DATA, /* [deprecated] - game data is now returned by identify call */
299
  RC_CLIENT_LOAD_GAME_STATE_STARTING_SESSION,
300
  RC_CLIENT_LOAD_GAME_STATE_DONE,
301
  RC_CLIENT_LOAD_GAME_STATE_ABORTED
302
};
303

304
/**
305
 * Determines if a game was successfully identified and loaded.
306
 */
307
RC_EXPORT int RC_CCONV rc_client_is_game_loaded(const rc_client_t* client);
308

309
/**
310
 * Unloads the current game.
311
 */
312
RC_EXPORT void RC_CCONV rc_client_unload_game(rc_client_t* client);
313

314
typedef struct rc_client_game_t {
315
  uint32_t id;
316
  uint32_t console_id;
317
  const char* title;
318
  const char* hash;
319
  const char* badge_name;
320
  /* minimum version: 12.0 */
321
  const char* badge_url;
322
} rc_client_game_t;
323

324
/**
325
 * Get information about the current game. Returns NULL if no game is loaded.
326
 * NOTE: returns a dummy game record if an unidentified game is loaded.
327
 */
328
RC_EXPORT const rc_client_game_t* RC_CCONV rc_client_get_game_info(const rc_client_t* client);
329

330
/**
331
 * Gets the URL for the game image.
332
 * Returns RC_OK on success.
333
 */
334
RC_EXPORT int RC_CCONV rc_client_game_get_image_url(const rc_client_game_t* game, char buffer[], size_t buffer_size);
335

336
#ifdef RC_CLIENT_SUPPORTS_HASH
337
/**
338
 * Changes the active disc in a multi-disc game.
339
 */
340
RC_EXPORT rc_client_async_handle_t* RC_CCONV rc_client_begin_identify_and_change_media(rc_client_t* client, const char* file_path,
341
    const uint8_t* data, size_t data_size, rc_client_callback_t callback, void* callback_userdata);
342
#endif
343

344
/**
345
 * Changes the active disc in a multi-disc game.
346
 */
347
RC_EXPORT rc_client_async_handle_t* RC_CCONV rc_client_begin_change_media(rc_client_t* client, const char* hash,
348
    rc_client_callback_t callback, void* callback_userdata);
349
/* this function was renamed in rcheevos 12.0 */
350
#define rc_client_begin_change_media_from_hash rc_client_begin_change_media
351

352
/*****************************************************************************\
353
| Subsets                                                                     |
354
\*****************************************************************************/
355

356
typedef struct rc_client_subset_t {
357
  uint32_t id;
358
  const char* title;
359
  char badge_name[16];
360

361
  uint32_t num_achievements;
362
  uint32_t num_leaderboards;
363

364
  /* minimum version: 12.0 */
365
  const char* badge_url;
366
} rc_client_subset_t;
367

368
RC_EXPORT const rc_client_subset_t* RC_CCONV rc_client_get_subset_info(rc_client_t* client, uint32_t subset_id);
369

370
RC_EXPORT void RC_CCONV rc_client_get_user_subset_summary(const rc_client_t* client, uint32_t subset_id, rc_client_user_game_summary_t* summary);
371

372
/*****************************************************************************\
373
| Fetch Game Hashes                                                           |
374
\*****************************************************************************/
375

376
typedef struct rc_client_hash_library_entry_t {
377
  char hash[33];
378
  uint32_t game_id;
379
} rc_client_hash_library_entry_t;
380

381
typedef struct rc_client_hash_library_t {
382
  rc_client_hash_library_entry_t* entries;
383
  uint32_t num_entries;
384
} rc_client_hash_library_t;
385

386
/**
387
 * Callback that is fired when a hash library request completes. list may be null if the query failed.
388
 */
389
typedef void(RC_CCONV* rc_client_fetch_hash_library_callback_t)(int result, const char* error_message,
390
                                                                rc_client_hash_library_t* list, rc_client_t* client,
391
                                                                void* callback_userdata);
392

393
/**
394
 * Starts an asynchronous request for all hashes for the given console.
395
 * This request returns a mapping from hashes to the game's unique identifier. A single game may have multiple
396
 * hashes in the case of multi-disc games, or variants that are still compatible with the same achievement set.
397
 */
398
RC_EXPORT rc_client_async_handle_t* RC_CCONV rc_client_begin_fetch_hash_library(
399
  rc_client_t* client, uint32_t console_id, rc_client_fetch_hash_library_callback_t callback, void* callback_userdata);
400

401
/**
402
 * Destroys a previously-allocated result from the rc_client_destroy_hash_library() callback.
403
 */
404
RC_EXPORT void RC_CCONV rc_client_destroy_hash_library(rc_client_hash_library_t* list);
405

406
/*****************************************************************************\
407
| Achievements                                                                |
408
\*****************************************************************************/
409

410
enum {
411
  RC_CLIENT_ACHIEVEMENT_STATE_INACTIVE = 0, /* unprocessed */
412
  RC_CLIENT_ACHIEVEMENT_STATE_ACTIVE = 1,   /* eligible to trigger */
413
  RC_CLIENT_ACHIEVEMENT_STATE_UNLOCKED = 2, /* earned by user */
414
  RC_CLIENT_ACHIEVEMENT_STATE_DISABLED = 3, /* not supported by this version of the runtime */
415
  NUM_RC_CLIENT_ACHIEVEMENT_STATES = 4
416
};
417

418
enum {
419
  RC_CLIENT_ACHIEVEMENT_CATEGORY_NONE = 0,
420
  RC_CLIENT_ACHIEVEMENT_CATEGORY_CORE = (1 << 0),
421
  RC_CLIENT_ACHIEVEMENT_CATEGORY_UNOFFICIAL = (1 << 1),
422
  RC_CLIENT_ACHIEVEMENT_CATEGORY_CORE_AND_UNOFFICIAL = RC_CLIENT_ACHIEVEMENT_CATEGORY_CORE | RC_CLIENT_ACHIEVEMENT_CATEGORY_UNOFFICIAL
423
};
424

425
enum {
426
  RC_CLIENT_ACHIEVEMENT_TYPE_STANDARD = 0,
427
  RC_CLIENT_ACHIEVEMENT_TYPE_MISSABLE = 1,
428
  RC_CLIENT_ACHIEVEMENT_TYPE_PROGRESSION = 2,
429
  RC_CLIENT_ACHIEVEMENT_TYPE_WIN = 3
430
};
431

432
enum {
433
  RC_CLIENT_ACHIEVEMENT_BUCKET_UNKNOWN = 0,
434
  RC_CLIENT_ACHIEVEMENT_BUCKET_LOCKED = 1,
435
  RC_CLIENT_ACHIEVEMENT_BUCKET_UNLOCKED = 2,
436
  RC_CLIENT_ACHIEVEMENT_BUCKET_UNSUPPORTED = 3,
437
  RC_CLIENT_ACHIEVEMENT_BUCKET_UNOFFICIAL = 4,
438
  RC_CLIENT_ACHIEVEMENT_BUCKET_RECENTLY_UNLOCKED = 5,
439
  RC_CLIENT_ACHIEVEMENT_BUCKET_ACTIVE_CHALLENGE = 6,
440
  RC_CLIENT_ACHIEVEMENT_BUCKET_ALMOST_THERE = 7,
441
  RC_CLIENT_ACHIEVEMENT_BUCKET_UNSYNCED = 8,
442
  NUM_RC_CLIENT_ACHIEVEMENT_BUCKETS = 9
443
};
444

445
enum {
446
  RC_CLIENT_ACHIEVEMENT_UNLOCKED_NONE = 0,
447
  RC_CLIENT_ACHIEVEMENT_UNLOCKED_SOFTCORE = (1 << 0),
448
  RC_CLIENT_ACHIEVEMENT_UNLOCKED_HARDCORE = (1 << 1),
449
  RC_CLIENT_ACHIEVEMENT_UNLOCKED_BOTH = RC_CLIENT_ACHIEVEMENT_UNLOCKED_SOFTCORE | RC_CLIENT_ACHIEVEMENT_UNLOCKED_HARDCORE
450
};
451

452
typedef struct rc_client_achievement_t {
453
  const char* title;
454
  const char* description;
455
  char badge_name[8];
456
  char measured_progress[24];
457
  float measured_percent;
458
  uint32_t id;
459
  uint32_t points;
460
  time_t unlock_time;
461
  uint8_t state;
462
  uint8_t category;
463
  uint8_t bucket;
464
  uint8_t unlocked;
465
  /* minimum version: 11.1 */
466
  float rarity;
467
  float rarity_hardcore;
468
  uint8_t type;
469
  /* minimum version: 12.0 */
470
  const char* badge_url;
471
  const char* badge_locked_url;
472
} rc_client_achievement_t;
473

474
/**
475
 * Get information about an achievement. Returns NULL if not found.
476
 */
477
RC_EXPORT const rc_client_achievement_t* RC_CCONV rc_client_get_achievement_info(rc_client_t* client, uint32_t id);
478

479
/**
480
 * Gets the URL for the achievement image.
481
 * Returns RC_OK on success.
482
 */
483
RC_EXPORT int RC_CCONV rc_client_achievement_get_image_url(const rc_client_achievement_t* achievement, int state, char buffer[], size_t buffer_size);
484

485
typedef struct rc_client_achievement_bucket_t {
486
  const rc_client_achievement_t** achievements;
487
  uint32_t num_achievements;
488

489
  const char* label;
490
  uint32_t subset_id;
491
  uint8_t bucket_type;
492
} rc_client_achievement_bucket_t;
493

494
typedef struct rc_client_achievement_list_t {
495
  const rc_client_achievement_bucket_t* buckets;
496
  uint32_t num_buckets;
497
} rc_client_achievement_list_t;
498

499
enum {
500
  RC_CLIENT_ACHIEVEMENT_LIST_GROUPING_LOCK_STATE = 0,
501
  RC_CLIENT_ACHIEVEMENT_LIST_GROUPING_PROGRESS = 1
502
};
503

504
/**
505
 * Creates a list of achievements matching the specified category and grouping.
506
 * Returns an allocated list that must be free'd by calling rc_client_destroy_achievement_list.
507
 */
508
RC_EXPORT rc_client_achievement_list_t* RC_CCONV rc_client_create_achievement_list(rc_client_t* client, int category, int grouping);
509

510
/**
511
 * Destroys a list allocated by rc_client_get_achievement_list.
512
 */
513
RC_EXPORT void RC_CCONV rc_client_destroy_achievement_list(rc_client_achievement_list_t* list);
514

515
/**
516
 * Returns non-zero if there are any achievements that can be queried through rc_client_create_achievement_list().
517
 */
518
RC_EXPORT int RC_CCONV rc_client_has_achievements(rc_client_t* client);
519

520
/**
521
 * Returns the number of outstanding achievement unlocks.
522
 */
523
RC_EXPORT int RC_CCONV rc_client_get_award_achievement_pending_count(rc_client_t* client);
524

525
/*****************************************************************************\
526
| Leaderboards                                                                |
527
\*****************************************************************************/
528

529
enum {
530
  RC_CLIENT_LEADERBOARD_STATE_INACTIVE = 0,
531
  RC_CLIENT_LEADERBOARD_STATE_ACTIVE = 1,
532
  RC_CLIENT_LEADERBOARD_STATE_TRACKING = 2,
533
  RC_CLIENT_LEADERBOARD_STATE_DISABLED = 3,
534
  NUM_RC_CLIENT_LEADERBOARD_STATES = 4
535
};
536

537
enum {
538
  RC_CLIENT_LEADERBOARD_FORMAT_TIME = 0,
539
  RC_CLIENT_LEADERBOARD_FORMAT_SCORE = 1,
540
  RC_CLIENT_LEADERBOARD_FORMAT_VALUE = 2,
541
  NUM_RC_CLIENT_LEADERBOARD_FORMATS = 3
542
};
543

544
#define RC_CLIENT_LEADERBOARD_DISPLAY_SIZE 24
545

546
typedef struct rc_client_leaderboard_t {
547
  const char* title;
548
  const char* description;
549
  const char* tracker_value;
550
  uint32_t id;
551
  uint8_t state;
552
  uint8_t format;
553
  uint8_t lower_is_better;
554
} rc_client_leaderboard_t;
555

556
/**
557
 * Get information about a leaderboard. Returns NULL if not found.
558
 */
559
RC_EXPORT const rc_client_leaderboard_t* RC_CCONV rc_client_get_leaderboard_info(const rc_client_t* client, uint32_t id);
560

561
typedef struct rc_client_leaderboard_tracker_t {
562
  char display[RC_CLIENT_LEADERBOARD_DISPLAY_SIZE];
563
  uint32_t id;
564
} rc_client_leaderboard_tracker_t;
565

566
typedef struct rc_client_leaderboard_bucket_t {
567
  const rc_client_leaderboard_t** leaderboards;
568
  uint32_t num_leaderboards;
569

570
  const char* label;
571
  uint32_t subset_id;
572
  uint8_t bucket_type;
573
} rc_client_leaderboard_bucket_t;
574

575
typedef struct rc_client_leaderboard_list_t {
576
  const rc_client_leaderboard_bucket_t* buckets;
577
  uint32_t num_buckets;
578
} rc_client_leaderboard_list_t;
579

580
enum {
581
  RC_CLIENT_LEADERBOARD_BUCKET_UNKNOWN = 0,
582
  RC_CLIENT_LEADERBOARD_BUCKET_INACTIVE = 1,
583
  RC_CLIENT_LEADERBOARD_BUCKET_ACTIVE = 2,
584
  RC_CLIENT_LEADERBOARD_BUCKET_UNSUPPORTED = 3,
585
  RC_CLIENT_LEADERBOARD_BUCKET_ALL = 4,
586
  NUM_RC_CLIENT_LEADERBOARD_BUCKETS = 5
587
};
588

589
enum {
590
  RC_CLIENT_LEADERBOARD_LIST_GROUPING_NONE = 0,
591
  RC_CLIENT_LEADERBOARD_LIST_GROUPING_TRACKING = 1
592
};
593

594
/**
595
 * Creates a list of leaderboards matching the specified grouping.
596
 * Returns an allocated list that must be free'd by calling rc_client_destroy_leaderboard_list.
597
 */
598
RC_EXPORT rc_client_leaderboard_list_t* RC_CCONV rc_client_create_leaderboard_list(rc_client_t* client, int grouping);
599

600
/**
601
 * Destroys a list allocated by rc_client_create_leaderboard_list.
602
 */
603
RC_EXPORT void RC_CCONV rc_client_destroy_leaderboard_list(rc_client_leaderboard_list_t* list);
604

605
/**
606
 * Returns non-zero if the current game has any leaderboards.
607
 */
608
RC_EXPORT int RC_CCONV rc_client_has_leaderboards(rc_client_t* client, int include_hidden);
609

610
typedef struct rc_client_leaderboard_entry_t {
611
  const char* user;
612
  char display[RC_CLIENT_LEADERBOARD_DISPLAY_SIZE];
613
  time_t submitted;
614
  uint32_t rank;
615
  uint32_t index;
616
} rc_client_leaderboard_entry_t;
617

618
typedef struct rc_client_leaderboard_entry_list_t {
619
  rc_client_leaderboard_entry_t* entries;
620
  uint32_t num_entries;
621
  uint32_t total_entries;
622
  int32_t user_index;
623
} rc_client_leaderboard_entry_list_t;
624

625
typedef void (RC_CCONV *rc_client_fetch_leaderboard_entries_callback_t)(int result, const char* error_message,
626
    rc_client_leaderboard_entry_list_t* list, rc_client_t* client, void* callback_userdata);
627

628
/**
629
 * Fetches a list of leaderboard entries from the server.
630
 * Callback receives an allocated list that must be free'd by calling rc_client_destroy_leaderboard_entry_list.
631
 */
632
RC_EXPORT rc_client_async_handle_t* RC_CCONV rc_client_begin_fetch_leaderboard_entries(rc_client_t* client, uint32_t leaderboard_id,
633
    uint32_t first_entry, uint32_t count, rc_client_fetch_leaderboard_entries_callback_t callback, void* callback_userdata);
634

635
/**
636
 * Fetches a list of leaderboard entries from the server containing the logged-in user.
637
 * Callback receives an allocated list that must be free'd by calling rc_client_destroy_leaderboard_entry_list.
638
 */
639
RC_EXPORT rc_client_async_handle_t* RC_CCONV rc_client_begin_fetch_leaderboard_entries_around_user(rc_client_t* client, uint32_t leaderboard_id,
640
    uint32_t count, rc_client_fetch_leaderboard_entries_callback_t callback, void* callback_userdata);
641

642
/**
643
 * Gets the URL for the profile picture of the user associated to a leaderboard entry.
644
 * Returns RC_OK on success.
645
 */
646
RC_EXPORT int RC_CCONV rc_client_leaderboard_entry_get_user_image_url(const rc_client_leaderboard_entry_t* entry, char buffer[], size_t buffer_size);
647

648
/**
649
 * Destroys a list allocated by rc_client_begin_fetch_leaderboard_entries or rc_client_begin_fetch_leaderboard_entries_around_user.
650
 */
651
RC_EXPORT void RC_CCONV rc_client_destroy_leaderboard_entry_list(rc_client_leaderboard_entry_list_t* list);
652

653
/**
654
 * Used for scoreboard events. Contains the response from the server when a leaderboard entry is submitted.
655
 * NOTE: This structure is only valid within the event callback. If you want to make use of the data outside
656
 * of the callback, you should create copies of both the top entries and usernames within.
657
 */
658
typedef struct rc_client_leaderboard_scoreboard_entry_t {
659
  /* The user associated to the entry */
660
  const char* username;
661
  /* The rank of the entry */
662
  uint32_t rank;
663
  /* The value of the entry */
664
  char score[RC_CLIENT_LEADERBOARD_DISPLAY_SIZE];
665
} rc_client_leaderboard_scoreboard_entry_t;
666

667
typedef struct rc_client_leaderboard_scoreboard_t {
668
  /* The ID of the leaderboard which was submitted */
669
  uint32_t leaderboard_id;
670
  /* The value that was submitted */
671
  char submitted_score[RC_CLIENT_LEADERBOARD_DISPLAY_SIZE];
672
  /* The player's best submitted value */
673
  char best_score[RC_CLIENT_LEADERBOARD_DISPLAY_SIZE];
674
  /* The player's new rank within the leaderboard */
675
  uint32_t new_rank;
676
  /* The total number of entries in the leaderboard */
677
  uint32_t num_entries;
678

679
  /* An array of the top entries for the leaderboard */
680
  rc_client_leaderboard_scoreboard_entry_t* top_entries;
681
  /* The number of items in the top_entries array */
682
  uint32_t num_top_entries;
683
} rc_client_leaderboard_scoreboard_t;
684

685
/*****************************************************************************\
686
| Rich Presence                                                               |
687
\*****************************************************************************/
688

689
/**
690
 * Returns non-zero if the current game supports rich presence.
691
 */
692
RC_EXPORT int RC_CCONV rc_client_has_rich_presence(rc_client_t* client);
693

694
/**
695
 * Gets the current rich presence message.
696
 * Returns the number of characters written to buffer.
697
 */
698
RC_EXPORT size_t RC_CCONV rc_client_get_rich_presence_message(rc_client_t* client, char buffer[], size_t buffer_size);
699

700
/**
701
 * Returns a list of all possible rich presence strings.
702
 * The list is terminated by NULL.
703
 */
704
RC_EXPORT int RC_CCONV rc_client_get_rich_presence_strings(rc_client_t* client, const char** buffer, size_t buffer_size, size_t* count);
705

706
/*****************************************************************************\
707
| Processing                                                                  |
708
\*****************************************************************************/
709

710
enum {
711
  RC_CLIENT_EVENT_TYPE_NONE = 0,
712
  RC_CLIENT_EVENT_ACHIEVEMENT_TRIGGERED = 1, /* [achievement] was earned by the player */
713
  RC_CLIENT_EVENT_LEADERBOARD_STARTED = 2, /* [leaderboard] attempt has started */
714
  RC_CLIENT_EVENT_LEADERBOARD_FAILED = 3, /* [leaderboard] attempt failed */
715
  RC_CLIENT_EVENT_LEADERBOARD_SUBMITTED = 4, /* [leaderboard] attempt submitted */
716
  RC_CLIENT_EVENT_ACHIEVEMENT_CHALLENGE_INDICATOR_SHOW = 5, /* [achievement] challenge indicator should be shown */
717
  RC_CLIENT_EVENT_ACHIEVEMENT_CHALLENGE_INDICATOR_HIDE = 6, /* [achievement] challenge indicator should be hidden */
718
  RC_CLIENT_EVENT_ACHIEVEMENT_PROGRESS_INDICATOR_SHOW = 7, /* progress indicator should be shown for [achievement] */
719
  RC_CLIENT_EVENT_ACHIEVEMENT_PROGRESS_INDICATOR_HIDE = 8, /* progress indicator should be hidden */
720
  RC_CLIENT_EVENT_ACHIEVEMENT_PROGRESS_INDICATOR_UPDATE = 9, /* progress indicator should be updated to reflect new badge/progress for [achievement] */
721
  RC_CLIENT_EVENT_LEADERBOARD_TRACKER_SHOW = 10, /* [leaderboard_tracker] should be shown */
722
  RC_CLIENT_EVENT_LEADERBOARD_TRACKER_HIDE = 11, /* [leaderboard_tracker] should be hidden */
723
  RC_CLIENT_EVENT_LEADERBOARD_TRACKER_UPDATE = 12, /* [leaderboard_tracker] updated */
724
  RC_CLIENT_EVENT_LEADERBOARD_SCOREBOARD = 13, /* [leaderboard_scoreboard] possibly-new ranking received for [leaderboard] */
725
  RC_CLIENT_EVENT_RESET = 14, /* emulated system should be reset (as the result of enabling hardcore) */
726
  RC_CLIENT_EVENT_GAME_COMPLETED = 15, /* all achievements for the game have been earned */
727
  RC_CLIENT_EVENT_SERVER_ERROR = 16, /* an API response returned a [server_error] and will not be retried */
728
  RC_CLIENT_EVENT_DISCONNECTED = 17, /* an unlock request could not be completed and is pending */
729
  RC_CLIENT_EVENT_RECONNECTED = 18, /* all pending unlocks have been completed */
730
  RC_CLIENT_EVENT_SUBSET_COMPLETED = 19 /* all achievements for the subset have been earned */
731
};
732

733
typedef struct rc_client_server_error_t {
734
  const char* error_message;
735
  const char* api;
736
  int result;
737
  uint32_t related_id;
738
} rc_client_server_error_t;
739

740
typedef struct rc_client_event_t {
741
  uint32_t type;
742

743
  rc_client_achievement_t* achievement;
744
  rc_client_leaderboard_t* leaderboard;
745
  rc_client_leaderboard_tracker_t* leaderboard_tracker;
746
  rc_client_leaderboard_scoreboard_t* leaderboard_scoreboard;
747
  rc_client_server_error_t* server_error;
748
  rc_client_subset_t* subset;
749

750
} rc_client_event_t;
751

752
/**
753
 * Callback used to notify the client when certain events occur.
754
 */
755
typedef void (RC_CCONV *rc_client_event_handler_t)(const rc_client_event_t* event, rc_client_t* client);
756

757
/**
758
 * Provides a callback for event handling.
759
 */
760
RC_EXPORT void RC_CCONV rc_client_set_event_handler(rc_client_t* client, rc_client_event_handler_t handler);
761

762
/**
763
 * Provides a callback for reading memory.
764
 */
765
RC_EXPORT void RC_CCONV rc_client_set_read_memory_function(rc_client_t* client, rc_client_read_memory_func_t handler);
766

767
/**
768
 * Specifies whether rc_client is allowed to read memory outside of rc_client_do_frame/rc_client_idle.
769
 */
770
RC_EXPORT void RC_CCONV rc_client_set_allow_background_memory_reads(rc_client_t* client, int allowed);
771

772
/**
773
 * Determines if there are any active achievements/leaderboards/rich presence that need processing.
774
 */
775
RC_EXPORT int RC_CCONV rc_client_is_processing_required(rc_client_t* client);
776

777
/**
778
 * Processes achievements for the current frame.
779
 */
780
RC_EXPORT void RC_CCONV rc_client_do_frame(rc_client_t* client);
781

782
/**
783
 * Processes the periodic queue.
784
 * Called internally by rc_client_do_frame.
785
 * Should be explicitly called if rc_client_do_frame is not being called because emulation is paused.
786
 */
787
RC_EXPORT void RC_CCONV rc_client_idle(rc_client_t* client);
788

789
/**
790
 * Determines if a sufficient amount of frames have been processed since the last call to rc_client_can_pause.
791
 * Should not be called unless the client is trying to pause.
792
 * If false is returned, and frames_remaining is not NULL, frames_remaining will be set to the number of frames
793
 * still required before pause is allowed, which can be converted to a time in seconds for displaying to the user.
794
 */
795
RC_EXPORT int RC_CCONV rc_client_can_pause(rc_client_t* client, uint32_t* frames_remaining);
796

797
/**
798
 * Informs the runtime that the emulator has been reset. Will reset all achievements and leaderboards
799
 * to their initial state (includes hiding indicators/trackers).
800
 */
801
RC_EXPORT void RC_CCONV rc_client_reset(rc_client_t* client);
802

803
/**
804
 * Gets the number of bytes needed to serialized the runtime state.
805
 */
806
RC_EXPORT size_t RC_CCONV rc_client_progress_size(rc_client_t* client);
807

808
/**
809
 * Serializes the runtime state into a buffer.
810
 * Returns RC_OK on success, or an error indicator.
811
 * [deprecated] use rc_client_serialize_progress_sized instead
812
 */
813
RC_EXPORT int RC_CCONV rc_client_serialize_progress(rc_client_t* client, uint8_t* buffer);
814

815
/**
816
 * Serializes the runtime state into a buffer.
817
 * Returns RC_OK on success, or an error indicator.
818
 */
819
RC_EXPORT int RC_CCONV rc_client_serialize_progress_sized(rc_client_t* client, uint8_t* buffer, size_t buffer_size);
820

821
/**
822
 * Deserializes the runtime state from a buffer.
823
 * Returns RC_OK on success, or an error indicator.
824
 * [deprecated] use rc_client_deserialize_progress_sized instead
825
 */
826
RC_EXPORT int RC_CCONV rc_client_deserialize_progress(rc_client_t* client, const uint8_t* serialized);
827

828
/**
829
 * Serializes the runtime state into a buffer.
830
 * Returns RC_OK on success, or an error indicator.
831
 */
832
RC_EXPORT int RC_CCONV rc_client_deserialize_progress_sized(rc_client_t* client, const uint8_t* serialized, size_t serialized_size);
833

834
RC_END_C_DECLS
835

836
#endif /* RC_RUNTIME_H */
837

838