1
#ifndef RC_API_RUNTIME_H
2
#define RC_API_RUNTIME_H
3

4
#include "rc_api_request.h"
5

6
#include <stdint.h>
7
#include <time.h>
8

9
RC_BEGIN_C_DECLS
10

11
/* --- Fetch Image --- */
12

13
/**
14
 * API parameters for a fetch image request.
15
 * NOTE: fetch image server response is the raw image data. There is no rc_api_process_fetch_image_response function.
16
 */
17
typedef struct rc_api_fetch_image_request_t {
18
  /* The name of the image to fetch */
19
  const char* image_name;
20
  /* The type of image to fetch */
21
  uint32_t image_type;
22
}
23
rc_api_fetch_image_request_t;
24

25
#define RC_IMAGE_TYPE_GAME 1
26
#define RC_IMAGE_TYPE_ACHIEVEMENT 2
27
#define RC_IMAGE_TYPE_ACHIEVEMENT_LOCKED 3
28
#define RC_IMAGE_TYPE_USER 4
29

30
RC_EXPORT int RC_CCONV rc_api_init_fetch_image_request(rc_api_request_t* request, const rc_api_fetch_image_request_t* api_params);
31
RC_EXPORT int RC_CCONV rc_api_init_fetch_image_request_hosted(rc_api_request_t* request, const rc_api_fetch_image_request_t* api_params, const rc_api_host_t* host);
32

33
/* --- Resolve Hash --- */
34

35
/**
36
 * API parameters for a resolve hash request.
37
 */
38
typedef struct rc_api_resolve_hash_request_t {
39
  /* Unused - hash lookup does not require credentials */
40
  const char* username;
41
  /* Unused - hash lookup does not require credentials */
42
  const char* api_token;
43
  /* The generated hash of the game to be identified */
44
  const char* game_hash;
45
}
46
rc_api_resolve_hash_request_t;
47

48
/**
49
 * Response data for a resolve hash request.
50
 */
51
typedef struct rc_api_resolve_hash_response_t {
52
  /* The unique identifier of the game, 0 if no match was found */
53
  uint32_t game_id;
54

55
  /* Common server-provided response information */
56
  rc_api_response_t response;
57
}
58
rc_api_resolve_hash_response_t;
59

60
RC_EXPORT int RC_CCONV rc_api_init_resolve_hash_request(rc_api_request_t* request, const rc_api_resolve_hash_request_t* api_params);
61
RC_EXPORT int RC_CCONV rc_api_init_resolve_hash_request_hosted(rc_api_request_t* request, const rc_api_resolve_hash_request_t* api_params, const rc_api_host_t* host);
62
/* [deprecated] use rc_api_process_resolve_hash_server_response instead */
63
RC_EXPORT int RC_CCONV rc_api_process_resolve_hash_response(rc_api_resolve_hash_response_t* response, const char* server_response);
64
RC_EXPORT int RC_CCONV rc_api_process_resolve_hash_server_response(rc_api_resolve_hash_response_t* response, const rc_api_server_response_t* server_response);
65
RC_EXPORT void RC_CCONV rc_api_destroy_resolve_hash_response(rc_api_resolve_hash_response_t* response);
66

67
/* --- Fetch Game Data --- */
68

69
/**
70
 * API parameters for a fetch game data request.
71
 */
72
typedef struct rc_api_fetch_game_data_request_t {
73
  /* The username of the player */
74
  const char* username;
75
  /* The API token from the login request */
76
  const char* api_token;
77
  /* The unique identifier of the game */
78
  uint32_t game_id;
79
  /* The generated hash of the game to be identified (ignored if game_id is not 0) */
80
  const char* game_hash;
81
}
82
rc_api_fetch_game_data_request_t;
83

84
/* A leaderboard definition */
85
typedef struct rc_api_leaderboard_definition_t {
86
  /* The unique identifier of the leaderboard */
87
  uint32_t id;
88
  /* The format to pass to rc_format_value to format the leaderboard value */
89
  int format;
90
  /* The title of the leaderboard */
91
  const char* title;
92
  /* The description of the leaderboard */
93
  const char* description;
94
  /* The definition of the leaderboard to be passed to rc_runtime_activate_lboard */
95
  const char* definition;
96
  /* Non-zero if lower values are better for this leaderboard */
97
  uint8_t lower_is_better;
98
  /* Non-zero if the leaderboard should not be displayed in a list of leaderboards */
99
  uint8_t hidden;
100
}
101
rc_api_leaderboard_definition_t;
102

