573 lines
28 KiB
C++
573 lines
28 KiB
C++
/********************************************************
|
|
* *
|
|
* Copyright (C) Microsoft. All rights reserved. *
|
|
* *
|
|
********************************************************/
|
|
|
|
// Sentient Client AvatarSuperstars Fame API
|
|
//
|
|
// Include this to get access to all Fame-related Sentient features.
|
|
|
|
#pragma once
|
|
|
|
#include "SenClientSys.h"
|
|
|
|
namespace Sentient
|
|
{
|
|
/**********************
|
|
***** Fame Types *****
|
|
**********************/
|
|
enum SenFameVIPLevel
|
|
{
|
|
SenFameVIPLevel_Unknown = 0xFFFFFFFF,
|
|
SenFameVIPLevel_Fan = 0,
|
|
SenFameVIPLevel_Newcomer = 1,
|
|
SenFameVIPLevel_UpAndComing = 2,
|
|
SenFameVIPLevel_Headliner = 3,
|
|
SenFameVIPLevel_Star = 4,
|
|
SenFameVIPLevel_Superstar = 5,
|
|
};
|
|
|
|
/// @brief Information about a user's VIP status
|
|
///
|
|
/// @details This structure contains the user's current VIP level and fame points
|
|
///
|
|
struct SenFameVIPData
|
|
{
|
|
PlayerUID user; ///< ID for the user whose VIP status this instance describes
|
|
unsigned int vipLevel; ///< Current VIP level [0-n]
|
|
unsigned int lastAckedVIPLevel; ///< VIP level last time this structure was acknowledged by a Sentient client
|
|
unsigned int famePointsCurrent; ///< Fame Points accrued across all Fame titles since the last VIP level passed.
|
|
unsigned int famePointsWeek; ///< Fame Points accrued across all Fame titles this week.
|
|
unsigned int famePointsLifetime; ///< Fame Points accrued across all Fame titles over the user's entire history.
|
|
unsigned int pointsToNextLevel; ///< Incremental Fame Points that must be acquired to gain a new VIP level.
|
|
unsigned int superstarCounter; ///< Number of times the user has achieved the maximum possible VIP level.
|
|
SYSTEMTIME vipLevelExpiresAt; ///< Date at which current VIP level will expire. Only relevant when vipLevelExpires is true.
|
|
bool vipLevelExpires; ///< Whether or not the current VIP level will expire.
|
|
};
|
|
|
|
/// @brief Information about a single row in a Fame leaderboard
|
|
///
|
|
/// @details This structure contains the identity of the user and summary information about their Fame status
|
|
///
|
|
struct SenFameLeaderboardEntry
|
|
{
|
|
PlayerUID user; ///< ID for the user this row describes
|
|
unsigned int vipLevel; ///< Current VIP level[0-n]
|
|
unsigned int famePoints; ///< Fame Points accrued. May be weekly or lifetime depending on leaderboard type queried.
|
|
unsigned int superstarCounter; ///< Number of times the user has achieved the maximum possible VIP level.
|
|
unsigned int rank; ///< Global rank in the leaderboard [1-n]
|
|
};
|
|
|
|
/// @brief Leaderboard query ranking options
|
|
///
|
|
/// @details When querying leaderboards, these are the options for how the leaderboard is ranked.
|
|
///
|
|
enum SenFameLeaderboardRankType
|
|
{
|
|
SenFameLeaderboardRankType_Week, ///< Return ranking for fame points earned this week.
|
|
SenFameLeaderboardRankType_Lifetime, ///< Return ranking for fame points earned all time
|
|
SenFameLeaderboardRankType_Superstar ///< Return ranking for superstar counter
|
|
};
|
|
|
|
/// @brief Leaderboard query filter options
|
|
///
|
|
/// @details When querying leaderboards, these are the options for how the leaderboard is filtered.
|
|
///
|
|
enum SenFameLeaderboardFilter
|
|
{
|
|
SenFameLeaderboardFilter_Everyone = 0, ///< Return the unfiltered leaderboard
|
|
SenFameLeaderboardFilter_Friends, ///< Filter leaderboard by friends.
|
|
};
|
|
|
|
/// @brief Information about the parameters for a leaderboard query
|
|
///
|
|
/// @details This structure should be filled in to specify parameters for a leaderboard query
|
|
///
|
|
struct SenFameLeaderboardRequest
|
|
{
|
|
SenFameLeaderboardRankType type; ///< Ranking option for this query.
|
|
SenFameLeaderboardFilter filter; ///< Filter option for this query.
|
|
int startIndex; ///< Rank at which leaderboard query should start. Set to -1 to center on querying user.
|
|
};
|
|
|
|
/// @brief Information about the results of a leaderboard query
|
|
///
|
|
/// @details This structure contains information about the results of a leaderboard query.
|
|
///
|
|
struct SenFameLeaderboardResults
|
|
{
|
|
unsigned int playerIndex; ///< When playerIndex < numEntriesReturned, provides the index into result set at which the row for the querying user is located.
|
|
size_t numEntriesReturned; ///< Number of rows returned by the query.
|
|
size_t numLeaderboardEntries; ///< Total number of rows in the leaderboard.
|
|
};
|
|
|
|
/// @brief Fame progress (challenge) types
|
|
///
|
|
/// @details Defines a set of well-known challenge types, plus a range for titles to use for their custom challenge types
|
|
///
|
|
enum SenFameProgressID
|
|
{
|
|
SenFameProgressID_TitleDefinedFirst = 0, ///< First possible ID for a title-defined challenge.
|
|
SenFameProgressID_TitleDefinedLast = 1023, ///< Last possible ID for a title-defined challenge.
|
|
|
|
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.
|
|
SenFameProgressID_AvatarAward1, ///< Challenge tracks the user receiving the first available Avatar Award. Progress against this challenge must be submitted by titles.
|
|
SenFameProgressID_AvatarAward2, ///< Challenge tracks the user receiving the second available Avatar Award. Progress against this challenge must be submitted by titles.
|
|
SenFameProgressID_FriendsOwnTitle,
|
|
|
|
// These challenges are not currently implemented. Contact senhelp@microsoft.com before using.
|
|
SenFameProgressID_MPWithFriend,
|
|
SenFameProgressID_MPWithVIP1,
|
|
SenFameProgressID_MPWithVIP2,
|
|
SenFameProgressID_MPWithVIP3,
|
|
SenFameProgressID_MPWithVIP4,
|
|
SenFameProgressID_MPWithVIP5,
|
|
SenFameProgressID_FriendsAtVIP1,
|
|
SenFameProgressID_FriendsAtVIP2,
|
|
SenFameProgressID_FriendsAtVIP3,
|
|
SenFameProgressID_FriendsAtVIP4,
|
|
SenFameProgressID_FriendsAtVIP5,
|
|
|
|
SenFameProgressID_Invalid = 0xffffffff ///< Reserved identifier for an invalid challenge.
|
|
};
|
|
|
|
/// @brief Constants that may be reported when Fame APIs return a count.
|
|
enum SenFameCount : unsigned int
|
|
{
|
|
SenFameCount_Unbounded = 0xffffffff ///< Indicates that there is no fixed limit on the number of items.
|
|
};
|
|
|
|
/// @brief Information about a granted award (milestone)
|
|
///
|
|
/// @details When querying for awards, this structure will be filled out with summary information about any award granted to the user.
|
|
struct SenAwardMessageData
|
|
{
|
|
wchar_t awardDesc[128]; ///< Localized string containing a message for display.
|
|
unsigned int awardPoints; ///< Fame Points granted as a result of this award.
|
|
unsigned int awardTrigger; ///< Progress within the associated Challenge that caused the award to trigger.
|
|
};
|
|
|
|
/// @brief Measures a time period.
|
|
///
|
|
/// @details Provides a display-friendly way to report time differences - e.g. the time until the current Fame week expires.
|
|
struct SenFameTime
|
|
{
|
|
int days;
|
|
int hours;
|
|
int minutes;
|
|
int seconds;
|
|
};
|
|
|
|
/// @brief Information about a user's progress against a single Challenge
|
|
///
|
|
/// @details Provides a display-friendly format for retrieving information about a user's progress against Fame Challenges.
|
|
///
|
|
struct SenFameDisplayData
|
|
{
|
|
wchar_t milestoneTypeDescription[128]; ///< Localized string that describes the challenge.
|
|
SenFameProgressID milestoneTypeID; ///< ID for the Challenge.
|
|
unsigned int milestoneCount; ///< Total number of milestones (awards) available for this Challenge. May be SenFameCount_Unbounded.
|
|
unsigned int currentMilestone; ///< Index of the milestone the user is currently working towards (i.e. 0 indicates no milestones have been passed).
|
|
unsigned int xpSinceLastMilestone; ///< Progress achieved since the last milestone in this Challenge was passed.
|
|
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
|
|
unsigned int famePointsSoFar; ///< Fame Points achieved in this Challenge.
|
|
unsigned int famePointsMaximum; ///< Total Fame Points available from this Challenge. May be SenFameCount_Unbounded.
|
|
bool isWeekly; ///< When true, progress against this Challenge is reset weekly.
|
|
};
|
|
|
|
/// @brief Information about a participant in a multiplayer game.
|
|
///
|
|
/// @details Use for reporting information about multiplayer games to the Sentient server.
|
|
///
|
|
struct SenFameMPGameParticipant
|
|
{
|
|
PlayerUID user; ///< ID of a user who should be credited with participation in the game.
|
|
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.
|
|
};
|
|
|
|
|
|
/**************************
|
|
***** Fame Functions *****
|
|
**************************/
|
|
|
|
/// @brief Query the server for VIP status information for a collection of arbitrary users.
|
|
///
|
|
/// @param[in] userIndex
|
|
/// The index of the initiating user on the console. Note: This is NOT a XUID.
|
|
///
|
|
/// @param[in] userIDCount
|
|
/// The number of valid XUIDs in @a userIDArray
|
|
///
|
|
/// @param[in] userIDArray
|
|
/// Users for whom VIP data should be retrieved.
|
|
///
|
|
/// @param[out] out_userFameVIPArray
|
|
/// The structures to fill in with the retrieved information.
|
|
/// It is assumed that this is preallocated to at least @a userIDCount entries.
|
|
///
|
|
/// @param[in] userCallback
|
|
/// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
|
|
///
|
|
/// @param[in] userCallbackData
|
|
/// Data to be passed to the @a userCallback on completion.
|
|
///
|
|
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
|
|
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
|
|
/// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
|
|
/// E_POINTER: out_userFameVIPArray is NULL.
|
|
/// SENTIENT_E_TOO_MANY_CALLS: This call has been rejected to avoid excessive server load. Try again later.
|
|
/// E_FAIL: Failed to spawn server call.
|
|
/// S_OK: Server call spawned successfully.
|
|
///
|
|
/// @details This overload can be used to retrieve VIP status for friends or remote participants in a multiplayer session.
|
|
/// For local users, prefer SenGetFameVIPLevel(int, SenFameVIPData*)
|
|
///
|
|
HRESULT SenGetFameVIPLevel(
|
|
int userIndex,
|
|
size_t userIDCount,
|
|
const PlayerUID *userIDArray,
|
|
SenFameVIPData *out_userFameVIPArray,
|
|
SenSysCompletedCallback userCallback,
|
|
void *userCallbackData );
|
|
|
|
/// @brief Query for VIP status information for a local user.
|
|
///
|
|
/// @param[in] userIndex
|
|
/// The index of the initiating user on the console. Note: This is NOT a XUID.
|
|
///
|
|
/// @param[out] out_fameVIPData
|
|
/// The structure to fill in with the retrieved information.
|
|
/// It is assumed that this is preallocated to fit at least 1 entry.
|
|
///
|
|
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
|
|
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
|
|
/// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
|
|
/// E_POINTER: out_fameVIPData is NULL.
|
|
/// SENTIENT_S_OPERATION_IN_PROGRESS: The call could not be completed immediately and out_fameVIPData has not been filled in.
|
|
/// S_OK: The operation completed successfully.
|
|
///
|
|
/// @details This overload is preferred when retrieving information about local users.
|
|
/// There are no restrictions on the call frequency and it will typically return immediately.
|
|
/// In rare cases where SENTIENT_S_OPERATION_IN_PROGRESS is returned the title should call again
|
|
/// on the next scheduled iteration of their Sentient update loop.
|
|
///
|
|
HRESULT SenGetFameVIPLevel(
|
|
int userIndex,
|
|
SenFameVIPData *out_fameVIPData );
|
|
|
|
/// @brief Acknowledge a change in user VIP level reported by the server.
|
|
///
|
|
/// @param[in] userIndex
|
|
/// The index of the initiating user on the console. Note: This is NOT a XUID.
|
|
///
|
|
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
|
|
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
|
|
/// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
|
|
/// E_FAIL: Failed to spawn server call.
|
|
/// S_OK: Server call spawned successfully.
|
|
///
|
|
/// @details When retrieving user VIP status, the server will include the user's last VIP level
|
|
/// for which it has not received an acknowledgement message. Titles can use this information
|
|
/// to highlight changes in VIP level. Once a change has been messaged titles should
|
|
/// call this API to clear the server state.
|
|
HRESULT SenAcknowledgeVIPLevelChange(
|
|
int userIndex );
|
|
|
|
/// @brief Query a Fame leaderboard
|
|
///
|
|
/// @param[in] userIndex
|
|
/// The index of the initiating user on the console. Note: This is NOT a XUID.
|
|
///
|
|
/// @param[in] leaderboardRequest
|
|
/// Defines the parameters for the leaderboard query.
|
|
///
|
|
/// @param[in] entryCountMax
|
|
/// The maximum number of leaderboard rows to return.
|
|
///
|
|
/// @param[out] out_entryArray
|
|
/// The structures to fill in with the rows returned from the leaderboard query.
|
|
/// It is assumed that this is preallocated to hold at least entryCountMax entries.
|
|
///
|
|
/// @param[out] out_leaderboardResults
|
|
/// Summary information about the results of the leaderboard query.
|
|
///
|
|
/// @param[out] out_senHandle
|
|
/// Provides a handle to the async task, which will allow for calling SentientCancel
|
|
///
|
|
/// @param[in] userCallback
|
|
/// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
|
|
///
|
|
/// @param[in] userCallbackData
|
|
/// Data to be passed to the @a userCallback on completion.
|
|
///
|
|
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
|
|
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
|
|
/// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
|
|
/// E_POINTER: out_entryArray or out_leaderboardResults is NULL.
|
|
/// E_INVALIDARG: userCallback is NULL and out_senHandle is non-NULL. Task handles are not supported for synchronous requests.
|
|
/// SENTIENT_E_TOO_MANY_CALLS: This call has been rejected to avoid excessive server load. Try again later.
|
|
/// E_FAIL: Failed to spawn server call.
|
|
/// S_OK: Server call spawned successfully.
|
|
///
|
|
HRESULT SenGetFameLeaderboard(
|
|
int userIndex,
|
|
const SenFameLeaderboardRequest &leaderboardRequest,
|
|
size_t entryCountMax,
|
|
SenFameLeaderboardEntry *out_entryArray,
|
|
SenFameLeaderboardResults *out_leaderboardResults,
|
|
SenHandle *out_senHandle,
|
|
SenSysCompletedCallback userCallback,
|
|
void *userCallbackData );
|
|
|
|
|
|
/// @brief Poll for notifications of when a user passes a Fame milestone.
|
|
///
|
|
/// @param[in] userIndex
|
|
/// The index of the initiating user on the console. Note: This is NOT a XUID.
|
|
///
|
|
/// @param[out] out_awardData
|
|
/// Structure to fill in with information about any new award.
|
|
///
|
|
/// @return SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
|
|
/// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
|
|
/// E_POINTER: out_awardData is NULL.
|
|
/// SENTIENT_S_OPERATION_IN_PROGRESS: The call could not be completed immediately and out_awardData has not been filled in.
|
|
/// S_FALSE: The operation completed successfully but there were no awards to report. out_awardData has not been filled in.
|
|
/// S_OK: The operation completed successfully and there was a valid award to report. out_awardData contains information about the award.
|
|
///
|
|
/// @details There are no restrictions on how frequently this API may be called, and it returnes immediately, so titles should poll
|
|
/// in all states where they can display award messages. When a message is returned it is popped from an internal queue
|
|
/// and will not be returned again by further calls.
|
|
///
|
|
HRESULT SenGetAwardMessage(
|
|
int userIndex,
|
|
SenAwardMessageData *out_awardData );
|
|
|
|
/// @brief Retrieve the time left before weekly fame progress is reset.
|
|
///
|
|
/// @param[out] out_timeRemaining
|
|
/// Structure to fill in with information about time remaining.
|
|
///
|
|
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
|
|
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
|
|
/// E_POINTER: out_timeRemaining is NULL.
|
|
/// SENTIENT_S_OPERATION_IN_PROGRESS: The call could not be completed immediately and out_timeRemaining has not been filled in.
|
|
/// E_FAIL: Internal failure. Check log for output.
|
|
/// S_OK: Call completed successfully and out_timeRemaining has been filled in.
|
|
///
|
|
/// @details Some Fame Challenges are reset weekly. Use this API when displaying a timer for the reset.
|
|
///
|
|
HRESULT SenGetTimeLeftInFameWeek(
|
|
SenFameTime *out_timeRemaining );
|
|
|
|
//
|
|
/// @brief Retrieve the time left before transient VIP level is reset.
|
|
///
|
|
/// @param[in] userIndex
|
|
/// The index of the initiating user on the console. Note: This is NOT a XUID.
|
|
///
|
|
/// @param[out] out_timeRemaining
|
|
/// Structure to fill in with information about time remaining.
|
|
///
|
|
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
|
|
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
|
|
/// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
|
|
/// E_POINTER: out_timeRemaining is NULL.
|
|
/// SENTIENT_S_OPERATION_IN_PROGRESS: The call could not be completed immediately and out_timeRemaining has not been filled in.
|
|
/// S_FALSE: The VIP level of the supplied user does not expire. out_timeRemaining has not been filled in.
|
|
/// E_FAIL: Internal failure. Check log for output.
|
|
/// S_OK: Call completed successfully and out_timeRemaining has been filled in.
|
|
///
|
|
/// @details Some VIP levels are reset if the user does not actively maintain them. Use this API
|
|
/// when displaying a timer for the reset.
|
|
///
|
|
HRESULT SenGetTimeLeftInVIPLevel(
|
|
int userIndex,
|
|
SenFameTime *out_timeRemaining );
|
|
|
|
/// @brief Get a localized string that names the given VIP level.
|
|
///
|
|
/// @param[in] vipLevel
|
|
/// The level whose name should be returned.
|
|
///
|
|
/// @param[in] maxNameLength
|
|
/// The maximum length (including null terminating character) of the string to return.
|
|
///
|
|
/// @param[out] out_name
|
|
/// The string to fill in with the VIP level name.
|
|
/// It is assumed that this is preallocated to fit at least @a maxNameLength characters.
|
|
///
|
|
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
|
|
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
|
|
/// E_POINTER: out_name is NULL.
|
|
/// E_INVALIDARG: vipLevel is outside the range of known VIP levels.
|
|
/// SENTIENT_S_OPERATION_IN_PROGRESS: The call could not be completed immediately and out_name has not been filled in.
|
|
/// S_OK: The operation completed successfully.
|
|
///
|
|
/// @details Titles can use this API to get the server-defined name for a VIP level for additional flexibility post-release.
|
|
/// In rare cases where SENTIENT_S_OPERATION_IN_PROGRESS is returned the title should call again
|
|
/// on the next scheduled iteration of their Sentient update loop.
|
|
///
|
|
HRESULT SenGetVIPLevelName(
|
|
unsigned int vipLevel,
|
|
size_t maxNameLength,
|
|
wchar_t *out_name);
|
|
|
|
|
|
/// @brief Get the maximum number of items that will be returned by a call to SenGetFameDisplayData
|
|
///
|
|
/// @param[out] out_count
|
|
/// Location to be filled in with the number of display data items available.
|
|
///
|
|
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
|
|
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
|
|
/// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
|
|
/// E_POINTER: out_count is NULL.
|
|
/// SENTIENT_S_OPERATION_IN_PROGRESS: The call could not be completed immediately and out_count has not been filled in.
|
|
/// E_FAIL: Internal failure. Check log for output.
|
|
/// S_OK: The operation completed successfully.
|
|
///
|
|
/// @details Titles can use this API to ensure that they allocate a buffer of appropriate size
|
|
/// before making a call to SenGetFameDisplayData.
|
|
///
|
|
HRESULT SenGetFameDisplayDataCount(
|
|
size_t *out_count );
|
|
|
|
/// @brief Retrieve a summary of a user's progress against Fame Challenges.
|
|
///
|
|
/// @param[in] userIndex
|
|
/// The index of the initiating user on the console. Note: This is NOT a XUID.
|
|
///
|
|
/// @param[in] startIndex
|
|
/// Global index of first item to return.
|
|
/// This parameter can be used to support results paging.
|
|
///
|
|
/// @param[in] maxDisplayDataCount
|
|
/// Maximum number of items to return.
|
|
///
|
|
/// @param[out] out_dataCount
|
|
/// Location to fill in with number of items actually returned.
|
|
///
|
|
/// @param[out] out_displayData
|
|
/// The structures to fill in with the retrieved information.
|
|
/// It is assumed that this is preallocated to at least @a maxDisplayDataCount entries.
|
|
///
|
|
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
|
|
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
|
|
/// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
|
|
/// E_POINTER: out_dataCount or out_displayData is NULL.
|
|
/// E_INVALIDARG: startIndex is greater than the total number of items available.
|
|
/// SENTIENT_S_OPERATION_IN_PROGRESS: The call could not be completed immediately and output parameters have not been filled in.
|
|
/// E_FAIL: Internal failure. Check log for output.
|
|
/// S_OK: The operation completed successfully.
|
|
///
|
|
/// @details For titles with weekly Challenge rotations, only Challenges active for the current week are reported.
|
|
/// Use SenGetFameDisplayDataCount() to dynamically size a buffer large enough to obtain all the display data entries
|
|
/// in a single call, or use the startIndex parameter for paging.
|
|
///
|
|
HRESULT SenGetFameDisplayData(
|
|
int userIndex,
|
|
size_t startIndex,
|
|
size_t maxDisplayDataCount,
|
|
size_t *out_dataCount,
|
|
SenFameDisplayData *out_displayData );
|
|
|
|
/// @brief Notify Sentient about user progress against a Fame Challenge.
|
|
///
|
|
/// @param[in] userIndex
|
|
/// The index of the initiating user on the console. Note: This is NOT a XUID.
|
|
///
|
|
/// @param[in] milestoneTypeID
|
|
/// The id of the Challenge for which progress has been achieved.
|
|
///
|
|
/// @param[in] xpGained
|
|
/// Incremental progress. For binary milestones this can be safely set to 1 each time the awarding event takes place.
|
|
///
|
|
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
|
|
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
|
|
/// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
|
|
/// SENTIENT_E_BUFFER_EXHAUSTED: The progress update failed because Sentient's internal buffer is full.
|
|
/// E_FAIL: Internal failure. Check log for output.
|
|
/// S_OK: The operation completed successfully.
|
|
///
|
|
/// @details Titles should call this API whenever a user makes progress against a Fame Challenge. Long-term storage for progress exists
|
|
/// on the Sentient server, but it may be buffered on the client to prevent excessive server load. Titles should call
|
|
/// SenFlushFameProgress as appropriate (e.g. on game save) to ensure that all progress writes are committed to the server.
|
|
/// Titles should not submit updates against Fame Challenges whose progress is determined by the server(e.g. First Play)
|
|
HRESULT SenUpdateFameProgress(
|
|
int userIndex,
|
|
unsigned int milestoneTypeID,
|
|
unsigned int xpGained );
|
|
|
|
/// @brief Ensure that all progress writes are committed to the Sentient server.
|
|
///
|
|
/// @param[in] userIndex
|
|
/// The index of the initiating user on the console. Note: This is NOT a XUID.
|
|
///
|
|
/// @param[in] userCallback
|
|
/// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
|
|
///
|
|
/// @param[in] userCallbackData
|
|
/// Data to be passed to the @a userCallback on completion.
|
|
///
|
|
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
|
|
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
|
|
/// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
|
|
/// SENTIENT_E_TOO_MANY_CALLS: This call has been rejected to avoid excessive server load. Try again later.
|
|
/// E_FAIL: Failed to spawn server call. This may be because there is already a flush scheduled.
|
|
/// S_OK: The operation completed successfully.
|
|
///
|
|
/// @details Long-term storage for progress exists on the Sentient server, but it may be buffered on the client to
|
|
/// prevent excessive server load. Titles should call this API as appropriate (e.g. on game save) to ensure
|
|
/// that all progress writes are committed to the server. The callback parameters provide a mechanism for
|
|
/// detecting when the server call has completed and updating user interface appropriately.
|
|
/// When there is no local data that needs flushing, the supplied callback will be invoked before execution
|
|
/// returns from this function, and the return code will be S_OK.
|
|
///
|
|
HRESULT SenFlushFameProgress(
|
|
int userIndex,
|
|
SenSysCompletedCallback userCallback,
|
|
void *userCallbackData );
|
|
|
|
/// @brief Inform the Sentient server about the results of a multiplayer game.
|
|
///
|
|
/// @param[in] userIndex
|
|
/// The index of the initiating user on the console. Note: This is NOT a XUID.
|
|
///
|
|
/// @param[in] participantCount
|
|
/// The number of valid items in @a participants.
|
|
///
|
|
/// @param[in] participants
|
|
/// Structures describing the users who participated in this multiplayer game.
|
|
///
|
|
/// @param[out] out_senHandle
|
|
/// Provides a handle to the async task, which will allow for calling SentientCancel
|
|
///
|
|
/// @param[in] userCallback
|
|
/// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
|
|
///
|
|
/// @param[in] userCallbackData
|
|
/// Data to be passed to the @a userCallback on completion.
|
|
///
|
|
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
|
|
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
|
|
/// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
|
|
/// E_INVALIDARG: Either userCallback is NULL and out_senHandle is non-NULL, or participantCount is less than 2.
|
|
/// E_POINTER: participants is NULL.
|
|
/// E_FAIL: Failed to spawn server call.
|
|
/// S_OK: Server call spawned successfully.
|
|
///
|
|
/// @details Titles should report multiplayer sessions to the Sentient server via this API in order to support
|
|
/// tracking of progress against certain Fame Challenges. For proper tracking each user in the multiplayer
|
|
/// session should independently call this function on completion of a game.
|
|
HRESULT SenRegisterFameMPGame(
|
|
int userIndex,
|
|
size_t participantCount,
|
|
const SenFameMPGameParticipant *participants,
|
|
SenHandle *out_senHandle,
|
|
SenSysCompletedCallback userCallback,
|
|
void *userCallbackData );
|
|
|
|
} // namespace Sentient
|