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 UGC API
8//
9// Include this to get access to all UGC related Sentient features
10
11#pragma once
12
13// Local headers
14#include "SenClientMarkers.h"
15#include "SenClientUGCLeaderboards.h"
16#include "SenClientUGCTypes.h"
17
18// Sentient headers
19#include "SenClientSys.h"
20#include "SenClientCulture.h"
21
22namespace Sentient
23{
24 /**********************************
25 ***** UGC Creation Functions *****
26 **********************************/
27
28 /// @brief Generate a unique ID that will be used to
29 /// identify a given instance of UGC. This ID
30 /// will is referenced by every other UGC function.
31 ///
32 /// @param[in] userIndex
33 /// The index of the initiating user on the console.
34 /// Note: This is NOT a XUID.
35 ///
36 /// @param[out] outResult
37 /// The unique ID that has been generated and provisioned
38 /// for an instance of UGC.
39 ///
40 /// @param[in] userCallback
41 /// If this call returns a success code,
42 /// the userCallback will be called at the end of the
43 /// asynchronous process.
44 ///
45 /// @param[in] userCallbackData
46 /// Data to be passed to the @a userCallback on completion.
47 ///
48 /// @return TBD
49 ///
50 /// @details All UGC functions require a uniquely provisioned UGC ID.
51 ///
52 /// @related All UGC related functions.
53 HRESULT SenUGCCreatePublishingUGCID(
54 int userIndex,
55 SenUGCID *outResult,
56 SenSysCompletedCallback userCallback,
57 void *userCallbackData );
58
59 ///
60 /// @brief Async output information for SenUGCUpload or Download callers
61 ///
62 /// @details Contains progress or retry information in addition to a cancellation token
63 ///
64 struct SenUGCProgressInfo
65 {
66 SenHandle out_taskHandle; /// token for canceling the upload process
67 INT8 percentageComplete; /// 1-100, how much percent is complete of upload process for blob
68 size_t bytesCompleted; /// how many bytes have been successfully transmitted for the task
69 HRESULT lastStepResult; /// sentient client SDK HRESULT value
70 int numRetries; /// does not reset between internal steps for a long-running task
71 };
72
73 //************************************
74 // Method: SenUGCUpload
75 // FullName: Sentient::SenUGCUpload
76 // Access: public
77 // Returns: HRESULT
78 // Qualifier:
79 // Parameter: int userIndex
80 // Parameter: SenUGCID ugcID
81 // Parameter: const SenUGCMetaData * metaData
82 // Parameter: int nrMainDataBlobs
83 // Parameter: const void * * mainDataBlobs
84 // Parameter: const size_t * mainDataBlobSizes
85 // Parameter: bool pushToFeed
86 // Parameter: SenSysCompletedCallback userCallback
87 // Parameter: void * userCallbackData
88 // Upload the metadata, as well as one or more binary data blobs to the server.
89 // There are multiple data blobs supported (the exact number is defined in
90 // SenUGCMainData_NrBlobs). One use would be that a game may want store a
91 // preview thumbnail that can be downloaded without having to download the
92 // rest of the UGC. This could save bandwidth and make the game more responsive.
93 // Note: data blob 0 should be the main level data blob, for the automatic
94 // download counter to work.
95 // The metadata will also have a data blob associated, but this should be
96 // kept to a minimum, as UGC download menus will probably want to download
97 // metadata for a lot of UGCs at once.
98 // Note: if a level has been uploaded with main data before, and the creator
99 // wants to just modify the metadata, they can upload the metadata with the
100 // maindatablobs being NULL.
101 // NOTE: for large items, use the SenUGCUploadMainData method with the SenUGCProgressInfo
102 // signature so you can get the running progress and a cancellation token
103 // to abort the upload (allowing UI for the user, etc)
104 //************************************
105 HRESULT SenUGCUpload(
106 int userIndex,
107 SenUGCID ugcID,
108 const SenUGCMetaData *metaData,
109 int nrMainDataBlobs,
110 const void **mainDataBlobs,
111 const size_t *mainDataBlobSizes,
112 SenSysCompletedCallback userCallback,
113 void *userCallbackData );
114
115 //************************************
116 // Method: SenUGCUploadMetadata
117 // FullName: Sentient::SenUGCUploadMetadata
118 // Access: public
119 // Returns: HRESULT
120 // Qualifier:
121 // Parameter: int userIndex
122 // Parameter: SenUGCID ugcID
123 // Parameter: const SenUGCMetaData * metaData
124 // Parameter: SenSysCompletedCallback userCallback
125 // Parameter: void * userCallbackData
126 // Upload the metadata and one binary data blob to the server.
127 // NOTE: data blob at index 0 should be the main level data blob, for the automatic
128 // download counter to work.
129 // The metadata will also have a data blob associated, but this should be
130 // kept to a minimum, as UGC download menus will probably want to download
131 // metadata for a lot of UGCs at once.
132 // NOTE: If a creator uploads metadata again, it will overwrite the previous
133 // stored blob with the new one.
134 //************************************
135 HRESULT SenUGCUploadMetadata(
136 int userIndex,
137 SenUGCID ugcID,
138 const SenUGCMetaData* metaData,
139 SenSysCompletedCallback userCallback,
140 void* userCallbackData);
141
142 //************************************
143 // Method: SenUGCUploadMainData
144 // FullName: Sentient::SenUGCUploadMainData
145 // Access: public
146 // Returns: HRESULT
147 // Qualifier:
148 // Parameter: int userIndex
149 // Parameter: SenUGCID ugcID
150 // Parameter: int mainDataBlobIndex
151 // Parameter: const void * mainDataBlob
152 // Parameter: const size_t mainDataBlobSize
153 // Parameter: SenSysCompletedCallback userCallback
154 // Parameter: void * userCallbackData
155 // Parameter: SenUGCProcessInfo* out_ugcUploadInfo
156 // Upload one binary data blob to the server.
157 // This SenUGCUpload method with the SenUGCProcessInfo signature is so you
158 // can get the progress percentage and a cancellation token, which can
159 // be used to abort the upload. This is useful for large uploads where
160 // you may want to allow the user to cancel.
161 // NOTE: This call is asynchronous ONLY and will error for synchronous
162 // attempts with a NULL param for userCallback.
163 // There are multiple data blobs supported (the exact number is defined in
164 // SenUGCMainData_NrBlobs) on subsequent calls. Slot zero is to be used by a
165 // game to store a preview thumbnail, which can then be downloaded without
166 // having to download the rest of the UGC. This could save bandwidth and
167 // make the game more responsive.
168 // NOTE: data blob at index 0 should be the main level data blob, for the automatic
169 // download counter to work.
170 // The metadata will also have a data blob associated, but this should be
171 // kept to a minimum, as UGC download menus will probably want to download
172 // metadata for a lot of UGCs at once.
173 // NOTE: if a level has been uploaded with main data before, and the creator
174 // wants to just modify the metadata, they can upload the metadata with the
175 // main data blob being NULL.
176 // NOTE: If a creator uploads a data blob again, it will overwrite the previous
177 // stored blob with the new one.
178 //************************************
179 HRESULT SenUGCUploadMainDataBlob(
180 int userIndex,
181 SenUGCID ugcID,
182 int mainDataBlobIndex,
183 const void* mainDataBlob,
184 const size_t mainDataBlobSize,
185 SenSysCompletedCallback userCallback,
186 void* userCallbackData,
187 SenUGCProgressInfo* out_progressInfo);
188
189 //************************************
190 // Method: SenUGCDelete
191 // FullName: Sentient::SenUGCDelete
192 // Access: public
193 // Returns: HRESULT
194 // Qualifier:
195 // Parameter: int userIndex
196 // Parameter: SenUGCID ugcID
197 // Parameter: SenSysCompletedCallback userCallback
198 // Parameter: void * userCallbackData
199 // Delete the UGC - only the user that created the UGC can delete it.
200 //************************************
201 HRESULT SenUGCDelete(
202 int userIndex,
203 SenUGCID ugcID,
204 SenSysCompletedCallback userCallback,
205 void* userCallbackData );
206
207 /*************************************
208 ***** UGC Consumption Functions *****
209 *************************************/
210
211 //************************************
212 // Method: SenUGCEnumerate
213 // FullName: Sentient::SenUGCEnumerate
214 // Access: public
215 // Returns: HRESULT
216 // Qualifier:
217 // Parameter: int userIndex
218 // Parameter: SenSysTitleID titleID
219 // Parameter: SenUGCSortBy sortBy
220 // Parameter: SenUGCType type
221 // Parameter: SenUGCAuthorType authorType
222 // Parameter: int nrAuthors
223 // Parameter: const XUID * authorList
224 // Parameter: SenUGCMetaDataFlags metaDataFlagFilter
225 // Parameter: SenUGCPublishState minPublishStateFilter
226 // Parameter: SenUGCPublishState maxPublishStateFilter
227 // Parameter: SenSysDateTime newerThan
228 // Parameter: SenUGCDescriptor descriptor
229 // Parameter: int maxNrResults
230 // Parameter: SenUGCSearchResult * outBuffer
231 // Parameter: unsigned int * outNrResults
232 // Parameter: SenSysCompletedCallback userCallback
233 // Parameter: void * userCallbackData
234 // Search the database for all the UGCs that match various search criteria.
235 // outBuffer should be an preallocated array of [sizeof(SenUGCSearchResult)*maxNrResults] bytes.
236 //************************************
237 HRESULT SenUGCEnumerate(
238 int userIndex,
239 SenSysTitleID titleID,
240 SenUGCSortBy sortBy,
241 SenUGCType type,
242 SenUGCAuthorType authorType,
243 int nrAuthors,
244 const PlayerUID *authorList,
245 SenUGCMetaDataFlags metaDataFlagFilter,
246 SYSTEMTIME *newerThan,
247 SenUGCDescriptor descriptor,
248 int maxNrResults,
249 SenUGCSearchResult *outBuffer,
250 UINT *outNrResults,
251 SenSysCompletedCallback userCallback,
252 void* userCallbackData );
253
254
255 /// @brief public
256 ///
257 /// @param[in] userIndex
258 /// @param[in] titleID
259 /// @param[in] sortBy
260 /// @param[in] type
261 /// @param[in] authorType
262 /// @param[in] nrAuthors
263 /// @param[in] authorList
264 /// @param[in] metaDataFlagFilter
265 /// @param[in] newerThan
266 /// @param[in] nrDescriptors
267 /// @param[in] descriptors
268 /// @param[in] maxNrResults
269 /// @param[out] outBuffer
270 /// @param[out] outNrResults
271 /// @param[in] userCallback
272 /// @param[in] userCallbackData
273 ///
274 /// @return Search the database for all the UGCs that match various search criteria.
275 /// outBuffer should be an preallocated array of [sizeof(SenUGCSearchResult)*maxNrResults] bytes.
276 ///
277 /// @details Enumerate by name will perform a look based on a various search criteria. The Collection
278 /// of descriptors will perform an equality lookup on Descriptor
279 ///
280 /// @related SenUGCEnumerate
281 HRESULT SenUGCEnumerate(
282 int userIndex,
283 SenSysTitleID titleID,
284 SenUGCSortBy sortBy,
285 SenUGCType type,
286 SenUGCAuthorType authorType,
287 int nrAuthors,
288 const PlayerUID *authorList,
289 SenUGCMetaDataFlags metaDataFlagFilter,
290 SYSTEMTIME *newerThan,
291 int nrDescriptors,
292 INT64 *descriptors,
293 int maxNrResults,
294 SenUGCSearchResult *outBuffer,
295 UINT *outNrResults,
296 SenSysCompletedCallback userCallback,
297 void* userCallbackData );
298
299 /// @brief public
300 ///
301 /// @param[in] userIndex
302 /// @param[in] titleID
303 /// @param[in] sortBy
304 /// @param[in] type
305 /// @param[in] authorType
306 /// @param[in] nrAuthors
307 /// @param[in] authorList
308 /// @param[in] metaDataFlagFilter
309 /// @param[in] newerThan
310 /// @param[in] nrDescriptors
311 /// @param[in] descriptors
312 /// @param[in] maxNrResults
313 /// @param[out] outBuffer
314 /// @param[out] outNrResults
315 /// @param[in] userCallback
316 /// @param[in] userCallbackData
317 ///
318 /// @return Search the database for all the UGCs that match various search criteria.
319 /// outBuffer should be an preallocated array of [sizeof(SenUGCSearchResult)*maxNrResults] bytes.
320 ///
321 /// @details Enumerate by Descriptor using a Logical And against all submitted Descriptor values.
322 /// The API filters the results on a specific UGC Type as well as an author
323 /// list type. Author List type of Everyone is NOT supported.
324 /// Note: The collection of descriptor bit masks is constrained to four.
325 ///
326 /// @related SenUGCEnumerate
327 HRESULT SenUGCEnumerateByDescriptorWithLogicalAnd(
328 int userIndex,
329 SenSysTitleID titleID,
330 SenUGCSortBy sortBy,
331 SenUGCType type,
332 SenUGCAuthorType authorType,
333 int nrAuthors,
334 const PlayerUID *authorList,
335 SenUGCMetaDataFlags metaDataFlagFilter,
336 SYSTEMTIME *newerThan,
337 int nrDescriptors,
338 INT64 *descriptors,
339 int maxNrResults,
340 SenUGCSearchResult *outBuffer,
341 UINT *outNrResults,
342 SenSysCompletedCallback userCallback,
343 void* userCallbackData );
344
345 /// @brief public
346 ///
347 /// @param[in] userIndex
348 /// @param[in] titleID
349 /// @param[in] type
350 /// @param[in] authorType
351 /// @param[in] nrAuthors
352 /// @param[in] authorList
353 /// @param[in] name
354 /// @param[in] maxNrResults
355 /// @param[out] outBuffer
356 /// @param[out] outNrResults
357 /// @param[in] userCallback
358 /// @param[in] userCallbackData
359 ///
360 /// @return Search the database for all the UGCs that match various search criteria.
361 /// outBuffer should be an preallocated array of [sizeof(SenUGCSearchResult)*maxNrResults] bytes.
362 ///
363 /// @details Enumerate by name will perform a wild card lookup on UGC name. The lookup will return anything
364 /// in the range of "%<NAME>%". The API filters the results on a specific UGC Type as well as an author
365 /// list type. Author List type of Everyone is NOT supported.
366 ///
367 /// @related SenUGCEnumerate
368 __declspec(deprecated("Use SenUGCEnumerateByName() instead"))
369 HRESULT SenUGCEnumerate(
370 int userIndex,
371 SenSysTitleID titleID,
372 SenUGCType type,
373 SenUGCAuthorType authorType,
374 int nrAuthors,
375 const PlayerUID *authorList,
376 const wchar_t *name,
377 int maxNrResults,
378 SenUGCSearchResult *outBuffer,
379 UINT *outNrResults,
380 SenSysCompletedCallback userCallback,
381 void* userCallbackData );
382
383 /// @brief public
384 ///
385 /// @param[in] userIndex
386 /// @param[in] titleID
387 /// @param[in] type
388 /// @param[in] authorType
389 /// @param[in] nrAuthors
390 /// @param[in] authorList
391 /// @param[in] name
392 /// @param[in] performWildCardLookup
393 /// @param[in] maxNrResults
394 /// @param[out] outBuffer
395 /// @param[out] outNrResults
396 /// @param[in] userCallback
397 /// @param[in] userCallbackData
398 ///
399 /// @return Search the database for all the UGCs that match various search criteria.
400 /// outBuffer should be an preallocated array of [sizeof(SenUGCSearchResult)*maxNrResults] bytes.
401 ///
402 /// @details Enumerate by name will perform an exact or wild card string lookup on UGC name. The API filters the results
403 /// on a specific UGC Type as well as an author list type. Author List type of Everyone is NOT supported.
404 ///
405 /// @related SenUGCEnumerate
406 HRESULT SenUGCEnumerateByName(
407 int userIndex,
408 SenSysTitleID titleID,
409 SenUGCType type,
410 SenUGCAuthorType authorType,
411 int nrAuthors,
412 const PlayerUID *authorList,
413 const wchar_t *name,
414 bool performWildCardLookup,
415 int maxNrResults,
416 SenUGCSearchResult *outBuffer,
417 UINT *outNrResults,
418 SenSysCompletedCallback userCallback,
419 void* userCallbackData );
420
421 //************************************
422 // Method: SenUGCDownloadMetaData
423 // FullName: Sentient::SenUGCDownloadMetaData
424 // Access: public
425 // Returns: HRESULT
426 // Qualifier:
427 // Parameter: int userIndex
428 // Parameter: SenSysTitleID titleID
429 // Parameter: int nrUGCs
430 // Parameter: const SenUGCID * ugcIDList
431 // Parameter: SenUGCDownloadedMetaData2 * outBuffer
432 // Parameter: SenSysCompletedCallback userCallback
433 // Parameter: void * userCallbackData
434 // Download the metadata for an array of UGCs
435 // Note that the metadata structure is a superset of the uploaded metadata,
436 // with various other information exposed.
437 // outBuffer should be an preallocated array of [(sizeof(SenUGCDownloadedMetaData)+SenUGCMetaData::BlobSizeLimit)*nrUGCs] bytes.
438 // This new signature is compatible with resubmission feature and 64-bit UGC Ids.
439 //************************************
440 HRESULT SenUGCDownloadMetaData(
441 int userIndex,
442 SenSysTitleID titleID,
443 int nrUGCs,
444 const SenUGCID *ugcIDList,
445 SenUGCDownloadedMetaData2 *out_metaData,
446 size_t *out_metaDataCount,
447 SenSysCompletedCallback userCallback,
448 void *userCallbackData );
449
450 __declspec(deprecated("Use signature with SenUGCDownloadedMetaData2."))
451 HRESULT SenUGCDownloadMetaData(
452 int userIndex,
453 SenSysTitleID titleID,
454 int nrUGCs,
455 const SenUGCID *ugcIDList,
456 SenUGCDownloadedMetaData *out_metaData,
457 size_t *out_metaDataCount,
458 SenSysCompletedCallback userCallback,
459 void *userCallbackData );
460
461 //************************************
462 // Method: SenUGCDownloadMainDataBlob
463 // FullName: Sentient::SenUGCDownloadMainDataBlob
464 // Access: public
465 // Returns: HRESULT
466 // Qualifier:
467 // Parameter: int userIndex
468 // Parameter: SenUGCID ugcID
469 // Parameter: int mainDataBlobID
470 // Parameter: size_t bufferSize
471 // Parameter: UINT blobVersion
472 // Parameter: void * outBuffer
473 // Parameter: size_t * outSize
474 // Parameter: SenSysCompletedCallback userCallback
475 // Parameter: void * userCallbackData
476 // Download a single blob of UGC data
477 // note that zero byte downloads will fail.
478 // ID, blobVersion, and bufferSize should be coming
479 // from SenUGCDownloadedMetaData.
480 // outBuffer should be an preallocated array of bufferSize bytes.
481 //************************************
482 HRESULT SenUGCDownloadMainDataBlob(
483 int userIndex,
484 SenSysTitleID titleID,
485 SenUGCID ugcID,
486 UINT mainDataBlobIndex,
487 size_t bufferSize,
488 UINT blobVersion,
489 void *outBuffer,
490 size_t *outSize,
491 SenSysCompletedCallback userCallback,
492 void *userCallbackData );
493
494 __declspec(deprecated("Use signature with blobVersion."))
495 HRESULT SenUGCDownloadMainDataBlob(
496 int userIndex,
497 SenSysTitleID titleID,
498 SenUGCID ugcID,
499 int mainDataBlobIndex,
500 size_t bufferSize,
501 void *outBuffer,
502 size_t *outBytesReceived,
503 SenSysCompletedCallback userCallback,
504 void *userCallbackData );
505
506 //************************************
507 // Method: SenUGCDownloadMainDataBlob
508 // FullName: Sentient::SenUGCDownloadMainDataBlob
509 // Access: public
510 // Returns: HRESULT
511 // Qualifier:
512 // Parameter: int userIndex
513 // Parameter: SenUGCID ugcID
514 // Parameter: int mainDataBlobID
515 // Parameter: size_t bufferSize
516 // Parameter: UINT blobVersion
517 // Parameter: void * outBuffer
518 // Parameter: size_t * outBytesReceived
519 // Parameter: SenSysCompletedCallback userCallback
520 // Parameter: void * userCallbackData
521 // Download a single blob of UGC data
522 // NOTE: zero byte downloads will fail.
523 // ID, mainDataRevision and bufferSize should be coming from a
524 // SenUGCDownloadedMetaData2 (where bufferSize comes from
525 // SenUGCDownloadedMetaData2's BlobInfo[mainDataBlobID].Size).
526 // outBuffer should be an preallocated array of bufferSize bytes.
527 // This signature includes an out param to include the progress
528 // percentage and cancellation token, etc to monitor and abort
529 // long running downloads (can be wired up to UI for users).
530 // BlobVersion is the version of the blob you want to download,
531 // which is available on the metadata information for the
532 // main data blobs (via DownloadMetaData).
533 //************************************
534 HRESULT SenUGCDownloadMainDataBlob(
535 int userIndex,
536 SenSysTitleID titleID,
537 SenUGCID ugcID,
538 UINT mainDataBlobIndex,
539 size_t bufferSize,
540 UINT blobVersion,
541 void *outBuffer,
542 size_t *outBytesReceived,
543 SenSysCompletedCallback userCallback,
544 void *userCallbackData,
545 SenUGCProgressInfo* out_progressInfo);
546
547 __declspec(deprecated("Use signature with blobVersion."))
548 HRESULT SenUGCDownloadMainDataBlob(
549 int userIndex,
550 SenSysTitleID titleID,
551 SenUGCID ugcID,
552 int mainDataBlobIndex,
553 size_t bufferSize,
554 void *outBuffer,
555 size_t *outBytesReceived,
556 SenSysCompletedCallback userCallback,
557 void *userCallbackData,
558 SenUGCProgressInfo* out_progressInfo);
559
560 /**********************************************
561 ***** UGC Reviewing and Rating Functions *****
562 **********************************************/
563
564 //************************************
565 // Method: SenUGCSetReviewScore
566 // FullName: Sentient::SenUGCSetReviewScore
567 // Access: public
568 // Returns: HRESULT
569 // Qualifier:
570 // Parameter: int userIndex
571 // Parameter: SenUGCID ugcId
572 // Parameter: SenUGCReviewScoreType type
573 // Parameter: UINT score
574 // Parameter: bool isFavorite
575 // Parameter: SenSysCompletedCallback callback
576 // Parameter: void * callbackData
577 //************************************
578 HRESULT SenUGCSetReviewScore(
579 int userIndex,
580 SenUGCID ugcId,
581 SenUGCReviewScoreType type,
582 unsigned int score,
583 bool isFavorite,
584 SenSysCompletedCallback callback,
585 void *callbackData );
586
587 //************************************
588 // Method: SenUGCGetReviewScore
589 // FullName: Sentient::SenUGCGetReviewScore
590 // Access: public
591 // Returns: HRESULT
592 // Qualifier:
593 // Parameter: int userIndex
594 // Parameter: SenUGCID ugcId
595 // Parameter: SenUGCReviewScoreType type
596 // Parameter: UINT * out_score
597 // Parameter: SenSysCompletedCallback callback
598 // Parameter: void * callbackData
599 //************************************
600 HRESULT SenUGCGetReviewScore(
601 int userIndex,
602 SenUGCID ugcId,
603 SenUGCReviewScoreType type,
604 unsigned int *out_score,
605 SenSysCompletedCallback callback,
606 void *callbackData );
607
608 //************************************
609 // Method: SenUGCSetFavoriteFlag
610 // FullName: Sentient::SenUGCSetFavoriteFlag
611 // Access: public
612 // Returns: HRESULT
613 // Qualifier:
614 // Parameter: int userIndex
615 // Parameter: SenSysTitleID titleID
616 // Parameter: SenUGCID ugcID
617 // Parameter: bool isFavorite
618 // Parameter: SenSysCompletedCallback userCallback
619 // Parameter: void * userCallbackData
620 // Users can flag the UGCs that they really like, which can be used for
621 // the search results
622 //************************************
623 HRESULT SenUGCSetFavoriteFlag(
624 int userIndex,
625 SenSysTitleID titleID,
626 SenUGCID ugcID,
627 BOOL isFavorite,
628 SenSysCompletedCallback userCallback,
629 void *userCallbackData );
630
631 //************************************
632 // Method: SenUGCGetFavoriteFlag
633 // FullName: Sentient::SenUGCGetFavoriteFlag
634 // Access: public
635 // Returns: HRESULT
636 // Qualifier:
637 // Parameter: int userIndex
638 // Parameter: SenSysTitleID titleID
639 // Parameter: SenUGCID ugcID
640 // Parameter: BOOL * outResult
641 // Parameter: SenSysCompletedCallback userCallback
642 // Parameter: void * userCallbackData
643 // Users can flag the UGCs that they really like, which can be used for
644 // the search results
645 //************************************
646 HRESULT SenUGCGetFavoriteFlag(
647 int userIndex,
648 SenSysTitleID titleID,
649 SenUGCID ugcID,
650 BOOL *outResult,
651 SenSysCompletedCallback userCallback,
652 void *userCallbackData );
653
654 //************************************
655 // Method: SenUGCGetFriendFavoriteCount
656 // FullName: Sentient::SenUGCGetFriendFavoriteCount
657 // Access: public
658 // Returns: HRESULT
659 // Qualifier:
660 // Parameter: int userIndex
661 // Parameter: SenSysTitleID titleID
662 // Parameter: SenUGCID ugcID
663 // Parameter: int * outResult
664 // Parameter: SenSysCompletedCallback userCallback
665 // Parameter: void * userCallbackData
666 // Find out how many friends of the user have flagged this UGC as
667 // a favorite (inclusive the user's favorite flag also)
668 //************************************
669 HRESULT SenUGCGetFriendFavoriteCount(
670 int userIndex,
671 SenSysTitleID titleID,
672 SenUGCID ugcID,
673 int *outResult,
674 SenSysCompletedCallback userCallback,
675 void *userCallbackData );
676
677 //************************************
678 // Method: SenUGCAddToCustomCounters
679 // FullName: Sentient::SenUGCAddToCustomCounters
680 // Access: public
681 // Returns: HRESULT
682 // Qualifier:
683 // Parameter: int userIndex
684 // Parameter: SenSysTitleID titleID
685 // Parameter: SenUGCID ugcID
686 // Parameter: INT64 customCounters[SenUGCDownloadedMetaData_NrCustomCounters]
687 // Parameter: SenSysCompletedCallback userCallback
688 // Parameter: void * userCallbackData
689 // Users can add to a fixed number of global counters stored on the
690 // servers, to count up a few basic stats per UGC (number of deaths,
691 // number of enemies killed, total playtime etc.)
692 //************************************
693 HRESULT SenUGCAddToCustomCounters(
694 int userIndex,
695 SenSysTitleID titleID,
696 SenUGCID ugcID,
697 INT64 customCounters[SenUGCDownloadedMetaData_NrCustomCounters],
698 SenSysCompletedCallback userCallback,
699 void* userCallbackData );
700
701 /// @brief API to flag a given piece of UGC as offensive.
702 ///
703 /// @param[in] userIndex
704 /// The index of the initiating user on the console.
705 /// Note: This is NOT a XUID.
706 ///
707 /// @param[in] ugcID
708 /// The unique ID for an instance of UGC.
709 ///
710 /// @param[in] offensivenessFlag
711 /// Offensive flag type.
712 ///
713 /// @param[in] reason
714 /// Reason for marking a given piece of UGC as offensive.
715 ///
716 /// @param[in] userCallback
717 /// If this call returns a success code,
718 /// the userCallback will be called at the end of the
719 /// asynchronous process.
720 ///
721 /// @param[in] userCallbackData
722 /// Data to be passed to the @a userCallback on completion.
723 ///
724 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success.
725 /// Specific values include:
726 ///
727 /// @details Users can flag a level that they think is offensive. The goal is that
728 /// the Sentient system will automatically be able to take down
729 /// levels after enough people have flagged a UGC as bad.
730 /// The number of votes to take something down will depend on the
731 /// reliability of the reviewers (number of offensiveness flags vs number of
732 /// downloads etc.) as well as the number of offensive uploads by the creator.
733 /// This function is also used by moderators to confirm or deny something as
734 /// being offensive.
735 ///
736 /// @related <Related API>
737 HRESULT SenUGCSetOffensivenessFlag(
738 int userIndex,
739 SenUGCID ugcID,
740 SenUGCOffensivenessFlag offensivenessFlag,
741 const wchar_t *reason,
742 SenSysCompletedCallback userCallback,
743 void *userCallbackData );
744
745 /// @brief This function will return whether or not a particular
746 /// piece of UGC has been banned.
747 ///
748 /// @param[in] userIndex
749 /// The index of the initiating user on the console.
750 /// Note: This is NOT a XUID.
751 ///
752 /// @param[in] The unique ID for UGC.
753 ///
754 /// @param[in] True if content is banned (and should not be viewed by user).
755 ///
756 /// @param[in] userCallback
757 /// If this call returns a success code,
758 /// the userCallback will be called at the end of the
759 /// asynchronous process.
760 ///
761 /// @param[in] userCallbackData
762 /// Data to be passed to the @a userCallback on completion.
763 ///
764 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success.
765 /// Specific values include:
766 ///
767 /// @details Any piece of UGC can been banned by a moderator or
768 /// moderation engine. This API allows clients to verify
769 /// if a given piece of UGC has been banned.
770 ///
771 /// @related SenUGCCreatePublishingUGCID()
772 /// @related SenUGCSetOffensivenessFlag()
773 /// @related SenUGCPublish()
774 HRESULT SenUGCIsBanned(
775 int userIndex,
776 SenUGCID ugcID,
777 BOOL *out_result,
778 SenSysCompletedCallback userCallback,
779 void *userCallbackData );
780
781 /*********************
782 ***** UGC Feeds *****
783 *********************/
784
785 /// @brief UGC Feed information
786 ///
787 /// @details When enumerating feeds, these are the available feeds that can be retrieved.
788 ///
789 struct SenUGCFeedInfo
790 {
791 SenUGCFeedType feedType;
792 wchar_t Name[32];
793 wchar_t Description[128];
794 };
795
796 /// @brief Retrieves a specific feed based on feedtype.
797 ///
798 /// @param[in] userIndex
799 /// The index of the initiating user on the console.
800 /// Note: This is NOT a XUID.
801 ///`
802 /// @param[in] titleID
803 ///
804 /// @param[in] feedType
805 /// Feed Type identifier for for the given feed being retrieved.
806 ///
807 /// @param[in] maxNumberOfFeedItems
808 /// Used to indicate the number of items to be returned by @a out_feedInfo.
809 /// If the actual number of items exceeds this, you will receive an error.
810 ///
811 /// @param[out] out_buffer
812 /// Pointer to the collection of structures to fill with SenUGCFeedItem data.
813 ///
814 /// @param[out] out_buffersize
815 /// The number of entries actually enumerated by the call.
816 ///
817 /// @param[in] userCallback
818 /// If this call returns a success code,
819 /// the userCallback will be called at the end of the
820 /// asynchronous process.
821 ///
822 /// @param[in] userCallbackData
823 /// Data to be passed to the @a userCallback on completion.
824 ///
825 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success.
826 /// Specific values include:
827 /// E_POINTER: out_buffer or out_buffersize are null.
828 ///
829 /// @details <Insert detailed method documentation>
830 ///
831 /// @related SenUGCEnumerateFeeds()
832 HRESULT SenUGCGetFeed(
833 int userIndex,
834 SenSysTitleID titleID,
835 SenUGCFeedType feedType,
836 size_t maxNumberOfFeedItems,
837 SenUGCFeedItem *out_buffer,
838 UINT *out_buffersize,
839 SenSysCompletedCallback userCallback,
840 void *userCallbackData );
841
842 /// @brief Retrieves a collection of feeds that are viewable by the
843 /// current user.
844 ///
845 /// @param[in] userIndex
846 /// The index of the initiating user on the console.
847 /// Note: This is NOT a XUID.
848 ///
849 /// @param[in] culture
850 /// This is the result of a call to SenCultureFind() or SenCultureGet*().
851 /// You may also pass NULL to use the culture set with SenCultureSetCurrent().
852 /// May be NULL for default culture.
853 ///
854 /// @param[in] maxResults
855 /// Used to indicate the number of items to be returned by @a out_feedInfo.
856 /// If the actual number of items exceeds this, you will receive an error.
857 ///
858 /// @param[out] out_feedInfo
859 /// Pointer to a collection of structures to fill with SenUGCFeedInfo data.
860 ///
861 /// @param[out] out_resultCount
862 /// The number of entries actually enumerated by the call.
863 ///
864 /// @param[in] userCallback
865 /// If this call returns a success code,
866 /// the userCallback will be called at the end of the
867 /// asynchronous process.
868 ///
869 /// @param[in] userCallbackData
870 /// Data to be passed to the @a userCallback on completion.
871 ///
872 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success.
873 /// Specific values include:
874 /// E_POINTER: out_feedInfo or out_resultCount are null.
875 ///
876 /// @details <Insert detailed method documentation>
877 ///
878 /// @related SenUGCGetFeed()
879 HRESULT SenUGCEnumerateFeeds(
880 int userIndex,
881 size_t maxResults,
882 SenUGCFeedInfo *out_feedInfo,
883 size_t *out_resultCount,
884 SenSysCompletedCallback userCallback,
885 void *userCallbackData);
886
887 /// @brief API that publishes UGC and makes the content accessible
888 /// to everyone on the Sentient service.
889 ///
890 /// @param[in] userIndex
891 /// The index of the initiating user on the console.
892 /// Note: This is NOT a XUID.
893 ///
894 /// @param[in] ugcID
895 /// The unique ID for an instance of UGC.
896 ///
897 /// @param[in] leaderboardDefinition
898 /// Optional parameter. Definition for a Leaderboard that
899 /// will be created and associated to newly published UGC.
900 ///
901 /// @param[out] out_leaderboardId
902 /// Created Leaderboard Id. Only returned to the client if
903 /// a Leaderboards Definition is passed to the server.
904 ///
905 /// @param[in] userCallback
906 /// If this call returns a success code,
907 /// the userCallback will be called at the end of the
908 /// asynchronous process.
909 ///
910 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success.
911 /// Specific values include:
912 ///
913 /// @details UGC is only accessible to the author until it has been published.
914 /// The user making the call must be the author of the UGC item.
915 /// The call will fail if this UGC item has previously been published.
916 /// By supplying an optional Leaderboard definition a Leaderboard is automatically
917 // allocated and associated with the UGC item.
918 /// This is the preferred way of creating UGC Leaderboards.
919 ///
920 /// @related SenCreateLeaderboard()
921 HRESULT SenUGCPublish(
922 int userIndex,
923 SenUGCID ugcID,
924 const SenLeaderboardDefinition *leaderboardDefinition,
925 SenLeaderboardId *out_leaderboardId,
926 SenSysCompletedCallback userCallback,
927 void *userCallbackData);
928
929 /// @brief API that publishes a new version of a UGC item and makes the revised content accessible
930 /// to everyone on the Sentient service.
931 ///
932 /// @param[in] userIndex
933 /// The index of the initiating user on the console.
934 /// Note: This is NOT a XUID.
935 ///
936 /// @param[in] ugcID
937 /// The unique ID for an instance of UGC.
938 ///
939 /// @param[in] userCallback
940 /// If this call returns a success code,
941 /// the userCallback will be called at the end of the
942 /// asynchronous process.
943 ///
944 /// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success.
945 /// Specific values include:
946 ///
947 /// @details New versions of UGC are only accessible to the author until it has been republished.
948 /// The user making the call must be the author of the UGC item.
949 ///
950 /// @related SenUGCPublish()
951 HRESULT SenUGCRepublish(
952 int userIndex,
953 SenUGCID ugcID,
954 SenSysCompletedCallback userCallback,
955 void* userCallbackData);
956
957} // namespace Sentient