103
/* An achievement definition */
104
typedef struct rc_api_achievement_definition_t {
105
  /* The unique identifier of the achievement */
106
  uint32_t id;
107
  /* The number of points the achievement is worth */
108
  uint32_t points;
109
  /* The achievement category (core, unofficial) */
110
  uint32_t category;
111
  /* The title of the achievement */
112
  const char* title;
113
  /* The description of the achievement */
114
  const char* description;
115
  /* The definition of the achievement to be passed to rc_runtime_activate_achievement */
116
  const char* definition;
117
  /* The author of the achievment */
118
  const char* author;
119
  /* The image name for the achievement badge */
120
  const char* badge_name;
121
  /* When the achievement was first uploaded to the server */
122
  time_t created;
123
  /* When the achievement was last modified on the server */
124
  time_t updated;
125
  /* The achievement type (win/progression/missable) */
126
  uint32_t type;
127
  /* The approximate rarity of the achievement (X% of users have earned the achievement) */
128
  float rarity;
129
  /* The approximate rarity of the achievement in hardcore (X% of users have earned the achievement in hardcore) */
130
  float rarity_hardcore;
131
  /* The URL for the achievement badge */
132
  const char* badge_url;
133
  /* The URL for the locked achievement badge */
134
  const char* badge_locked_url;
135
}
136
rc_api_achievement_definition_t;
137

138
#define RC_ACHIEVEMENT_CATEGORY_CORE 3
139
#define RC_ACHIEVEMENT_CATEGORY_UNOFFICIAL 5
140

141
#define RC_ACHIEVEMENT_TYPE_STANDARD 0
142
#define RC_ACHIEVEMENT_TYPE_MISSABLE 1
143
#define RC_ACHIEVEMENT_TYPE_PROGRESSION 2
144
#define RC_ACHIEVEMENT_TYPE_WIN 3
145

146
/**
147
 * Response data for a fetch game data request.
148
 */
149
typedef struct rc_api_fetch_game_data_response_t {
150
  /* The unique identifier of the game */
151
  uint32_t id;
152
  /* The console associated to the game */
153
  uint32_t console_id;
154
  /* The title of the game */
155
  const char* title;
156
  /* The image name for the game badge */
157
  const char* image_name;
158
  /* The URL for the game badge */
159
  const char* image_url;
160
  /* The rich presence script for the game to be passed to rc_runtime_activate_richpresence */
161
  const char* rich_presence_script;
162

163
  /* An array of achievements for the game */
164
  rc_api_achievement_definition_t* achievements;
165
  /* The number of items in the achievements array */
166
  uint32_t num_achievements;
167

168
  /* An array of leaderboards for the game */
169
  rc_api_leaderboard_definition_t* leaderboards;
170
  /* The number of items in the leaderboards array */
171
  uint32_t num_leaderboards;
172

173
  /* Common server-provided response information */
174
  rc_api_response_t response;
175
}
176
rc_api_fetch_game_data_response_t;
177

178
RC_EXPORT int RC_CCONV rc_api_init_fetch_game_data_request(rc_api_request_t* request, const rc_api_fetch_game_data_request_t* api_params);
179
RC_EXPORT int RC_CCONV rc_api_init_fetch_game_data_request_hosted(rc_api_request_t* request, const rc_api_fetch_game_data_request_t* api_params, const rc_api_host_t* host);
180
/* [deprecated] use rc_api_process_fetch_game_data_server_response instead */
181
RC_EXPORT int RC_CCONV rc_api_process_fetch_game_data_response(rc_api_fetch_game_data_response_t* response, const char* server_response);
182
RC_EXPORT int RC_CCONV rc_api_process_fetch_game_data_server_response(rc_api_fetch_game_data_response_t* response, const rc_api_server_response_t* server_response);
183
RC_EXPORT void RC_CCONV rc_api_destroy_fetch_game_data_response(rc_api_fetch_game_data_response_t* response);
184

185
/* --- Fetch Game Sets --- */
186

187
/**
188
 * API parameters for a fetch game data request.
189
 */
190
typedef struct rc_api_fetch_game_sets_request_t {
191
  /* The username of the player */
192
  const char* username;
193
  /* The API token from the login request */
194
  const char* api_token;
195
  /* The unique identifier of the game */
196
  uint32_t game_id;
197
  /* The generated hash of the game to be identified (ignored if game_id is not 0) */
198
  const char* game_hash;
199
}
200
rc_api_fetch_game_sets_request_t;
201

202
#define RC_ACHIEVEMENT_SET_TYPE_CORE 0
203
#define RC_ACHIEVEMENT_SET_TYPE_BONUS 1
204
#define RC_ACHIEVEMENT_SET_TYPE_SPECIALTY 2
205
#define RC_ACHIEVEMENT_SET_TYPE_EXCLUSIVE 3
206

