Initial commit

1 files changed, 419 insertions, 0 deletions

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 <xnamath.h>
+#include <xonline.h>
+
+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