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 AvatarSuperstars Avatar API
8//
9// Include this to get access to all Avatar-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 <xnamath.h>
19#include <xonline.h>
20
21namespace Sentient
22{
23 //====================//
24 // //
25 // Avatar Types //
26 // //
27 //====================//
28
29 // When enumerating avatars, these are the options for pre-sorting the
30 // returned list.
31 enum SenAvatarSortBy
32 {
33 SenAvatarSortBy_Default = 0,
34 // ... TBD ...
35
36 };
37
38 // This structure contains the information needed to download the
39 // raw data for a given gender.
40 struct SenAvatarGenderInfo
41 {
42 SenRawDataTransferInfo metadata;
43 SenRawDataTransferInfo assets;
44 SenRawDataTransferInfo xml;
45 SenRawDataTransferInfo icon;
46 };
47
48 // This structure contains the original uploaded info plus info
49 // needed to download raw data.
50 struct SenAvatarInfo : public SenResourceInfo
51 {
52 int vipLevel;
53 SenAvatarGenderInfo female;
54 SenAvatarGenderInfo male;
55 };
56
57 struct SenAvatarPalette
58 {
59 XMCOLOR entry[3];
60 };
61
62 struct SenAvatarNamedPalette : SenAvatarPalette
63 {
64 wchar_t name[57+1];
65 };
66
67 /// @brief Extra avatar information.
68 ///
69 /// @details This structure contains additional data about the avatar, such as localized strings and palettes.
70 ///
71 struct SenAvatarExtraInfo
72 {
73 wchar_t title[XMARKETPLACE_MAX_TITLE_NAME_LENGTH+1]; ///< The localized game title associated with the avatar.
74 wchar_t name[XMARKETPLACE_MAX_OFFER_NAME_LENGTH+1]; ///< The localized name associated with the avatar.
75 wchar_t description[XMARKETPLACE_MAX_OFFER_SELL_TEXT_LENGTH+1]; ///< The localized short description associated with the avatar.
76
77 size_t paletteCount;
78 SenAvatarNamedPalette palette[16];
79 };
80
81 //========================//
82 // //
83 // Avatar Functions //
84 // //
85 //========================//
86
87 /// @brief Search the database for all the avatars that match the search criteria.
88 ///
89 /// @param[in] userIndex
90 /// The index of the initiating user on the console. Note: This is NOT a XUID.
91 ///
92 /// @param[in] avatarInfoCountMax
93 /// The number of SenAvatarInfo structures available in @a out_avatarInfoList.
94 ///
95 /// @param[out] out_avatarInfoCount
96 /// This is the number of entries actually enumerated by the call.
97 ///
98 /// @param[out] out_avatarInfoList
99 /// The structures to fill in with the enumerated information.
100 /// It is assumed that this is preallocated to at least @a avatarInfoCountMax entries.
101 ///
102 /// @param[in] userCallback
103 /// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
104 ///
105 /// @param[in] userCallbackData
106 /// Data to be passed to the @a userCallback on completion.
107 ///
108 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
109 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
110 /// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
111 /// E_POINTER: out_avatarInfoList is NULL.
112 /// E_FAIL: Failed to spawn server call.
113 /// S_OK: Server call spawned successfully.
114 ///
115 /// @details Enumerates in default order, at the current time, for all titles.
116 ///
117 /// @related SenAvatarDownloadExtraInfo()
118 /// @related SenAvatarDownloadMetadata()
119 /// @related SenAvatarDownloadAssets()
120 /// @related SenAvatarDownloadIcon()
121 ///
122 HRESULT SenAvatarEnumerate(
123 int userIndex,
124 size_t avatarInfoCountMax,
125 size_t *out_avatarInfoCount,
126 SenAvatarInfo *out_avatarInfoList,
127 SenSysCompletedCallback userCallback,
128 void *userCallbackData );
129
130 // Search the database for a specific avatar at the current time.
131 /// @brief Search the database for a specific avatar at the current time
132 ///
133 /// @param[in] titleID
134 /// The ID of the title that the avatar item is associated with.
135 ///
136 /// @param[in] resourceID
137 /// The ID of the specific asset about which information should be returned.
138 ///
139 /// @param[out] out_avatarInfo
140 /// The structures to fill in with the information.
141 /// It is assumed that this is preallocated to at least 1 entry.
142 ///
143 /// @param[in] userCallback
144 /// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
145 ///
146 /// @param[in] userCallbackData
147 /// Data to be passed to the @a userCallback on completion.
148 ///
149 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
150 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
151 /// SENTIENT_E_GUEST_ACCESS_VIOLATION: A guest may not spawn this call.
152 /// E_POINTER: out_avatarInfo is NULL.
153 /// E_FAIL: Failed to spawn server call.
154 /// S_OK: Server call spawned successfully.
155 ///
156 /// @related SenAvatarEnumerate()
157 /// @related SenAvatarDownloadExtraInfo()
158 /// @related SenAvatarDownloadMetadata()
159 /// @related SenAvatarDownloadAssets()
160 /// @related SenAvatarDownloadIcon()
161 ///
162 HRESULT SenAvatarFind(
163 SenSysTitleID titleID,
164 SenResourceID resourceID,
165 SenAvatarInfo *out_avatarInfo,
166 SenSysCompletedCallback userCallback,
167 void *userCallbackData );
168
169 /// @brief Download the avatar metadata to the client.
170 ///
171 /// @param[in] avatarInfo
172 /// The info describing the attributes and data of the avatar asset.
173 /// This is obtained from SenAvatarEnumerate().
174 ///
175 /// @param[in] male
176 /// Whether or not to receive information about the male avatar (vs. the female)
177 ///
178 /// @param[in] dataSizeMax
179 /// Used to indicate the size of the buffer pointed to by @a out_data.
180 /// If the actual size of the data exceeds this, you will receive an error.
181 /// It is assumed that this is at least @a avatarInfo.[fe]male.metadata.GetBufferSize() bytes.
182 ///
183 /// @param[out] out_data
184 /// The buffer to fill in with the metadata.
185 ///
186 /// @param[in] userCallback
187 /// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
188 ///
189 /// @param[in] userCallbackData
190 /// Data to be passed to the @a userCallback on completion.
191 ///
192 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
193 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
194 /// E_INVALIDARG: avatarInfo.resourceID or avatarInfo.[fe]male.metadata is invalid.
195 /// E_POINTER: out_data is NULL.
196 /// E_FAIL: Failed to spawn server call.
197 /// S_OK: Server call spawned successfully.
198 ///
199 /// @related SenAvatarEnumerate()
200 /// @related SenAvatarDownloadExtraInfo()
201 /// @related SenAvatarDownloadAssets()
202 /// @related SenAvatarDownloadIcon()
203 ///
204 HRESULT SenAvatarDownloadMetadata(
205 const SenAvatarInfo &avatarInfo,
206 bool male,
207 size_t dataSizeMax,
208 void *out_data,
209 SenSysCompletedCallback userCallback,
210 void *userCallbackData );
211
212 /// @brief Download the avatar asset binary data to the client.
213 ///
214 /// @param[in] avatarInfo
215 /// The info describing the attributes and data of the avatar asset.
216 /// This is obtained from SenAvatarEnumerate().
217 ///
218 /// @param[in] male
219 /// Whether or not to receive information about the male avatar (vs. the female)
220 ///
221 /// @param[in] dataSizeMax
222 /// Used to indicate the size of the buffer pointed to by @a out_data.
223 /// If the actual size of the data exceeds this, you will receive an error.
224 /// It is assumed that this is at least @a avatarInfo.[fe]male.assets.GetBufferSize() bytes.
225 ///
226 /// @param[out] out_data
227 /// The buffer to fill in with the asset data.
228 ///
229 /// @param[in] userCallback
230 /// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
231 ///
232 /// @param[in] userCallbackData
233 /// Data to be passed to the @a userCallback on completion.
234 ///
235 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
236 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
237 /// E_INVALIDARG: avatarInfo.resourceID or avatarInfo.[fe]male.assets is invalid.
238 /// E_POINTER: out_data is NULL.
239 /// E_FAIL: Failed to spawn server call.
240 /// S_OK: Server call spawned successfully.
241 ///
242 /// @related SenAvatarEnumerate()
243 /// @related SenAvatarDownloadExtraInfo()
244 /// @related SenAvatarDownloadMetadata()
245 /// @related SenAvatarDownloadIcon()
246 ///
247 HRESULT SenAvatarDownloadAssets(
248 const SenAvatarInfo &avatarInfo,
249 bool male,
250 size_t dataSizeMax,
251 void *out_data,
252 SenSysCompletedCallback userCallback,
253 void *userCallbackData );
254
255 /// @brief Download the avatar icon binary data to the client.
256 ///
257 /// @param[in] avatarInfo
258 /// The info describing the attributes and data of the avatar asset.
259 /// This is obtained from SenAvatarEnumerate().
260 ///
261 /// @param[in] male
262 /// Whether or not to receive information about the male avatar (vs. the female)
263 ///
264 /// @param[in] dataSizeMax
265 /// Used to indicate the size of the buffer pointed to by @a out_data.
266 /// If the actual size of the data exceeds this, you will receive an error.
267 /// It is assumed that this is at least @a avatarInfo.[fe]male.icon.GetBufferSize() bytes.
268 ///
269 /// @param[out] out_data
270 /// The buffer to fill in with the binary icon data.
271 ///
272 /// @param[in] userCallback
273 /// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
274 ///
275 /// @param[in] userCallbackData
276 /// Data to be passed to the @a userCallback on completion.
277 ///
278 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
279 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
280 /// E_INVALIDARG: avatarInfo.resourceID or avatarInfo.[fe]male.icon is invalid.
281 /// E_POINTER: out_data is NULL.
282 /// E_FAIL: Failed to spawn server call.
283 /// S_OK: Server call spawned successfully.
284 ///
285 /// @related SenAvatarEnumerate()
286 /// @related SenAvatarDownloadExtraInfo()
287 /// @related SenAvatarDownloadMetadata()
288 /// @related SenAvatarDownloadAssets()
289 ///
290 HRESULT SenAvatarDownloadIcon(
291 const SenAvatarInfo &avatarInfo,
292 bool male,
293 size_t dataSizeMax,
294 void *out_data,
295 SenSysCompletedCallback userCallback,
296 void *userCallbackData );
297
298 /// @brief Download extra information about a given avatar to the client.
299 ///
300 /// @param[in] avatarInfo
301 /// The info describing the attributes and data of the avatar.
302 /// This is obtained from SenAvatarEnumerate().
303 ///
304 /// @param[in] male
305 /// Whether or not to receive information about the male avatar (vs. the female).
306 ///
307 /// @param[out] out_avatarExtraInfo
308 /// The structure to populate with extra information.
309 ///
310 /// @param[in] userCallback
311 /// If this call returns a success code, the userCallback will be called at the end of the asynchronous process.
312 ///
313 /// @param[in] userCallbackData
314 /// Data to be passed to the @a userCallback on completion.
315 ///
316 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
317 /// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
318 /// E_INVALIDARG: avatarInfo.resourceID or avatarInfo.xml is invalid.
319 /// E_POINTER: out_avatarExtraInfo is NULL.
320 /// E_FAIL: Failed to spawn server call.
321 /// S_OK: Server call spawned successfully.
322 ///
323 /// @details On completion, the structure will contain extra information, such as localized strings.
324 ///
325 /// @related SenAvatarEnumerate()
326 /// @related SenAvatarDownloadMetadata()
327 /// @related SenAvatarDownloadAssets()
328 /// @related SenAvatarDownloadIcon()
329 ///
330 HRESULT SenAvatarDownloadExtraInfo(
331 const SenAvatarInfo &avatarInfo,
332 bool male,
333 SenAvatarExtraInfo *out_avatarExtraInfo,
334 SenSysCompletedCallback userCallback, void *userCallbackData );
335
336 // Download the raw binary data to the client.
337 // It is assumed that out_data is preallocated to (at least) dataSizeMax bytes,
338 // which in turn should be at least avatarInfo.[fe]male.xml.GetBufferSize() bytes.
339 HRESULT SenAvatarDownloadXML(
340 const SenAvatarInfo &avatarInfo,
341 bool male,
342 size_t dataSizeMax,
343 void *out_data,
344 SenSysCompletedCallback userCallback,
345 void *userCallbackData );
346
347 // Obtain a wide, localized string with a given avatar's game title.
348 //
349 // Assumes you have already downloaded the XML and run it through
350 // SenXMLParse() to get a SenXML struct.
351 //
352 // First method, filling a fixed-size buffer:
353 //
354 // wchar_t buffer[1234];
355 // SenAvatarXMLGetTitle( xml, loc, _countof(buffer), NULL, buffer );
356 //
357 // Second method, filling a dynamically-allocated buffer:
358 //
359 // size_t bufferLength;
360 // SenAvatarXMLGetTitle( xml, loc, 0, &bufferLength, NULL );
361 // wchar_t buffer = new wchar_t[bufferLength];
362 // SenAvatarXMLGetTitle( xml, loc, bufferLength, NULL, buffer );
363 //
364 // Note that bufferLength is in wchars, and includes the terminating nul.
365 // The actual length of the _string_ is (*out_bufferLength - 1).
366 //
367 HRESULT SenAvatarXMLGetTitle(
368 const SenXML &senXML,
369 size_t bufferLengthMax,
370 size_t *out_bufferLength, // optional
371 wchar_t *out_buffer ); // optional
372
373 // Obtain a wide, localized string with a given avatar's name.
374 // See the similar SenAvatarGetTitle() for details.
375 HRESULT SenAvatarXMLGetName(
376 const SenXML &senXML,
377 size_t bufferLengthMax,
378 size_t *out_bufferLength, // optional
379 wchar_t *out_buffer ); // optional
380
381 // Obtain a wide, localized string with a given avatar's description.
382 // See the similar SenAvatarGetTitle() for details.
383 HRESULT SenAvatarXMLGetDescription(
384 const SenXML &senXML,
385 size_t bufferLengthMax,
386 size_t *out_bufferLength, // optional
387 wchar_t *out_buffer ); // optional
388
389 // Obtain the number of custom avatar palettes.
390 HRESULT SenAvatarXMLGetPaletteCount(
391 const SenXML &senXML,
392 size_t *out_paletteCount );
393
394 // Obtain the localized name for an avatar palettes.
395 // See the similar SenAvatarGetTitle() for details.
396 HRESULT SenAvatarXMLGetPaletteName(
397 const SenXML &senXML,
398 int paletteIndex,
399 size_t bufferLengthMax,
400 size_t *out_bufferLength, // optional
401 wchar_t *out_buffer ); // optional
402
403 // Obtain a single palette at a given index in the list of palettes
404 // for a given avatar.
405 HRESULT SenAvatarXMLGetPalette(
406 const SenXML &senXML,
407 int paletteIndex,
408 SenAvatarPalette *out_palette );
409
410 // Extract all palette entries at once.
411 // It is assumed that out_paletteList is preallocated to (at least)
412 // paletteCountMax entries.
413 HRESULT SenAvatarXMLGetPalettes(
414 const SenXML &senXML,
415 size_t paletteCountMax,
416 size_t *out_paletteCount, // optional
417 SenAvatarPalette *out_paletteList );
418
419} // namespace Sentient