diff options
Diffstat (limited to 'Minecraft.Client/Xbox/Sentient/Include/SenClientBoxArt.h')
| -rw-r--r-- | Minecraft.Client/Xbox/Sentient/Include/SenClientBoxArt.h | 409 |
1 files changed, 409 insertions, 0 deletions
diff --git a/Minecraft.Client/Xbox/Sentient/Include/SenClientBoxArt.h b/Minecraft.Client/Xbox/Sentient/Include/SenClientBoxArt.h new file mode 100644 index 00000000..09662243 --- /dev/null +++ b/Minecraft.Client/Xbox/Sentient/Include/SenClientBoxArt.h @@ -0,0 +1,409 @@ +/******************************************************** +* * +* Copyright (C) Microsoft. All rights reserved. * +* * +********************************************************/ + +// Sentient Client BoxArt API +// +// Include this to get access to all BoxArt-related Sentient features. + +#pragma once + +#include "SenClientRawData.h" +#include "SenClientResource.h" +#include "SenClientSys.h" +#include "SenClientXML.h" + +#include <xonline.h> + +namespace Sentient +{ + //====================// + // // + // BoxArt Types // + // // + //====================// + + /// @brief Box Art sorting options. + /// + /// @details When enumerating box Art, these are the options for pre-sorting the returned list. + /// + enum SenBoxArtSortBy + { + /// Sort by the default order (currently just the order stored on the server). + SenBoxArtSortBy_Default = 0, + }; + + /// @brief Box art command/action types. + /// + /// @details When the user selects box art, these are the options for generating the resulting action. + /// + enum SenBoxArtCommand + { + /// The game should call up the marketplace UI with info.GetOfferID(). + SenBoxArtCommand_Store = 0, + + // (more commands TBD) + }; + + /// @brief Basic box art information. + /// + /// @details This structure contains the original uploaded info plus any info implied by the raw data that was uploaded (e.g. data sizes). + /// + struct SenBoxArtInfo : public SenResourceInfo + { + SenRawDataTransferInfo image; ///< Points to a file, typically JPG or PNG, which can be passed to D3DXCreateTextureFromFileInMemory(). + SenRawDataTransferInfo xml; ///< Points to an opaque XML file used to hold extended information about the box art. Use SenBoxArtDownloadExtraInfo() to retrieve. + + SenBoxArtCommand command; ///< What to do when the box art is selected. + INT32 commandData0; ///< 32 bits of arbitrary data to go with command. (e.g. offerID high bits) + INT32 commandData1; ///< 32 bits of arbitrary data to go with command. (e.g. offerID low bits) + + UINT32 friendsWithTitle; ///< Number of friends owning the title this box art is associated with. + + /// @brief + /// Get the offerID associated with this box art. + /// + /// @details + /// If command==SenBoxArtCommand_Store, this returns commandData0,1 as a SenSysOfferID. + /// Otherwise, it returns SenSysOfferID_Invalid. + /// + SenSysOfferID GetOfferID() const; + }; + + /// @brief Extra box art information. + /// + /// @details This structure contains additional data about box art, such as localized strings. + /// + struct SenBoxArtExtraInfo + { + wchar_t title[XMARKETPLACE_MAX_OFFER_NAME_LENGTH+1]; ///< The localized title associated with the offer. + wchar_t description[XMARKETPLACE_MAX_OFFER_SELL_TEXT_LENGTH+1]; ///< The localized short description associated with the offer. + }; + + //========================// + // // + // BoxArt Functions // + // // + //========================// + + + /// @brief Search the database for all the box arts 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] boxArtInfoCountMax + /// The number of SenBoxArtInfo structures available in @a out_boxArtInfoList. + /// + /// @param[out] out_boxArtInfoCount + /// This is the number of entries actually enumerated by the call. + /// + /// @param[out] out_boxArtInfoList + /// The structures to fill in with the enumerated information. + /// It is assumed that this is preallocated to at least @a boxArtInfoCountMax entries. + /// + /// @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_boxArtInfoList 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, the box art available to display. + /// + /// @related SenBoxArtDownloadImage() + /// @related SenBoxArtDownloadXML() + /// + HRESULT SenBoxArtEnumerate( + int userIndex, + size_t boxArtInfoCountMax, + size_t *out_boxArtInfoCount, + SenBoxArtInfo *out_boxArtInfoList, + SenHandle *out_senHandle, + SenSysCompletedCallback userCallback, + void *userCallbackData ); + + /// @brief Download the raw box art image data to the client. + /// + /// @param[in] boxArtInfo + /// The info describing the attributes and data of the box art. + /// This is obtained from SenBoxArtEnumerate(). + /// + /// @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 boxArtInfo.image.GetBufferSize() bytes. + /// + /// @param[out] out_data + /// The buffer to fill in with the raw image data. + /// + /// @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. + /// E_INVALIDARG: boxArtInfo.resourceID or boxArtInfo.image is invalid. + /// E_POINTER: out_data is NULL. + /// E_FAIL: Failed to spawn server call. + /// S_OK: Server call spawned successfully. + /// + /// @details The data is expected to contain a PNG or JPG file, suitable for use with D3DXCreateTextureFromFileInMemory(). + /// + /// @related SenBoxArtEnumerate() + /// @related SenBoxArtDownloadXML() + /// + HRESULT SenBoxArtDownloadImage( + const SenBoxArtInfo &boxArtInfo, + size_t dataSizeMax, + void *out_data, + SenHandle *out_senHandle, + SenSysCompletedCallback userCallback, + void *userCallbackData ); + + /// @brief Download extra information about a give box art to the client. + /// + /// @param[in] boxArtInfo + /// The info describing the attributes and data of the box art. + /// This is obtained from SenBoxArtEnumerate(). + /// + /// @param[out] out_boxArtExtraInfo + /// The structure to populate with extra information. + /// + /// @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. + /// E_INVALIDARG: boxArtInfo.resourceID or boxArtInfo.xml is invalid. + /// E_POINTER: out_boxArtExtraInfo 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 SenBoxArtEnumerate() + /// @related SenBoxArtDownloadImage() + /// + HRESULT SenBoxArtDownloadExtraInfo( + const SenBoxArtInfo &boxArtInfo, + SenBoxArtExtraInfo *out_boxArtExtraInfo, + SenHandle *out_senHandle, + SenSysCompletedCallback userCallback, void *userCallbackData ); + + /// @brief Download the raw box art xml data to the client. + /// + /// @param[in] boxArtInfo + /// The info describing the attributes and data of the box art. + /// This is obtained from SenBoxArtEnumerate(). + /// + /// @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 boxArtInfo.xml.GetBufferSize() bytes. + /// + /// @param[out] out_data + /// The buffer to fill in with the raw image 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: boxArtInfo.resourceID or boxArtInfo.xml is invalid. + /// E_POINTER: out_data is NULL. + /// E_FAIL: Failed to spawn server call. + /// S_OK: Server call spawned successfully. + /// + /// @details The data is expected to contain a UTF-8 XML file, though those details + /// are irrelevant, as the contents are parsed transparently with SenXMLParse(). + /// + /// @related SenBoxArtEnumerate() + /// @related SenBoxArtDownloadImage() + /// + /// @deprecated Use SenBoxArtDownloadExtraInfo() instead. + /// + __declspec(deprecated("This function is deprecated, use SenBoxArtDownloadExtraInfo instead")) HRESULT SenBoxArtDownloadXML( + const SenBoxArtInfo &boxArtInfo, + size_t dataSizeMax, + void *out_data, + SenSysCompletedCallback userCallback, + void *userCallbackData ); + + /// @brief Obtain a wide, localized string describing a given box art's game title. + /// + /// @param[in] senXML + /// This is the result of a call to SenXMLParse() with the results of + /// SenBoxArtDownloadXML(). + /// + /// @param[in] culture + /// This is the result of a call to SenCultureFind() or SenCultureGet*(). + /// You may also pass NULL to use the culture set with SenCultureSetCurrent(). + /// + /// @param[in] bufferLength + /// Note that bufferLength is in wchars, and needs to _include_ space for the terminating nul. + /// + /// @param[out] out_bufferLength + /// Used to return the actual number of wchars written to the buffer, including the terminating nul. + /// The actual length of the _string_ is (*out_bufferLength - 1). + /// Pass @a out_bufferLength = NULL if you don't care about the actual size. + /// + /// @param[out] out_buffer + /// The buffer to fill in with the string. + /// It is assumed that this is preallocated to at least @a bufferLength wchars. + /// Pass @a out_buffer = NULL if you are only interested in finding out the necessary buffer size. + /// + /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include: + /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first. + /// E_UNEXPECTED: passed a NULL culture without a default culture being set first. + /// E_INVALIDARG: senXML does not contain parsed XML data. + /// E_FAIL: Failed to locate text. + /// S_OK: Server call spawned successfully. + /// + /// @details 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]; + /// SenBoxArtXMLGetTitle( xml, culture, _countof(buffer), NULL, buffer ); + /// + /// Second method, filling a dynamically-allocated buffer: + /// + /// size_t bufferLength; + /// SenBoxArtXMLGetTitle( xml, culture, 0, &bufferLength, NULL ); + /// wchar_t buffer = new wchar_t[bufferLength]; + /// SenBoxArtXMLGetTitle( xml, culture, bufferLength, NULL, buffer ); + /// + /// @related SenBoxArtDownloadXML() + /// @related SenXMLParse() + /// + /// @deprecated Use SenBoxArtDownloadExtraInfo() instead. + /// + __declspec(deprecated("This function is deprecated, use SenBoxArtDownloadExtraInfo instead")) HRESULT SenBoxArtXMLGetTitle( + const SenXML &senXML, + size_t bufferLengthMax, + size_t *out_bufferLength, + wchar_t *out_buffer ); + + /// @brief Obtain a wide, localized string describing a given box art's game title. + /// + /// @param[in] senXML + /// This is the result of a call to SenXMLParse() with the results of + /// SenBoxArtDownloadXML(). + /// + /// @param[in] culture + /// This is the result of a call to SenCultureFind() or SenCultureGet*(). + /// You may also pass NULL to use the culture set with SenCultureSetCurrent(). + /// + /// @param[in] bufferLength + /// Note that bufferLength is in wchars, and needs to _include_ space for the terminating nul. + /// + /// @param[out] out_bufferLength + /// Used to return the actual number of wchars written to the buffer, including the terminating nul. + /// The actual length of the _string_ is (*out_bufferLength - 1). + /// Pass @a out_bufferLength = NULL if you don't care about the actual size. + /// + /// @param[out] out_buffer + /// The buffer to fill in with the string. + /// It is assumed that this is preallocated to at least @a bufferLength wchars. + /// Pass @a out_buffer = NULL if you are only interested in finding out the necessary buffer size. + /// + /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include: + /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first. + /// E_UNEXPECTED: passed a NULL culture without a default culture being set first. + /// E_INVALIDARG: senXML does not contain parsed XML data. + /// E_FAIL: Failed to locate text. + /// S_OK: Server call spawned successfully. + /// + /// @details 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]; + /// SenBoxArtXMLGetDescription( xml, culture, _countof(buffer), NULL, buffer ); + /// + /// Second method, filling a dynamically-allocated buffer: + /// + /// size_t bufferLength; + /// SenBoxArtXMLGetDescription( xml, culture, 0, &bufferLength, NULL ); + /// wchar_t buffer = new wchar_t[bufferLength]; + /// SenBoxArtXMLGetDescription( xml, culture, bufferLength, NULL, buffer ); + /// + /// @related SenBoxArtDownloadXML() + /// @related SenXMLParse() + /// + /// @deprecated Use SenBoxArtDownloadExtraInfo() instead. + /// + __declspec(deprecated("This function is deprecated, use SenBoxArtDownloadExtraInfo instead")) HRESULT SenBoxArtXMLGetDescription( + const SenXML &senXML, + size_t bufferLengthMax, + size_t *out_bufferLength, + wchar_t *out_buffer ); + + /// @brief Download the raw box art image data to the client. + /// + /// @param[in] boxArtInfo + /// The info describing the attributes and data of the box art. + /// This is obtained from SenBoxArtEnumerate(). + /// + /// @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 boxArtInfo.image.GetBufferSize() bytes. + /// + /// @param[out] out_data + /// The buffer to fill in with the raw image 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: boxArtInfo.resourceID or boxArtInfo.image is invalid. + /// E_POINTER: out_data is NULL. + /// E_FAIL: Failed to spawn server call. + /// S_OK: Server call spawned successfully. + /// + /// @details The data is expected to contain a PNG or JPG file, suitable for use with D3DXCreateTextureFromFileInMemory(). + /// + /// @related SenBoxArtEnumerate() + /// @related SenBoxArtDownloadXML() + /// + __declspec(deprecated("This function is deprecated, use the overload with a SenHandle out param instead")) HRESULT SenBoxArtDownloadImage( + const SenBoxArtInfo &boxArtInfo, + size_t dataSizeMax, + void *out_data, + SenSysCompletedCallback userCallback, + void *userCallbackData ); + +} // namespace Sentient |