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 AvatarSuperstars Fame API
8//
9// Include this to get access to all Fame-related Sentient features.
10
11#pragma once
12
13#include "SenClientSys.h"
14
15namespace Sentient
16{
17 /**********************
18 ***** Fame Types *****
19 **********************/
20 enum SenFameVIPLevel
21 {
22 SenFameVIPLevel_Unknown = 0xFFFFFFFF,
23 SenFameVIPLevel_Fan = 0,
24 SenFameVIPLevel_Newcomer = 1,
25 SenFameVIPLevel_UpAndComing = 2,
26 SenFameVIPLevel_Headliner = 3,
27 SenFameVIPLevel_Star = 4,
28 SenFameVIPLevel_Superstar = 5,
29 };
30
31 /// @brief Information about a user's VIP status
32 ///
33 /// @details This structure contains the user's current VIP level and fame points
34 ///
35 struct SenFameVIPData
36 {
37 PlayerUID user; ///< ID for the user whose VIP status this instance describes
38 unsigned int vipLevel; ///< Current VIP level [0-n]
39 unsigned int lastAckedVIPLevel; ///< VIP level last time this structure was acknowledged by a Sentient client
40 unsigned int famePointsCurrent; ///< Fame Points accrued across all Fame titles since the last VIP level passed.
41 unsigned int famePointsWeek; ///< Fame Points accrued across all Fame titles this week.
42 unsigned int famePointsLifetime; ///< Fame Points accrued across all Fame titles over the user's entire history.
43 unsigned int pointsToNextLevel; ///< Incremental Fame Points that must be acquired to gain a new VIP level.
44 unsigned int superstarCounter; ///< Number of times the user has achieved the maximum possible VIP level.
45 SYSTEMTIME vipLevelExpiresAt; ///< Date at which current VIP level will expire. Only relevant when vipLevelExpires is true.
46 bool vipLevelExpires; ///< Whether or not the current VIP level will expire.
47 };
48
49 /// @brief Information about a single row in a Fame leaderboard
50 ///
51 /// @details This structure contains the identity of the user and summary information about their Fame status
52 ///
53 struct SenFameLeaderboardEntry
54 {
55 PlayerUID user; ///< ID for the user this row describes
56 unsigned int vipLevel; ///< Current VIP level[0-n]
57 unsigned int famePoints; ///< Fame Points accrued. May be weekly or lifetime depending on leaderboard type queried.
58 unsigned int superstarCounter; ///< Number of times the user has achieved the maximum possible VIP level.
59 unsigned int rank; ///< Global rank in the leaderboard [1-n]
60 };
61
62 /// @brief Leaderboard query ranking options
63 ///
64 /// @details When querying leaderboards, these are the options for how the leaderboard is ranked.
65 ///
66 enum SenFameLeaderboardRankType
67 {
68 SenFameLeaderboardRankType_Week, ///< Return ranking for fame points earned this week.
69 SenFameLeaderboardRankType_Lifetime, ///< Return ranking for fame points earned all time
70 SenFameLeaderboardRankType_Superstar ///< Return ranking for superstar counter
71 };
72
73 /// @brief Leaderboard query filter options
74 ///
75 /// @details When querying leaderboards, these are the options for how the leaderboard is filtered.
76 ///
77 enum SenFameLeaderboardFilter
78 {
79 SenFameLeaderboardFilter_Everyone = 0, ///< Return the unfiltered leaderboard
80 SenFameLeaderboardFilter_Friends, ///< Filter leaderboard by friends.
81 };
82
83 /// @brief Information about the parameters for a leaderboard query
84 ///
85 /// @details This structure should be filled in to specify parameters for a leaderboard query
86 ///
87 struct SenFameLeaderboardRequest
88 {
89 SenFameLeaderboardRankType type; ///< Ranking option for this query.
90 SenFameLeaderboardFilter filter; ///< Filter option for this query.
91 int startIndex; ///< Rank at which leaderboard query should start. Set to -1 to center on querying user.
92 };
93
94 /// @brief Information about the results of a leaderboard query
95 ///
96 /// @details This structure contains information about the results of a leaderboard query.
97 ///
98 struct SenFameLeaderboardResults
99 {
100 unsigned int playerIndex; ///< When playerIndex < numEntriesReturned, provides the index into result set at which the row for the querying user is located.
101 size_t numEntriesReturned; ///< Number of rows returned by the query.
102 size_t numLeaderboardEntries; ///< Total number of rows in the leaderboard.
103 };
104
105 /// @brief Fame progress (challenge) types
106 ///
107 /// @details Defines a set of well-known challenge types, plus a range for titles to use for their custom challenge types
108 ///
109 enum SenFameProgressID
110 {
111 SenFameProgressID_TitleDefinedFirst = 0, ///< First possible ID for a title-defined challenge.
112 SenFameProgressID_TitleDefinedLast = 1023, ///< Last possible ID for a title-defined challenge.
113
114 SenFameProgressID_FirstPlay = 1024, ///< Challenge tracks the first time a user plays a given title. This challenge is implemented on the Sentient server. Do not submit updates for it.
115 SenFameProgressID_AvatarAward1, ///< Challenge tracks the user receiving the first available Avatar Award. Progress against this challenge must be submitted by titles.
116 SenFameProgressID_AvatarAward2, ///< Challenge tracks the user receiving the second available Avatar Award. Progress against this challenge must be submitted by titles.
117 SenFameProgressID_FriendsOwnTitle,
118
119 // These challenges are not currently implemented. Contact senhelp@microsoft.com before using.
120 SenFameProgressID_MPWithFriend,
121 SenFameProgressID_MPWithVIP1,
122 SenFameProgressID_MPWithVIP2,
123 SenFameProgressID_MPWithVIP3,
124 SenFameProgressID_MPWithVIP4,
125 SenFameProgressID_MPWithVIP5,
126 SenFameProgressID_FriendsAtVIP1,
127 SenFameProgressID_FriendsAtVIP2,
128 SenFameProgressID_FriendsAtVIP3,
129 SenFameProgressID_FriendsAtVIP4,
130 SenFameProgressID_FriendsAtVIP5,
131
132 SenFameProgressID_Invalid = 0xffffffff ///< Reserved identifier for an invalid challenge.
133 };
134
135 /// @brief Constants that may be reported when Fame APIs return a count.
136 enum SenFameCount : unsigned int
137 {
138 SenFameCount_Unbounded = 0xffffffff ///< Indicates that there is no fixed limit on the number of items.
139 };
140
141 /// @brief Information about a granted award (milestone)
142 ///
143 /// @details When querying for awards, this structure will be filled out with summary information about any award granted to the user.
144 struct SenAwardMessageData
145 {
146 wchar_t awardDesc[128]; ///< Localized string containing a message for display.
147 unsigned int awardPoints; ///< Fame Points granted as a result of this award.
148 unsigned int awardTrigger; ///< Progress within the associated Challenge that caused the award to trigger.
149 };
150
151 /// @brief Measures a time period.
152 ///
153 /// @details Provides a display-friendly way to report time differences - e.g. the time until the current Fame week expires.
154 struct SenFameTime
155 {
156 int days;
157 int hours;
158 int minutes;
159 int seconds;
160 };
161
162 /// @brief Information about a user's progress against a single Challenge
163 ///
164 /// @details Provides a display-friendly format for retrieving information about a user's progress against Fame Challenges.
165 ///
166 struct SenFameDisplayData
167 {
168 wchar_t milestoneTypeDescription[128]; ///< Localized string that describes the challenge.
169 SenFameProgressID milestoneTypeID; ///< ID for the Challenge.
170 unsigned int milestoneCount; ///< Total number of milestones (awards) available for this Challenge. May be SenFameCount_Unbounded.
171 unsigned int currentMilestone; ///< Index of the milestone the user is currently working towards (i.e. 0 indicates no milestones have been passed).
172 unsigned int xpSinceLastMilestone; ///< Progress achieved since the last milestone in this Challenge was passed.
173 unsigned int xpToNextMilestone; ///< Progress required to hit the next milestone in this Challenge. Expressed as the progress difference between milestones, i.e. does not vary with xpSinceLastMilestone
174 unsigned int famePointsSoFar; ///< Fame Points achieved in this Challenge.
175 unsigned int famePointsMaximum; ///< Total Fame Points available from this Challenge. May be SenFameCount_Unbounded.
176 bool isWeekly; ///< When true, progress against this Challenge is reset weekly.
177 };
178
179 /// @brief Information about a participant in a multiplayer game.
180 ///
181 /// @details Use for reporting information about multiplayer games to the Sentient server.
182 ///
183 struct SenFameMPGameParticipant
184 {
185 PlayerUID user; ///< ID of a user who should be credited with participation in the game.
186 bool winner; ///< When true, this user should be considered among the winners of the game. There are no restrictions on the number of 'winners' a game may have.
187 };
188
189
190 /**************************
191 ***** Fame Functions *****
192 **************************/
193
194 /// @brief Query the server for VIP status information for a collection of arbitrary users.
195 ///
196 /// @param[in] userIndex
197 /// The index of the initiating user on the console. Note: This is NOT a XUID.
198 ///
199 /// @param[in] userIDCount
200 /// The number of valid XUIDs in @a userIDArray
201 ///
202 /// @param[in] userIDArray
203 /// Users for whom VIP data should be retrieved.
204 ///
205 /// @param[out] out_userFameVIPArray
206 /// The structures to fill in with the retrieved information.
207 /// It is assumed that this is preallocated to at least @a userIDCount entries.
208 ///
209 /// @param[in] userCallback
210 /// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
211 ///
212 /// @param[in] userCallbackData
213 /// Data to be passed to the @a userCallback on completion.
214 ///
215 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
216 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
217 /// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
218 /// E_POINTER: out_userFameVIPArray is NULL.
219 /// SENTIENT_E_TOO_MANY_CALLS: This call has been rejected to avoid excessive server load. Try again later.
220 /// E_FAIL: Failed to spawn server call.
221 /// S_OK: Server call spawned successfully.
222 ///
223 /// @details This overload can be used to retrieve VIP status for friends or remote participants in a multiplayer session.
224 /// For local users, prefer SenGetFameVIPLevel(int, SenFameVIPData*)
225 ///
226 HRESULT SenGetFameVIPLevel(
227 int userIndex,
228 size_t userIDCount,
229 const PlayerUID *userIDArray,
230 SenFameVIPData *out_userFameVIPArray,
231 SenSysCompletedCallback userCallback,
232 void *userCallbackData );
233
234 /// @brief Query for VIP status information for a local user.
235 ///
236 /// @param[in] userIndex
237 /// The index of the initiating user on the console. Note: This is NOT a XUID.
238 ///
239 /// @param[out] out_fameVIPData
240 /// The structure to fill in with the retrieved information.
241 /// It is assumed that this is preallocated to fit at least 1 entry.
242 ///
243 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
244 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
245 /// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
246 /// E_POINTER: out_fameVIPData is NULL.
247 /// SENTIENT_S_OPERATION_IN_PROGRESS: The call could not be completed immediately and out_fameVIPData has not been filled in.
248 /// S_OK: The operation completed successfully.
249 ///
250 /// @details This overload is preferred when retrieving information about local users.
251 /// There are no restrictions on the call frequency and it will typically return immediately.
252 /// In rare cases where SENTIENT_S_OPERATION_IN_PROGRESS is returned the title should call again
253 /// on the next scheduled iteration of their Sentient update loop.
254 ///
255 HRESULT SenGetFameVIPLevel(
256 int userIndex,
257 SenFameVIPData *out_fameVIPData );
258
259 /// @brief Acknowledge a change in user VIP level reported by the server.
260 ///
261 /// @param[in] userIndex
262 /// The index of the initiating user on the console. Note: This is NOT a XUID.
263 ///
264 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
265 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
266 /// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
267 /// E_FAIL: Failed to spawn server call.
268 /// S_OK: Server call spawned successfully.
269 ///
270 /// @details When retrieving user VIP status, the server will include the user's last VIP level
271 /// for which it has not received an acknowledgement message. Titles can use this information
272 /// to highlight changes in VIP level. Once a change has been messaged titles should
273 /// call this API to clear the server state.
274 HRESULT SenAcknowledgeVIPLevelChange(
275 int userIndex );
276
277 /// @brief Query a Fame leaderboard
278 ///
279 /// @param[in] userIndex
280 /// The index of the initiating user on the console. Note: This is NOT a XUID.
281 ///
282 /// @param[in] leaderboardRequest
283 /// Defines the parameters for the leaderboard query.
284 ///
285 /// @param[in] entryCountMax
286 /// The maximum number of leaderboard rows to return.
287 ///
288 /// @param[out] out_entryArray
289 /// The structures to fill in with the rows returned from the leaderboard query.
290 /// It is assumed that this is preallocated to hold at least entryCountMax entries.
291 ///
292 /// @param[out] out_leaderboardResults
293 /// Summary information about the results of the leaderboard query.
294 ///
295 /// @param[out] out_senHandle
296 /// Provides a handle to the async task, which will allow for calling SentientCancel
297 ///
298 /// @param[in] userCallback
299 /// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
300 ///
301 /// @param[in] userCallbackData
302 /// Data to be passed to the @a userCallback on completion.
303 ///
304 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
305 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
306 /// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
307 /// E_POINTER: out_entryArray or out_leaderboardResults is NULL.
308 /// E_INVALIDARG: userCallback is NULL and out_senHandle is non-NULL. Task handles are not supported for synchronous requests.
309 /// SENTIENT_E_TOO_MANY_CALLS: This call has been rejected to avoid excessive server load. Try again later.
310 /// E_FAIL: Failed to spawn server call.
311 /// S_OK: Server call spawned successfully.
312 ///
313 HRESULT SenGetFameLeaderboard(
314 int userIndex,
315 const SenFameLeaderboardRequest &leaderboardRequest,
316 size_t entryCountMax,
317 SenFameLeaderboardEntry *out_entryArray,
318 SenFameLeaderboardResults *out_leaderboardResults,
319 SenHandle *out_senHandle,
320 SenSysCompletedCallback userCallback,
321 void *userCallbackData );
322
323
324 /// @brief Poll for notifications of when a user passes a Fame milestone.
325 ///
326 /// @param[in] userIndex
327 /// The index of the initiating user on the console. Note: This is NOT a XUID.
328 ///
329 /// @param[out] out_awardData
330 /// Structure to fill in with information about any new award.
331 ///
332 /// @return SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
333 /// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
334 /// E_POINTER: out_awardData is NULL.
335 /// SENTIENT_S_OPERATION_IN_PROGRESS: The call could not be completed immediately and out_awardData has not been filled in.
336 /// S_FALSE: The operation completed successfully but there were no awards to report. out_awardData has not been filled in.
337 /// S_OK: The operation completed successfully and there was a valid award to report. out_awardData contains information about the award.
338 ///
339 /// @details There are no restrictions on how frequently this API may be called, and it returnes immediately, so titles should poll
340 /// in all states where they can display award messages. When a message is returned it is popped from an internal queue
341 /// and will not be returned again by further calls.
342 ///
343 HRESULT SenGetAwardMessage(
344 int userIndex,
345 SenAwardMessageData *out_awardData );
346
347 /// @brief Retrieve the time left before weekly fame progress is reset.
348 ///
349 /// @param[out] out_timeRemaining
350 /// Structure to fill in with information about time remaining.
351 ///
352 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
353 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
354 /// E_POINTER: out_timeRemaining is NULL.
355 /// SENTIENT_S_OPERATION_IN_PROGRESS: The call could not be completed immediately and out_timeRemaining has not been filled in.
356 /// E_FAIL: Internal failure. Check log for output.
357 /// S_OK: Call completed successfully and out_timeRemaining has been filled in.
358 ///
359 /// @details Some Fame Challenges are reset weekly. Use this API when displaying a timer for the reset.
360 ///
361 HRESULT SenGetTimeLeftInFameWeek(
362 SenFameTime *out_timeRemaining );
363
364 //
365 /// @brief Retrieve the time left before transient VIP level is reset.
366 ///
367 /// @param[in] userIndex
368 /// The index of the initiating user on the console. Note: This is NOT a XUID.
369 ///
370 /// @param[out] out_timeRemaining
371 /// Structure to fill in with information about time remaining.
372 ///
373 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
374 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
375 /// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
376 /// E_POINTER: out_timeRemaining is NULL.
377 /// SENTIENT_S_OPERATION_IN_PROGRESS: The call could not be completed immediately and out_timeRemaining has not been filled in.
378 /// S_FALSE: The VIP level of the supplied user does not expire. out_timeRemaining has not been filled in.
379 /// E_FAIL: Internal failure. Check log for output.
380 /// S_OK: Call completed successfully and out_timeRemaining has been filled in.
381 ///
382 /// @details Some VIP levels are reset if the user does not actively maintain them. Use this API
383 /// when displaying a timer for the reset.
384 ///
385 HRESULT SenGetTimeLeftInVIPLevel(
386 int userIndex,
387 SenFameTime *out_timeRemaining );
388
389 /// @brief Get a localized string that names the given VIP level.
390 ///
391 /// @param[in] vipLevel
392 /// The level whose name should be returned.
393 ///
394 /// @param[in] maxNameLength
395 /// The maximum length (including null terminating character) of the string to return.
396 ///
397 /// @param[out] out_name
398 /// The string to fill in with the VIP level name.
399 /// It is assumed that this is preallocated to fit at least @a maxNameLength characters.
400 ///
401 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
402 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
403 /// E_POINTER: out_name is NULL.
404 /// E_INVALIDARG: vipLevel is outside the range of known VIP levels.
405 /// SENTIENT_S_OPERATION_IN_PROGRESS: The call could not be completed immediately and out_name has not been filled in.
406 /// S_OK: The operation completed successfully.
407 ///
408 /// @details Titles can use this API to get the server-defined name for a VIP level for additional flexibility post-release.
409 /// In rare cases where SENTIENT_S_OPERATION_IN_PROGRESS is returned the title should call again
410 /// on the next scheduled iteration of their Sentient update loop.
411 ///
412 HRESULT SenGetVIPLevelName(
413 unsigned int vipLevel,
414 size_t maxNameLength,
415 wchar_t *out_name);
416
417
418 /// @brief Get the maximum number of items that will be returned by a call to SenGetFameDisplayData
419 ///
420 /// @param[out] out_count
421 /// Location to be filled in with the number of display data items available.
422 ///
423 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
424 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
425 /// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
426 /// E_POINTER: out_count is NULL.
427 /// SENTIENT_S_OPERATION_IN_PROGRESS: The call could not be completed immediately and out_count has not been filled in.
428 /// E_FAIL: Internal failure. Check log for output.
429 /// S_OK: The operation completed successfully.
430 ///
431 /// @details Titles can use this API to ensure that they allocate a buffer of appropriate size
432 /// before making a call to SenGetFameDisplayData.
433 ///
434 HRESULT SenGetFameDisplayDataCount(
435 size_t *out_count );
436
437 /// @brief Retrieve a summary of a user's progress against Fame Challenges.
438 ///
439 /// @param[in] userIndex
440 /// The index of the initiating user on the console. Note: This is NOT a XUID.
441 ///
442 /// @param[in] startIndex
443 /// Global index of first item to return.
444 /// This parameter can be used to support results paging.
445 ///
446 /// @param[in] maxDisplayDataCount
447 /// Maximum number of items to return.
448 ///
449 /// @param[out] out_dataCount
450 /// Location to fill in with number of items actually returned.
451 ///
452 /// @param[out] out_displayData
453 /// The structures to fill in with the retrieved information.
454 /// It is assumed that this is preallocated to at least @a maxDisplayDataCount entries.
455 ///
456 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
457 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
458 /// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
459 /// E_POINTER: out_dataCount or out_displayData is NULL.
460 /// E_INVALIDARG: startIndex is greater than the total number of items available.
461 /// SENTIENT_S_OPERATION_IN_PROGRESS: The call could not be completed immediately and output parameters have not been filled in.
462 /// E_FAIL: Internal failure. Check log for output.
463 /// S_OK: The operation completed successfully.
464 ///
465 /// @details For titles with weekly Challenge rotations, only Challenges active for the current week are reported.
466 /// Use SenGetFameDisplayDataCount() to dynamically size a buffer large enough to obtain all the display data entries
467 /// in a single call, or use the startIndex parameter for paging.
468 ///
469 HRESULT SenGetFameDisplayData(
470 int userIndex,
471 size_t startIndex,
472 size_t maxDisplayDataCount,
473 size_t *out_dataCount,
474 SenFameDisplayData *out_displayData );
475
476 /// @brief Notify Sentient about user progress against a Fame Challenge.
477 ///
478 /// @param[in] userIndex
479 /// The index of the initiating user on the console. Note: This is NOT a XUID.
480 ///
481 /// @param[in] milestoneTypeID
482 /// The id of the Challenge for which progress has been achieved.
483 ///
484 /// @param[in] xpGained
485 /// Incremental progress. For binary milestones this can be safely set to 1 each time the awarding event takes place.
486 ///
487 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
488 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
489 /// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
490 /// SENTIENT_E_BUFFER_EXHAUSTED: The progress update failed because Sentient's internal buffer is full.
491 /// E_FAIL: Internal failure. Check log for output.
492 /// S_OK: The operation completed successfully.
493 ///
494 /// @details Titles should call this API whenever a user makes progress against a Fame Challenge. Long-term storage for progress exists
495 /// on the Sentient server, but it may be buffered on the client to prevent excessive server load. Titles should call
496 /// SenFlushFameProgress as appropriate (e.g. on game save) to ensure that all progress writes are committed to the server.
497 /// Titles should not submit updates against Fame Challenges whose progress is determined by the server(e.g. First Play)
498 HRESULT SenUpdateFameProgress(
499 int userIndex,
500 unsigned int milestoneTypeID,
501 unsigned int xpGained );
502
503 /// @brief Ensure that all progress writes are committed to the Sentient server.
504 ///
505 /// @param[in] userIndex
506 /// The index of the initiating user on the console. Note: This is NOT a XUID.
507 ///
508 /// @param[in] userCallback
509 /// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
510 ///
511 /// @param[in] userCallbackData
512 /// Data to be passed to the @a userCallback on completion.
513 ///
514 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
515 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
516 /// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
517 /// SENTIENT_E_TOO_MANY_CALLS: This call has been rejected to avoid excessive server load. Try again later.
518 /// E_FAIL: Failed to spawn server call. This may be because there is already a flush scheduled.
519 /// S_OK: The operation completed successfully.
520 ///
521 /// @details Long-term storage for progress exists on the Sentient server, but it may be buffered on the client to
522 /// prevent excessive server load. Titles should call this API as appropriate (e.g. on game save) to ensure
523 /// that all progress writes are committed to the server. The callback parameters provide a mechanism for
524 /// detecting when the server call has completed and updating user interface appropriately.
525 /// When there is no local data that needs flushing, the supplied callback will be invoked before execution
526 /// returns from this function, and the return code will be S_OK.
527 ///
528 HRESULT SenFlushFameProgress(
529 int userIndex,
530 SenSysCompletedCallback userCallback,
531 void *userCallbackData );
532
533 /// @brief Inform the Sentient server about the results of a multiplayer game.
534 ///
535 /// @param[in] userIndex
536 /// The index of the initiating user on the console. Note: This is NOT a XUID.
537 ///
538 /// @param[in] participantCount
539 /// The number of valid items in @a participants.
540 ///
541 /// @param[in] participants
542 /// Structures describing the users who participated in this multiplayer game.
543 ///
544 /// @param[out] out_senHandle
545 /// Provides a handle to the async task, which will allow for calling SentientCancel
546 ///
547 /// @param[in] userCallback
548 /// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
549 ///
550 /// @param[in] userCallbackData
551 /// Data to be passed to the @a userCallback on completion.
552 ///
553 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
554 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
555 /// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
556 /// E_INVALIDARG: Either userCallback is NULL and out_senHandle is non-NULL, or participantCount is less than 2.
557 /// E_POINTER: participants is NULL.
558 /// E_FAIL: Failed to spawn server call.
559 /// S_OK: Server call spawned successfully.
560 ///
561 /// @details Titles should report multiplayer sessions to the Sentient server via this API in order to support
562 /// tracking of progress against certain Fame Challenges. For proper tracking each user in the multiplayer
563 /// session should independently call this function on completion of a game.
564 HRESULT SenRegisterFameMPGame(
565 int userIndex,
566 size_t participantCount,
567 const SenFameMPGameParticipant *participants,
568 SenHandle *out_senHandle,
569 SenSysCompletedCallback userCallback,
570 void *userCallbackData );
571
572} // namespace Sentient