207
/* A game subset definition */
208
typedef struct rc_api_achievement_set_definition_t {
209
  /* The unique identifier of the achievement set */
210
  uint32_t id;
211
  /* The legacy game_id of the achievement set (used for editor API calls) */
212
  uint32_t game_id;
213
  /* The title of the achievement set */
214
  const char* title;
215
  /* The image name for the achievement set badge */
216
  const char* image_name;
217
  /* The URL for the achievement set badge */
218
  const char* image_url;
219

220
  /* An array of achievements for the achievement set */
221
  rc_api_achievement_definition_t* achievements;
222
  /* The number of items in the achievements array */
223
  uint32_t num_achievements;
224

225
  /* An array of leaderboards for the achievement set */
226
  rc_api_leaderboard_definition_t* leaderboards;
227
  /* The number of items in the leaderboards array */
228
  uint32_t num_leaderboards;
229

230
  /* The type of the achievement set */
231
  uint8_t type;
232
}
233
rc_api_achievement_set_definition_t;
234

235
/**
236
 * Response data for a fetch game sets request.
237
 */
238
typedef struct rc_api_fetch_game_sets_response_t {
239
  /* The unique identifier of the game */
240
  uint32_t id;
241
  /* The console associated to the game */
242
  uint32_t console_id;
243
  /* The title of the game */
244
  const char* title;
245
  /* The image name for the game badge */
246
  const char* image_name;
247
  /* The URL for the game badge */
248
  const char* image_url;
249
  /* The rich presence script for the game to be passed to rc_runtime_activate_richpresence */
250
  const char* rich_presence_script;
251
  /* The unique identifier of the game to use for session requests (startsession/ping/etc) */
252
  uint32_t session_game_id;
253

254
  /* An array of sets for the game */
255
  rc_api_achievement_set_definition_t* sets;
256
  /* The number of items in the sets array */
257
  uint32_t num_sets;
258

259
  /* Common server-provided response information */
260
  rc_api_response_t response;
261
}
262
rc_api_fetch_game_sets_response_t;
263

264
RC_EXPORT int RC_CCONV rc_api_init_fetch_game_sets_request(rc_api_request_t* request, const rc_api_fetch_game_sets_request_t* api_params);
265
RC_EXPORT int RC_CCONV rc_api_init_fetch_game_sets_request_hosted(rc_api_request_t* request, const rc_api_fetch_game_sets_request_t* api_params, const rc_api_host_t* host);
266
RC_EXPORT int RC_CCONV rc_api_process_fetch_game_sets_server_response(rc_api_fetch_game_sets_response_t* response, const rc_api_server_response_t* server_response);
267
RC_EXPORT void RC_CCONV rc_api_destroy_fetch_game_sets_response(rc_api_fetch_game_sets_response_t* response);
268

269
/* --- Ping --- */
270

271
/**
272
 * API parameters for a ping request.
273
 */
274
typedef struct rc_api_ping_request_t {
275
  /* The username of the player */
276
  const char* username;
277
  /* The API token from the login request */
278
  const char* api_token;
279
  /* The unique identifier of the game */
280
  uint32_t game_id;
281
  /* (optional) The current rich presence evaluation for the user */
282
  const char* rich_presence;
283
  /* (recommended) The hash associated to the game being played */
284
  const char* game_hash;
285
  /* Non-zero if hardcore is currently enabled (ignored if game_hash is null) */
286
  uint32_t hardcore;
287
}
288
rc_api_ping_request_t;
289

290
/**
291
 * Response data for a ping request.
292
 */
293
typedef struct rc_api_ping_response_t {
294
  /* Common server-provided response information */
295
  rc_api_response_t response;
296
}
297
rc_api_ping_response_t;
298

299
RC_EXPORT int RC_CCONV rc_api_init_ping_request(rc_api_request_t* request, const rc_api_ping_request_t* api_params);
300
RC_EXPORT int RC_CCONV rc_api_init_ping_request_hosted(rc_api_request_t* request, const rc_api_ping_request_t* api_params, const rc_api_host_t* host);
301
/* [deprecated] use rc_api_process_ping_server_response instead */
302
RC_EXPORT int RC_CCONV rc_api_process_ping_response(rc_api_ping_response_t* response, const char* server_response);
303
RC_EXPORT int RC_CCONV rc_api_process_ping_server_response(rc_api_ping_response_t* response, const rc_api_server_response_t* server_response);
304
RC_EXPORT void RC_CCONV rc_api_destroy_ping_response(rc_api_ping_response_t* response);
305

306
/* --- Award Achievement --- */
307

308
/**
309
 * API parameters for an award achievement request.
310
 */
311
typedef struct rc_api_award_achievement_request_t {
312
  /* The username of the player */
313
  const char* username;
314
  /* The API token from the login request */
315
  const char* api_token;
316
  /* The unique identifier of the achievement */
317
  uint32_t achievement_id;
318
  /* Non-zero if the achievement was earned in hardcore */
319
  uint32_t hardcore;
320
  /* The hash associated to the game being played */
321
  const char* game_hash;
322
  /* The number of seconds since the achievement was unlocked */
323
  uint32_t seconds_since_unlock;
324
}
325
rc_api_award_achievement_request_t;
326

