087b7e7abf
This code was not tested and breaks in Release builds, reverting to restore
functionality of the nightly. All in-game menus do not work and generating
a world crashes.
This reverts commit a9be52c41a.
410 lines
19 KiB
C++
410 lines
19 KiB
C++
/********************************************************
|
|
* *
|
|
* 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
|