ocrm.bsky.social
the game where you go into mines and start crafting! but for consoles (forked directly from smartcmd's github)
1/********************************************************
2* *
3* Copyright (C) Microsoft. All rights reserved. *
4* *
5********************************************************/
6
7// Sentient Client BoxArt API
8//
9// Include this to get access to all BoxArt-related Sentient features.
10
11#pragma once
12
13#include "SenClientRawData.h"
14#include "SenClientResource.h"
15#include "SenClientSys.h"
16#include "SenClientXML.h"
17
18#include <xonline.h>
19
20namespace Sentient
21{
22 //====================//
23 // //
24 // BoxArt Types //
25 // //
26 //====================//
27
28 /// @brief Box Art sorting options.
29 ///
30 /// @details When enumerating box Art, these are the options for pre-sorting the returned list.
31 ///
32 enum SenBoxArtSortBy
33 {
34 /// Sort by the default order (currently just the order stored on the server).
35 SenBoxArtSortBy_Default = 0,
36 };
37
38 /// @brief Box art command/action types.
39 ///
40 /// @details When the user selects box art, these are the options for generating the resulting action.
41 ///
42 enum SenBoxArtCommand
43 {
44 /// The game should call up the marketplace UI with info.GetOfferID().
45 SenBoxArtCommand_Store = 0,
46
47 // (more commands TBD)
48 };
49
50 /// @brief Basic box art information.
51 ///
52 /// @details This structure contains the original uploaded info plus any info implied by the raw data that was uploaded (e.g. data sizes).
53 ///
54 struct SenBoxArtInfo : public SenResourceInfo
55 {
56 SenRawDataTransferInfo image; ///< Points to a file, typically JPG or PNG, which can be passed to D3DXCreateTextureFromFileInMemory().
57 SenRawDataTransferInfo xml; ///< Points to an opaque XML file used to hold extended information about the box art. Use SenBoxArtDownloadExtraInfo() to retrieve.
58
59 SenBoxArtCommand command; ///< What to do when the box art is selected.
60 INT32 commandData0; ///< 32 bits of arbitrary data to go with command. (e.g. offerID high bits)
61 INT32 commandData1; ///< 32 bits of arbitrary data to go with command. (e.g. offerID low bits)
62
63 UINT32 friendsWithTitle; ///< Number of friends owning the title this box art is associated with.
64
65 /// @brief
66 /// Get the offerID associated with this box art.
67 ///
68 /// @details
69 /// If command==SenBoxArtCommand_Store, this returns commandData0,1 as a SenSysOfferID.
70 /// Otherwise, it returns SenSysOfferID_Invalid.
71 ///
72 SenSysOfferID GetOfferID() const;
73 };
74
75 /// @brief Extra box art information.
76 ///
77 /// @details This structure contains additional data about box art, such as localized strings.
78 ///
79 struct SenBoxArtExtraInfo
80 {
81 wchar_t title[XMARKETPLACE_MAX_OFFER_NAME_LENGTH+1]; ///< The localized title associated with the offer.
82 wchar_t description[XMARKETPLACE_MAX_OFFER_SELL_TEXT_LENGTH+1]; ///< The localized short description associated with the offer.
83 };
84
85 //========================//
86 // //
87 // BoxArt Functions //
88 // //
89 //========================//
90
91
92 /// @brief Search the database for all the box arts that match the search criteria.
93 ///
94 /// @param[in] userIndex
95 /// The index of the initiating user on the console. Note: This is NOT a XUID.
96 ///
97 /// @param[in] boxArtInfoCountMax
98 /// The number of SenBoxArtInfo structures available in @a out_boxArtInfoList.
99 ///
100 /// @param[out] out_boxArtInfoCount
101 /// This is the number of entries actually enumerated by the call.
102 ///
103 /// @param[out] out_boxArtInfoList
104 /// The structures to fill in with the enumerated information.
105 /// It is assumed that this is preallocated to at least @a boxArtInfoCountMax entries.
106 ///
107 /// @param[out] out_senHandle
108 /// Provides a handle to the async task, which will allow for calling SentientCancel
109 ///
110 /// @param[in] userCallback
111 /// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
112 ///
113 /// @param[in] userCallbackData
114 /// Data to be passed to the @a userCallback on completion.
115 ///
116 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
117 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
118 /// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
119 /// E_POINTER: out_boxArtInfoList is NULL.
120 /// E_FAIL: Failed to spawn server call.
121 /// S_OK: Server call spawned successfully.
122 ///
123 /// @details Enumerates in default order, at the current time, for all titles, the box art available to display.
124 ///
125 /// @related SenBoxArtDownloadImage()
126 /// @related SenBoxArtDownloadXML()
127 ///
128 HRESULT SenBoxArtEnumerate(
129 int userIndex,
130 size_t boxArtInfoCountMax,
131 size_t *out_boxArtInfoCount,
132 SenBoxArtInfo *out_boxArtInfoList,
133 SenHandle *out_senHandle,
134 SenSysCompletedCallback userCallback,
135 void *userCallbackData );
136
137 /// @brief Download the raw box art image data to the client.
138 ///
139 /// @param[in] boxArtInfo
140 /// The info describing the attributes and data of the box art.
141 /// This is obtained from SenBoxArtEnumerate().
142 ///
143 /// @param[in] dataSizeMax
144 /// Used to indicate the size of the buffer pointed to by @a out_data.
145 /// If the actual size of the data exceeds this, you will receive an error.
146 /// It is assumed that this is at least @a boxArtInfo.image.GetBufferSize() bytes.
147 ///
148 /// @param[out] out_data
149 /// The buffer to fill in with the raw image data.
150 ///
151 /// @param[out] out_senHandle
152 /// Provides a handle to the async task, which will allow for calling SentientCancel
153 ///
154 /// @param[in] userCallback
155 /// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
156 ///
157 /// @param[in] userCallbackData
158 /// Data to be passed to the @a userCallback on completion.
159 ///
160 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
161 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
162 /// E_INVALIDARG: boxArtInfo.resourceID or boxArtInfo.image is invalid.
163 /// E_POINTER: out_data is NULL.
164 /// E_FAIL: Failed to spawn server call.
165 /// S_OK: Server call spawned successfully.
166 ///
167 /// @details The data is expected to contain a PNG or JPG file, suitable for use with D3DXCreateTextureFromFileInMemory().
168 ///
169 /// @related SenBoxArtEnumerate()
170 /// @related SenBoxArtDownloadXML()
171 ///
172 HRESULT SenBoxArtDownloadImage(
173 const SenBoxArtInfo &boxArtInfo,
174 size_t dataSizeMax,
175 void *out_data,
176 SenHandle *out_senHandle,
177 SenSysCompletedCallback userCallback,
178 void *userCallbackData );
179
180 /// @brief Download extra information about a give box art to the client.
181 ///
182 /// @param[in] boxArtInfo
183 /// The info describing the attributes and data of the box art.
184 /// This is obtained from SenBoxArtEnumerate().
185 ///
186 /// @param[out] out_boxArtExtraInfo
187 /// The structure to populate with extra information.
188 ///
189 /// @param[out] out_senHandle
190 /// Provides a handle to the async task, which will allow for calling SentientCancel
191 ///
192 /// @param[in] userCallback
193 /// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
194 ///
195 /// @param[in] userCallbackData
196 /// Data to be passed to the @a userCallback on completion.
197 ///
198 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
199 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
200 /// E_INVALIDARG: boxArtInfo.resourceID or boxArtInfo.xml is invalid.
201 /// E_POINTER: out_boxArtExtraInfo is NULL.
202 /// E_FAIL: Failed to spawn server call.
203 /// S_OK: Server call spawned successfully.
204 ///
205 /// @details On completion, the structure will contain extra information, such as localized strings.
206 ///
207 /// @related SenBoxArtEnumerate()
208 /// @related SenBoxArtDownloadImage()
209 ///
210 HRESULT SenBoxArtDownloadExtraInfo(
211 const SenBoxArtInfo &boxArtInfo,
212 SenBoxArtExtraInfo *out_boxArtExtraInfo,
213 SenHandle *out_senHandle,
214 SenSysCompletedCallback userCallback, void *userCallbackData );
215
216 /// @brief Download the raw box art xml data to the client.
217 ///
218 /// @param[in] boxArtInfo
219 /// The info describing the attributes and data of the box art.
220 /// This is obtained from SenBoxArtEnumerate().
221 ///
222 /// @param[in] dataSizeMax
223 /// Used to indicate the size of the buffer pointed to by @a out_data.
224 /// If the actual size of the data exceeds this, you will receive an error.
225 /// It is assumed that this is at least @a boxArtInfo.xml.GetBufferSize() bytes.
226 ///
227 /// @param[out] out_data
228 /// The buffer to fill in with the raw image data.
229 ///
230 /// @param[in] userCallback
231 /// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
232 ///
233 /// @param[in] userCallbackData
234 /// Data to be passed to the @a userCallback on completion.
235 ///
236 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
237 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
238 /// E_INVALIDARG: boxArtInfo.resourceID or boxArtInfo.xml is invalid.
239 /// E_POINTER: out_data is NULL.
240 /// E_FAIL: Failed to spawn server call.
241 /// S_OK: Server call spawned successfully.
242 ///
243 /// @details The data is expected to contain a UTF-8 XML file, though those details
244 /// are irrelevant, as the contents are parsed transparently with SenXMLParse().
245 ///
246 /// @related SenBoxArtEnumerate()
247 /// @related SenBoxArtDownloadImage()
248 ///
249 /// @deprecated Use SenBoxArtDownloadExtraInfo() instead.
250 ///
251 __declspec(deprecated("This function is deprecated, use SenBoxArtDownloadExtraInfo instead")) HRESULT SenBoxArtDownloadXML(
252 const SenBoxArtInfo &boxArtInfo,
253 size_t dataSizeMax,
254 void *out_data,
255 SenSysCompletedCallback userCallback,
256 void *userCallbackData );
257
258 /// @brief Obtain a wide, localized string describing a given box art's game title.
259 ///
260 /// @param[in] senXML
261 /// This is the result of a call to SenXMLParse() with the results of
262 /// SenBoxArtDownloadXML().
263 ///
264 /// @param[in] culture
265 /// This is the result of a call to SenCultureFind() or SenCultureGet*().
266 /// You may also pass NULL to use the culture set with SenCultureSetCurrent().
267 ///
268 /// @param[in] bufferLength
269 /// Note that bufferLength is in wchars, and needs to _include_ space for the terminating nul.
270 ///
271 /// @param[out] out_bufferLength
272 /// Used to return the actual number of wchars written to the buffer, including the terminating nul.
273 /// The actual length of the _string_ is (*out_bufferLength - 1).
274 /// Pass @a out_bufferLength = NULL if you don't care about the actual size.
275 ///
276 /// @param[out] out_buffer
277 /// The buffer to fill in with the string.
278 /// It is assumed that this is preallocated to at least @a bufferLength wchars.
279 /// Pass @a out_buffer = NULL if you are only interested in finding out the necessary buffer size.
280 ///
281 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
282 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
283 /// E_UNEXPECTED: passed a NULL culture without a default culture being set first.
284 /// E_INVALIDARG: senXML does not contain parsed XML data.
285 /// E_FAIL: Failed to locate text.
286 /// S_OK: Server call spawned successfully.
287 ///
288 /// @details Assumes you have already downloaded the XML and run it through
289 /// SenXMLParse() to get a SenXML struct.
290 ///
291 /// First method, filling a fixed-size buffer:
292 ///
293 /// wchar_t buffer[1234];
294 /// SenBoxArtXMLGetTitle( xml, culture, _countof(buffer), NULL, buffer );
295 ///
296 /// Second method, filling a dynamically-allocated buffer:
297 ///
298 /// size_t bufferLength;
299 /// SenBoxArtXMLGetTitle( xml, culture, 0, &bufferLength, NULL );
300 /// wchar_t buffer = new wchar_t[bufferLength];
301 /// SenBoxArtXMLGetTitle( xml, culture, bufferLength, NULL, buffer );
302 ///
303 /// @related SenBoxArtDownloadXML()
304 /// @related SenXMLParse()
305 ///
306 /// @deprecated Use SenBoxArtDownloadExtraInfo() instead.
307 ///
308 __declspec(deprecated("This function is deprecated, use SenBoxArtDownloadExtraInfo instead")) HRESULT SenBoxArtXMLGetTitle(
309 const SenXML &senXML,
310 size_t bufferLengthMax,
311 size_t *out_bufferLength,
312 wchar_t *out_buffer );
313
314 /// @brief Obtain a wide, localized string describing a given box art's game title.
315 ///
316 /// @param[in] senXML
317 /// This is the result of a call to SenXMLParse() with the results of
318 /// SenBoxArtDownloadXML().
319 ///
320 /// @param[in] culture
321 /// This is the result of a call to SenCultureFind() or SenCultureGet*().
322 /// You may also pass NULL to use the culture set with SenCultureSetCurrent().
323 ///
324 /// @param[in] bufferLength
325 /// Note that bufferLength is in wchars, and needs to _include_ space for the terminating nul.
326 ///
327 /// @param[out] out_bufferLength
328 /// Used to return the actual number of wchars written to the buffer, including the terminating nul.
329 /// The actual length of the _string_ is (*out_bufferLength - 1).
330 /// Pass @a out_bufferLength = NULL if you don't care about the actual size.
331 ///
332 /// @param[out] out_buffer
333 /// The buffer to fill in with the string.
334 /// It is assumed that this is preallocated to at least @a bufferLength wchars.
335 /// Pass @a out_buffer = NULL if you are only interested in finding out the necessary buffer size.
336 ///
337 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
338 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
339 /// E_UNEXPECTED: passed a NULL culture without a default culture being set first.
340 /// E_INVALIDARG: senXML does not contain parsed XML data.
341 /// E_FAIL: Failed to locate text.
342 /// S_OK: Server call spawned successfully.
343 ///
344 /// @details Assumes you have already downloaded the XML and run it through
345 /// SenXMLParse() to get a SenXML struct.
346 ///
347 /// First method, filling a fixed-size buffer:
348 ///
349 /// wchar_t buffer[1234];
350 /// SenBoxArtXMLGetDescription( xml, culture, _countof(buffer), NULL, buffer );
351 ///
352 /// Second method, filling a dynamically-allocated buffer:
353 ///
354 /// size_t bufferLength;
355 /// SenBoxArtXMLGetDescription( xml, culture, 0, &bufferLength, NULL );
356 /// wchar_t buffer = new wchar_t[bufferLength];
357 /// SenBoxArtXMLGetDescription( xml, culture, bufferLength, NULL, buffer );
358 ///
359 /// @related SenBoxArtDownloadXML()
360 /// @related SenXMLParse()
361 ///
362 /// @deprecated Use SenBoxArtDownloadExtraInfo() instead.
363 ///
364 __declspec(deprecated("This function is deprecated, use SenBoxArtDownloadExtraInfo instead")) HRESULT SenBoxArtXMLGetDescription(
365 const SenXML &senXML,
366 size_t bufferLengthMax,
367 size_t *out_bufferLength,
368 wchar_t *out_buffer );
369
370 /// @brief Download the raw box art image data to the client.
371 ///
372 /// @param[in] boxArtInfo
373 /// The info describing the attributes and data of the box art.
374 /// This is obtained from SenBoxArtEnumerate().
375 ///
376 /// @param[in] dataSizeMax
377 /// Used to indicate the size of the buffer pointed to by @a out_data.
378 /// If the actual size of the data exceeds this, you will receive an error.
379 /// It is assumed that this is at least @a boxArtInfo.image.GetBufferSize() bytes.
380 ///
381 /// @param[out] out_data
382 /// The buffer to fill in with the raw image data.
383 ///
384 /// @param[in] userCallback
385 /// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
386 ///
387 /// @param[in] userCallbackData
388 /// Data to be passed to the @a userCallback on completion.
389 ///
390 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
391 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
392 /// E_INVALIDARG: boxArtInfo.resourceID or boxArtInfo.image is invalid.
393 /// E_POINTER: out_data is NULL.
394 /// E_FAIL: Failed to spawn server call.
395 /// S_OK: Server call spawned successfully.
396 ///
397 /// @details The data is expected to contain a PNG or JPG file, suitable for use with D3DXCreateTextureFromFileInMemory().
398 ///
399 /// @related SenBoxArtEnumerate()
400 /// @related SenBoxArtDownloadXML()
401 ///
402 __declspec(deprecated("This function is deprecated, use the overload with a SenHandle out param instead")) HRESULT SenBoxArtDownloadImage(
403 const SenBoxArtInfo &boxArtInfo,
404 size_t dataSizeMax,
405 void *out_data,
406 SenSysCompletedCallback userCallback,
407 void *userCallbackData );
408
409} // namespace Sentient