327
/**
328
 * Response data for an award achievement request.
329
 */
330
typedef struct rc_api_award_achievement_response_t {
331
  /* The unique identifier of the achievement that was awarded */
332
  uint32_t awarded_achievement_id;
333
  /* The updated player score */
334
  uint32_t new_player_score;
335
  /* The updated player softcore score */
336
  uint32_t new_player_score_softcore;
337
  /* The number of achievements the user has not yet unlocked for this game
338
   * (in hardcore/non-hardcore per hardcore flag in request) */
339
  uint32_t achievements_remaining;
340

341
  /* Common server-provided response information */
342
  rc_api_response_t response;
343
}
344
rc_api_award_achievement_response_t;
345

346
RC_EXPORT int RC_CCONV rc_api_init_award_achievement_request(rc_api_request_t* request, const rc_api_award_achievement_request_t* api_params);
347
RC_EXPORT int RC_CCONV rc_api_init_award_achievement_request_hosted(rc_api_request_t* request, const rc_api_award_achievement_request_t* api_params, const rc_api_host_t* host);
348
/* [deprecated] use rc_api_process_award_achievement_server_response instead */
349
RC_EXPORT int RC_CCONV rc_api_process_award_achievement_response(rc_api_award_achievement_response_t* response, const char* server_response);
350
RC_EXPORT int RC_CCONV rc_api_process_award_achievement_server_response(rc_api_award_achievement_response_t* response, const rc_api_server_response_t* server_response);
351
RC_EXPORT void RC_CCONV rc_api_destroy_award_achievement_response(rc_api_award_achievement_response_t* response);
352

353
/* --- Submit Leaderboard Entry --- */
354

355
/**
356
 * API parameters for a submit lboard entry request.
357
 */
358
typedef struct rc_api_submit_lboard_entry_request_t {
359
  /* The username of the player */
360
  const char* username;
361
  /* The API token from the login request */
362
  const char* api_token;
363
  /* The unique identifier of the leaderboard */
364
  uint32_t leaderboard_id;
365
  /* The value being submitted */
366
  int32_t score;
367
  /* The hash associated to the game being played */
368
  const char* game_hash;
369
  /* The number of seconds since the leaderboard attempt was completed */
370
  uint32_t seconds_since_completion;
371
}
372
rc_api_submit_lboard_entry_request_t;
373

374
/* A leaderboard entry */
375
typedef struct rc_api_lboard_entry_t {
376
  /* The user associated to the entry */
377
  const char* username;
378
  /* The rank of the entry */
379
  uint32_t rank;
380
  /* The value of the entry */
381
  int32_t score;
382
}
383
rc_api_lboard_entry_t;
384

385
/**
386
 * Response data for a submit lboard entry request.
387
 */
388
typedef struct rc_api_submit_lboard_entry_response_t {
389
  /* The value that was submitted */
390
  int32_t submitted_score;
391
  /* The player's best submitted value */
392
  int32_t best_score;
393
  /* The player's new rank within the leaderboard */
394
  uint32_t new_rank;
395
  /* The total number of entries in the leaderboard */
396
  uint32_t num_entries;
397

398
  /* An array of the top entries for the leaderboard */
399
  rc_api_lboard_entry_t* top_entries;
400
  /* The number of items in the top_entries array */
401
  uint32_t num_top_entries;
402

403
  /* Common server-provided response information */
404
  rc_api_response_t response;
405
}
406
rc_api_submit_lboard_entry_response_t;
407

408
RC_EXPORT int RC_CCONV rc_api_init_submit_lboard_entry_request(rc_api_request_t* request, const rc_api_submit_lboard_entry_request_t* api_params);
409
RC_EXPORT int RC_CCONV rc_api_init_submit_lboard_entry_request_hosted(rc_api_request_t* request, const rc_api_submit_lboard_entry_request_t* api_params, const rc_api_host_t* host);
410
/* [deprecated] use rc_api_process_submit_lboard_entry_server_response instead */
411
RC_EXPORT int RC_CCONV rc_api_process_submit_lboard_entry_response(rc_api_submit_lboard_entry_response_t* response, const char* server_response);
412
RC_EXPORT int RC_CCONV rc_api_process_submit_lboard_entry_server_response(rc_api_submit_lboard_entry_response_t* response, const rc_api_server_response_t* server_response);
413
RC_EXPORT void RC_CCONV rc_api_destroy_submit_lboard_entry_response(rc_api_submit_lboard_entry_response_t* response);
414

415
RC_END_C_DECLS
416

417
#endif /* RC_API_RUNTIME_H */
418

419