ocrm.bsky.social
the game where you go into mines and start crafting! but for consoles (forked directly from smartcmd's github)
1/********************************************************
2* *
3* Copyright (C) Microsoft. All rights reserved. *
4* *
5********************************************************/
6
7// Sentient Client UGC Leaderboard API
8//
9// Include this to get access to all UGC Leaderboard features
10
11#pragma once
12
13#include "SenClientUGCTypes.h"
14
15#include "SenClientSys.h"
16
17
18namespace Sentient
19{
20 // This system does not rely on existing XBox Leaderboards, but runs completely in parallel.
21
22 /********************************************
23 ***** Leaderboard Creation Functions *****
24 ********************************************/
25
26 /// @brief Creates a dynamic Leaderboard based on a given definition.
27 ///
28 /// @param[in] userIndex
29 /// The index of the initiating user on the console.
30 /// Note: This is NOT a XUID.
31 ///
32 /// @param[in] definition
33 /// Leaderboard definition that describes the behavior for the to be created Leaderboard.
34 ///
35 /// @param[in] metadataBlob
36 /// Binary metadata blob that is associated to the created Leaderboard.
37 /// Can be used to store information about the Leaderboard being created.
38 /// This information can be re-uploaded at any time.
39 ///
40 /// @param[in] metadataBlobSize
41 /// Used to indelicate the size of the buffer pointed to by @a metadataBlob.
42 ///
43 /// @param[out] out_leaderboardId
44 /// The Leaderboard Id that has been created by the service.
45 ///
46 /// @param[in] userCallback
47 /// If this call returns a success code,
48 /// the userCallback will be called at the end of the
49 /// asynchronous process.
50 ///
51 /// @param[in] userCallbackData
52 /// Data to be passed to the @a userCallback on completion.
53 ///
54 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success.
55 /// Specific values include:
56 ///
57 /// @details Creates a new Leaderboard based on the supplied Leaderboard Definition.
58 ///
59 /// @related SenCreateLeaderboard()
60 HRESULT SenCreateLeaderboard(
61 int userIndex,
62 const SenLeaderboardDefinition &definition,
63 const void *metadataBlob,
64 size_t metadataBlobSize,
65 SenLeaderboardId *out_leaderboardId,
66 SenSysCompletedCallback callback,
67 void *callbackData );
68
69 /********************************************
70 ***** Leaderboard Set Score Functions *****
71 ********************************************/
72
73 /// @brief Set a specific Leaderboard entry value.
74 ///
75 /// @param[in] userIndex
76 /// The index of the initiating user on the console.
77 /// Note: This is NOT a XUID.
78 ///
79 /// @param[in] leaderboardId
80 /// Leaderboard Id to set a value on.
81 ///
82 /// @param[in] value
83 /// Value of the Leaderboard entry.
84 ///
85 /// @param[in] userCallback
86 /// If this call returns a success code,
87 /// the userCallback will be called at the end of the
88 /// asynchronous process.
89 ///
90 /// @param[in] userCallbackData
91 /// Data to be passed to the @a userCallback on completion.
92 ///
93 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success.
94 /// Specific values include:
95 ///
96 /// @details The Leaderboard entry value will be set for the given Leaderboard.
97 /// The actor or owner of the value will be the XUID of user
98 /// logged in at the specified index.
99 ///
100 /// @related SenSetUserLeaderboardValue()
101 __declspec(deprecated("This function is deprecated, and should not be used"))
102 HRESULT SenSetUserLeaderboardValue(
103 int userIndex,
104 SenLeaderboardId leaderboardId,
105 SenLeaderboardEntryValue value,
106 SenSysCompletedCallback callback,
107 void *callbackData );
108
109 HRESULT SenSetUserLeaderboardValue(
110 int userIndex,
111 SenLeaderboardId leaderboardId,
112 SenLeaderboardEntryValue value,
113 LONGLONG descriptor,
114 SenSysCompletedCallback callback,
115 void *callbackData );
116
117 /// @brief Set a specific Leaderboard entry value and metadata.
118 ///
119 /// @param[in] userIndex
120 /// The index of the initiating user on the console.
121 /// Note: This is NOT a XUID.
122 ///
123 /// @param[in] leaderboardId
124 /// Leaderboard Id to set a value on.
125 ///
126 /// @param[in] value
127 /// Value of the Leaderboard entry.
128 ///
129 /// @param[in] metadataBlob
130 /// Binary metadata blob that is associated to the created Leaderboard Entry.
131 /// Can be used to store information about the Leaderboard Entry being created.
132 /// This information can be re-uploaded at any time.
133 ///
134 /// @param[in] metadataBlobSize
135 /// Used to indicate the size of the buffer pointed to by @a metadataBlob.
136 /// If the actual size of the data exceeds this, you will receive an error.
137 ///
138 /// @param[in] userCallback
139 /// If this call returns a success code,
140 /// the userCallback will be called at the end of the
141 /// asynchronous process.
142 ///
143 /// @param[in] userCallbackData
144 /// Data to be passed to the @a userCallback on completion.
145 ///
146 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success.
147 /// Specific values include:
148 ///
149 /// @details The Leaderboard entry value will be set for the given Leaderboard.
150 /// The actor or owner of the value will be the XUID of user
151 /// logged in at the specified index.
152 ///
153 /// @related SenSetUserLeaderboardValue()
154 __declspec(deprecated("This function is deprecated, and should not be used"))
155 HRESULT SenSetUserLeaderboardValue(
156 int userIndex,
157 SenLeaderboardId leaderboardId,
158 SenLeaderboardEntryValue value,
159 const void *metadataBlob,
160 size_t metadataBlobSize,
161 SenSysCompletedCallback callback,
162 void *callbackData );
163
164 HRESULT SenSetUserLeaderboardValue(
165 int userIndex,
166 SenLeaderboardId leaderboardId,
167 SenLeaderboardEntryValue value,
168 LONGLONG descriptor,
169 const void *metadataBlob,
170 size_t metadataBlobSize,
171 SenSysCompletedCallback callback,
172 void *callbackData );
173
174 /********************************************
175 ***** Leaderboard Retrieval Functions *****
176 ********************************************/
177
178 /*For documentation: the output structure contains a pointer to a buffer that is allocated by Sentient (specifically the transport layer). The pointer is only valid during the callback. If title developers want to hold on to the metadata they'll need to copy the data into a buffer of their own before execution leaves the completion callback.
179 It's definitely an ugly pattern which is why we strongly prefer to avoid it (and use title-allocated buffers), but I don't see a way round it in this case.*/
180
181 /// @brief Retrieves a single Leaderboard Entry.
182 ///
183 /// @param[in] userIndex
184 /// The index of the initiating user on the console.
185 /// Note: This is NOT a XUID.
186 ///
187 /// @param[in] leaderboardId
188 /// Leaderboard Id where the entry being retrieved is stored.
189 ///
190 /// @param[in] leaderboardFlag
191 /// Flag for determining how Leaderboard specific Metadata should be retrieved.
192 ///
193 /// @param[in] entryFlag
194 /// Flag for determining how Leaderboard Entry specific Metadata should be retrieved.
195 ///
196 /// @param[out] out_leaderboardEntry
197 /// Leaderboard Entry being retrieved.
198 ///
199 /// @param[in] maxLeaderboardMetadataBlobSize
200 /// Used to indicate the size of the buffer pointed to by @a out_leaderboardMetadataBlob.
201 /// If the actual size of the data exceeds this, you will receive an error.
202 ///
203 /// @param[out] out_leaderboardMetadataBlob
204 /// Metadata buffer associated to the Leaderboard.
205 ///
206 /// @param[out] out_leaderboardMetadataBlobSize
207 /// Used to return the actual size of the Leaderboard Metadata being returned.
208 ///
209 /// @param[in] userCallback
210 /// If this call returns a success code,
211 /// the userCallback will be called at the end of the
212 /// asynchronous process.
213 ///
214 /// @param[in] userCallbackData
215 /// Data to be passed to the @a userCallback on completion.
216 ///
217 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success.
218 /// Specific values include:
219 ///
220 /// @details Retrieves a single Leaderboard Entry.
221 /// The actor or owner of the value will be the XUID of user
222 /// logged in at the specified index.
223 ///
224 /// @related SenGetLeaderboardEntry()
225 HRESULT SenGetLeaderboardEntry(
226 int userIndex,
227 SenLeaderboardId leaderboardId,
228 SenLeaderboardMetadataFlag leaderboardFlag,
229 SenLeaderboardMetadataFlag entryFlag,
230 SenLeaderboardEntry *out_leaderboardEntry,
231 size_t maxLeaderboardMetadataBlobSize, // LB
232 void *out_leaderboardMetadataBlob, // LB
233 size_t *out_leaderboardMetadataBlobSize, // LB
234 SenSysCompletedCallback callback,
235 void *callbackData );
236
237 /// @brief Retrieves a single Leaderboard Entry for any given actor (XUID).
238 ///
239 /// @param[in] userIndex
240 /// The index of the initiating user on the console.
241 /// Note: This is NOT a XUID.
242 ///
243 /// @param[in] actorId
244 /// Actor Id for the Leaderboard Entry being retrieved.
245 ///
246 /// @param[in] leaderboardId
247 /// Leaderboard Id where the entry being retrieved is stored.
248 ///
249 /// @param[in] leaderboardFlag
250 /// Flag for determining how Leaderboard specific Metadata should be retrieved.
251 ///
252 /// @param[in] entryFlag
253 /// Flag for determining how Leaderboard Entry specific Metadata should be retrieved.
254 ///
255 /// @param[out] out_leaderboardEntry
256 /// Leaderboard Entry being retrieved.
257 ///
258 /// @param[in] maxLeaderboardMetadataBlobSize
259 /// Used to indicate the size of the buffer pointed to by @a out_leaderboardMetadataBlob.
260 /// If the actual size of the data exceeds this, you will receive an error.
261 ///
262 /// @param[out] out_leaderboardMetadataBlob
263 /// Metadata buffer associated to the Leaderboard.
264 ///
265 /// @param[out] out_leaderboardMetadataBlobSize
266 /// Used to return the actual size of the Leaderboard Metadata being returned.
267 ///
268 /// @param[in] userCallback
269 /// If this call returns a success code,
270 /// the userCallback will be called at the end of the
271 /// asynchronous process.
272 ///
273 /// @param[in] userCallbackData
274 /// Data to be passed to the @a userCallback on completion.
275 ///
276 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success.
277 /// Specific values include:
278 ///
279 /// @details Retrieves a single Leaderboard Entry for a given actor.
280 ///
281 /// @related SenGetLeaderboardEntry()
282 HRESULT SenGetLeaderboardEntry(
283 int userIndex,
284 SenLeaderboardActorId actorId,
285 SenLeaderboardId leaderboardId,
286 SenLeaderboardMetadataFlag leaderboardFlag,
287 SenLeaderboardMetadataFlag entryFlag,
288 SenLeaderboardEntry *out_leaderboardEntry,
289 size_t maxLeaderboardMetadataBlobSize, // LB
290 void *out_leaderboardMetadataBlob, // LB
291 size_t *out_leaderboardMetadataBlobSize, // LB
292 SenSysCompletedCallback callback,
293 void *callbackData );
294
295
296 /// @brief Retrieve a specific Leaderboard that is ranked by Xbox Live Friends.
297 ///
298 /// @param[in] userIndex
299 /// The index of the initiating user on the console.
300 /// Note: This is NOT a XUID.
301 ///
302 /// @param[in] leaderboardId
303 /// Leaderboard Id where the entry being retrieved is stored.
304 ///
305 /// @param[in] leaderboardFlag
306 /// Flag for determining how Leaderboard specific Metadata should be retrieved.
307 ///
308 /// @param[in] entryFlag
309 /// Flag for determining how Leaderboard Entry specific Metadata should be retrieved.
310 ///
311 /// @param[in] maxLeaderboardEntries
312 /// Used to indicate the number of Leaderboard Entries to be returned by @a out_leaderboardEntries.
313 /// If the actual number of items exceeds this, you will receive an error.
314 ///
315 /// @param[out] out_leaderboardEntries
316 /// Collection of Leaderboard Entries being retrieved.
317 ///
318 /// @param[out] out_leaderboardEntriesSize
319 /// Actual size of the returned Leaderboard Entry collection.
320 ///
321 /// @param[in] maxLeaderboardMetadataBlobSize
322 /// Used to indicate the size of the buffer pointed to by @a out_leaderboardMetadataBlob.
323 /// If the actual size of the data exceeds this, you will receive an error.
324 ///
325 /// @param[out] out_leaderboardMetadataBlob
326 /// Metadata buffer associated to the Leaderboard.
327 ///
328 /// @param[out] out_leaderboardMetadataBlobSize
329 /// Used to return the actual size of the Leaderboard Metadata being returned.
330 ///
331 /// @param[in] userCallback
332 /// If this call returns a success code,
333 /// the userCallback will be called at the end of the
334 /// asynchronous process.
335 ///
336 /// @param[in] userCallbackData
337 /// Data to be passed to the @a userCallback on completion.
338 ///
339 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success.
340 /// Specific values include:
341 ///
342 /// @details Returns a ranked Leaderboard.
343 HRESULT SenGetLeaderboardFriends(
344 int userIndex,
345 SenLeaderboardId leaderboardId,
346 SenLeaderboardMetadataFlag leaderboardFlag,
347 SenLeaderboardMetadataFlag entryFlag,
348 size_t maxLeaderboardEntries,
349 SenLeaderboardEntry *out_leaderboardEntries,
350 size_t *out_leaderboardEntriesSize,
351 size_t maxLeaderboardMetadataBlobSize, // LB
352 void *out_leaderboardMetadataBlob, // LB
353 size_t *out_leaderboardMetadataBlobSize, // LB
354 SenSysCompletedCallback callback,
355 void *callbackData );
356
357 /// @brief Retrieve a specific Leaderboard that is ranked by the top Leaderboard Entries.
358 ///
359 /// @param[in] userIndex
360 /// The index of the initiating user on the console.
361 /// Note: This is NOT a XUID.
362 ///
363 /// @param[in] leaderboardId
364 /// Leaderboard Id where the entry being retrieved is stored.
365 ///
366 /// @param[in] maxLeaderboardEntries
367 /// Used to indicate the number of Leaderboard Entries to be returned by @a out_leaderboardEntries.
368 /// If the actual number of items exceeds this, you will receive an error.
369 ///
370 /// @param[out] out_leaderboardEntries
371 /// Collection of Leaderboard Entries being retrieved.
372 ///
373 /// @param[out] out_leaderboardEntriesSize
374 /// Actual size of the returned Leaderboard Entry collection.
375 ///
376 /// @param[in] userCallback
377 /// If this call returns a success code,
378 /// the userCallback will be called at the end of the
379 /// asynchronous process.
380 ///
381 /// @param[in] userCallbackData
382 /// Data to be passed to the @a userCallback on completion.
383 ///
384 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success.
385 /// Specific values include:
386 ///
387 /// @details Returns a ranked Leaderboard of all the top Leaderboard Entries.
388 HRESULT SenGetLeaderboardTop(
389 int userIndex,
390 SenLeaderboardId leaderboardId,
391 size_t maxLeaderboardEntries,
392 SenLeaderboardEntry *out_leaderboardEntries,
393 size_t *out_leaderboardEntriesSize,
394 SenSysCompletedCallback callback,
395 void *callbackData );
396
397} // namespace Sentient