From b691c43c44ff180d10e7d4a9afc83b98551ff586 Mon Sep 17 00:00:00 2001 From: daoge_cmd <3523206925@qq.com> Date: Sun, 1 Mar 2026 12:16:08 +0800 Subject: Initial commit --- .../Xbox/Sentient/Include/SenClientAvatar.h | 419 +++++++++++++++++++++ 1 file changed, 419 insertions(+) create mode 100644 Minecraft.Client/Xbox/Sentient/Include/SenClientAvatar.h (limited to 'Minecraft.Client/Xbox/Sentient/Include/SenClientAvatar.h') diff --git a/Minecraft.Client/Xbox/Sentient/Include/SenClientAvatar.h b/Minecraft.Client/Xbox/Sentient/Include/SenClientAvatar.h new file mode 100644 index 00000000..dfccfd3b --- /dev/null +++ b/Minecraft.Client/Xbox/Sentient/Include/SenClientAvatar.h @@ -0,0 +1,419 @@ +/******************************************************** +* * +* Copyright (C) Microsoft. All rights reserved. * +* * +********************************************************/ + +// Sentient Client AvatarSuperstars Avatar API +// +// Include this to get access to all Avatar-related Sentient features. + +#pragma once + +#include "SenClientRawData.h" +#include "SenClientResource.h" +#include "SenClientSys.h" +#include "SenClientXML.h" + +#include +#include + +namespace Sentient +{ + //====================// + // // + // Avatar Types // + // // + //====================// + + // When enumerating avatars, these are the options for pre-sorting the + // returned list. + enum SenAvatarSortBy + { + SenAvatarSortBy_Default = 0, + // ... TBD ... + + }; + + // This structure contains the information needed to download the + // raw data for a given gender. + struct SenAvatarGenderInfo + { + SenRawDataTransferInfo metadata; + SenRawDataTransferInfo assets; + SenRawDataTransferInfo xml; + SenRawDataTransferInfo icon; + }; + + // This structure contains the original uploaded info plus info + // needed to download raw data. + struct SenAvatarInfo : public SenResourceInfo + { + int vipLevel; + SenAvatarGenderInfo female; + SenAvatarGenderInfo male; + }; + + struct SenAvatarPalette + { + XMCOLOR entry[3]; + }; + + struct SenAvatarNamedPalette : SenAvatarPalette + { + wchar_t name[57+1]; + }; + + /// @brief Extra avatar information. + /// + /// @details This structure contains additional data about the avatar, such as localized strings and palettes. + /// + struct SenAvatarExtraInfo + { + wchar_t title[XMARKETPLACE_MAX_TITLE_NAME_LENGTH+1]; ///< The localized game title associated with the avatar. + wchar_t name[XMARKETPLACE_MAX_OFFER_NAME_LENGTH+1]; ///< The localized name associated with the avatar. + wchar_t description[XMARKETPLACE_MAX_OFFER_SELL_TEXT_LENGTH+1]; ///< The localized short description associated with the avatar. + + size_t paletteCount; + SenAvatarNamedPalette palette[16]; + }; + + //========================// + // // + // Avatar Functions // + // // + //========================// + + /// @brief Search the database for all the avatars that match the search criteria. + /// + /// @param[in] userIndex + /// The index of the initiating user on the console. Note: This is NOT a XUID. + /// + /// @param[in] avatarInfoCountMax + /// The number of SenAvatarInfo structures available in @a out_avatarInfoList. + /// + /// @param[out] out_avatarInfoCount + /// This is the number of entries actually enumerated by the call. + /// + /// @param[out] out_avatarInfoList + /// The structures to fill in with the enumerated information. + /// It is assumed that this is preallocated to at least @a avatarInfoCountMax 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_avatarInfoList is NULL. + /// E_FAIL: Failed to spawn server call. + /// S_OK: Server call spawned successfully. + /// + /// @details Enumerates in default order, at the current time, for all titles. + /// + /// @related SenAvatarDownloadExtraInfo() + /// @related SenAvatarDownloadMetadata() + /// @related SenAvatarDownloadAssets() + /// @related SenAvatarDownloadIcon() + /// + HRESULT SenAvatarEnumerate( + int userIndex, + size_t avatarInfoCountMax, + size_t *out_avatarInfoCount, + SenAvatarInfo *out_avatarInfoList, + SenSysCompletedCallback userCallback, + void *userCallbackData ); + + // Search the database for a specific avatar at the current time. + /// @brief Search the database for a specific avatar at the current time + /// + /// @param[in] titleID + /// The ID of the title that the avatar item is associated with. + /// + /// @param[in] resourceID + /// The ID of the specific asset about which information should be returned. + /// + /// @param[out] out_avatarInfo + /// The structures to fill in with the information. + /// It is assumed that this is preallocated to at least 1 entry. + /// + /// @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_avatarInfo is NULL. + /// E_FAIL: Failed to spawn server call. + /// S_OK: Server call spawned successfully. + /// + /// @related SenAvatarEnumerate() + /// @related SenAvatarDownloadExtraInfo() + /// @related SenAvatarDownloadMetadata() + /// @related SenAvatarDownloadAssets() + /// @related SenAvatarDownloadIcon() + /// + HRESULT SenAvatarFind( + SenSysTitleID titleID, + SenResourceID resourceID, + SenAvatarInfo *out_avatarInfo, + SenSysCompletedCallback userCallback, + void *userCallbackData ); + + /// @brief Download the avatar metadata to the client. + /// + /// @param[in] avatarInfo + /// The info describing the attributes and data of the avatar asset. + /// This is obtained from SenAvatarEnumerate(). + /// + /// @param[in] male + /// Whether or not to receive information about the male avatar (vs. the female) + /// + /// @param[in] dataSizeMax + /// Used to indicate the size of the buffer pointed to by @a out_data. + /// If the actual size of the data exceeds this, you will receive an error. + /// It is assumed that this is at least @a avatarInfo.[fe]male.metadata.GetBufferSize() bytes. + /// + /// @param[out] out_data + /// The buffer to fill in with the metadata. + /// + /// @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. + /// E_INVALIDARG: avatarInfo.resourceID or avatarInfo.[fe]male.metadata is invalid. + /// E_POINTER: out_data is NULL. + /// E_FAIL: Failed to spawn server call. + /// S_OK: Server call spawned successfully. + /// + /// @related SenAvatarEnumerate() + /// @related SenAvatarDownloadExtraInfo() + /// @related SenAvatarDownloadAssets() + /// @related SenAvatarDownloadIcon() + /// + HRESULT SenAvatarDownloadMetadata( + const SenAvatarInfo &avatarInfo, + bool male, + size_t dataSizeMax, + void *out_data, + SenSysCompletedCallback userCallback, + void *userCallbackData ); + + /// @brief Download the avatar asset binary data to the client. + /// + /// @param[in] avatarInfo + /// The info describing the attributes and data of the avatar asset. + /// This is obtained from SenAvatarEnumerate(). + /// + /// @param[in] male + /// Whether or not to receive information about the male avatar (vs. the female) + /// + /// @param[in] dataSizeMax + /// Used to indicate the size of the buffer pointed to by @a out_data. + /// If the actual size of the data exceeds this, you will receive an error. + /// It is assumed that this is at least @a avatarInfo.[fe]male.assets.GetBufferSize() bytes. + /// + /// @param[out] out_data + /// The buffer to fill in with the asset data. + /// + /// @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. + /// E_INVALIDARG: avatarInfo.resourceID or avatarInfo.[fe]male.assets is invalid. + /// E_POINTER: out_data is NULL. + /// E_FAIL: Failed to spawn server call. + /// S_OK: Server call spawned successfully. + /// + /// @related SenAvatarEnumerate() + /// @related SenAvatarDownloadExtraInfo() + /// @related SenAvatarDownloadMetadata() + /// @related SenAvatarDownloadIcon() + /// + HRESULT SenAvatarDownloadAssets( + const SenAvatarInfo &avatarInfo, + bool male, + size_t dataSizeMax, + void *out_data, + SenSysCompletedCallback userCallback, + void *userCallbackData ); + + /// @brief Download the avatar icon binary data to the client. + /// + /// @param[in] avatarInfo + /// The info describing the attributes and data of the avatar asset. + /// This is obtained from SenAvatarEnumerate(). + /// + /// @param[in] male + /// Whether or not to receive information about the male avatar (vs. the female) + /// + /// @param[in] dataSizeMax + /// Used to indicate the size of the buffer pointed to by @a out_data. + /// If the actual size of the data exceeds this, you will receive an error. + /// It is assumed that this is at least @a avatarInfo.[fe]male.icon.GetBufferSize() bytes. + /// + /// @param[out] out_data + /// The buffer to fill in with the binary icon data. + /// + /// @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. + /// E_INVALIDARG: avatarInfo.resourceID or avatarInfo.[fe]male.icon is invalid. + /// E_POINTER: out_data is NULL. + /// E_FAIL: Failed to spawn server call. + /// S_OK: Server call spawned successfully. + /// + /// @related SenAvatarEnumerate() + /// @related SenAvatarDownloadExtraInfo() + /// @related SenAvatarDownloadMetadata() + /// @related SenAvatarDownloadAssets() + /// + HRESULT SenAvatarDownloadIcon( + const SenAvatarInfo &avatarInfo, + bool male, + size_t dataSizeMax, + void *out_data, + SenSysCompletedCallback userCallback, + void *userCallbackData ); + + /// @brief Download extra information about a given avatar to the client. + /// + /// @param[in] avatarInfo + /// The info describing the attributes and data of the avatar. + /// This is obtained from SenAvatarEnumerate(). + /// + /// @param[in] male + /// Whether or not to receive information about the male avatar (vs. the female). + /// + /// @param[out] out_avatarExtraInfo + /// The structure to populate with extra information. + /// + /// @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. + /// E_INVALIDARG: avatarInfo.resourceID or avatarInfo.xml is invalid. + /// E_POINTER: out_avatarExtraInfo is NULL. + /// E_FAIL: Failed to spawn server call. + /// S_OK: Server call spawned successfully. + /// + /// @details On completion, the structure will contain extra information, such as localized strings. + /// + /// @related SenAvatarEnumerate() + /// @related SenAvatarDownloadMetadata() + /// @related SenAvatarDownloadAssets() + /// @related SenAvatarDownloadIcon() + /// + HRESULT SenAvatarDownloadExtraInfo( + const SenAvatarInfo &avatarInfo, + bool male, + SenAvatarExtraInfo *out_avatarExtraInfo, + SenSysCompletedCallback userCallback, void *userCallbackData ); + + // Download the raw binary data to the client. + // It is assumed that out_data is preallocated to (at least) dataSizeMax bytes, + // which in turn should be at least avatarInfo.[fe]male.xml.GetBufferSize() bytes. + HRESULT SenAvatarDownloadXML( + const SenAvatarInfo &avatarInfo, + bool male, + size_t dataSizeMax, + void *out_data, + SenSysCompletedCallback userCallback, + void *userCallbackData ); + + // Obtain a wide, localized string with a given avatar's game title. + // + // Assumes you have already downloaded the XML and run it through + // SenXMLParse() to get a SenXML struct. + // + // First method, filling a fixed-size buffer: + // + // wchar_t buffer[1234]; + // SenAvatarXMLGetTitle( xml, loc, _countof(buffer), NULL, buffer ); + // + // Second method, filling a dynamically-allocated buffer: + // + // size_t bufferLength; + // SenAvatarXMLGetTitle( xml, loc, 0, &bufferLength, NULL ); + // wchar_t buffer = new wchar_t[bufferLength]; + // SenAvatarXMLGetTitle( xml, loc, bufferLength, NULL, buffer ); + // + // Note that bufferLength is in wchars, and includes the terminating nul. + // The actual length of the _string_ is (*out_bufferLength - 1). + // + HRESULT SenAvatarXMLGetTitle( + const SenXML &senXML, + size_t bufferLengthMax, + size_t *out_bufferLength, // optional + wchar_t *out_buffer ); // optional + + // Obtain a wide, localized string with a given avatar's name. + // See the similar SenAvatarGetTitle() for details. + HRESULT SenAvatarXMLGetName( + const SenXML &senXML, + size_t bufferLengthMax, + size_t *out_bufferLength, // optional + wchar_t *out_buffer ); // optional + + // Obtain a wide, localized string with a given avatar's description. + // See the similar SenAvatarGetTitle() for details. + HRESULT SenAvatarXMLGetDescription( + const SenXML &senXML, + size_t bufferLengthMax, + size_t *out_bufferLength, // optional + wchar_t *out_buffer ); // optional + + // Obtain the number of custom avatar palettes. + HRESULT SenAvatarXMLGetPaletteCount( + const SenXML &senXML, + size_t *out_paletteCount ); + + // Obtain the localized name for an avatar palettes. + // See the similar SenAvatarGetTitle() for details. + HRESULT SenAvatarXMLGetPaletteName( + const SenXML &senXML, + int paletteIndex, + size_t bufferLengthMax, + size_t *out_bufferLength, // optional + wchar_t *out_buffer ); // optional + + // Obtain a single palette at a given index in the list of palettes + // for a given avatar. + HRESULT SenAvatarXMLGetPalette( + const SenXML &senXML, + int paletteIndex, + SenAvatarPalette *out_palette ); + + // Extract all palette entries at once. + // It is assumed that out_paletteList is preallocated to (at least) + // paletteCountMax entries. + HRESULT SenAvatarXMLGetPalettes( + const SenXML &senXML, + size_t paletteCountMax, + size_t *out_paletteCount, // optional + SenAvatarPalette *out_paletteList ); + +} // namespace Sentient -- cgit v1.2.3