Sentient Web Services

Sentient offers a set of online features that can enhance player experience and potentially impact your business revenues. The Sentient team will work with you to determine which features best suit your title and business requirements and then help you integrate those services into your title. The following web services are available:

  • Telemetry: Monitor player patterns, through title-defined hooks, to create business intelligence reports and impact player experience.
  • Dynamic Configuration: Host custom data to modify game behaviors for online players.
  • Cross Title Promotional/Box Art*: Dynamically upsell additional, curated content offered on the Xbox LIVE Game Marketplace, using custom marketing text and box art delivered from Sentient.
  • News*: Keep your community informed and engaged. The Sentient News service retrieves localized programmed and system-generated news ticker messages from the server.
  • User Generated Content (UGC)*: Share and search for user created game content. Users can also flag inappropriate content and moderators can review and take down offensive material.
  • Leaderboard*: Support friend-based and top-100 leaderboard value tracking for user created content.
  • Avatar Superstars*: Create a social, cross title, participation-based reward system for high quality games, where avatars are featured as the primary stars of game play.
  • Fame*: Earn points through a variety of play milestones, events and weekly challenges, which go toward Avatar Superstar awards or Fame VIP status across all Sentient titles.

* Requires UI implementation by the game.

The Sentient services all work together to enhance the offerings of each other. For example, you can collect telemetry data and use this information to dynamically configure your game using the Dynamic Configuration feature. After you update your game, you can then send a message to players via the news ticker to let them know about the enhancements to the game.

The Sentient team recommends that all titles implement at least the Telemetry and Dynamic Configuration services.

Start Here

Before you decide whether to implement the Sentient Services in your title, browse through the available services and then contact the Sentient team (senaccts@microsoft.com) to help you design your solution. For more information, see:

Getting Started with Sentient

Documentation Version

Version: Build 2871

The current version of the Sentient documentation is available on the Sentient Developer Website.


Copyright Notice

Information in this document, including URLs and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in examples herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2011 Microsoft Corporation. All rights reserved.

Microsoft, Xbox, Xbox 360, Xbox LIVE and Sentient Web Services are trademarks of the Microsoft group of companies.

All other trademarks are property of their respective owners.


What's New in This Release

The following features and documentation updates are new for this release.

What's New in Sentient

What's New in Sentient Core

The Sentient culture functionality was deprecated and the following API were removed from the headers:

  • SenCultureFind Function
  • SenCultureGetCurrent Function
  • SenCultureSetCurrent Function
  • SenCultureGetDefault Function
  • SenCultureSetDefault Function
  • SenCultureGetParent Function
  • SenCultureGetSystemCultureString Function
  • SenCultureGetSystemLanguageString Function
  • SenCultureGetSystemLocaleString Function
  • SenCultureInfo Structure

The following functions were deprecated and new versions created with the culture parameter removed:

  • SenAvatarDownloadExtraInfo
  • SenBoxArtDownloadExtraInfo
  • SenGetAwardMessage
  • SenGetFameDisplayData
  • SenGetTickerMessage
  • SenUGCEnumerateFeeds
  • SenGetVIPLevelName

What's New in Dynamic Configuration

The following API have been deprecated:

  • SenConfigFileFind Function
  • SenConfigFileDownload Function
  • SenConfigInfo Structure

Instead, use these functions to retrieve configuration files:

  • SenDynamicConfigGetSize
  • SenDynamicConfigGetSize (overloaded)
  • SenDynamicConfigGetBytes
  • SenDynamicConfigGetBytes (overloaded)

What's New in Sentient Core

The following raw data API have been deprecated in SenRawData.h and removed from the documentation:

  • SenRawDataCategory Enumeration
  • SenRawDataSetDefaultDevice Function
  • SenRawDataGetDefaultDevice Function
  • SenRawDataAllowPrompt Function
  • SenRawDataPromptAllowed Function
  • SenRawDataAvailable Function

The overloaded SentientInitialize and the Sentient Configuration File are deprecated and have been removed from the documentation.

What's New in Leaderboards

The following API have been updated with a descriptor parameter that identifies the leaderbaord entry.

  • SenSetUserLeaderboardValue Function
  • SenSetUserLeaderboardValue Function (overloaded)
  • SenLeaderboardEntry Structure

What's New in User Generated Content

The following API have been updated to remove the mainDataRevision parameter.

  • SenUGCDownloadMainDataBlob Function
  • SenUGCDownloadedMetaData Structure

What's New in Avater

The Sentient Help API have been deprecated.

  • SenHelpFileFind Function
  • SenHelpFileDownload Function
  • SenHelpInfo Structure

What's New in the Documentation

New Cultures Topic

  • Using Cultures with Sentient

New Dynamic Configuration API

  • SenDynamicConfigGetSize
  • SenDynamicConfigGetSize (overloaded)
  • SenDynamicConfigGetBytes
  • SenDynamicConfigGetBytes (overloaded)

Portal Procedures have been Updated

The procedure to upload and download information to the Sentient Developer Website (https://sentient.msgamestudios.com/Default.aspx) have been updated in these topics:

  • Getting the Sentient Configuration Tools
  • Downloading the Schema
  • Telemetry Reports
  • Uploading a Configuration File to the Sentient Developer Website
  • Uploading Fame Challenges to the Sentient Developer Website


What's New in Build 2734

The following features and documentation updates are new for this release.

What's New in Sentient

What's New in User Generated Content

An overloaded version of SenUGCEnumerate was added to SenClientUGC.h. This function searches for UGC items by name.

A new feed type was added toSenUGCFeedType (SenClientUGCTypes.h) to support custom feed types.

What's New in Leaderbaord

SenLeaderboardEntryValue is now an int64 in SenClientUGCTypes.h.

What's New in News

A new constant (MAX_NEWS_ITEM_COUNT) to limit the number of new items was added to SenClientNews.h.

What's New in Fame

The order of members is changed in the SenFameLeaderboardEntry structure.

What's New in the Documentation

Telemetry

Extensive new documentation on how to design your telemetry statistics. For more information, see Understanding Telemetry.

User Generated Content

Added the SenUGCEnumerate overloaded function.


What's New in Build 2449

The following features and documentation updates are new for this release.

What's New in Sentient

What's New in Box Art

The deprecated versions of the following functions have been removed from the docs.

  • SenBoxArtEnumerate
  • SenBoxArtDownloadExtraInfo

You should already be using the updated versions of these functions.

What's New in Telemetry

The following API was added to request that Sentient immediately send any buffered statistics.

  • SentientFlushStats

What's New in UGC

The following SenUGCFeedType enumeration value has been updated:

  • Old Value: SenUGCFeedType_PendingModeratorReview = 0x80000000
  • New Value: SenUGCFeedType_PendingModeratorReview = 0x60

What's New in Front Page

The SenClientFrontPage.h header was removed from the build.

What's New in the Documentation

Telemetry

The new API SentientFlushStats to send buffered statistics immediately to Sentient.

Dynamic Configuration

Added example code to Retrieving a Configuration File.


What's New in Build 2339

The following features and documentation updates are new for this build.

What's New in Sentient

What's New in User Generated Content

The SenUGCFeed structure was removed from SenClientUGC.h. Instead use SenUGCFeedInfo and SenUGCFeedItem.

The SenUGCReviewScore structure was removed from SenClientUGCTypes.h.

What's New in Leaderboards

The reserved_metaDataBlocCount member was added to the SenLeaderboardEntry structure in SenClientUGCTypes.h.

What's New in Fame

The SenFameVIPLevel enumeration is new in SenClientFame.h.

The SenFameLeaderboardFilter enumeration constants in SenClientFame.h have been renamed to indicate that they are filters.

The user index parameters have been removed from the SenGetTimeLeftInFameWeek and SenGetFameDisplayDataCount functions in SenClientFame.h

The SenGetVIPLevelName function in SenClientFame.h is deprecated.

What's New in the Documentation

Fame

The documentation includes the Fame reference topics and overview topics on Fame Challenges.

Avatar Superstars

The documentation includes all API reference material.

News

The documentation includes all API reference material.

UGC Revocation API

New topics include:

UGC Publish States

Managing User Generated Content

The Sentient Moderation Engine

Moderating User Generated Content

Managing Flagged Content


What's New in Build 2227

The following features and documentation updates were released in build 2227.

What's New in Sentient

What's New in Telemetry

You can set the interval to send Telemetry statistics to the server with the new SentientSetStatSendInterval function. This function is provided for debug mode only in SenClientStats.h.

What's New in Box Art

The Box Art functions are updated to include Sentient handles that you can use to cancel the operation (in SenClientBoxArt.h):

  • SenBoxArtEnumerate
  • SenBoxArtDownloadExtraInfo
  • SenBoxArtDownloadImage

What's New in News

Updated SenGetTickerMessage in SenClientNews.h to retrieve culture information.

What's New in Sentient Types

New error coders were added for invalid parameters in SenTypes.h. The system language type was also removed as all API are now using Sentient cultures to set language.

What's New in Fame

The following API are new in SenClientFame.h:

SenRegisterFameMPGame Function: Registers participants in a game.

SenAcknowledgeVIPLevelChange Function: Acknowledge VIP level change.

SenGetFameVIPLevelName Function: Gets the name for a VIP level.

SenFameMPGameParticipant Structure: : Holds player status.

SenFameDisplayData Structure: Holds Fame data.

SenFameLeaderboardRequest Structure: Holds leaderboard rank and filter.

SenFameLeaderboardFilter Enumeration: Flags to filter on friends or allow everyone.

SenFameLeaderboardRankType Enumeration: Flags to describe if rank is weekly, lifetime or superstar.

The following API have been updated in SenClientFame.h:

SenGetFameDisplayData Function: New parameter to get the Culture information.

SenGetAwardMessage Function: New parameter to get the Culture information.

SenGetVIPLevelName Function: Gets the VIP level.

SenGetTimeLeftInVIPLevel Function: Removed the period parameter.

SenGetTimeLeftInFameWeek Function: Removed the SenFameEventFrequency period parameter.

SenAwardMessageData Structure: Removed members.

SenFameLeaderboardEntry Structure: New member to count superstars.

SenFameVIPData Structure: Added members to count fame points.

The following API have been removed from SenClientFame.h:

SenFameAwardID Enumeration

SenFameEventFrequency Enumeration

SenFameLeaderboardType Enumeration

SenFameTimePeriod Enumeration

SenFameGamesList Enumeration

SenFameGamesList Enumeration

SenFameLeaderboardData Structure

What's New in the Documentation

UGC Revocation API: Players can flag offensive content and moderators can remove inappropriate items.

UGC Feeds API: Players can subscribe to feeds to get the top rated or top downloaded UGC items.

Leaderboard API: Create custom leaderboards and add entries, or use the Sentient-generated leaderboards for Xbox LIVE Friends or top-rated players.

Miscellaneous Updates:

SenBoxArtEnumerate: This deprecates SenBoxArtEnumerate

SenBoxArtDownloadExtraInfo: This deprecates SenBoxArtDownloadExtraInfo

SenBoxArtDownloadImage: This deprecates SenBoxArtDownloadImage

SentientSetStatSendInterval: Telemetry API to set send interval in debug mode.


What's New in Build 2025

The following features and documentation updates are new for build 2025.

What's New in the Sentient API

Sentient User Generated Content (UGC) v1.0 is feature complete.

Moderation and Revocation System

The following moderation and revocation system features were added for this release:

  • Users can flag a piece of content as objectionable based on specific Sentient reason codes from within the title.
  • After a piece of content has reached the moderation threshold, it is removed from enumeration and public feeds until it has been reviewed by approved, title specific moderators.
  • Approved moderators receive a unique moderation feed while playing the title which highlights all content that should be reviewed.
  • Moderator can either ban or approve the content to return to the community

API updates for this feature include:

SenUGCPublishState enumeration: Updated to remove unused publish states.

SenUGCOffensivenessFlag enumeration: The codes have been finalized. Thte title decides which reason (if any) are exposed to the user.

SenUserRole enumeration: New enumeration to specify moderator role.

SenUserIsInRole function: New function to determine if a moderator exists. Tow versions are supplied, one to identify moderator by

SenUserIsInRole function: New function to determine if a moderator exists (overloaded version).

UGC Feeds

The following feed system features were added for this release:

  • Users identified as moderators for your title will receive a new moderator feed. The SenUGCFeedType_PendingModeratorReview is returned by SenUGCEnumerateFeeds.
  • A new feed for "Top Rated this Week" based on average review scores with a sliding 7 day time window.
  • A new feed for "Top Downloaded this Week" defined by a sliding 7 day time window.

Client Transport

The following Sentient Client Transport bug fix is included in this release:

  • The callback is not called if the client disconnects before a callback is invoked.

What's New in the Documentation

Cross Title Promotional : How to enumerate and download content offered in the Xbox LIVE Game Marketplace to upsell content to players.

Dynamic Configuration : How to find and download your custom configuration data to modify game behaviors.

Setting the Device ID: How to set the device on which to store content such Box Art or configuration data.

Reference documentation for the following headers:

Sentient Culture Utility Functions: SenClientCulture.h

Sentient Utilities: SenClientUtil.h

Sentient Types: SenClientTypes.h

Sentient Core Functions: SenClientMain.h

Sentient System Utilities: SenClientSys.h

Sentient Box Art: SenClientBoxArt.h

Sentient XML Utilities: SenClientXML.h


Getting Started with Sentient

This Getting Started Guide is a quick guide to downloading the Sentient SDK and implementing the basic Sentient Services in your title.

Deciding Which Features to Use

Integrating Sentient into your title is a collaborative effort between title developers, Microsoft Studio (MS) Producers and the Sentient team. After you determine what features you want to incorporate into your title, we encourage you to schedule time with the Sentient team so we can review your requirements and provide guidance on how best to achieve your goals. If an existing Sentient feature does not exactly meet your needs, send us your feedback to help us improve our offerings.

Contacting the Sentient Team

Email the Sentient Onboarding Team at senhelp@microsoft.com with any questions while you are evaluating the Sentient SDK.

In This Section

Downloading the Sentient SDK

Using the Sentient Service

Connecting to the Sentient Service

Updating the Sentient Service


Downloading the Sentient SDK

The Sentient Developer Website (https://sentient.msgamestudios.com) has the latest Sentient SDK downloads and release notes, along with several tools to help you get started using the Sentient services. When you register your title on the site, you can manage your product’s version and game configurations for the features you implement in your title. The telemetry data reports generated for your title are also available on this site.

To gain access to the Sentient SDK and Developer Website, ask your MGS Producer to return the information requested in the email below to the Sentient Onboarding team (senhelp@microsoft.com).

Create an Account

After your account is created, you can download the latest Sentient SDK from the Sentient Developer Website.


Sentient Libraries

The libraries that you use are dependent on the features that your title implements. To connect to the Sentient servers you must include the SenClientCore.h file and link to the SenCore.lib library. This library also implements the Telemetry and Dynamic Configuration services. Other services require additional libraries.

To help you develop and test your title, debug versions of the libraries for each feature are provided. The debug libraries output additional information that helps you debug your application. For example, you can use the SenCoreD.lib to develop your title and then link to the SenCore.lib version before you release the game. Debug libraries are located in the libs folder along with the released version libraries. The SDK download includes the following folders:

           SDK Version: The version of the Sentient SDK that your title uses.

           include: The header files for all Sentient features.
           libs: The libraries for each feature.

                    Telemetry: SenCore.lib
                    Dynamic Configuration: SenCore.lib
                    Cross Title Promotional/Box Art: SenBoxArt.lib
                    News: SenNews.lib
                    User Generated Content (UGC): SenUGC.lib
                    Leaderboard: SenUGC.lib
                    Avatar Superstars/Fame: SenSuperstars.lib

For more information, see the Getting Started Guides for the individual Sentient features to determine which headers to include.


Getting the Sentient Configuration Tools

Sentient provides tools on the Sentient Developer Website to help you implement the following Sentient Services:

Telemetry Tool: Download the Telemetry definition schema and define telemetry data for your title. To download the schema:

  1. On the Management Tools menu, select the Telemetry Tool.
  2. Click on the Telemetry Definition Schema link to download it.

When you upload your XML document, the Telemetry CodeGen tool generates methods that you call to send data to Sentient. To upload your telemetry XML document and access your generated code:

  1. On the Management Tools menu, select the Telemetry Tool.
  2. Select your title from the drop-down list (if you only have one title, the UI to upload your XML document appears immediately).
  3. Click Browse to upload a new XML document, and then click Upload.
  4. Sentient creates the custom code and enters the file in the list of telemetry files for your title.

For more information, see Getting Started with Telemetry.

Telemetry Reports: Sentient aggregates the telemetry data that you send to the service and generates reports that you can use to test your telemetry data. To view reports for your title:

  1. On the Data Tools menu, select Telemetry Logs.
  2. Select your title from the drop-down list (if you only have one title, your telemetry reports appear immediately).
  3. Click on a Report link to download your report.

Fame Management Tool: Download the Challenge Definition Schema to define Fame challenges for your title. To access this tool and download the schema:

  1. On the Management Tools menu, select Fame Management.
  2. Click on the Challenge Definition Schema link to download it.

Create your Fame challenges and enter them into your Challenge Definition XML document. To upload this document:

  1. On the Management Tools menu, select Fame Management.
  2. Select your title from the drop-down list (if you only have one title, the UI to upload your XML document appears immediately).
  3. Click Browse to upload a new XML document.

After you uploaded the challenge document, they appear in a list on this page.

Dynamic Configuration Tool: Use this tool to upload your dynamic configuration files and then access them from your title to dynamically configure your online game. To access this tool and upload a configuration file:

  1. On the Management Tools menu, select Dynamic Configuration.
  2. Select your title from the drop-down list (if you only have one title, the UI to upload your XML document appears immediately).
  3. Select Create New and enter the ResourceID, Start Date/Time, End Date/Time, Priority and Comments.
  4. Select Browse to upload a configuration file. The uploaded file appears in the list of files available for your title.

News Tool: Use this tool to upload news ticker messages. These messages are displayed randomly in the news ticker. To access this tool and create News Messages:

  1. On the Management Tools menu, select News Management.
  2. Select your title from the drop-down list (if you only have one title, the UI to upload your XML document appears immediately).
  3. Select Create New to create a new message.
  4. Enter the Start Date, Expiry Date, Priority, Message, Characters/Second, Language ID, Geographic ID, and then click Create.

The news messages available to your title appear in the list.


Using the Sentient Service

To connect your title to the Sentient Services:

  1. Verify that your title is registered on the Sentient Developer Website.
  2. Include the SenClientCore.h and SenCore.lib files in your project.
  3. Call SentientInitialize to connect to the Sentient and XLSP servers and start using the service. During initialization, Sentient connects to the server and downloads game configuration files.
  4. Call SentientUpdate continually to check the connections to the server and download information from the server. Asynchronous requests to Sentient can only complete in this call.

You can call SentientCancel to cancel asynchronous operation at any time. When you are ready to shut down the service, call SentientShutdown.


Connecting to the Sentient Service

To connect to the Sentient and XLSP servers and start using the Sentient Service, call SentintenInitialize as follows:

    HRESULT hr;
    SenSysTitleID titleID;

    // The Xbox LIVE title ID
    titleID = 0xFFFFDC4A;

    hr = SentientInitialize( titleID );

When you call SentientInitialize, Sentient connects your title to the XLSP and Sentient servers.


Updating the Sentient Service

You should call SentientUpdate continually in your code, which prompts Sentient to do the following:

  1. Check the connection to the Sentient and XLSP servers and return connection errors to the game. Sentient attempts to reconnect if connections are lost for any reason.
  2. Send and retrieve data from the server for all services implemented by your title such as ticker messages or telemetry statistics.
  3. Perform requested tasks, such as downloading cached data to the hard drive or processing network messages and then invoke the callback for completed tasks.

Example code to call SentientUpdate:

HRESULT SentientService::Update()
{
    HRESULT hr = S_OK;

    // Update Sentient System
    HRESULT sentientResult = Sentient::SentientUpdate();

    switch(sentientResult)
    {
         case S_OK:
         {
          // Sentient is connected
          OutputDebugString ("\nCONNECTED\n");

             // Add title specific code here. . .
      }
      break;

      case Sentient::SENTIENT_S_NOT_SIGNED_IN_TO_LIVE:
      {
               // Login required
            OutputDebugString ("\nWARNING: an Xbox LIVE-enabled user
                                   needs to be logged in.\n");

             // Add title specific code here. . .
      }
         break;

      case Sentient::SENTIENT_S_INITIALIZING_CONNECTION:
      {
             // Server connection in progress
          OutputDebugString ("Establishing connection to sentient server.\n");

             // Add title specific code here. . .
      }
      break;

      case Sentient::SENTIENT_S_SERVER_CONNECTION_FAILED:
      {
             // Server connection failed
          OutputDebugString ("\nWARNING: connection to sentient
                                 server failed.\n");

             // Add title specific code here. . .
       }
       break;

       default:
       {
              // Unknown failure
        OutputDebugString ("Unknown result from SentientUpdate()");

             // Add title specific code here. . .
          }
       break;
    }

    return hr;
}


Sentient Core Services

The Sentient core services include the following functionality:

  • Functions to initialize, update and shutdown the Sentient Service
  • File and raw data transfer structures
  • System callback functions
  • Custom memory allocation functions
  • Utilities to help with system time and word wrap


Using Cultures with Sentient

Some Sentient services, such as Box art and Avatars, supply localized strings to players. When Sentient API return localized strings, Sentient uses the system language and locale settings to determine which string to return. Sentient uses the following rules to return localized strings:

  1. If the locale specific string is available, Sentient returns that version of the string.
  2. If the locale specific string is not available and the locale neutral version is available, Sentient returns the locale neutral version of the string.
  3. If the locale neutral string is not available, Sentient returns the “en” version of the string.

Creating Localized Strings

Sentient supports all the cultures on the local machine, either Xbox or Windows; however, when you define localized strings, Sentient requires that you adhere to the following rules:

  1. You must supply an “en” string as the final fallback for all localized strings. For example, you can define an “en-US” string, but because it is not the Sentient-defined final fallback specifier, you must also define an “en” version.
  2. For all languages that you support, you must also supply the locale neutral string for that language. For example, if you define a string for the “fr-CA” culture, you must also define a string for the locale neutral culture for that language “fr”.

Note that the locale neutral identifier for traditional Chinese is “zh-hant” and the locale neutral identifier for simplified Chinese is “zh-hans”.

Localized Strings Example

Depending on the service, Sentient has different ways to create localized strings. For example, you can provide localized strings in an XML document or in the UI on the Sentient Developer Portal (https://sentient.msgamestudios.com/). The following example shows how to create locale neutral English language strings for a Fame Challenge:

<ChallengeDefinition id="11" name="game winner">

<description language="en">Win five games</description>

<milestone target="5" famePoints="75">

<description language="en">You won five games!</description>

</milestone>

</ChallengeDefinition>

You can create additional language and locale strings as shown below, but you must always supply the locale neutral and the “en” versions as follows:

<description language="fr-CA">Premier ami ayant le titre - eh!</description>

<description language="fr">Premier ami ayant le titre!</description>

<description language="en">First friend owns the title!</description>

For more information on how to provide localized strings for your Sentient service, contact the Sentient Team at (senhelp@microsoft.com).


Sentient Core Reference

This section contains reference information for the Microsoft Sentient API.

In This Section

  • Core Functions
  • Core Structures
  • Core Enumerations
  • Core Callback Functions
  • Core Operators
  • Sentient Constants
  • Sentient Types
  • Sentient Configuration File


Core Functions

This section contains API reference functions that you use with the Microsoft Sentient APIs.

In This Section

Sentient Core

All titles use the core Sentient functions to connect to the service and receive callbacks.

Function | Description
SentientInitialize | Initializes the Sentient core libraries and loads the server configurations.
SentientUpdate | Connects to the Sentient XLSP (Xbox LIVE Server Platform) and Xbox LIVE servers and performs scheduled tasks.
SentientCancel | Immediately cancels the specified asynchronous Sentient operation.
SentientShutdown | Disconnects from the Sentient servers and disables the Sentient Service.
Sentient File

Titles use these functions for services that download files from the Sentient servers.

Function | Description
SenFileDigestCreate | Calculates a digest from the contents of a file.
Sentient System

Titles use these functions across all services to retrieve SDK versions and set custom allocators.

Function | Description
SenSysGetGFWLSDKVersion | Returns the Games for Windows LIVE (GFWL) SDK version number that Sentient was compiled against.
SenSysGetXDKVersion | Returns the XDK version that Sentient was compiled against.
SenSysMemAllocated | Returns the sum of all the memory currently allocated by Sentient.
SenSysSetMemAllocCallback | Redirects Sentient's memory allocator to a custom memory allocator.
SenSysSetMemFreeCallback | Redirects Sentient's memory release operations to a custom memory deallocator.
SenSysSetOutputCallback | Redirects Sentient's debug output to a custom debug callback.
Sentient Utilities

Titles use these functions across all services to determine if line lengths are suitable for display.

Function | Description
SenUtilDateTimeMax | Returns a SYSTEMTIME structure set to the latest representable SQL time.
SenUtilDateTimeMin | Returns a SYSTEMTIME structure set to the earliest representable SQL time.
SenUtilWordWrapFindNextLine | Signals a callback function that returns the width, in pixels, of a line of text.


SentientInitialize Function

Initializes the Sentient core libraries and loads the server configurations.

Syntax

C ++
HRESULT SentientInitialize(
   SenSysTitleID  titleID
);

Parameters

titleID

[in] A SenSysTitleID that uniquely identifies an Xbox LIVE title. Internally, Sentient assigns a title identifier to each title that is within the 32 bit range specified by the SenSysTitleID enumeration.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

Sentient initialized successfully.

SENTIENT_E_ALREADY_INITIALIZED

Sentient is already initialized.

E_FAIL

An unknown error occurred during Sentient initialization. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

Remarks

This function must be called before your title attempts to transfer data to or from the Sentient servers. SentientInitialize can only be called once; shutting down and reinitializing Sentient is not supported. Internally this API may allocate memory and generate network traffic.

Titles that want to handle Sentient memory allocations and debug output should initialize these systems before calling SentientInitialize. For more information, see SenSysMemAllocated and SenSysMemFreeCallback.

The following functions may be called before SentientInitialize:

  • SenSysGetXDKVersion
  • SenSysSetMemAllocCallback
  • SenSysSetMemFreeCallback
  • SenSysSetOutputCallback

Requirements

Header: SenClientMain.h

Library: SenCore.lib

See Also

Core Functions

SentientUpdate

SentientShutdown

SentientCancel

Getting Started with Sentient

Start Using the Sentient Service

Connect to the Sentient Service


SentientUpdate Function

Connects to the Sentient XLSP (Xbox LIVE Server Platform) and Xbox LIVE servers and performs scheduled tasks.

Syntax

C ++
HRESULT Sentientupdate();

Parameters

This function takes no parameters.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The connection to the Sentient XLSP and Xbox LIVE servers was successful.

SENTIENT_S_NOT_SIGNED_IN_TO_LIVE

The local user is not currently signed into Xbox LIVE. Any calls to Sentient APIs other than SentientUpdate will fail immediately.

SENTIENT_S_SERVER_CONNECTION_FAILED

The connection to the Xbox LIVE server is active, but the connection to the Sentient XLSP is not available.

SENTIENT_S_INITIALIZING_CONNECTION

A new connection to the Sentient XLSP servers has been established.

SENTIENT_E_NOT_INITIALIZED

Sentient is not currently initialized.

Remarks

When you call SentientUpdate, Sentient perform various scheduled tasks such as downloading news ticker messages or uploading statistics. Sentient also downloads cached data to the hard drive and processes network messages. Asynchronous requests to Sentient can only complete in the call to SentientUpdate unless they were previously canceled in a call toSentientCancel.

SentientUpdate return codes provide information about the status of the connection to the Sentient servers. Call this function on a regular basis to verify the connections to the servers. Server connections can change due to external events such as users logging in or out of Xbox LIVE.

When this function returns a success code, you should check the specific return value to present the appropriate user experience. To comply with the Xbox TCR099 requirements, it is important to distinguish between the SENTIENT_S_NOT_SIGNED_IN_TO_LIVE and SENTIENT_S_SERVER_CONNECTION_FAILED.

Requirements

Header: SenClientMain.h

Library: SenCore.lib

See Also

Core Functions

SentientInitialize

SentientShutdown

SentientCancel

Update the Sentient Service

Getting Started with Sentient

Start Using the Sentient Service


SentientCancel Function

Immediately cancels the specified asynchronous Sentient operation.

Syntax

C ++
HRESULT SentientCancel(
   SenHandle  task
);

Parameters

task

[in] A handle to the asynchronous operation that is canceled. This handle was previously returned to the application from a call to an asynchronous Sentient API.

Return Values

Returns S_OK if the asynchronous operation was canceled; otherwise, an error code. The following is one possible error code:

E_HANDLE

The supplied handle was NULL or was not a valid Sentient handle.

Remarks

Before SentientCancel returns, any completion callback functions passed to the Sentient API that initiated the asynchronous operation will be invoked. You can safely free any memory associated with the cancelled operation immediately following the call to SentientCancel.

Requirements

Header: SenClientMain.h

Library: SenCore.lib

See Also

Core Functions

SentientInitialize

SentientUpdate

SentientShutdown

Getting Started with Sentient

Start Using the Sentient Service


SentientShutdown Function

Disconnects from the Sentient servers and disables the Sentient Service.

Syntax

C ++
HRESULT SentientShutdown();

Parameters

This function takes no parameters.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

Sentient shut down was successful.

E_FAIL

Sentient failed to shut down.

Note: You should consider that Sentient has shut down even when you receive this error code.

SENTIENT_E_NOT_INITIALIZED

Sentient is not currently initialized or is already shut down.

Remarks

Call this function when the game shuts down. You do not need to call SentientShutdown on an Xbox 360.

Requirements

Header: SenClientMain.h

Library: SenCore.lib

See Also

Core Functions

SentientInitialize

SentientUpdate

SentientCancel

Getting Started with Sentient

Start Using the Sentient Service


SenFileDigestCreate Function

Calculates a digest from the contents of a file.

Syntax

C ++
SenFileDigest SenFileDigestCreate(
    size_t dataSize,
    const BYTE *data
);

Parameters

dataSize

[in] The number of bytes in the file.

data

[in] The raw data of the file.

Return Values

This function always returns a SenFileDigest structure that contains the digest of the file.

Remarks

In general, titles do not need to call this function. However, you can use this function if you want to manually cache your files.

Requirements

Header: SenClientFile.h

Library: SenCore.lib

See Also

Core Functions

SenFileDigest


SenSysGetGFWLSDKVersion Function

Returns the Games for Windows Live (GFWL) SDK version number that Sentient was compiled against.

Syntax

C ++
int SenSysGetGFWLSDKVersion(
);

Parameters

The function takes no parameters.

Return Values

If the function succeeds, it returns the GFWL SDK version number that Sentient was compiled against; otherwise zero.

Remarks

The GFWL SDK version.

Requirements

Header: SenClientSys.h

Library: SenCore.lib

See Also

Core Functions

SenSysGetXDKVersion


SenSysGetXDKVersion Function

Returns the XDK version that Sentient was compiled against.

Syntax

C ++
int SenSysGetXDKVersion(
);

Parameters

This function takes no parameters.

Return Values

If the function succeeds, it returns the XDK version number that Sentient was compiled against; otherwise zero.

Remarks

This function is only used to test your application and can be called as follows:

     // Ensure this links against the right version of the XDK
     assert(Sentient::SenSysGetXDKVersion() == _XDK_VER);

Requirements

Header: SenClientSys.h

Library: SenCore.lib

See Also

Core Functions

SenSysGetGFWLSDKVersion


SenSysMemAllocated Function

Returns the sum of all the memory currently allocated by Sentient.

Syntax

C ++
size_t SenSysMemAllocated(
);

Parameters

This function takes no parameters.

Return Values

If the function succeeds, it returns the number of bytes that are currently allocated by Sentient; otherwise zero.

Remarks

Memory tracking is only performed in debug builds. In release builds this function always returns 0.

Requirements

Header: SenClientSys.h

Library: SenCore.lib

See Also

Core Functions

SenSysSetMemAllocCallback

SenSysSetMemFreeCallback


SenSysSetMemAllocCallback Function

Redirects Sentient's memory allocator to a custom memory allocator.

Syntax

C ++
void SenSysSetMemAllocCallback(
   SenSysMemAllocCallback  callback
);

Parameters

callback

[in] The memory allocator callback defined by SenSysMemAllocCallback.

Return Values

This function does not return a value.

Remarks

By default Sentient passes all memory allocation requests to XMemAlloc. You can override the default allocation behavior without replacing XMemAlloc. To override the default memory allocator, implement a callback with this signature defined in SenSysMemAllocCallback and then call SenSysSetMemAllocCallback with a pointer to your callback. SenSysSetMemAllocCallback must be called before SentientInitialize. The corresponding SenSysMemFreeCallback function must also be implemented and set in the call to SenSystSetMemFreeCallback. You must set both the allocator and free callbacks; otherwise Sentient returns an error.

Requirements

Header: SenClientSys.h

Library: SenCore.lib

See Also

Core Functions

SenSysMemAllocated

SenSysSetMemFreeCallback

SenSysMemAllocCallback

SenSysMemFreeCallback


SenSysSetMemFreeCallback Function

Redirects Sentient's memory release operation to a custom memory deallocator.

Syntax

C ++
void SenSysSetMemFreeCallback(
   SenSysMemFreeCallback  callback
);

Parameters

callback

[in] The memory free callback defined by SenSysMemFreeCallback.

Return Values

This function does not return a value.

Remarks

By default Sentient passes all memory release requests to XMemFreec. You can override the default memory release behavior without replacing XMemFreec. To override the default memory deallocator, implement a callback with the signature defined in SenSysMemFreeCallback and then call SenSysSetMemFreeCallback with a pointer to your callback. SenSysSetMemFreeCallback must be called before SentientInitialize. The corresponding SenSysMemAllocCallback function must also be implemented and set in the call to SenSystSetMemAllocCallback. You must set both the allocator and free callbacks; otherwise Sentient returns an error.

Requirements

Header: SenClientSys.h

Library: SenCore.lib

See Also

Core Functions

SenSysMemAllocated

SenSysSetMemAllocCallback

SenSysMemAllocCallback

SenSysMemFreeCallback


SenSysSetOutputCallback Function

Redirects Sentient's debug output to a custom debug callback.

Syntax

C ++
void SenSysSetOutputCallback(
   SenSysOutputCallback callback
);

Parameters

callback

[in/out] The debug output callback defined by SenSysOutputCallback.

Return Values

This function does not return a value.

Remarks

By default Sentient passes the debug output to OutputDebugString. To override the default debug output behavior, implement a callback with the signature defined by SenSysOutputCallback and then call SenSysSetOutputCallback with a pointer to your callback. You must call SenSysSetOutputCallback before SentientInitialize.

Note: The strings that are passed in to this callback are for Xbox 360 TCR014 debug output. Do not display the output string supplied to this callback in the released version of your title.

Requirements

Header: SenClientSys.h

Library: SenCore.lib

See Also

Core Functions

SenSysCompletedCallback

SenSysOutputCallback


SenUtilDateTimeMax Function

Returns a SYSTEMTIME structure set to the latest representable SQL time.

Syntax

C ++
void SYSTEMTIME SenUtilDateTimeMax(
);

Parameters

None.

Return Values

If the function succeeds, it returns a SYSTEMTIME structure; otherwise zero.

Remarks

This function specifies the max timestamp for SQL queries. For example, the end time for a history.

Requirements

Header: SenClientUtil.h

Library: SenCore.lib

See Also

Core Functions

SenUtilDateTimeMin


SenUtilDateTimeMin Function

Returns a SYSTEMTIME structure set to the earliest representable SQL time.

Syntax

C ++
void SYSTEMTIME SenUtilDateTimeMin(
);

Parameters

None.

Return Values

If the function succeeds, it returns a SYSTEMTIME structure; otherwise zero.

Remarks

This function specifies the min timestamp for SQL queries. For example, the start time for a history.

Requirements

Header: SenClientUtil.h

Library: SenCore.lib

See Also

Core Functions

SenUtilDateTimeMax


SenUtilWordWrapFindNextLine Function

Signals a callback function that returns the width, in pixels, of a line of text.

Syntax

C ++
void SenUtilWordWrapFindNextLine(
   const wchar_t  *startOfThisLine,
   unsigned int  maxWidth,
   SenUtilGetCharacterWidthCallback  characterWidthCallback,
   const wchar_t  **out_endOfThisLine,
   const wchar_t  **out_beginningOfNextLine
);

Parameters

startOfThisLine

[in] A pointer to the start of the line.

maxWidth

[in] The maximum width of a character.

characterWidthCallback

[in] The callback function that Sentient calls to return the width, in pixels, of the line of text.

out_endOfThisLine

[out] A pointer to the end of the current line of text.

out_beginningOfNextLine

[out] A pointer to the beginning of the next line of text.

Return Values

This function does not return a value.

Remarks

Call this function to determine if a line of text will fit on the screen. When you call this function with a line of text (startOfThisLine), the out_endOfThisLine parameter indicates the position in startOfThisLine to end the current line of text. When you call this function a second time, use the out_beginningOfNextLine parameter from this call as the startOfThisLine value.

Requirements

Header: SenClientUtil.h

Library: SenCore.lib

See Also

Core Functions

SenUtilGetCharacterWidthCallback


Core Structures

This section contains structures that you use with the Microsoft Sentient APIs.

In This Section

Structure | Description
SenFileTransferInfo | Contains the information required to download a file from the server.
SenFileDigest | Stores the digest of the contents of a file.
SenRawDataTransferInfo | Contains the information required to download content from the Sentient server.
SenResourceInfo | Contains the information to identify a resource.


SenFileTransferInfo Structure

Contains the information required to download a file from the server.

Syntax

C ++
struct SenFileTransferInfo{
   SenFileID  fileID;
   SenSysFileSize  fileSize;
   SenFileDigest  digest;
   bool  IsValid() const;
   SenSysFileSize   GetFileSize()  const;
   SenSysFileSize  GetBufferSize() const;
};

Members

fileID

A SenFileID that specifies the unique identifier of the file. Internally, Sentient uses the file ID to locate the file on the server.

fileSize

The size of the file, in bytes.

Note: Do not use this value directly in your code. It is supplied only for debugging purposes. Instead, use the GetFileSize method to retrieve the true size of the file, or GetBufferSize to retrieve the (potentially-larger) size of the buffer that receives the file.

digest

A SenFileDigest structure that contains the expected digest of the file.

IsValid

The IsValid function returns true if this structure refers to a valid file. A value of false indicates that the call to SenConfigFileDownload will return E_INVLAIDARG.

GetFileSize

The GetFileSize function returns the size of the file, in bytes. Use this member after the file has been downloaded to determine the actual number of bytes in the file. Do not use this method to allocate the destination buffer.

GetBufferSize

The GetBufferSize function returns the size, in bytes, of the buffer that is needed to download the file. Note that for efficient data transfer, this value is greater than or equal to the size, in bytes, of the data file. Titles must use GetBufferSize to allocate the destination buffer.

Remarks

This structure is only provided for help in debugging your title; you do not need to access any of the members in your code.

Requirements

Header: SenClientFile.h

Library: SenCore.lib

See Also

Core Structures

SenRawDataTransferInfo


SenFileDigest Structure

Stores the digest of the contents of a file.

Syntax

C ++
struct SenFileDigest{
   UINT8  value[16];
};

Members

value[16]

The 128-bit digest of the file.

Remarks

The file digest is used to determine whether the contents of a file are corrupt.

Requirements

Header: SenClientFile.h

Library: SenCore.lib

See Also

Core Structures

== Operator

!= Operator

SenFileDigestCreate

SenFileTransferInfo


SenRawDataTransferInfo Structure

Contains the information required to download content from the Sentient server.

Syntax

C ++
struct SenRawDataTransferInfo{
   SenRawDataType  type;
   union
   {
      SenFileTransferInfo   file;
      SenPackageFileTransferInfo  package;
   }
   bool  IsValid() const;
   SenSysFileSize GetFileSize()  const;
   SenSysFileSize  GetBufferSize() const;
};

Members

type

A member of the SenRawDataType enumeration that specifies whether the union member contains a file or package structure. Sentient decides internally whether to download the content as a package or a file.

union members

file

A SenFileTransferInfo structure that contains the information required to download files from the server.

package

A SenPackageFileTransferInfo structure that contains the information required to download the package from the Sentient server.

IsValid()

The IsValid function returns true if the structure in the union member (the SenFileTransferInfo or SenPackageFileTransferInfo structure) points to a valid file.

GetFileSize()

The GetFileSize function returns the size, in bytes, of the file pointed to by the union member of this structure.

Note: Use this method after the file has been downloaded to determine the actual number of bytes in the file. Do not use this method to allocate the destination buffer, instead use GetBufferSize.

Note: Call GetFileSize function from this structure to get the size of the file referred to by this structure. Do not call the GetFileSize function from the file or package union member structures.

GetBufferSize()

The GetBufferSize function returns the size, in bytes, of the buffer that is needed to download the file pointed to by the union member of this structure.

Note: For efficient data transfer, this value is greater than or equal to the size, in bytes, of the data file. Titles must use GetBufferSize to allocate the destination buffer.

Note: Call the GetBufferSize function from this structure to get the size of the file referred to by this structure. Do not call the GetBufferSize function from the file or package union member structures.

Remarks

This structure contains all the information that Sentient needs to download content from the server. Sentient populates this structure with the attributes of the data when you upload the file to the Sentient Developer Website. Use the methods in this structure in your code to determine the file and buffer sizes rather than the values in the embedded file or package structures.

For more information, see Dynamic Configuration.

Requirements

Header: SenClientRawData.h

Library: SenCore.lib

See Also

Core Reference

Related Topics

Core Enumerations

SenBoxArtInfo

SenConfigInfo


SenResourceInfo Structure

Contains the information to identify a resource.

Syntax

C ++
struct SenResourceInfo{
  SenSysTitleID  titleID;
  SenResourceID  resourceID;
  SenResourcePriority  priority;
  SYSTEMTIME  begins;
  SYSTEMTIME  ends;
};

Members

titleID

A SenSysTitleID that uniquely identifies an Xbox LIVE title. Internally, Sentient assigns a title identifier to each title that is within the 32-bit range specified by the SenSysTitleID enumeration.

resourceID

A member of the SenResourceID enumeration that specifies the type of resource.

priority

Reserved, must be zero.

begins

Reserved, must be NULL.

ends

Reserved, must be NULL.

Remarks

The resource information structure is contained in the following structures:

  • SenConfigInfo: Contains the Dynamic Configuration data. Returned in the call to SenConfigFileFind.
  • SenBoxArtInfo: Contains the Box Art data. Returned in the call to SenBoxArtEnumerate.

Requirements

Header: SenClientResource.h

Library: SenCore.lib

See Also

Core Structures

SenConfigInfo

SenBoxArtInfo


Core Enumerations

This section contains API reference enumeration types that you use with the Microsoft Sentient APIs.

In This Section

Enumeration | Description
SenFileID | Contains the unique identifier of the file.
SenRawDataType | Describes the types of content downloaded from the Sentient server.
SenResourceID | Defines the identifiers that Sentient uses to locate a resource.
SenResourceType | Defines the categories of the Sentient resources.
SenResourcePriority | This feature is currently not implemented, do not use.
SenSysOfferID | Defines the offer ID type that identifies an offer on the Xbox LIVE Marketplace.
SenSysTitleID | Defines the title identifier type that uniquely identifies a title to the Xbox LIVE service.


SenFileID Enumeration

Contains the unique identifier of the file.

Syntax

C ++
enum SenFileID: INT32{
   SenFileID_Invalid = 0x00000000,
};

Constants

SenFileID_Invalid

The file does not exist or could not be found.

Remarks

Sentient assigns a unique file identifier to every file that is stored on the server within the range specified by this enumeration. Internally, Sentient uses the file ID to locate the file on the server. The ID of a specified file is returned to the titles in the SenFileTransferInfo structure in the following API:

  • SenConfigFileFind

Requirements

Header: SenClientFile.h

Library: SenCore.lib

See Also

Core Enumerations

SenFileTransferInfo


SenRawDataType Enumeration

Describes the types of content downloaded from the Sentient server.

Syntax

C ++
enum SenRawDataType{
  SenRawDataType_Invalid  ,
  SenRawDataType_File  ,
  SenRawDataType_Package
};

Constants

SenRawDataType_Invalid

The SenRawDataTransferInfo structure does not refer to a valid file.

SenRawDataType_File

The union member of the SenRawDataTransferInfo structure contains a SenFileTransferInfo structure.

SenRawDataType_Package

The union member of the SenRawDataTransferInfo structure contains a SenPackageFileTransferInf o structure.

Remarks

This enumeration is used in the SenRawDataTransferInfo structure to specify the type of content downloaded from the Sentient server.

Requirements

Header: SenClientRawData.h

Library: SenCore.lib

See Also

Core Enumerations

SenRawDataTransferInfo


SenResourceID Enumeration

Defines the identifiers that Sentient uses to locate a resource. Resource IDs are defined per title and may be reused across other titles.

Syntax

C ++
enum SenResourceID : INT32 {
  SenResourceID_Invalid  = (INT32)SenResourceType_Invalid << 24,
  SenResourceID_Superstar_0  = (INT32)SenResourceType_Avatar << 24,
  SenResourceID_Superstar_1,
  SenResourceID_Superstar_2,
  SenResourceID_Superstar_3,
  SenResourceID_Superstar_4,
  SenResourceID_BoxArt_0 = (INT32)SenResourceType_BoxArt << 24,
  SenResourceID_Config_0 = (INT32)SenResourceType_Config << 24,
  SenResourceID_Help_0 = (INT32)SenResourceType_Help << 24
};

Constants

SenResourceID_Invalid

An invalid resource identifier. This resource ID can be associated with an error such as a failed search or an invalid resource structure. This identifier may also be used as a default value.

SenResourceID_Superstar_0

An Avatar Superstar resource identifier. This resource ID represents the first level Avatar VIP reward. There is only one reward at this level for each title.

SenResourceID_Superstar_1

An Avatar Superstar resource identifier. This resource ID represents the second level VIP reward. There is only one reward at this level for each title.

SenResourceID_Superstar_2

An Avatar Superstar resource identifier. This resource ID represents the third level VIP reward. There is only one reward at this level for each title.

SenResourceID_Superstar_3

An Avatar Superstar resource identifier. This resource ID represents the fourth level VIP reward. There is only one reward at this level shared across all titles.

SenResourceID_Superstar_4

An Avatar Superstar resource identifier. This resource ID represents the fifth level VIP reward. There is only one reward at this level shared across all titles.

SenResourceID_BoxArt_0

A Box Art resource identifier. This resource ID is used in the cross-title promotional screen and contains promotional offerings such as images or text.

SenResourceID_Config_0

A Configuration resource identifier. This resource ID is used for game configuration files where the top bottom 24 bits identify multiple custom configuration files.

SenResourceID_Help_0

A Help Text resource identifier. This resource ID is currently not supported.

Remarks

The top 8 bits of each resource ID is the corresponding member of the SenResourceType enumeration. For the configuration resource type (SenResourceID_Config_0), the bottom 24 bits identify the various configuration type resources that are available to the title. For example, if a title has several configuration files on the server, they can be identified by the resource identifiers as follows:

        Index = SenResourceID_Config_0 + 37;

In this case, the resource ID is used in the call to SenConfigFileFind to search for a specific configuration file. The resource ID for configuration files is set when the title uploads a configuration file on the Sentient Developer Website. You can also retrieve the resource ID for your configuration files on the Sentient Developer Website. You can also use the other resource types in a similar pattern.

Requirements

Header: SenClientResource.h

Library: SenCore.lib

See Also

Core Enumerations

SenConfigFileFind

SenResourceInfo

SenResourceType


SenResourcePriority Enumeration

Describes the priority of a resource.

Note: This feature is currently not implemented, do not use.

Syntax

C ++
typedef INT32 SenResourcePriority;
enum {
   SenResourcePriority = 0
};

Constants

SenResourcePriority

The priority of the resource.

Remarks

Note: This feature is currently not implemented, do not use.

Requirements

Header: SenClientResource.h

Library: SenCore.h

See Also

Core Enumerations

SenResourceInfo


SenResourceType Enumeration

Defines the categories of the Sentient resources.

Syntax

C ++
enum SenResourceType{
  SenResourceType_Invalid,
  SenResourceType_Avatar,
  SenResourceType_BoxArt,
  SenResourceType_Config,
  SenResourceType_Help
};

Constants

SenResourceType_Invalid

An invalid resource type.

SenResourceType_Avatar

An Avatar Superstar resource type.

SenResourceType_BoxArt

A Box Art resource type.

SenResourceType_Config

A Configuration resource type.

SenResourceType_Help

A Help Text resource type.

Remarks

The values in this enumeration define the top 8 bits of the corresponding value in the SenResourceID enumeration. For example, the value of the SenResourceID_Config_0 is defined as SenResourceType_Config shifted 24 bits.

Requirements

Header: SenClientResource.h

Lirary: SenCore.lib

See Also

Core Enumerations

SenResourceID


SenSysOfferID Enumeration

Defines the offer ID type that identifies an offer on the Xbox LIVE Marketplace.

Syntax

C ++
enum SenSysOfferID : INT64  {
   SenSysOfferID_Invalid   = (SenSysOfferID) 0x0000000000000000LL,
};

Constants

SenSysOfferID_Invalid

A predefined offer ID that indicates the offer ID is not available.

Remarks

Use this identifier in system routines that prompt a user to buy a product such as an avatar item or game.

Note: All offer IDs are private and must only be obtained through calls to the Sentient APIs. You should not create an offer ID manually. For example, the call to GetOfferID in the SenBoxArtInfo structure returns the offer ID of the associated Box Art.

Requirements

Header: SenClientTypes.h

Library: SenCore.h

See Also

Core Enumerations

SenBoxArtInfo


SenSysTitleID Enumeration

Defines the title identifier type that uniquely identifies a title to the Xbox LIVE service.

Syntax

C ++
enum SenSysTitleID : INT32  {
   SenSysTitleID_This   = (SenSysTitleID)0x00000000,
   SenSysTitleID_Shared = (SenSysTitleID)0xffffffff,
};

Constants

SenSysTitleID_This

A predefined title ID that you should use for your title in calls to the Sentient API. Internally, Sentient converts this title ID to the actual title ID.

SenSysTitleID_Shared

A predefined title ID that you use to access shared, cross-game resources such as level 4 and 5 avatar costumes.

Remarks

Every Xbox LIVE title is given a 32 bit title identifier. Sentient uses these IDs to identify a title.

Note: All title IDs are private and must be assigned by the Xbox LIVE Marketplace. Titles do not manually create IDs. The only private ID that a title may produce is the one that is passed to SentientInitialize.

Requirements

Header: SenClientTypes.h

Library: SenCore.lib

See Also

Core Enumerations

SenResourceInfo

SentientInitialize

Connect to the Sentient Service


Core Callback Functions

This section contains API reference callback functions that you use with the Microsoft Sentient API.

In This Section

Function | Description
SenSysCompletedCallback | Standard callback that all asynchronous Sentient operations invoke on either successful or failed completions.
SenSysMemAllocCallback | Memory allocation callback that allocates the requested number of bytes.
SenSysMemFreeCallback | Callback that releases the memory previously allocated in the call to SenSysMemAllocCallback.
SenSysOutputCallback | Callback that overrides the default debug output from Sentient.
SenUtilGetCharacterWidthCallback | Returns the width (in pixels) of a single character.


SenSysCompletedCallback Callback

Standard callback that all asynchronous Sentient operations invoke on either successful or failed completions.

Syntax

C ++
typedef void *SenSysCompletedCallback(
   HRESULT   taskResult,
   void   *userCallbackData
);

Parameters

taskResult

[in] The result of the asynchronous operation that completed. If the operation succeeded, taskResult is S_OK; otherwise, taskResult specifies an error code.

userCallbackData

[in] The title specific data that is associated with the asynchronous operation that initiated this callback. The value of this parameter matches the value of the userCallbackData parameter passed in to the API that initiated the operation.

Return Values

This function does not return a value.

Remarks

Sentient API that return asynchronously indicate completion by invoking a standard callback supplied in the original API call. All Sentient API callbacks conform to this signature.

Requirements

Header: SenClientSys.h

Library: SenCore.lib

See Also

Core Callbacks

SenSysOutputCallback


SenSysMemAllocCallback Callback

Memory allocation callback that allocates the requested number of bytes.

Syntax

C ++
typedef void *(*SenSysMemAllocCallback)(
   size_t  size
);

Parameters

size

[in] The number of bytes requested by Sentient. This number will always be greater than zero.

Return Values

A pointer to the allocated memory that contains the number of requested bytes. This pointer may not be NULL.

Remarks

By default Sentient passes all memory allocation requests to XMemAlloc. You can override the default allocation behavior without replacing XMemAlloc. To override the default memory allocator, implement a function with this signature and then call SenSysSetMemAllocCallback to with a pointer to the callback. SenSysSetMemAllocCallback must be called before SentientInitialize. The corresponding SenSysMemFreeCallback function must also be implemented and set in the call to SenSystSetMemFreeCallback. You must set both the allocator and free callbacks; otherwise Sentient returns an error.

Requirements

Header: SenClientSys.h

Library: SenCore.lib

See Also

Core Callbacks

SenSysMemAllocated

SenSysSetMemAllocCallback

SenSysSetMemFreeCallback

SenSysMemFreeCallback


SenSysMemFreeCallback Callback

Callback that releases the memory previously allocated in the call to SenSysMemAllocCallback.

Syntax

C ++
typedef void (*SenSysMemFreeCallback)(
   void  *ptr
);

Parameters

ptr

[in] A pointer to the memory allocated in the corresponding call to SenSysMemAllocCallback. This pointer will never be NULL.

Return Values

This function does not return a value.

Remarks

By default Sentient passes all memory release requests to XMemFree You can override the default deallocation behavior without replacing XMemFree. To override the default memory release function, implement a function with this signature and then call SenSysSetMemFreeCallback with a pointer to the callback. SenSysSetMemFreeCallback must be called before SentientInitialize. The corresponding SenSysMemAllocCallback function must also be implemented and set in the call to SenSystSetMemAllocCallback. You must set both the allocator and free callbacks; otherwise Sentient returns an error.

Requirements

Header: SenClientSys.h

Library: SenCore.lib

See Also

Core Callbacks

SenSysMemAllocated

SenSysSetMemAllocCallback

SenSysSetMemFreeCallback

SenSysMemAllocCallback


SenSysOutputCallback Callback

Callback that overrides the default debug output from Sentient.

Syntax

C ++
typedef void *SenSysOutputCallback(
   const wchar_t  *outputString
);

Parameters

outputString

[in] A NULL terminated string that contains the debug information from Sentient.

Return Values

This function does not return a value.

Remarks

By default Sentient passes the debug output to OutputDebugString. To override the default behavior, implement a function with this signature and then call SenSysSetOutputCallback with a pointer to your callback. You must call SenSysSetOutputCallback before SentientInitialize.

Note: The strings that are passed in to this callback are for Xbox 360 TCR014 debug output. Do not display the output string supplied to this callback in the released version of your title.

Requirements

Header: SenClientSys.h

Library: SenCore.lib

See Also

Core Callbacks

SenSysCompletedCallback


SenUtilGetCharacterWidthCallback Callback

Returns the width (in pixels) of a single character.

Syntax

C ++
typedef unsigned int (*SenUtilGetCharacterWidthCallback) (
   wchar_t  character
);

Parameters

character

[in] The character whose width is returned.

Return Values

If the function succeeds, it returns the width, in pixels, of the character; otherwise zero.

Remarks

Call this function to determine the number of characters that can fit on a single line on the screen.

Requirements

Header: SenClientUtil.h

Library: SenCore.lib

See Also

Core Callbacks

SenUtilWordWrapFindNextLine


Core Operators

This section contains API reference operators that you use with the Microsoft Sentient APIs.

In This Section

Operator | Description
== Operators | Compares two SenFileDigest values and determines if they are equal.
!= Operator | Compares two SenFileDigest values and determines if they are not equal.


== operator (&SenFileDigest, &SenFileDigest)

Compares two SenFileDigest values and determines if they are equal.

Syntax

C ++
BOOL operator ==(
  const SenFileDigest &value0,
  const SenFileDigest &value1
);

Parameters

SenFileDigest

[in] The left comparison value.

SenFileDigest

[in] The right comparison value.

Return Values

This operator returns true if the supplied values are equal; otherwise false.

Requirements

Header: SenClientFile.h

Library: SenCore.lib

See Also

Core Operators

!= Operator


!= operator (&SenFileDigest, &SenFileDigest)

Compares two SenFileDigest values and determines if they are not equal.

Syntax

C ++
BOOL operator ==(
  const SenFileDigest &value0,
  const SenFileDigest &value1
);

Parameters

SenFileDigest

[in] The left comparison value.

SenFileDigest

[in] The right comparison value.

Return Values

This operator returns true if the supplied values are not equal; otherwise false.

Requirements

Header: SenClientFile.h

Library: SenCore.lib

See Also

Core Operators

== Operator


Sentient Constants

The Sentient APIs define the following constants.

Error Codes

Sentient functions may return one of following HRESULT error codes:

Constant | Value | Description
HRESULT SENTIENT_E_NOT_INITIALIZED = SENTIENT_E_FIRST_ERROR + 0x0001 | 0x80580001 | The title attempted to call a Sentient function before the library was initialized.
HRESULT SENTIENT_E_ALREADY_INITIALIZED = SENTIENT_E_FIRST_ERROR + 0x0002 | 0x80580002 | The title attempted to initialize an already-initialized library.
SENTIENT_E_NO_UGC_PUBLISH_PRIVILEGE = SENTIENT_E_FIRST_ERROR + 0x0003 | x80580003 | The user does not have UGC upload or publish privileges.
SENTIENT_E_NO_UGC_USE_PRIVILEGE = SENTIENT_E_FIRST_ERROR + 0x0004 | 0x80580004 | The user does not have UGC download or use privileges.
SENTIENT_E_GUEST_ACCESS_VIOLATION = SENTIENT_E_FIRST_ERROR + 0x0005 | 0x80580005 | The user is a guest, and therefore does not have access to certain Sentient features.
SENTIENT_E_TOO_MANY_CALLS = SENTIENT_E_FIRST_ERROR + 0x0006 | 0x80580006 | The title called an API too frequently. The call was discarded to avoid excessive server load.
SENTIENT_E_SERVER_ERROR = SENTIENT_E_FIRST_ERROR + 0x0007 | 0x80580007 | The call generated an unhandled error on the server. Contact senhelp@microsoft.com for assistance.
SENTIENT_E_TIME_OUT = SENTIENT_E_FIRST_ERROR + 0x0008 | 0x80580008 | The operation timed out and was therefore abandoned.
SENTIENT_E_CANCELED = SENTIENT_E_FIRST_ERROR + 0x0009 | 0x80580009 | The operation was canceled because the user signed out or the title called SentientCancel.
SENTIENT_E_FORBIDDEN = SENTIENT_E_FIRST_ERROR + 0x000a | 0x8058000a | The user is not permitted to perform this operation.
SENTIENT_E_USERINDEX_IS_ANY = SENTIENT_E_FIRST_ERROR + 0x000b | 0x8058000b | The user index of ANY (0xFF) is not valid.
SENTIENT_E_USERINDEX_IS_NONE = SENTIENT_E_FIRST_ERROR + 0x000c | 0x8058000c | The user index of NONE (0xFE) is not valid.
SENTIENT_E_USERINDEX_IS_INVALID = SENTIENT_E_FIRST_ERROR + 0x000d | 0x8058000d | The user index is outside the range 0 to 3.
SENTIENT_E_USERINDEX_IS_FOCUS = SENTIENT_E_FIRST_ERROR + 0x000e | 0x8058000e | The user index FOCUS (0xFD) is not valid.
HRESULT SENTIENT_E_BUFFER_EXHAUSTED = SENTIENT_E_FIRST_ERROR + 0x000f | 0x8058000f | Sentient's internal buffer is full.

Status Codes

Sentient functions may return one of following HRESULT status codes:

Constant | Value | Description
SENTIENT_S_NOT_SIGNED_IN_TO_LIVE = SENTIENT_S_FIRST_STATUS + 0x0003 | 0x00580003 | The local user is not currently signed into Xbox LIVE. Any calls to Sentient APIs other than SentientUpdate will fail immediately.
SENTIENT_S_INITIALIZING_CONNECTION = SENTIENT_S_FIRST_STATUS + 0x0004 | 0x00580004 | A new connection to the Sentient XLSP servers has been established.
SENTIENT_S_SERVER_CONNECTION_FAILED = SENTIENT_S_FIRST_STATUS + 0x0005 | 0x00580005 | The connection to the Xbox LIVE server is active, but the connection to the Sentient XLSP is not available.
SENTIENT_S_OPERATION_IN_PROGRESS = SENTIENT_S_FIRST_STATUS + 0x0006 | 0x00580006 | The call to the Sentient API was successful, but Sentient is waiting for information from the server to complete the operation. This status is only returned from APIs that do not have an associated callback. Titles should wait for the Sentient update to loop to complete and then call the function again.

Macros

The Sentient API use the following macros to create Sentient error and status codes.

Constant | Value | Description
SENTIENT_FACILITY | 0x00000058 | The base value used to create all Sentient error and status codes. All Sentient codes are offsets from this value. Note: Sentient uses the MAKE_HRESULT macros to shift this byte into the higher bits.
SENTIENT_E_FIRST_ERROR MAKE_HRESULT( SEVERITY_ERROR, SENTIENT_FACILITY, 0x0000 ) | 0x80580000 | A macro that creates the base Sentient error code from the base Sentient offset.
SENTIENT_S_FIRST_STATUS MAKE_HRESULT( SEVERITY_SUCCESS, SENTIENT_FACILITY, 0x0000 ) | 0x00580000 | A macro that creates the base Sentient success code from the base Sentient offset.

Requirements

Header: SenClientTypes.h

Library: SenCore.lib

See Also

Core Reference


Sentient Types

The Sentient API defines the following types and constants.

Types

Type | Description
typedef UINT32 SenSysDateTime | A low-resolution timestamp.
typedef DWORD SenSysLanguageID | The language identifier. This value maps to either the Xbox or Windows language identifier depending on the platform.
typedef INT32 SenSysFileSize | The size of a resource file.
typedef VOID *SenHandle | A handle to an asynchronous task that can be used to SentientCancel the operation.
typedef XCONTENTDEVICEID SenContentDeviceID | A unique identifier for an Xbox device.
typedef DWORD SenContentDeviceID | A unique identifier for a non-Xbox device.

Constants

Sentient provides the following predefined constants.

Type | Value | Description
SenSysLanguageID_Default | 0xffffffff | The default language ID.
SenContentDeviceID_Any | XCONTENTDEVICE_ANY | The Xbox device identifier is not specified.
SenContentDeviceID_Any | 0 | The device identifier is not specified.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

UGC Reference


Telemetry

Using the Sentient Telemetry Service, you can collect custom statistics for your title. Sentient stores and aggregates telemetry data collected from the player community and provides reports that game designers and producers can use to optimize their game-play. Sentient records basic statistics such as:

  • Events: Record events that occur in game play (for example, you can record data when a player completes a level or defeats an enemy).
  • Incrementing values: Adds the total numbers of times an event occurred (for example, the number of times a player defeats an enemy or the number of times a player uses a skill).
  • Accumulated values: Add the event values to accumulate a grand total (for example, the total damage done by a player).
  • Maximum/Minimum values: Track the highest or lowest value achieved over a period of time (for example, the longest jump or highest skill level a player attained).
  • Amount of Time: Accumulate the amount of time spent in a title-defined scope (for example, the amount of time a player spends in level 1).

    • Note: This feature is currently under development.

Using the Telemetry Definition Schema to define your statistics, you can collect any type of data generated in game play.

Note: Currently Sentient does not support direct game-play feedback for end users or most types of marketing data such as demographics or user preferences.

You can use the telemetry data with the Sentient Dynamic Configuration service to modify game behavior based on usage patterns. For more information, see Dynamic Configuration.

For more information on the types of statistics that you can collect and the operations that you can perform, see the Telemetry Definition Schema.


Getting Started with Telemetry

When you begin to define your telemetry data, you should work with the Sentient Team (senaccts@microsoft.com) to obtain feedback on your design. Ideally, you want to define your telemetry statistics during the design phase of development. To collect telemetry statistics for your title:

  1. Define the statistics you want to collect. Telemetry data is generated from events that occur in your game.
  2. Download the schema and example template from the Sentient Developer Website (https://sentient.msgamestudios.com/Telemetry.aspx). Following this schema, enter your statistics in an XML document.
  3. Upload your XML document, and get the auto-generated header and source code files that contain the methods for your title’s data.
  4. Link the Sentient core library (sencore.lib) into your title, and start using the Sentient Service. For more information, see Getting Started with Sentient.
  5. Review the reports generated for your telemetry data on the Sentient Developer Website.


Defining Telemetry Statistics

Using the Telemetry Definition Schema, you can define up to 128 statistics for your title. Each statistic can have up to 20 parameters, as shown in the Telemetry Definition schema diagram below:

You can record event-based or time-based types of statistics (statType). Typically, data operations such as accumulate values or minimum/maximum values are performed only on specific parameters. When parameters do not have an operator, this information is gathered as context for the statistic. You can perform the following operations on the parameters:

  • none: No operations are performed on this parameter. For example, the player’s level is reported “as is” with no operation performed.
  • accumulate: The value of the parameter is accumulated. For example, a player gathers 12 new pieces of gold which is added to their current stash of 34 gold.
  • increment: The value of the parameter is incremented each time this event occurs. For example, the number of kills is incremented by one each event.
  • min: The minimum value of a parameter over time. For example, the minimum power level of the player.
  • max: The maximum value of a parameter over time. For example, the maximum power level of the player.

For more information, see Using Value Parameters.

Using this schema, you can gather statistics such as Damage Done or Monsters Killed, as shown in the example below. You can define either event-based or time-based types of statistics (statType). In the example below, DemoStat1 is an event-based statistic, which means the game sends an event to Sentient every time damage is recorded during game play. Sentient uses the Level, Strength, Agility, and Class parameters to categorize (or qualify) the Damage Done statistic. Only the DamageDone parameter is increased when Sentient receives the event. What this translates to in game play is that Level, Strength, Agility, and Class are characteristics of the player who created the damage. In the schema, Level, Strength, Agility, and Class are parameters that have no operator (or an operator defined as “none”) while the DamageDone parameter is defined with an accumulate operator. Here is the example XML:

<SentientStats xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" …

<Stat name="DemoStat1" desc="Damage Done By Player”)" type="event">

<Parameters>

<Param name="Level" type="int" op="none"/>

<Param name="Strength" type="int" op="none"/>

<Param name="Agility" type="int" op="none"/>

<Param name="Class" type="int" op="none"/>

<!--This is a value-->

<Param name="DamageDone" type="int" op="accumulate"/>

</Parameters>

</Stat>

<Stat name="DemoStat2" desc="Monsters Killed" type="event">

<Parameters>

<Param name="WeaponType" type="int" op="none"/>

<Param name="ArmorType" type="int" op="none"/>

<Param name="DeadMonsters" type="int" op="max"/>

</Parameters>

</Stat> . . .

For more information on the schema, see Telemetry Definition Schema. To download the telemetry schema and start gathering telemetry statistics for your game, see Downloading the Telemetry Schema and Implementing Telemetry Statistics.


Downloading the Schema

To start collecting telemetry data, download the schema from the Sentient Developer Website (https://sentient.msgamestudios.com/Default.aspx) and enter your statistics as follows:

  1. On the Sentient Developer Website, select Telemetry Tool from the Management Tools menu.
  2. Select the Telemetry Definition Schema link to download the telemetry schema.

Create an XML document that follows the telemetry schema. Before you upload your XML document, you should validate it against the schema using Visual Studio or any other XML tool. To upload the XML document to the Sentient Developer Website:

  1. On the Sentient Developer Website site, select Telemetry Tool on the Management Tools menu.
  2. Select the name of your title from the dropdown list. This is the titles that the Sentient Team previously registered for you on the site. If you only have one Sentient title registered, the title will be selected for you automatically.
  3. Select the Browse button and navigate to the location of your XML document.
  4. Select the Upload button. The C++ and header files with the auto-generated code will be added to the "Uploaded Data" list with new version number.

To start generating telemetry reports, call the methods in the auto generated C++ code to send your data to Sentient for processing. For more information, see Implementing Telemetry Statistics.


Implementing Telemetry Statistics

The example below shows an event-based telemetry statistic that defines four parameters. Here is the snippet from the title’s XML document:

<Stat name="DemoStat1" desc="Damage Done By Player”)" type="event">

<Parameters>

<Param name="Level" type="int" op="none"/>

<Param name="Strength" type="int" op="none"/>

<Param name="Agility" type="int" op="none"/>

<Param name="Class" type="int" op="none"/>

<!--This is a value-->

<Param name="DamageDone" type="int" op="accumulate"/>

</Parameters>

Sentient generates C++ code for the XML in this example. Titles use the generated C++ code to send event data to Sentient as follows:

        SenStatDemoStat1(playerID, level, strength,
                         agility, class, damageDone);

Note that all input parameters are integers, and you should cast event arguments to 32-bit integers before you call this function. Titles should call this function every time the player does damage. While it is safe to call telemetry functions as often as needed in your code, some data may be lost if the data is too excessive.

Multiple Players

Sentient always adds the player ID as the first parameter. If you have multiple players in a game, you should send the data for each player in separate calls to distinguish among events generated by different players as follows:

        SenStatDemoStat1(playerA, level, strength,
                         agility, class, damageDone);

        SenStatDemoStat1(playerB, level, strength,
                         agility, class, damageDone);


Telemetry Reports

Sentient aggregates the telemetry data that you send to the service and provides the raw data collected on the Sentient Developer Website (https://sentient.msgamestudios.com). Game designers and producers can use the feedback in these reports to design new features or dynamically change behavior of online games. To view the statistics for your title:

  1. On the Sentient Developer Website, select Telemetry Logs on the Data Tools menu.
  2. Select your title from the drop-down list. If you only have one Sentient title registered, the title will be selected for you automatically.
  3. The list of spreadsheets for your title appears. Click on the report link to download your data.

Spreadsheets on the Sentient Developer Website contain the data collected for a single session. Data in the spreadsheets is not aggregated across multiple sessions or files. You can use the data in these spreadsheets to debug the telemetry reporting code in your title, however, these are not the reports that you will use to analyze your telemetry data.

In addition to the parameters defined by the client, Sentient also collects the following data and includes it in every report:

  • XUID: The online XUID of the user.
  • IP Address: The IP address of the Client
  • Session ID: The ID of the session that is generated on the client when telemetry data is initiated. This guarantees a unique id for all telemetry sessions.
  • Client and Server Timestamp: The time that the associated data was collected.
  • User Index: The index of the user on the Xbox (0 to 3).
  • Capture Time: The amount of time that Sentient successfully captured data on the client.
  • Overflow Time: The amount of time that Sentient failed to capture data on the client due to lack of memory.

    • Note: The maximum time allowed for captured data plus overflow data is limited to 300s.

  • Machine ID: The unique ID of the Xbox or computer.

Data Aggregation

Note that telemetry data is buffered on the client for a period of time before it is sent to the Sentient server. During this buffering period, the telemetry data is aggregated on the client. After the buffer period elapses, data is sent to the Sentient servers and the client buffer is cleared. For more information, see the Telemetry Definition Schema remarks section.

Note: Currently, Sentient buffers data on the client for a period of 5 minutes; however, this time is subject to change.

Telemetry Data Analysis

You can use the data stored on the Sentient server to produce reports and visuals for business managers, producers, game designers and other members of your team. When you reach the stage where you are ready to build your data analytics, contact the Sentient team (senhelp@microsoft.com).


Understanding Telemetry

"The trick with this data is to know what to look for, why to look for it and how to make it valuable. "

Telemetry is a technology in the gaming industry in which intelligence data is collected remotely via automation. Using telemetry data, you can collect information on the game design and mechanics by measuring how users interact with the game. You can also collect business metrics on customer purchasing patterns after your title releases. Researching your game takes much of the guess work out of the design and creates games based on actual user data. Using telemetry data, you can:

  • Detect factors that influence conversion rates from trial to full, based on variables unique to your game.
  • Discover where players are dying, getting stuck, or quitting.
  • Identify key times to release title updates.
  • Catch potential exploits and other hot issues.
  • Find average playtime for overall sessions, levels or online matches.
  • Evaluate whether players use your game as intended and react with title updates or dynamic configurations.

Using intelligence data you can verify your game's design intent and make changes to your game before it releases. Telemetry is ultimately used to enhance players' experience and enjoyment. When you build intelligent design into your game by using dynamic configuration, you can identify friction points after your title releases and alter players experience by pushing dynamic updates to the game. Dynamically altering game behaviors helps ensure players have the best possible experience.

Types of Telemetry Data

Because telemetry data is gathered remotely via automation, it provides quantitative information about various aspects of the game rather than attitudinal data about players’ interest in the game. While telemetry data is not a replacement for qualitative data, the diversity of data that can be collected remotely includes many aspects of the game including menu interactions or business metrics. The types of telemetry data include:

  • Business and Marketing: Collect information on upsells, trial downloads and conversion rates.
  • Gameplay Metrics: Evaluate player actions, behaviors, navigation and interactions with game objects and entities.
  • UI and Menu Interaction: Track how players interact with the game UI.
  • Game Engine Performance: Crash locations.

Gameplay statistics are by far the most interesting because they provide insight into the design and users' experience in your game. As you begin to design your telemetry collection plan, identify what you want to learn about your game from the business, marketing and design perspective, and then decide how the data can be used to impact your game. For more information, see Designing Telemetry Statistics.

Who Uses Telemetry Data

Designers use telemetry data to validate that the game meets their design intent. Business managers and marketing departments use telemetry to gather conversion rates or other success indicators. Other roles use telemetry data for different purposes. For example:

  • Game researchers, usability engineers and user analysts use the data to enhance game play.
  • Game developers who want to apply telemetry to track and analyze user behavior or manage goods and trade.
  • Game producers use telemetry to measure the overall success of the game.
  • Marketing uses telemetry to gather business intelligence such as what players like or dislike to determine the selling points of the game.
  • Testers performing usability types of testing.

Telemetry Visuals

Telemetry data is most powerful when combined with reporting tools and visualizations. Reports such as time spent in various levels or time spent in various modes give valuable insights into player activities. Visualizations such as heat maps provide context for these player interactions. For more information, see Building Visuals and Reports.


Defining Gameplay Metrics

Game play statistics measure specific in-game activities of your players. These statistics examine player experiences and supplies intelligence on player actions. Using gameplay data, you can create metrics on any aspect of your game including the number of player deaths in an episode, or how players move through the game or which characters are most frequently chosen. Basically, gameplay covers all in-game actions of players, including navigation, purchasing, player interactions and other interactions with game assets.

Because you can evaluate the game design and user experience, gameplay metrics are by far the most valuable form of in-game metrics.

Gameplay metrics include:

  • Game Parameters: Includes player's actions, behaviors, navigation through levels, communication, and interactions with game objects or entities.
  • Location: Locate where problem areas exist. These can be used for different purposes:
    • Design: Discover movement patterns, unused areas or combat hotspots.
    • Engineering:Identify crash locations, resource usage or map performance goals.
    • QA/Production: Ensure path coverage.
  • Navigation: Discover how players move through the game or interact with game menus.
  • Levels: Identify the barriers to progression through a level, or discover which levels are most popular or performing well.
  • Objects and Entities: Identify which characters are most popular and balanced, or pinpoint weapons that are overpowering or ineffective.
  • Player Level: Measure player progression through player levels.
  • Game Balancing: Balance character abilities, game level difficulties and more.
  • Social: Map interactions with other players and connections to friend or a network of players. Understand patterns of interaction with other players such as trading patterns.
  • Session: Create session level metrics such as average time players spend in a session.

When combined with visuals such as heat maps that help you identify problem areas, gameplay metrics are valuable design tools for producers, designers, marketing and developers.

Designers and Developers

Gameplay metrics are essential to evaluating game design and user experience. Designers collect data to:

  • Evaluate whether the players use the game as intended.
  • Discover where users encounter problems while playing the game and gain insight on how to fix the issues.
  • Ask questions of the data, as well as explore the data for unpredictable behaviors.
  • Take the guesswork out of game design and moves toward a pattern of testing and redesign.

Marketing team

Gameplay metrics are essential to evaluating game design and user experience. Designers collect data to:

  • Identify what elements or segments of the game do target audiences prefer.
  • Enable targeted marketing by identifying the types of players that are central to the revenue stream.

Producers

  • Track engineering performance and the overall state of the game throughout the lifecycle of the game.
  • Chart the overall progress of the game, and evaluate the broader and finer aspects of game design.


Telemetry in the Development Lifecycle

Telemetry data is an important aspect of your project that is designed and scheduled into your project milestones as any other feature of your game. A well-designed telemetry collection plan gives you valuable insights to your game and should be a high priority feature. Even if you only have time to research one or two high priority questions, you can make a positive impact in your game.

Every telemetry data collection plan, should include data gathered over the entire lifecycle of your game including: design (prototype and pre-production phases), production (including alpha and beta), release and planning for the next generation. As such, plan for time in your schedule to:

  • Design telemetry statistics in the design phase.
  • Create the visuals and develop your visualization tools in the design phase.
  • Collect data and update the games during production.
  • Iterate over your design in production to optimize your data collection plan.
  • Continue to gather statistics and propagate updates to the game via dynamic configuration post release.
  • Use data collected post release to plan the next generation of your title.

Lifecycle Overview

Plan for time in the design phase to create your telemetry strategy. As you begin to design your telemetry data, first identify the questions you want to investigate and identify the actionable items that come out of the data. Also, as part of this phase you build the visuals and reports that display the data in a meaningful manner. For more information on designing your telemetry statistics, see Designing Telemetry Statistics.

During production, you collect data, test your assumptions and propagate updates to the game. In the end, a well-planned collection scheme saves time in the development phase and bypasses the common mistake of trying to collect and analyze too much data.

After your title releases, using the Sentient Dynamic Configuration service, you collect data from online players and propagate updates to your game via configuration files on the Sentient servers. As long as your telemetry is designed properly, you do not need to wait for the next release of your title to update your game!

Lather, Rinse and Repeat!

Telemetry data collection and subsequent updates to the game is an iterative process that is an integral part of your design and production phase. Plan for time in the schedule to collect data and analyze telemetry reports, and then propagate updates to the game. This is an iterative process where you measure, propagate updates and then repeat the process until you attain the desired result. Measuring whether your changes to the game effectively achieve the desired result is a critical part of the process. Repeat this process as needed until you reach your optimal design.

For example, the one team collected statistics about player deaths in the game. One of the levels showed a higher number of deaths than expected. As they looked through the checkpoints within that level they realized that they needed more granularity about where in the checkpoint the issue occurred. They changed the data to add coordinates within each checkpoint and were able to pinpoint where players were dying more closely. They were then able to identify what weapons were used and calculate the distance at which weapons were used. The team was then able to balance weapons to bring down the player death rate.

The telemetry data that you collect to validate your game design during production are also used after your game releases to gather data and identify sticking points after your title releases. When you build configuration variables into the game, you can then propagate dynamic updates to the game.

Identify your Test Audience

Gathering telemetry data in the production phase allows you to work out the bugs and measure whether your title meets the design intent. However, whether you bring in players from the outside, or rely on your test team or internal partners to gather data will affect the validity of your analysis. Test and developers who have been playing the game for several months are no longer novice users. Consider releasing a demo to gather metrics from outside players and collect data from the target audience. Here are some possible test players:

  • User Research
  • Developer team
  • Producers
  • Internal Partners
  • Demo Users
  • Test team

Because you gather data from a wider audience, data gathered after your title releases may look wildly different than the data you gathered during the production phase. Plan to test your assumptions and redesign metrics as needed post release.

Post Release Updates

After your game releases, you post updates to the game via configuration files stored by the Sentient Dynamic Configuration Service. You continue to gather statistics from the player community and update your game via online configurations. These updates are captured in the configuration files and accessed dynamically in the game from the Sentient servers.

As you design your statistics, consider what is possible to update during the production phase and what is possible to update after your title releases through Dynamic Configuration.


Designing Telemetry Statistics

Before you begin to design your telemetry data plan, consider the following:

  • What data are we tracking?
  • Why do we want to track it?
  • How will we adjust the game in light of the collected data?

To design telemetry statistics, you first identify what you want to learn about your game. A well planned telemetry collection scheme only includes about 10-12 well-designed questions that you identify as having the greatest impact on your game. However, if time is limited, a telemetry plan with only 1 or 2 statistics can give valuable insights.

The following steps roughly capture the process, but in practice, the process may not be as linear as described:

  1. Identify what you want to know about the game and turn these into your research questions.
  2. Identify the potential impact that the answers to these questions may have on the game.
  3. Define the hooks and supporting parameters for your research questions.
  4. Prioritize your list and then trim it to 10-12 questions.
  5. Build prototypes of your visuals and reports with mock data in the design phase.
  6. Enter your statistics into your Telemetry Definition XML document.
  7. Collect pilot data and iterate on your questions, hooks, and visuals/reports.


Step 1: Identify your Questions

Frame your telemetry analysis as questions that you want answers to not data that you can collect. Start by asking question such as “What do we want to learn about the game or experience?” Keep the questions generic at first, and then later you can identify supporting questions or add in the contextual data. For example, a simple research question common to many games is ““How did player’s choice of path through the level affect their progress/performance through the level? ”

Note: Don’t start by collecting a lot of random events just because you can. A common mistake is to collect lots of events without identifying actionable items or clearly defining your research strategy.

Use the commonly asked questions in Appendix A (under construction) for your game genre as a starting point for the questions you want to investigate. However, as the designer, producer or developer you are the most familiar with your game and you should focus on customizing these questions to your game. As you go through the list, prioritize the questions based on the expected impact to your game (see Step 2). Don’t try to ask too many questions; rather, trim the list down to only those questions that may have the greatest impact to the game. A robust data collection plan only includes about 10-12 well-designed questions. From a limited number of statistics, you can calculate a lot of data on the backend.

For more information about the lists of genre specific questions as well as the list of 7 questions every genre should ask, see Appendix A (under construction).


Step 2: Identify the Impact

After you lock down on a core set of questions, look closer at the potential impact that the answers to these questions might have on the game. Potential impacts to your game could be as simple as balancing player selection or balancing level difficulty. If you cannot identify any meaningful results from the data, then don’t spend time on the question. Use this rule to trim the list of questions you identified in Step 1.

To identify the impact that your research questions might have on the game, you may also need to determine what contextual data is required to answer the question. For example, you want to identify which tracks are successful in a racing game. Your research question is:

  • What tracks fail to meet the designer’s intent and what factors contribute to this failure?

If you find a track that players have difficulty completing, identify how this information can impact the game. For example, can you reconfiguring features on the track or change the time to complete a track.

For more information, see the Telemetry Example topic (under construction).


Step 4: Prioritize and Trim

Prioritize your list of questions and then trim it down to about 10 to 12 well-designed questions. You started this process in step 1 and step 2 and should finalize the list before you build your visuals. Lock down your design but remember there will be more tweaks as you build your visuals and begin to collect and analyze the data.

As part of the trimming process, consider combining or repurposing statistics. For example, most games will have questions around the trial conversion experience. You can add a license parameter to existing statistics and use the data collected to answer questions around the trial experience. While trial experience questions may have a different focus, many of the data points collected may overlap with existing statistics.


Step 3: Define the Hooks

Define the hooks (data points) and supporting parameters that you need to fully answer your research question.. These hooks are the events that you instrument into your game and parameters of the statistics in the Telemetry Definition schema in step 6.. Be sure to identify all the contextual data that you need to answer your questions and produce the desired impact. However, don’t define too many hooks, only collect the data necessary to answer the question. You should have a clear understanding of how your data can be used to make decisions.

For example, you consider the question we asked in step 2:

  • What tracks fail to meet the designer’s intent and what factors contribute to this failure??

To answer this question, you collect the following hooks:

  • Start Track
  • Checkpoint Reached
  • Fault
  • End Track
  • Track ID
  • Vehicle

These hooks map to the statistics defined in your Telemetry Definition XML document. After you identify the basic hooks, determine what supporting data you need to answer your research questions.

  • Track ID
  • Vehicle
  • Game Mode
  • License
  • Time

Using these hooks, you can identify where racers fail or what tracks take too long to complete or what game modes racers have difficulty with.

In summary, you define hooks to:

  1. Answer your research question.
  2. Gather sufficient data to determine where the issue exists. Is the data is granular enough, or do you have the proper context.
  3. Decide whether it is possible to produce the desired impact to the game.
  4. Determine how far you need to drill down into the data or game levels to answer questions.
  5. Define what parameters you need to explore unexpected behaviors.

Note: You need enough contextual data to answer your research question. A common mistake that many designers make is not enough contextual data to answer your questions.

For more information, see the suggested hooks for the common questions by genre listed in Appendix A (under construction).


Step 5: Build your Visuals & Reports

Prioritize your list of questions and then trim it down to about 10 to 12 well-designed questions. You started this process in step 1 and step 2 and should finalize the list before you build your visuals. Lock down your design but remember there will be more tweaks as you build your visuals and begin to collect and analyze the data. As part of the trimming process, consider combining or re-purposing existing statistics. For example, most games will have questions around the trial conversion experience. You can add a license parameter to existing statistics and use the data collected to answer questions around the trial experience. While trial experience questions may have a different focus, many of the data points collected may overlap with existing statistics.

  • Identify whether you have all the necessary hooks
  • Anticipate data patterns
  • Ensure you’re getting the answers you need to make the desired changes.

You should build reports and visuals before you begin the development phase and instrument the game. Initially, you can build prototype reports from the simple spreadsheets, and then build out full dashboards in production.To build visuals, create graphs that pivot your data from different angles and allows you to drill deeper into the layers and levels in the game. At this stage, you may also discover that you need to tweak your hooks.

When you build your visuals and reports, consider the following:

  • Who is the target audience?
  • Are visuals appropriate for the audience?
  • Are reports simple and understandable or is there too much data.
  • Getting feedback from all interested parties: Developers, Testers, Producers, User research, Marketing and Business.
  • Verify that you have the appropriate granularity and context to explore your research questions.

Types of reports include:

  • Graphs: Bar charts and line graphs that show various aspects of the such as tie in levels, number of players deaths in a level or in all levels.
  • Heat Maps: Map of activity in the game. Visualize data relavent to player’s location on the map such as where players are getting lost or killed.
  • Reports: For a summary of all the data.
  • Tables: Show interactions between players and attackers.

For example visuals, see the Telemetry Example topic (under construction).


Step 6: Map Hooks to the Telemetry Definition Schema

The hooks you defined in step 3 map to statistics and parameters in the Telemetry Definition schema. Generally, statistics are placeholder for your research questions and the contextual data are the parameters associated with these statistics. You may need to correlate multiple statistics to collect all the data points that you need to answer a research question. For example, to answer a question about how long players spend in game levels, you could create two statistics: a “Level Start” and a “Level Complete” and then correlate them using the unique session ID.

In the Telemetry Definition schema, the stat elements are the containers that hold an array of up to 20 param elements. Parameters are either property or value data points as follows:

  • Properties: Data points that provide contextual information such as location or player class that you can use to pivot data or correlate across multiple statistics. Property data points have no operator, they are reported “as is.”

    • For example, in a statistic called “Buy Item,” you could collect the Item Id as a value parameter to identify the types of items collected. You could also collect location and player class as addition contextual data points.

  • Values: These are measurement data points that Sentient performs operations on for client side aggregation. For example, client data aggregation can measure of how many times an event occurred or the min/max value within a few minutes. Client aggregation is essential for events that occur frequently and every stat must have at least one value parameter.

    • For example, in the Buy Item statistic, you collect a count parameter to aggregate items that are frequently purchased.

For more information on client aggregation and Value operators, see Using Value Parameters.

Sentient does not support string parameters but you should map string data to enumerations and provide this information to the Sentient team.

Use these statistics to instrument events and parameters into your game. Statistics are sent to Sentient through custom APIs that are created when you upload your Telemetry Definition XML document to the server. For more information on using the Telemetry Definition Schema to define your statistics, see Defining Telemetry Statistics. For more information on retrieving the Telemetry definition Schema and uploading your Telemetry Definition XML document to the Sentient Developer Website, see Downloading the Schema. For more information on using the custom send statistic API to send your statistics to Sentient, see Implementing Telemetry Statistics.

For examples of data in the schema, see Telemetry Examples (under construction).


Using Value Parameters

Using the Sentient Telemetry Definition schema, you define either value or property parameters in a statistic. Property parameters are defined as having no operator (operator=none) and contain contextual information for the statistic. Value parameters have one of the following operators:

  • Increment: This parameter increments by one every time this event is received. Count parameter are not sent to Sentient in the custom stat API, but are recorded in the data on the backend.
  • Accumulate: The value of this parameter is added to the current value every time this event is received.
  • Min / Max: The minimum or maximum value is recorded every time this event is received.

Typically, a statistic has only one or two value parameters.

Data Aggregation

The only way to implement client-side data aggregation is to add a value parameter to a statistic. While all statistics must include at least one value parameter, for events that fire frequently such as gold gathered, value parameters are essential to avoid data bloat. Sentient aggregates value parameters according to the following data aggregation rules:

  • All property parameters must be identical to aggregate with other stats.
  • Every statistic must have at least one value parameter. If you don’t need a value parameter, then include a count parameter with an increment operator.
  • You may have more than one value parameter in a statistic. Value parameters aggregate separately as long as the property parameters are identical.
  • Data aggregation only takes place on the client; Sentient does not implement server-side aggregation.
  • Sentient aggregates data on the client for 5 minutes before sending to the server. After 5 minutes, the client buffer is cleared and aggregation starts over.

    Note: Currently, Sentient aggregates for 5 minutes by default, however this period is subject to change.

For example, consider the following statistic:

<Stat name="DemoStat1" desc="Damage Done By Player”)" type="event">

<Parameters>

<Param name="Level" type="int" op="none"/>

<Param name="Strength" type="int" op="none"/>

<Param name="Agility" type="int" op="none"/>

<Param name="Class" type="int" op="none"/>

<!--This is a value-->

<Param name="DamageDone" type="int" op="accumulate"/>

</Parameters>

</Stat>

Sentient accumulates the DamageDone parameter on the client when all other property parameters (Level, Strength, Agility and Class) are equal.


Design Considerations for Telemetry Statistics

Sentient recommends a number of best practices for designing statistics using the Telemetry Definition schema. Following these recommendations you can:

  • Use network bandwidth more efficiently.
  • Avoid data bloat on the server
  • Avoid buffer overflow and loss of data on the client
  • Design statistics for effective data analysis and reporting

To reduce the amount of telemetry data stored on the server and simplify reporting, Sentient aggregates data on the client. In situations where there is limited storage on the client, data aggregation also helps avoid buffer overruns and potential loss of data from events that fire frequently. However, it is essential that you first design your statistics for efficient aggregation. The following practices help you design effective telemetry statistics:

Sentient recommends a number of best practices for designing statistics using the Telemetry Definition schema. Following these recommendations you can:

  • Use network bandwidth more efficiently
  • Avoid data bloat on the server
  • Avoid buffer overflow and loss of data on the client
  • Design statistics for effective data analysis and reporting

Because Sentient-enabled titles have only a finite amount of telemetry storage on the server, Sentient aggregates data on the client to minimize the amount of data stored. Data aggregation also avoids buffer overruns and potential loss of data on the client from events that fire frequently; however, it is essential that you first design your statistics for efficient aggregation. The following practices help you design effective telemetry statistics:

Client Data Aggregation

To enable aggregation on the client, you must have at least one value parameter in a statistic. Data aggregates when all the property parameters are exactly the same. For more information, see Using Value Parameters.

Location Parameters

Use game segments instead of x, y, z coordinates which are difficult to aggregate and tend to cause data bloat. To aggregate statistics on the client, all contextual data must be exactly the same which rarely happens with x, y coordinates.

For games with linear progression you can use level IDs and checkpoints within each level to identify location. You can also define more granular locations by adding additional segments into the checkpoints.

Frequent Events

All statistics should include a value parameter for data aggregation; however, when events fire frequently it is essential to aggregate the data.

  • Avoid widely varying parameters: Highly varying parameters such as number of seconds, explicit timestamps or currency are difficult to aggregate and tend to cause data bloat and buffer overflows on the client.
  • Add a count or accumulate parameter: It is essential to add a count or accumulate parameter for frequent events to enable data aggregation on the client. Consider the following Restart statistic with and without a count parameter:

    • Statistic: Every time a player restarts in a game level you send a statistic to Sentient.

    • Without a count parameter: Sentient logs a new entry every time it receives this statistic. If the player restarts 5 times in 5 minutes, Sentient logs 5 entries.

    • With a count parameter: Sentient aggregates statistics when all the contextual data have the same value. If the player restarts 5 times in the same checkpoint on a map, then Sentient logs only one statistic with a count value of 5.

Flush Data after Major Events

After major events such as “Level Exited” or “Exit to Menu,” call SentientFlushStats to immediately send any statistics buffered on the client to the server. If there is cached data on the client and the user exits the game or turns off the console, any cached data will be lost. In addition, to ensure that players do not turn off the console while telemetry data is being transmitted, you should hide the call to flush statistics behind a game save event and display the spinner UI element. You may choose not to implement this practice, but understand that you could lose data.

Appropriate Contextual Data

Collect enough data to answer your research question but don’t gather too much data. For more infomration, see step 3.

License Parameter

Titles that have a trail version should include a statistic that indicates whether players are using the full or trial version. Your telemetry plan will likely have questions around the trial conversion experience and it is possible to repurpose statistics to answer questions with a different focus.

Note: This is specific to titles that provide an upgrade from the trial version to the full version.

Combine Events

A large number of events can be combined into a single event with different parameters. For example, consider the following scenarios:

  • Instead of creating separate “Buy Bike Item” and “Buy Rider Item” statistics, combine them into one generic “Buy Item” statistic. You can differentiate between items with item ids or you can add an “Item Type” enumeration where Bike Item = 1 and Rider Item = 2.
  • It is may not be necessary to create different statistics for every type of track in a racing genre game. Instead, you can add a track type parameter and define only a single track statistic that contains all the same events.

Use Enumerations

String parameters are not supported by the Telemetry Definition Schema. You must map strings to enumeration values and provide these mappings to Sentient no later that 2 weeks before your title releases.

Heartbeat

Heartbeat is a critical data point; however, it may be possible to repurpose existing events to determine if players are still engaged. For example:

  • In a title with bite sized game experiences, use a menu selection statistic to identify whether players are still alive.
  • In action games where scenes and levels change quickly, you can use an event to track players path that can also be used as a heartbeat.


Step 7: Collect Pilot Data and Iterate

During production you have the opportunity to collect data and iterate on your questions, hooks and visuals or reports. Your test audience could be testers and other members of your team or you could arrange a preview weekend to collect data from your target audience. Repeat the process outlined in steps 1 through 6 to iterate.


Telemetry Reference

This section contains reference information for the Microsoft Sentient APIs.

In This Section

Topic | Description
SentientSetStatSendInterval | Sets the time interval to send telemetry data to the Sentient server.
SentientFlushStats | Immediately sends any statistics buffered on the client to the server.
Telemetry Definition Schema | Defines the telemetry statistics for your title.

Reserved API

Topic | Description
SentientStatsSend | Reserved, do not use.
SenStat Structure | Reserved, do not use.
SenStat Constants | Reserved, do not use.


SentientSetStatSendInterval Function

Sets the time interval to send telemetry data to the Sentient server.

Syntax

C ++
void SentientSetStatSendInterval(
   DWORD dwIntervalMs
);

Parameters

dwIntervalMs

[in] The interval, in milliseconds, to send statistics from the client to the Sentient server. The minimum time that you can set is 250 ms.

Return Values

This function does not return a value.

Remarks

This function is provided for testing purposes only and does not work in release builds.

Requirements

Header: SenClientStats.h

Library: SenCoreD.lib

See Also

Telemetry Reference


SentientFlushStats Function

Immediately sends any statistics buffered on the client to the server.

Syntax

C ++
HRESULT SentientFlushStats(
);

Parameters

This function takes no parameters.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The buffered statistics were flushed to the server.

SENTIENT_E_TOO_MANY_CALLS

You called this function to flush too quickly after a previous call to flush.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

Remarks

This API may only be called once every minute. If you attempt to call this API more frequently, Sentient throttles the call and returns SENTIENT_E_TOO_MANY_CALLS.

Requirements

Header: SenClientStats.h

Library: SenCore.lib

See Also

Telemetry Reference


Telemetry Definition Schema

Defines the telemetry statistics for your title.

Syntax

<?xml version="1.0" encoding="utf-8"?>

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:element name="SentientStats">

<xs:complexType>

<xs:sequence>

<xs:element ref="Stat" maxOccurs="128"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="Stat">

<xs:complexType>

<xs:sequence>

<xs:element ref="Parameters"/>

</xs:sequence>

<xs:attribute name="name" type="xs:string" use="required"/>

<xs:attribute name="desc" type="xs:string" use="required"/>

<xs:attribute name="type" type="statType" use="required"/>

</xs:complexType>

</xs:element>

<xs:element name="Parameters">

<xs:complexType>

<xs:sequence>

<xs:element ref="Param" maxOccurs="20"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="Param">

<xs:complexType>

<xs:attribute name="name" type="xs:string" use="required"/>

<xs:attribute name="type" type="paramType" use="required"/>

<xs:attribute name="op" type="operator" use="required"/>

</xs:complexType>

</xs:element>

<xs:simpleType name ="statType">

<xs:restriction base="xs:string">

<xs:enumeration value="event"/>

</xs:restriction>

</xs:simpleType>

<xs:simpleType name ="paramType">

<xs:restriction base="xs:string">

<xs:enumeration value="int"/>

</xs:restriction>

</xs:simpleType>

<xs:simpleType name ="operator">

<xs:restriction base="xs:string">

<xs:enumeration value="none"/>

<xs:enumeration value="accumulate"/>

<xs:enumeration value="increment"/>

<xs:enumeration value="min"/>

<xs:enumeration value="max"/>

</xs:restriction>

</xs:simpleType>

</xs:schema>

Telemetry Definition Elements

<SentientStats>

The root schema element that holds up to 128 Stat elements.

<Stat>

The second-level element that holds the parameter element and defines the type of statistic (statType).

<Parameters>

The third-level schema element that holds an array of 1 to 20 Param elements.

<Param>

The schema element that defines the type of parameter (that is, paramType enumeration) and the operation performed on the parameter (that is, operation enumeration).

Telemetry Definition Enumeration Types

operator

An enumeration that defines the operation that Sentient performs on the parameter. The operation may be one of the following:

none: A property type member indicating that no operations are performed on the parameter; the value of the parameter is reported “as is” (for example, the player’s level).

accumulate: A value type member indicating that Sentient adds the value of the parameter to the current value (for example, the player gathers 12 new pieces of gold, which is added to that player's current stash of 34 gold).

increment: A value type member indicating that Sentient increases the parameter by 1 each time this event occurs (for example, the number of kills is incremented by 1 each event). Note that param elements defined with this operator are not sent to Sentient through the custom API created for each stat. Instead, Sentient automatically increments the count for accumulate type param elements each time you call the API.

min: A value type member indicating that Sentient determines the minimum value of the parameter (for example, the minimum power level of the player).

max: A value type member indicating that Sentient determines the maximum value of the parameter (for example, the minimum power level of the player).

Note: Property types are not modified while value types are modified.

paramType

An enumeration that defines the type of parameter data. The value is currently limited to an integer:

  • int: The parameter is an integer value.

statType

An enumeration that defines the type of statistic. The statistic type may be one of the following:

  • event: An event-based statistic. This is the default value (for example, the player advanced to level 2).
  • time: A time-based static that is tracked for a specified duration (for example, the time it took for the player to advance to level 2).

Remarks

In addition to the parameters defined using this schema, Sentient gathers the following information:

  • XUID: The online XUID of the user.
  • IP Address: The IP address of the Client
  • Session ID: The ID of the session that is generated on the client when telemetry data is initiated. This guarantees a unique id for all telemetry sessions.
  • Client and Server Timestamp: The time that the associated data was collected.
  • User Index: The index of the user on the Xbox (0 to 3).
  • Capture Time: The amount of time that Sentient successfully captured data on the client.
  • Overflow Time: The amount of time that Sentient failed to capture data on the client due to lack of memory.

    • Note: The maximum time allowed for captured data plus overflow data is limited to 300s.

  • Machine ID: The unique ID of the Xbox or computer.

Data Aggregation

To use the network more efficiently, telemetry data is buffered on the client computer for a period of time before it is sent to the Sentient servers. During this buffering period, the telemetry data is aggregated on the client. When the buffering period elapses, all data is sent to the Sentient server and Sentient clears the client buffer (titles cannot clear the client buffer). Note that if a user exits the game or turns off the console, any statistics that have not been sent to Sentient will be lost.

Note: Currently, Sentient buffers data on the client for a period of 5 minutes; however, this time is subject to change.

Data aggregation is performed on the client only when there is at least one value parameter and every statistic should have at least one value parameter. If you don’t need a value parameter, then include a count parameter with an increment operator.

Sentient aggregates value parameters when all other property parameters are identical. You may have more than one value parameter in a statistic; however, all value parameters aggregate separately. For example, consider the following "Damage Done" statistic:

<Stat name="DemoStat1" desc="Damage Done By Player”)" type="event">

<Parameters>

<Param name="Level" type="int" op="none"/>

<Param name="Strength" type="int" op="none"/>

<Param name="Agility" type="int" op="none"/>

<Param name="Class" type="int" op="none"/>

<!--This is a value-->

<Param name="DamageDone" type="int" op="accumulate"/>

</Parameters>

</Stat>

Sentient accumulates the DamageDone parameter on the client when all the other property parameters (Level, Strength, Agility and Class) are equal.

Telemetry Data Analysis

You can use the data stored on the Sentient server to produce reports and visuals for business managers, producers, game designers and other members of your team. These reports provide feedback that is used to design new features or change game behaviors before your title releases. When telemetry is combined with the Sentient Dynamic Configuration service, producers and game designers can use telemetry reports to dynamically configure game behavior of online games, without requiring a title update or code change. For more information on defining and gathering telemetry data, see Getting Started with Telemetry.

See Also

Telemetry Reference

Telemetry

Defining Telemetry Statistics

Download the Schema

Sentient Reporting


SentientStatsSend Function

This function is reserved by Sentient, do not use.

Instead, define your statistics in the XML file and then call the autogenerated methods to send your telemetry data. For more information, see Implementing Telemetry Statistics.

Syntax

C ++
HRESULT SentientStatsSend(
   SenStat *pStat
);

Parameters

Reserved, do not use.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

Remarks

Reserved, do not use.

Requirements

Header: SenClientStats.h

Library: SenCore.lib

See Also

Telemetry Reference


SenStat Constants

These constants are reserved by Sentient, do not use.

Instead, define your statistics in the XML file and then call the autogenerated methods to send your telemetry data. For more information, see Implementing Telemetry Statistics.

SenStatID Constants

The Sentient stat flags are members of the SenStats structure.

#define | Value | Description
SenStatID_Custom | 128 | Reserved, do not use.

SenStatFlag Constants

The Sentient stat flags are members of the SenStats structure.

#define | Value | Description
SenStatFlag_Normal | 1 | Reserved, do not use.
SenStatFlag_Time | 2 | Reserved, do not use.
SenStatFlag_TimeEnd | 4 | Reserved, do not use.

SenStatValueFlag Constants

The Sentient stat value flags are members of the SenStats structure.

#define | Value | Description
SenStatValueFlag_Inc | 1 | Reserved, do not use.
SenStatValueFlag_Accum | 2 | Reserved, do not use.
SenStatValueFlag_Min | 4 | Reserved, do not use.
SenStatValueFlag_Max | 8 | Reserved, do not use.

Requirements

Header: SenClientStats.h

See Also

Telemetry Reference


SenStat Structure

This structure is reserved by Sentient, do not use.

Instead, define your statistics in the XML file and then call the autogenerated methods to send your telemetry data. For more information, see Implementing Telemetry Statistics.

Syntax

C ++
struct SenStat{
   DWORD  dwUserID;
   DWORD  dwStatID;
   DWORD  dwFlags;
   DWORD  dwNumProperties;
   CHAR*  arrProperties;
   DWORD  dwNumValues;
   CHAR*  arrValues;
   DWORD*  arrValueFlags;
};

Members

Reserved, do not use.

Requirements

Header: SenClientStats.h

See Also

Telemetry Reference


Dynamic Configuration

Sentient is able to host custom data that titles can use to dynamically modify the behaviors of online games. Using this Dynamic Configuration Service, you can dynamically tune game settings such as "start position" or "default player" without requiring a title update. When paired with the Sentient Telemetry Service, you can collect telemetry data on your title and then use this data to modify the dynamic configuration files stored by the Sentient Dynamic Configuration Service.

To use this feature:

  1. Upload a configuration files to the Sentient Developer Website (https://sentient.msgamestudios.com). You can store your configuration data as multiple configuration files or multiple versions. These files are not managed or formatted by Sentient. They are completely defined by the title.
  2. Call the SenDynamicConfigGetSize and SenDynamicConfigGetBytes functions to retrieve a specific configuration file for use during game play.

For more information, see Getting Started with Telemetry.


Uploading a Configuration File to the Sentient Developer Website

Configuration files contain game settings that your game accesses from the Sentient servers to dynamically change certain behaviors of your game.

Note: Configuration files can be ini files or xml files or any file format defined by the title. Sentient does not recommend using any specific file format.

You can upload multiple configuration files or multiple versions of a configuration file to the Sentient Developer Website (https://sentient.msgamestudios.com).

To manually upload a configuration file:

  1. On the Management Tools menu, select Dynamic Configuration. If you have more than one title, select your title from the dropdown list; otherwise, your title will appear on the Manage Config Files page.
  2. On the Manage Config Files page, select Create New. Enter the following information:

    3. Resource ID: The offset of the resource ID for this configuration file.

    Start Time: The time and date that the file is active.

    End Time: The time and date that the file becomes inactive.

    Priority : The priority of the configuration file.

    Comments: Comments that identify this file.

  3. Browse to the location of the file you want to upload, and then click Create.

    4. Sentient adds the configuration file to the list of files available to your title and displays the file name, resource ID and other parameters for your file.

When you upload a configuration file, Sentient creates a resource ID that you use to retrieve the configuration file in the calls to SenDynamicConfigGetSize. and SenDynamicConfigGetBytes.

Sentient treats the configuration files as generic blocks of data and does not manage or otherwise validate or alter the contents of files uploaded to the server. However, Sentient does create a file digest (see SenFileDigestCreate) to ensure data integrity.


Retrieving a Configuration File

You can retrieve the configuration file that you uploaded to the Sentient Developer Website (https://sentient.msgamestudios.com) from your game as follows:

  1. Call SenDynamicConfigGetSize to get the size of the configuration file.
  2. Allocate a return buffer to the size returned from SenDynamicConfigGetSize, and then call SenDynamicConfigGetBytes with the buffer to retrieve the configuration file.

Use the resource ID that you specified on the website in the call to SenDynamicConfigGetSize and SenDynamicConfigGetBytes to specify the configuration file. You should check the returned file ID to ensure it is a valid File ID (that is, not SenFileID_Invalid).


Dynamic Configuration Reference

This section contains reference information for the Microsoft Sentient APIs.

In This Section

Dynamic Configuration Functions
Function | Description
SenDynamicConfigGetSize | TBD
SenDynamicConfigGetSize (overloaded) | TBD
SenDynamicConfigGetBytes | TBD
SenDynamicConfigGetBytes (overloaded) | TBD


SenDynamicConfigGetBytes Function (overloaded)

Returns the contents of the specified configuration file.

Syntax

C ++
HRESULT SenDynamicConfigGetBytes(
   unsigned int titleID,
   unsigned int resourceID,
   size_t dataSizeMax,
   size_t* out_bytesWritten,
   void *out_data,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

titleID

[in] A SenSysTitleID that uniquely identifies an Xbox Live title. Internally, Sentient assigns a title identifier to each title that is within the 32 bit range specified by the SenSysTitleID enumeration.

resourceID

[in] The ID of the configuration file that is requested. This is the ID that is set when you upload your configuration file on the Sentient Developer Website (https://sentient.msgamestudios.com).

dataSizeMax

[in] the maximum number of bytes to return to the out_data buffer.

out_bytesWritten

[out] The number of bytes written to the out_data buffer.

out_data

[out] The buffer that receives the contents of the configuration file.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_data pointer is NULL.

Remarks

To upload a configuration file to the Sentient Developer Website (https://sentient.msgamestudios.com), see Uploading a Configuration File to the Sentient Developer Website. For information on downloading the configuration file, see Retrieving a Configuration File.

Requirements

Header: SenClientDynamicConfig.h

Library: SenCore.lib

See Also

Dynamic Configuration Reference

SenDynamicConfigGetBytes

SenDynamicConfigGetSize

SenDynamicConfigGetSize (overloaded)


SenDynamicConfigGetBytes Function

Returns the contents of the specified configuration file.

Syntax

C ++
HRESULT SenDynamicConfigGetBytes(
   unsigned int resourceID,
   size_t dataSizeMax,
   size_t* out_bytesWritten,
   void *out_data,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

resourceID

[in] The ID of the configuration file that is requested. This is the ID that is set when you upload your configuration file on the Sentient Developer Website (https://sentient.msgamestudios.com).

dataSizeMax

[in] the maximum number of bytes to return to the out_data buffer.

out_bytesWritten

[out] The number of bytes written to the out_data buffer.

out_data

[out] The buffer that receives the contents of the configuration file.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_data pointer is NULL.

Remarks

To upload a configuration file to the Sentient Developer Website (https://sentient.msgamestudios.com), see Uploading a Configuration File to the Sentient Developer Website. For information on downloading the configuration file, see Retrieving a Configuration File.

Requirements

Header: SenClientDynamicConfig.h

Library: SenCore.lib

See Also

Dynamic Configuration Reference

SenDynamicConfigGetSize

SenDynamicConfigGetSize (overloaded)

SenDynamicConfigGetBytes (overloaded)


SenDynamicConfigGetSize Function (overloaded)

Returns the size of the specified configuration file.

Syntax

C ++
HRESULT SenDynamicConfigGetSize(
   unsigned int titleID,
   unsigned int resourceID,
   size_t* out_size,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

titleID

[in] A SenSysTitleID that uniquely identifies an Xbox Live title. Internally, Sentient assigns a title identifier to each title that is within the 32 bit range specified by the SenSysTitleID enumeration.

resourceID

[in] The ID of the configuration file that is requested. This is the ID that is set when you upload your configuration file on the Sentient Developer Website (https://sentient.msgamestudios.com).

out_size

[out] The size of the configuration file, in bytes.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_size pointer is NULL.

Remarks

To upload a configuration file to the Sentient Developer Website (https://sentient.msgamestudios.com), see Uploading a Configuration File to the Sentient Developer Website. For information on downloading the configuration file, see Retrieving a Configuration File.

Requirements

Header: SenClientDynamicConfig.h

Library: SenCore.lib

See Also

Dynamic Configuration Reference

SenDynamicConfigGetBytes

SenDynamicConfigGetSize

SenDynamicConfigGetBytes (overloaded)


SenDynamicConfigGetSize Function

Returns the size of the specified configuration file.

Syntax

C ++
HRESULT SenDynamicConfigGetSize(
   unsigned int resourceID,
   size_t* out_size,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

resourceID

[in] The ID of the configuration file that is requested. This is the ID that is set when you upload your configuration file on the Sentient Developer Website (https://sentient.msgamestudios.com).

out_size

[out] The size of the configuration file, in bytes.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_size pointer is NULL.

Remarks

To upload a configuration file to the Sentient Developer Website (https://sentient.msgamestudios.com), see Uploading a Configuration File to the Sentient Developer Website. For information on downloading the configuration file, see Retrieving a Configuration File.

Requirements

Header: SenClientDynamicConfig.h

Library: SenCore.lib

See Also

Dynamic Configuration Reference

SenDynamicConfigGetBytes

SenDynamicConfigGetSize (overloaded)

SenDynamicConfigGetBytes (overloaded)


Cross Title Promotional

Using the Cross Title Promotion feature, you can upsell Xbox LIVE Marketplace content such as digitally distributed titles or downloadable content from the current or related titles. You can also store custom upsell images and text on the Sentient servers and then deliver them to players in your game.

To register your custom promotional content on the Xbox LIVE Marketplace, contact your Xbox Producer or Account Manager and provide the assets for your title. Sentient returns a list of the promotional assets that are available and are configured for your title when you call SenBoxArtEnumerate. This call returns a SenBoxArtInfo structures for each title that has box art.

Using the title information that's returned, you can dynamically build a UI to highlight additional content available for each title. To receive additional information about each piece of promotional content, call SenBoxArtDownloadExtraInfo and SenBoxArtDownloadImage. You can customize the design of your UI to the artistic style of your title; however, you should work with your Xbox Producer or Account Manager to determine the most effective location for the content and the best user experience.

When a player selects a promotion they are interested in, you can call XShowMarketplaceUI with the offer's ID returned in the SenBoxArtInfo structure. The player will then be presented with the standard Xbox Guide purchasing experience.


Retrieving Box Art

To retrieve box art from the Xbox LIVE Marketplace using the Sentient API:

  1. Call SenBoxArtEnumerate to get the list of SenBoxArtInfo structures that enumerate the box art available for your title.
  2. Use the SenBoxArtInfo structure to call SenBoxArtDownlaodExtraInfo to get the SenBoxArtExtraInfo structure. This structure contains the title and description of the box art.
  3. Use the SenBoxArtInfo structure to get the size of the image file and then call SenBoxArtDownloadImage to get the display image for a box art.
  4. Build a UI to display the box art.

The following code example shows the how to retrieve box art:

         // The number of box art Info structures returned
    // from the call to SenBoxArtEnumerate
    size_t g_boxArtInfoCount;

    // The list of Box Art Info structures returned
    // from the call to SenBoxArtEnumerate
    SenBoxArtInfo *g_boxArtInfoList;

    // The box art image returned from SenBoxArtDownloadImage
    void * g_boxArtImage;

    // The extra info returned from SenBoxArtDownloadExtraInfo
    SenBoxArtExtraInfo g_boxArtExtraInfo;

    void BoxArtImageCallback ( HRESULT result, void * callbackData)
    {
        // Check SUCCEEDED( hresult ) or FAILED( hresult )
        // to determine success
        if ( FAILED (result) )
        {
            // TODO: Enter code to handle error here
        }

        // Check the image file downloaded
        if ( g_boxArtImage == NULL )
        {
            // TODO: Enter code to handle error here
        }

        // TODO: Display the box art image on the box art menu

        free (g_boxArtImage);

    }

    void BoxArtExtraInfoCallback ( HRESULT result, void * callbackData)
    {
        // Check SUCCEEDED( hresult ) or FAILED( hresult )
        // to determine success
        if ( FAILED (result) )
        {
            // TODO: Enter code to handle error here
        }

        // TODO: Handle the returned SenBoxArtExtraInfo
    }

    void BoxArtEnumerateCallback ( HRESULT result, void * callbackData)
    {
        // Check SUCCEEDED( hresult ) or FAILED( hresult )
        // to determine success
        if ( FAILED (result) )
        {
            // TODO: Enter code to handle error here
        }

        //********************************************************
        //  Parameters for the call to SenBoxArtDownloadExtraInfo
        //********************************************************
        HRESULT hr = E_FAIL;
        SenHandle handle;
        SenSysOfferID boxArtOfferID;

        // After the player select a specific Box Art,
        // call this function to download the extra info
        // This call retrieves the second box art extra info
        hr = SenBoxArtDownloadExtraInfo( g_boxArtInfoList[1],
                                         &g_boxArtExtraInfo, &handle,
                                         &BoxArtExtraInfoCallback, NULL );

        //****************************************************
        //  Parameters for the call to SenBoxArtDownloadImage
        //****************************************************
        size_t dataSizeMax;
        dataSizeMax = g_boxArtInfoList[1].image.GetBufferSize();

        // Allocate the returned box art image buffer
        g_boxArtImage = malloc(dataSizeMax);
        memset( g_boxArtImage, 0, dataSizeMax );

        // After the player select a specific Box Art, call
        // this function to download the box art image
        hr = SenBoxArtDownloadImage(g_boxArtInfoList[1], dataSizeMax,
                                    g_boxArtImage, NULL,
                                    &BoxArtImageCallback, NULL);

        // Retrieve the ID of the offer on the Xbox LIVE marketplace
        boxArtOfferID = g_boxArtInfoList[1].GetOfferID();

        // TODO: Call the Xbox LIVE marketplace API with this offer ID

    }

    void DocSampleScene::RetrieveBoxArt()
    {
        //*****************************
        //  Box Art Example Code
        //    Enumerate Box Art
        //    Wait for the callback
        //*****************************

        //*************************************************
        //  Parameters for the call to SenBoxArtEnumerate
        //*************************************************
        int  userIndex =  0;    // TODO:  Get the user index
        size_t  boxArtCountMax = 5;
        HRESULT hr = E_FAIL;

        // Allocate the buffer that recieves the box art info
        // to the maximum number that you want to recieve
        g_boxArtInfoList = (SenBoxArtInfo *)malloc( boxArtCountMax * sizeof(SenBoxArtInfo) );
        memset( g_boxArtInfoList, 0, boxArtCountMax * sizeof(SenBoxArtInfo) );

        // Enumerate the box art for this title
        hr = SenBoxArtEnumerate( userIndex, boxArtCountMax,
                                 &g_boxArtInfoCount, g_boxArtInfoList,
                                 NULL, &BoxArtEnumerateCallback, NULL );

        // Check SUCCEEDED( hresult ) or FAILED( hresult )
        // to determine success
        if ( FAILED (hr) )
        {
            // TODO: Enter code to handle error here
        }

    }


Box Art Reference

This section contains reference information for the Microsoft Sentient APIs.

In This Section

Box Art Functions
Function | Description
SenBoxArtEnumerate | Searches the Sentient database for all box art that matches the search criteria.
SenBoxArtDownloadImage | Downloads the raw box art image from the Sentient servers.
SenBoxArtDownloadExtraInfo | Downloads the extra information about the box art from the Sentient servers.

Box Art Structures

Structure | Description
SenBoxArtInfo | Contains the basic box art information.
SenBoxArtExtraInfo | Contains additional information (localized title and description) about the box art.

Box Art Enumerations

Enumeration | Description
SenBoxArtCommand | Defines the box art command actions.
SenBoxArtSortBy | Defines the box art sort options.


SenBoxArtEnumerate Function

Searches the Sentient database for all box art that matches the search criteria.

Syntax

C ++
HRESULT SenBoxArtEnumerate(
   int  userIndex,
   size_t  boxArtInfoCountMax,
   size_t  *out_boxArtInfoCount,
   SenBoxArtInfo  *out_boxArtInfoList,
   SenHandle  *out_senHandle,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

boxArtInfoCountMax

[in] The maximum number of SenBoxArtInfo structures allocated in the out_boxArtInfoList.

Note: The number of box art available on the Sentient server is returned in the out_boxArtInfoCount parameter. This parameter contains the number of box art structures that the title can receive from this call.

out_boxArtInfoCount

[out] A pointer to the number of SenBoxArtInfo structures enumerated by this call.

Note: This number is limited to boxArtInfoCountMax and may be less than the number of box art available on the Sentient server.

out_boxArtInfoList

[out] A pointer to the SenBoxArtInfo structures that will contain the box art for enumerated titles after Sentient invokes the callback associated with this function. Sentient assumes that the memory is allocated to hold at least boxArtInfoCountMax entries.

out_senHandle,

[out] A handle to the asynchronous task that can be used to call SentientCancel on this operation. This parameter is optional and may be set to NULL.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to the SenSysCompletedCallback function. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

E_POINTER

The out_boxArtInfoList or out_boxArtInfoCount pointer is NULL.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest may not spawn this call.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_USERINDEX_IS_ANY

The user index of ANY (0xFF) is not valid.

SENTIENT_E_USERINDEX_IS_FOCUS

The user index FOCUS (0xFD) is not valid.

SENTIENT_E_USERINDEX_IS_NONE

The user index of NONE (0xFE) is not valid.

SENTIENT_E_USERINDEX_IS_INVALID

The user index is outside the range 0 to 3.

Remarks

This function returns the current list of box art stored on the Sentient servers for all titles. You must call this function to retrieve the SenBoxArtInfo structures before calling SenBoxArtDownloadExtraInfo and SenBoxArtDownloadImage.

Requirements

Header: SenClientBoxArt.h

Library: SenBoxArt.lib

See Also

Box Art Reference

SenBoxArtDownloadImage

SenBoxArtDownloadExtraInfo


SenBoxArtDownloadExtraInfo Function

Downloads the extra information about the box art from the Sentient servers.

Syntax

C ++
HRESULT SenBoxArtDownloadExtraInfo(
   const SenBoxArtInfo  &boxArtInfo,
   SenBoxArtExtraInfo  *out_boxArtExtraInfo,
   SenHandle  *out_senHandle,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
);

Parameters

boxArtInfo

[in] A reference to the SenBoxArtInfo structure that contains the information about the attributes and data of the box art. To retrieve this structure, call SenBoxArtEnumerate.

out_boxArtExtraInfo

[out] A pointer to the SenBoxArtExtraInfo structure that will contain the information about the attributes and data of the box art after Sentient invokes the callback associated with this function.

out_senHandle,

[out] A handle to the asynchronous task that can be used to call SentientCancel on this operation. This parameter is optional and may be set to NULL.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to the SenSysCompletedCallback function. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_INVALIDARG

Either the boxArtInfo.resourceID or boxArtInfo.xml is invalid.

E_POINTER

The out_boxArtExtraInfo pointer is NULL.

Remarks

On completion, the structure will contain extra information, such as localized strings. You must call SenBoxArtEnumerate to retrieve the SenBoxArtInfo structure before you call this function.

Requirements

Header: SenClientBoxArt.h

Library: SenBoxArt.lib

See Also

Core Reference

Related

Box Art Reference

SenBoxArtEnumerate

SenBoxArtDownloadImage


SenBoxArtDownloadImage Function

Downloads the raw box art image from the Sentient servers.

Syntax

C ++
HRESULT SenBoxArtDownloadImage(
   const SenBoxArtInfo &boxArtInfo,
   size_t dataSizeMax,
   void *out_data,
   SenHandle *out_senHandle,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

boxArtInfo

[in] A reference to the SenBoxArtInfo structure that contains the information about the attributes and data of the box art. To retrieve this structure, call SenBoxArtEnumerate.

dataSizeMax

[in] The size of the out_data buffer, in bytes. The size must be at least boxArtInfo.image.GetBufferSize() bytes. Sentient returns an error if the size of the returned data exceeds the size in this parameter.

out_data

[out] The buffer that will contain the image data after Sentient invokes the callback associated with this call. This must be pre-allocated to at least boxArtInfo.image.GetBufferSize() bytes.

out_senHandle

[out] A pointer to a Sentient handle that can be used to call SentientCancel on this operation. This parameter is optional and may be set to NULL.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to the SenSysCompletedCallback function. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_INVALIDARG

Either the boxArtInfo.resourceID or boxArtInfo.image parameter is not valid.

E_POINTER

The out_data pointer is NULL.

Remarks

The boxArtInfo parameter refers to a file whose format is compatible with D3DXCreateTextureFromFileInMemory file formats and XUI file formats. You must call SenBoxArtEnumerate to retrieve the SenBoxArtInfo structure before you call this function.

Requirements

Header: SenClientBoxArt.h

Library: SenBoxArt.lib

See Also

Box Art Reference

SenBoxArtEnumerate

SenBoxArtDownloadExtraInfo


SenBoxArtExtraInfo Structure

Contains additional information (localized title and description) about the box art.

Syntax

C ++
struct SenBoxArtExtraInfo{
   wchar_t title[XMARKETPLACE_MAX_OFFER_NAME_LENGTH+1];
   wchar_t description[XMARKETPLACE_MAX_OFFER_SELL_TEXT_LENGTH+1];
};

Members

title

The localized title of the offer.

description

The localized short description of the offer.

Remarks

This structure contains the localized strings that describe the box art. To retrieve this structure, call SenBoxArtDownloadExtraInfo. You must call SenBoxArtEnumerate, before you call SenBoxArtDownloadExtraInfo.

To return localized strings, Sentient uses the system language and locale settings on the local machine. To retrieve the localization settings on the machine, call XGetLocale or XGetLanguage.

Requirements

Header: SenClientBoxArt.h

Library: SenBoxArt.lib

See Also

Box Art Reference

SenBoxArtDownloadExtraInfo


SenBoxArtInfo Structure

Contains the basic box art information.

Inheritance

Inherits from SenResourceInfo.

Syntax

C ++
struct SenBoxArtInfo : public SenResourceInfo{
   SenRawDataTransferInfo  image;
   SenRawDataTransferInfo  xml;
   SenBoxArtCommand  command;
   INT32  commandData0;
   INT32  commandData1;
   UINT32  friendsWithTitle;
   SenSysOfferID GetOfferID() const;
};

Members

image

A SenRawDataTransferInfo structure that refers to the image file. The file referenced by this structure will be compatible with D3DXCreateTextureFromFileInMemory.

xml

A SenRawDataTransferInfo structure that refers to an opaque XML file that holds extended information about the box art. To retrieve this structure, call SenBoxArtDownloadExtraInfo.

command

A SenBoxArtCommand that specifies the action that the title should perform when the user selects a box art.

commandData0

Arbitrary data that is associated with the command. For example, the high bits of the offerID.

commandData1

Arbitrary data that is associated with the command. For example, the low bits of the offerID.

friendsWithTitle

The number of friends who own the title associated with this box art.

GetOfferID()

This function returns the SenSysOfferID associated with this box art. If the command is SenBoxArtCommand_Store, this call returns the commandData0 and commandData1 as SenSysOfferIDs; otherwise, it returns SenSysOfferID_Invalid.

Remarks

This structure contains the information originally uploaded for the box art plus any information that is implied by the raw data that was uploaded, such as size of data. To retrieve this structure, call SenBoxArtEnumerate.

Requirements

Header: SenClientBoxArt.h

Library: SenBoxArt.lib

See Also

Box Art Reference

SenBoxArtEnumerate

SenBoxArtDownloadImage

SenBoxArtDownloadExtraInfo

SenResourceInfo


SenBoxArtCommand Enumeration

Defines the box art command actions.

Syntax

C ++
enum SenBoxArtCommand{
   SenBoxArtCommand_Store = 0,
};

Parameters

SenBoxArtCommand_Store

The game should call the Xbox LIVE Marketplace UI. That is, call GetOfferID from the SenBoxArtInfo structure.

Remarks

When the user selects box art, these are the options that generate the resulting action.

Requirements

Header: SenClientBoxArt.h

Library: SenCore.lib

See Also

Box Art Reference

SenBoxArtInfo


SenBoxArtSortBy Enumeration

Defines the box art sort options.

Syntax

C ++
enum SenBoxArtSortBy{
   SenBoxArtSortBy_Default = 0,
};

Constants

SenBoxArtSortBy_Default

The default sort order.

Remarks

Use these constants when you enumerate box art to determine the sort order.

Requirements

Header: SenClientBoxArt.h

Library: SenBoxArt.lib

See Also

Box Art Reference


News

Using the Sentient News Service titles can display news and updates to their player community. Titles download news ticker messages from the Sentient servers and then displays messages on a news ticker in the game. To onboard with the Sentient News Service and create ticker messages, send email to Sentient (senhelp@microsoft.com) with the following information:

  • News type: This is one of the following: Game, Game Family, User or All.
  • Language: For example, en (English) or fr (French).
  • Title (code names are OK):
  • News ticker text:
  • Priority:
  • Metadata 1:
  • Metadata 2:
  • Start date:
  • End date:

To retrieve and display news ticker messages, call SenGetTickerMessage.

Examples of ticker messages include:

  • New DLC available for <GAME_TITLE>
  • <N> of your friends own <GAME_TITLE>
  • <N> of your friends are currently playing <GAME_TITLE>
  • <N> of your friends have recently played <GAME_TITLE>
  • 1 of your friends owns <GAME_TITLE>
  • 1 of your friends has played <GAME_TITLE>
  • 1 of your friends has recently played <GAME_TITLE>
  • <Special event> in <GAME_TITLE> happening now!
  • <FRIEND_GAMERTAG> just beat you on the leaderboards in <GAME_TITLE>


News Reference

This section contains API reference elements that you use with the Microsoft Sentient API.

In This Section

News Function
Function | Description
SenGetTickerMessage | Retrieves the localized message to display on the news ticker.
News Structure
Structure | Description
SenTickerData | Contains the ticker message and any additional information required to display the message.
News Enumeration
Enumeration | Description
SenTickerMessageType | Describes the type of text to display on the news ticker.
News Constants
Enumeration | Value | Description
MAX_NEWS_ITEM_COUNT | 40 | The maximum number of news items that may be uploaded to the Sentient server.


SenGetTickerMessage Function

Retrieves the localized message to display on the news ticker.

Syntax

C ++
HRESULT SenGetTickerMessage(
   int   userIndex,
   SenTickerData   *out_tickerData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

out_tickerData

[in] A pointer to the SenTickerData that contains the message and any additional information required to display the message.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

E_POINTER

The out_tickerData pointer is NULL.

SENTIENT_E_USERINDEX_IS_ANY

The user index of ANY (0xFF) is not valid.

SENTIENT_E_USERINDEX_IS_FOCUS

The user index FOCUS (0xFD) is not valid.

SENTIENT_E_USERINDEX_IS_NONE

The user index of NONE (0xFE) is not valid.

SENTIENT_E_USERINDEX_IS_INVALID

The user index is outside the range 0 to 3.

Remarks

The first time you call this function, it returns the welcome message. Subsequent calls will return the news messages stored on the Sentient server in a random order.

This function returns a maximum of 128 characters. To retrieve the next segment of a message or the next message, call this function again.

Requirements

Header: SenClientNews.h

Library: SenNews.lib

See Also

News Reference

SenTickerData


SenTickerData Structure

Contains the ticker message and any additional information required to display the message.

Syntax

C ++
struct SenTickerData{
   wchar_t   message[128];
   SenTickerMessageType   messageType;
   INT64   data1;
   INT64   data2;
   float   charPerSec;
};

Members

message

The localized message to display on the news ticker.

messageType

A member of the SenTickerMessageType enumeration that describes the type of news.

data1

Optional data for this news message.

data2

Optional data for this news message.

charPerSec

The rate to display news messages. The default rate

(DEFAULT_CHARS_PER_SEC) is 2.0 characters/second.

Remarks

This structure is returned in the call to SenGetTickerMessage.

The data1 and data2 members are used for Xbox LIVE marketplace offerings. They may also be used for special promotional's such as double XP weekends.

To return localized strings, Sentient uses the system language and locale settings on the local machine. To retrieve the localization settings on the machine, call XGetLocale or XGetLanguage.

Requirements

Header: SenClientNews.h

Library: SenNews.lib

See Also

News Reference

SenGetTickerMessage


SenTickerMessageType Enumeration

Describes the type of text to display on the news ticker.

Syntax

C ++
enum SenTickerMessageType{
   SenTickerMessageType_Text = 0,
   SenTickerMessageType_MarketplaceOffer,
   SenTickerMessageType_Max
};

Constants

SenTickerMessageType_Text

The ticker message contains text.

SenTickerMessageType_MarketplaceOffer

The ticker message contains an Xbox LIVE Marketplace offering.

SenTickerMessageType_Max

This constant is reserved.

Remarks

This enumeration is a member of the SenTickerData structure.

Requirements

Header: SenClientNews.h

Library: SenNews.lib

See Also

News Reference

SenTickerData


User Generated Content

The User Generated Content (UGC) service, enables players to create and publish game content (such as levels, skins, ghosts, replays, or screenshots) that other gamers can discover through aggregated feeds and search. Gamers can then download and rate content for quality or level of difficulty. Players are also able to tag content they feel is offensive, and moderators have the option to remove content they deem inappropriate.

The UGC version 1.0 API also features feeds that titles can retrieve and display leaderboards with the latest UGC items, top downloaded UGC or highest rated content. Sentient tracks these and other statistics for feeds that titles display for players. The following sections provide a review of the Sentient v 1.0 UGC API:

Creating, Uploading and Publishing UGC Content

The following steps show how to publish UGC content:

  1. Retrieve a unique UGC ID for publishing content by calling SenUGCCreatePublishingUGCID. This returns a UGC ID which is a handle to the UGC item.
  2. Upload the UGC item by calling SenUGCUpload with the UGC ID. This call uploads both the UGC content and metadata.
  3. Publish the UGC item by calling SenUGCPublish. When you publish UGC content it becomes available to all other players in the titles.

You can delete UGC content at any tiem by calling SenUGCDelete. Only the users that created the UGC item can delete it.

Enumerating and Downloading UGC Feeds

To view the UGC feeds available to your title, you first query the types of feeds and then subscribe to specific feeds. UGC feeds return all the UGC items for the type of feed requested.

  1. To enumerate the types of UGC feeds that are available to your title, call SenUGCEnumerateFeeds.
  2. To subscribe to specific types of feeds, call SenUGCGetFeed.

The types of feeds currently supported include:

  • Newest Items
  • Top Reviewed
  • Top Downloaded
  • Pending Moderator Review

For more information, see SenUGCFeedType.

Enumerating and Downloading UGC Content

To retrieve UGC content, you can either enumerate them directly or subscribe to feeds.

  1. To get the list of available UGC items, call SenUGCEnumerate.
  2. To download the metadata for the UGC item, call SenUGCDownloadMetaData. Typically, this data displayed to players to select UGC items. After players select a UGC item, then you download the content.
  3. To download the UGC item, call SenUGCDownloadMainDataBlob.
Reviewing and Rating UGC Content

Players can rate UGC items or flag them as their favorite. They can also retrieve their ratings or review their friends favorites.

To rate or flag a UGC items:

  • Call SenUGCSetReviewScore.
  • Call SenUGCSetFavoriteFlag.

To retrieve review scores:

  • Call SenUGCGetReviewScore to retrieve the players review score.
  • Call SenUGCGetFavoriteFlag to retrieve whether the player flagged a UGC item as a favorite.
  • Call SenUGCGetFriendFavoriteCount. to retrieve the number of friends that flagged a UGC item as their favorite.
Revoking UGC Content

Players can flag UGC content as offensive or check whether a UGC item has been banned.

To flag offensive content with a reason phrase:

  • Call SenUGCSetOffensivenessFlag.

To check whether content has been banned:

  • Call SenUGCIsBanned. Banned content should not be displayed to players.

When enough people flag content, a moderator (or moderator engine) can remove it from the published list. For more information, see Managing User Generated Content.


UGC Publish States

The publish state is set to various states when you create, upload and publish UGC items. These are defined in the SenUGCPublishState enumeration.

The sequence for uploading and publishing UGC items is shown below:

  1. First create the UGC ID in the call to SenUGCCreatePublishingUGCID and then call SenUGCUpload to upload the content to the Sentient servers. When you upload UGC content the publish state is set to SenUGCPublishState_Unpublished.
  2. The publish state remains unpublished until you call SenUGCPublish which sets the publish state to SenUGCPublishState_Published.

When you publish UGC content, it is visible to other players through enumerations and feeds.

Both players and community moderators can flag UGC items as inappropriate which changes the publish state to either "Pending Moderation" or "Banned." To flag UGC items:

  1. Players can flag content as offensive in the call to SenUGCSetOffensivenessFlag for various reasons. If several players flag a UGC item as offensive, the Sentient Moderation Engine sets the state to SenUGCPublishState_PendingModeratorReview.
  2. Moderators can also review content and immediately set the published state to SenUGCPublishState_PendingModeratorReview in the call to SenUGCSetOffensivenessFlag.
  3. A Moderator with Instaban privilege can instantly ban content by calling SenUGCSetOffensivenessFlag with any member of the SenUGCOffensivenessFlag enumeration other than none. The publish state then move to SenUGCPublishState_Banned.
  4. Titles should call SenUGCIsBanned to determine whether a UGC item has been banned before displaying content to players.

Only the user that created the UGC item can delete it in the call to SenUGCDelete.

Below is the Sentient Publish State diagram:

Moderators with Community Moderator Privilege

Titles grant community moderators privileges to monitor published UGC items. Moderators can either set UGC items to "Pending Moderation" or ban them outright. For more information, see Moderating User Generated Content.

Moderator Engine

Every time a player flags a UGC item, Sentient performs moderation analysis of the content. If the content is deemed offensive, Sentient sets the published state to banned. If enough players flag a content, the moderation engine may set it to pending moderator review based on the trust of the users that rated the content. For more information, see The Sentient Moderation Engine.


Managing User Generated Content

Because UGC items are created by the community, producers should assign monitors from their team or the community to screen content regularly for appropriateness. You can give moderators permission to either instantly ban content or set it to “Pending Moderation” for future review. The Sentient Moderation Engine evaluates feedback from the player community and flags content for moderator review; however, ultimately only community moderators can ban content.

The following sections contains information on moderating UGC content.

For more information on sending player feedback to the Sentient Moderation Engine, see: The Sentient Moderation.

For more information on setting community moderators flags, see: Moderating User Generated Content .

To manage content that has been flagged, see Managing Flagged Content.

After the moderators or players flag content, the publish states change to either “Pending Moderation” or “Banned.” For more information, see UGC Publish States.


The Sentient Moderation Engine

The Sentient Moderation Engine evaluates content flagged as offensive from the player community. Players can flag inappropriate content and give one of the following reasons:

  • Discriminating
  • Explicit
  • Obscene
  • Foul Language
  • License Infringement
  • Illegal Advertising
  • Illegal

Offensiveness flags set by moderators bypass the Moderation Engine and immediately set the publish state to "Pending Moderation." For more information, see Moderating User Generated Content.

When players identify inappropriate content, titles send the UGC ID and offensiveness flag to Sentient in the call to SenUGCSetOffensivenessFlag.

Note: Sentient ignores a "None" offensiveness flag in this call unless the specified user has moderator privileges.

Trust Level and the Flag Threshold

Sentient aggregates all the player flags for a UGC item and sets the published state to "Pending Moderation" if enough players flag it. The Moderation Engine’s analysis is based on the players trust level and the UGC threshold. Players start with a default trust rating of 20 which changes over time as follows:

  • If a player flags content that is ultimately banned, his or her trust level increases. Over time, players who benefit the community will be more trusted and have a greater impact on removing content quickly.
  • If a player flags content which subsequently returns to the published state, their trust level goes down. Over time, players who repeatedly complain for no reason have little or no impact on whether content is removed.

Sentient uses a threshold player score of 100 to flag a UGC as "Pending Moderation." For example, if 5 players with the default trust level of 20 flag a UGC, the aggregate score of all 5 players is 100 which is enough to set the content into the "Pending" state. Moderators then review all pending UGC items via the moderator feed and determine whether to republish or ban the content. Note that only moderators can ban UGC items, the moderation engine only flags content for moderation.

Sentient Player Trust Calculation

When players review content, they start with a default trust level of 20 which increases or decreases based on their number of hits and misses. Sentient calculates player trust as follows:

    Differential  = Reviewer Hits – Reviewer Misses
    if (Differential > 0)
          Trust = IUW + WI * (WE^Differential)

    else
          Trust = IUW – WD * (WE^Differential)

Where:

    IUW:  Initial User Weight (default = 20)
    WI:   Weight Increment    (default = 2)
    WD:   Weight Decrement    (default = 2)
    WE:   Weight Exponent     (default = 2)

For example if a player has three hits and no misses, then the player's trust calculation is:

    Differential = 3 – 0 = 3
    Trust = 20 + 2 * (2^3) = 20 + 16 = 36

At this trust level, it may only take two or three players to flag an offensive UGC.


Moderating User Generated Content

Moderators are typically users that examine UGC items on a regular basis and determine if they are appropriate for publication. Moderators as well as players in the community can flag content as inappropriate for any of the following reasons:

  • Discriminating
  • Explicit
  • Obscene
  • Foul Language
  • License Infringement
  • Illegal Advertising
  • Illegal

Moderators and players can only evaluate content that is in the published state. While player flags are handled by the Sentient Moderation Engine, moderator flags bypass the Moderation Engine and immediately set the publish state to “Pending Moderation.” Ultimately moderators are responsible for banning content regardless of whether the player community flagged it. For more information on the how Sentient evaluates flags from the player community, see The Sentient Moderation Engine.

Moderators can instantly ban a UGC item or set it to "Pending Moderation" based on their privilege level as follows:

  • Default Moderator: Can put UGC items into the "Pending Moderation" state or republish pending content.
  • InstaBan Moderator: Always bans UGC items regardless of the current state.

When an InstaBan Moderators flags a published UGC for any reason, it is immediately put into the "Banned" state. When a Default Moderator flags a published UGC, it is placed into the "Pending Moderation" state.

Setting Moderation Flags

Either the player community or a moderator can place a UGC item into the "Pending Moderation" state, however, only moderators can ban content. Moderators receive a special feed to review UGC items that are in the "Pending Moderation" state and then determine whether to ban or republish these UGCs.

To moderate content:

  • Call SenUGCSetOffensivenessFlag with the ID of a user that has moderator privileges and specify one of the SenUGCOffensivenessFlag enumeration types.

The "None" offensiveness flag is reserved for moderators to republish content in the "Pending Moderation" state. The table below specifies the state changes that transpire when moderators specify the various offensiveness flags in the call to SenUGCSetOffensivenessFlag.

Player Privilege | Flag | State: Published | State: Pending Moderation
Moderator | Any flag (except None) | Pending Moderation | Ban
InstaBan Moderator | Any flag (except None) | Ban | Ban
Moderator | None flag | Does nothing | Published
InstaBan Moderator | None flag | Does nothing | Ban

As shown in the table:

  • Default Moderators calling SenUGCSetOffensivenessFlag with any SenUGCOffensivenessFlag other than the None sets it to "Pending Moderation."
  • Default Moderators can republish a UGC by calling SenUGCSetOffensivenessFlag with a None SenUGCOffensivenessFlag.
  • InstaBan Moderators calling SenUGCSetOffensivenessFlag on an "Pending Moderation" UGC with any SenUGCOffensivenessFlag sets it to banned.

Banned content is removed from feeds and search results so that it is no longer available to players. For more information on how to manage banned or content awaiting moderation in the UI, see Managing Flagged Content. For more information on the state transitions, see UGC Publish States.

Moderator Feeds

To get the Moderator feed:

  • Call SenUGCGetFeed with the userIndex of the Moderator and the feedType set to SenUGCFeedType_PendingModeratorReview.

This call returns the collection of SenUGCFeedItem structures with the UGC IDs that are currently waiting for review.

Specifying Moderators

Moderators are responsible for reviewing content in a timely manner. Typically moderators are employed by the creator of the title, however you may want to grant privileges to players in the community. As an incentive, you could grant special awards to community moderators such as special avatar costumes or give them recognition in the community by highlighting them in the UI.

To specify moderators for your title, contact the Sentient team (senhelp@microsoft.com) with the moderator’s user ID and privilege level.


Managing Flagged Content

Sentient removes content awaiting moderation and banned UGC items from feeds or search results, however, players may have previously downloaded a UGC item that was subsequently banned or set as "Pending Moderation." Therefore, before you load a UGC item, check whether it has been banned by calling SenUGCIsBanned. Titles should decide what action to take when players try to load content that has been banned. The Sentient team recommends that you delete banned content from the disk. If content is in the "Pending Moderation" state, then you should decide whether to delete it or display a message to the player.

Moderators have a special feed to review content awaiting moderation and to determine whether to republish or ban these items.

To get the Moderator feed:

  • Call SenUGCGetFeed with the userIndex set to the ID of the Moderator and the feedType set to SenUGCFeedType_PendingModeratorReview.

This call returns the collection of SenUGCFeedItem structures with the UGCs that are currently waiting for review.

Only the user that created the UGC item can delete it from the Sentient servers. To delete content, titles call SenUGCDelete with the userIndex of the owner of the content. Deleted content is removed from feeds, and the Sentient team recommends that you also remove deleted content from the disk when players try to load it.


UGC Reference

This section contains reference information for the Microsoft Sentient APIs.

In This Section

  • UGC Functions
  • UGC Structures
  • UGC Enumerations
  • UGC Types


UGC Functions

This section contains API reference functions that you use with the Microsoft Sentient APIs.

In This Section

Create, Upload and Publish Functions
Function | Description
SenUGCCreatePublishingUGCID | Generates a unique ID that is used to identify a UGC item. This identifier is unique across all titles.
SenUGCUpload | Uploads the UGC metadata and one or more binary UGC data blobs to the Sentient server.
SenUGCPublish | Publishes a UGC and makes the content accessible to players in the title associated with the UGC.
SenUGCDelete | Marks the specified UGC item as deleted.
Enumerate and Download Functions
Function | Description
SenUGCEnumerate | Searches the database for all of the UGC items that match various search criteria.
SenUGCEnumerate (overloaded) | Searches the database for all of the UGC items that match various search criteria.
SenUGCDownloadMetaData | Downloads the metadata for an array of UGC items.
SenUGCDownloadMainDataBlob | Downloads one of the main data blobs for the specified UGC item.
Feeds Functions
Function | Description
SenUGCEnumerateFeeds | Returns a collection of the types of feeds available for download by the specified user and title.
SenUGCGetFeed | Returns a collection of the types of feeds that are available for download by the specified user and title.
Review and Rate Functions
Function | Description
SenUGCSetReviewScore | Sets a review score for a UGC item.
SenUGCSetFavoriteFlag | Allows players to flag their favorite UGC items for a specific title.
SenUGCGetReviewScore | Retrieves the players review score for the specified UGC item.
SenUGCGetFavoriteFlag | Retrieves whether the player flagged the specified UGC item as a favorite.
SenUGCGetFriendFavoriteCount | Retrieves the number of friends that flagged this UGC item as a favorite.
SenUGCAddToCustomCounters | Creates custom counters to record game play statistics.
Revocation Functions
Function | Description
SenUGCSetOffensivenessFlag | Flags the specified UGC as offensive.
SenUGCIsBanned | Returns whether the specified UGC has been banned.


SenUGCCreatePublishingUGCID Function

Generates a unique ID that is used to identify a UGC item. This identifier is unique across all titles.

Syntax

C ++
HRESULT SenUGCCreatePublishingUGCID(
   int userIndex,
   SenUGCID *outResult,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

outResult

[out] A pointer to a SenUGCID that will contain the unique identifier of the UGC item after Sentient invokes the callback associated with this call.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

E_POINTER

The outResult pointer is NULL.

SENTIENT_E_NO_UGC_PUBLISH_PRIVILEGE

The user does not have UGC publish privilege.

Remarks

All UGC identifiers must be generated and provisioned by Sentient before they can be used by other UGC functions. The UGC ID returned from this function is used in the UGC upload, download and rating functions and structures.

The user that initiated this call, the owner of the UGC item, also has the authority to delete it (see SenUGCDelete).

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCPublish

SenUGCUpload

SenUGCDelete


SenUGCUpload Function

Uploads the UGC metadata and one or more binary UGC data blobs to the Sentient server.

Syntax

C ++
HRESULT SenUGCUpload(
   int userIndex,
   SenUGCID ugcID,
   const SenUGCMetaData *metaData,
   int nrMainDataBlobs,
   const void **mainDataBlobs,
   const size_t *mainDataBlobSizes,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is NOT a XUID.

ugcID

[in] A SenUGCID that identifies the UGC item. This ID is created in the call to SenUGCCreatePublishingUGCID.

metaData

[in] A pointer to the SenUGCMetaData structure that contains the metadata associated with the UGC item.

nrMainDataBlobs

[in] The number of data blobs pointed to by the mainDataBlobs parameter. The maximum number of data blobs is defined by the SenUGCMainData_NrBlobs flag.

mainDataBlobs

[in] A pointer to a collection of main data blobs that contain the UGC content. This parameter is optional and may be NULL (see Remarks).

mainDataBlobSizes

[in] A pointer to the size, in bytes, of the collection of main data blobs.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_E_NO_UGC_PUBLISH_PRIVILEGE

The user does not have UGC publish privilege.

Remarks

Titles may upload up to 4 main data blobs for a UGC item. For example, you can store a preview thumbnail of the content in the metadata blob that can be downloaded as a preview before downloading the large main data blob.

Typically titles download the metadata for several UGC items to populate a UGC menu. Therefore, you should keep the metadata blob size to a minimum.

To modify the metadata of an existing UGC item, call this function with the new metadata structure and set the mainDataBlobs parameter to NULL. Metadata can be modified when the published state is either "unpublished" or "published."

To prevent confusion over reviewer ratings, the main data blob can only be modified when it is in the unpublished state. To modify the main data blob, call this function with the new data blobs and set the metadata set to NULL. For example, if you call this function with three data blobs in the mainDataBlobs parameter, it will overwrite the first three existing data blobs.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCCreatePublishingUGCID

SenUGCPublish

SenUGCDelete


SenUGCPublish Function

Publishes the UGC and makes the content accessible to players in the title associated with the UGC.

Syntax

C ++
HRESULT SenUGCPublish(
   int userIndex,
   SenUGCID ugcID,
   const SenLeaderboardDefinition *leaderboardDefinition,
   SenLeaderboardId *out_leaderboardId,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

ugcID

[in] A SenUGCID that uniquely identifies a UGC. This ID is created in the call to SenUGCCreatePublishingUGCID.

leaderboardDefinition

[in] (optional) A SenLeaderboardDefinition that uniquely defines the leaderboard that is created and associated with this UGC item. This parameter is optional and can be set to NULL.

out_leaderboardId

[out] A SenLeaderboardId that uniquely identifies the leaderboard that is created for the leaderboard definition. This parameter returns zero if the leaderboard definition is not supplied.

This parameter is optional and may be set to NULL. For more information, see the Remarks section.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_E_NO_UGC_PUBLISH_PRIVILEGE

The user does not have UGC publish privilege.

E_INVALIDARG

When the leaderboard definition is supplied in this call, the out_leaderboardId parameter may not be NULL.

Remarks

When you upload a UGC item to the Sentient server, it is only accessible to the author until it is published. The user specified in this call must be the author of the UGC item. When you call this function with a leaderboard definition, Sentient creates and allocates the leaderboard associated with the UGC item. This function is the only way to create UGC leaderboards; you cannot create UGC leaderboards by calling SenCreateLeaderboard. Note that a UGC item may only be associated with one leaderboard.

This function optionally creates a leaderboard. When you call SenUGCPublish with:

  1. A valid out_leaderboardId pointer and also supply a leaderboardDefintion, it creates a new leaderboard and returns a pointer to the leaderboard ID in out_leaderboardId.
  2. A NULL out_leaderboardId and a NULL leaderboardDefintion, it will not create a leaderboard and out_leaderboardId returns zero.

Note: These are the only two supported scenarios; any other combination will return an error.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCCreatePublishingUGCID

SenUGCUpload

SenUGCDelete


SenUGCDelete Function

Marks the specified UGC item as deleted.

Syntax

C ++
HRESULT SenUGCDelete(
   int userIndex,
   SenUGCID ugcID,
   SenSysCompletedCallback userCallback,
   void* userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is NOT a XUID.

ugcID

[in] A SenUGCID that identifies the UGC item. This ID is created in the call to SenUGCCreatePublishingUGCID.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackdata

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

Remarks

Only the user that created the UGC can delete it.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCCreatePublishingUGCID

SenUGCGUpload

SenUGCPublish


SenUGCEnumerate Function

Searches the database for all of the UGC items that match various search criteria.

Syntax

C ++
HRESULT SenUGCEnumerate(
   int userIndex,
   SenSysTitleID titleID,
   SenUGCSortBy sortBy,
   SenUGCType type,
   SenUGCAuthorType authorType,
   int nrAuthors,
   const XUID *authorList,
   SenUGCMetaDataFlags metaDataFlagFilter,
   SYSTEMTIME *newerThan,
   SenUGCDescriptor descriptor,
   int maxNrResults,
   SenUGCSearchResult *outBuffer,
   unsigned int *outNrResults,
   SenSysCompletedCallback userCallback,
   void* userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is NOT a XUID.

titleID

[in] A SenSysTitleID that defines the title to search for. Internally, Sentient assigns a title identifier to each title that is within the 32 bit range specified by the SenSysTitleID enumeration.

sortBy

[in] A member of the SenUGCSortBy enumeration that defines how to sort the returned items.

type

[in] A member of the SenUGCType enumeration that defines the type of item to search for.

authorType

[in] A member of the SenUGCAuthorType enumeration that defines the types of authors to search for. When the author type is list, the nAuthors and authorList parameters must contain the number of authors and the list of authors.

nrAuthors

[in] The number of authors to search on. This parameter is optional and may be 0.

authorList

[in] A pointer to a list of XUIDS of the author(s) to search for. This parameter is optional and may be NULL.

metaDataFlagFilter

[in] A member of the SenUGCMetaDataFlags enumeration that defines the metadata flags to filter the search on. This parameter is optional and may be 0.

newerThan

[in] A pointer to a SYSTEMTIME structure that defines the earliest time to search for UGC items. This parameter is optional and may be NULL.

descriptor

[in] A SenUGCDescriptor that identifies the UGC item. This parameter is optional and may be 0.

maxNrResults

[in] The maximum number of search results to return.

outBuffer

[out] A pointer to a collection of SenUGCSearchResult structures that will contain the returned UGC items after Sentient invokes the callback.

This should be a pre-allocated array which is maxNrResults*(sizeof)SenUGCSearchResult bytes.

outNrResults

[out] A pointer that will contain the number of returned UGC items after Sentient invokes the callback.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackdata

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

E_INVALIDARG

The authorType is not known.

The authorType SenUGCAuthorType_List requires a valid authorList.

An authorList is not supported for authorType SenUGCAuthorType_Friends or SenUGCAuthorType_LocalUsers.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

E_POINTER

The outBuffer or outNrResults pointer is NULL.

SENTIENT_E_NO_UGC_PUBLISH_PRIVILEGE

The user does not have UGC publish privilege.

E_INVALIDARG

The authorType is not known.

The authorType SenUGCAuthorType_List requires a valid authorList.

An authorList is not supported for authorType SenUGCAuthorType_Friends SenUGCAuthorType_LocalUsers or SenUGCAuthorType_LocalUsers.

Remarks

This function searches the database for all the UGC items that match various search criteria. The search criteria parameters (type, authorList, metaDataFlags, newerThan, and descriptor) are all logically ANDed together to filter the returned results.

When you upload your UGC item with SenUGCUpload, you can specify custom metadata and descriptor flags to search for UGC items. For more information, see SenUGCDescriptor and SenUGCMetaDataFlags.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCEnumerate

SenUGCDownloadMainDataBlob

SenUGCDownloadMetaData


SenUGCEnumerate Function (overloaded)

Searches the database for all of the UGC items that match various search criteria.

Syntax

C ++
HRESULT SenUGCEnumerate(
   int userIndex,
   SenSysTitleID titleID,
   SenUGCType type,
   SenUGCAuthorType authorType,
   int nrAuthors,
   const XUID *authorList,
   const wchar_t *name,
   int maxNrResults,
   SenUGCSearchResult *outBuffer,
   unsigned int *outNrResults,
   SenSysCompletedCallback userCallback,
   void* userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is NOT a XUID.

titleID

[in] A SenSysTitleID that defines the title to search for. Internally, Sentient assigns a title identifier to each title that is within the 32 bit range specified by the SenSysTitleID enumeration.

type

[in] A member of the SenUGCType enumeration that defines the type of item to search for.

authorType

[in] A member of the SenUGCAuthorType enumeration that defines the types of authors to search for. When the author type is list, the nAuthors and authorList parameters must contain the number of authors and the list of authors.

nrAuthors

[in] The number of authors to search on. This parameter is optional and may be 0.

authorList

[in] A pointer to a list of XUIDS of the author(s) to search for. This parameter is optional and may be NULL.

name

[in] A pointer to the UGC item name to search for. By default, Sentient searches for UGC items with this string anywhere in the name (see Remarks).

maxNrResults

[in] The maximum number of search results to return.

outBuffer

[out] A pointer to a collection of SenUGCSearchResult structures that will contain the returned UGC items after Sentient invokes the callback.

This should be a pre-allocated array which is maxNrResults*(sizeof)SenUGCSearchResult bytes.

outNrResults

[out] A pointer that will contain the number of returned UGC items after Sentient invokes the callback.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackdata

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

E_POINTER

The outBuffer or outNrResults pointer is NULL.

E_INVALIDARG

The authorType SenUGCAuthorType_Everyone is not supported.

The authorType is not known.

The authorType SenUGCAuthorType_List requires a valid authorList.

An authorList is not supported for authorType SenUGCAuthorType_Friends or SenUGCAuthorType_LocalUsers.

SENTIENT_E_NO_UGC_PUBLISH_PRIVILEGE

The user does not have UGC publish privilege.

Remarks

This function searches the database for all the UGC items that match the various search criteria. The search criteria parameters (type, authorList, and name) are all logically ANDed together to filter the returned results.

Note: This function does not support SenUGCAuthorType_Everyone in the authorType parameter.

When you search using the name parameter, Sentient performs a wildcard search on the supplied name. For example, consider the following three UGC items:

  • MyName1
  • MyName2
  • MyName3

When you search on "MyName," Sentient returns all three items. When you search on "Name3," only the third item is returned.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCEnumerate

SenUGCDownloadMainDataBlob

SenUGCDownloadMetaData


SenUGCDownloadMetaData Function

Downloads the metadata for an array of UGC items.

Syntax

C ++
HRESULT SenUGCDownloadMetaData(
   int userIndex,
   SenSysTitleID titleID,
   int nrUGCs,
   const SenUGCID *ugcIDList,
   SenUGCDownloadedMetaData *out_metaData,
   size_t *out_metaDataCount,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is NOT a XUID.

titleID

[in] A SenSysTitleID that defines the title to search for. Internally, Sentient assigns a title identifier to each title that is within the 32 bit range specified by the SenSysTitleID enumeration.

nrUGCs

[in] The number of UGC items in ugcIDList.

ugcIDList

[in] A pointer to a list of SenUGCID identifiers that define the UGC metadata items to return.

out_metaData

[out] A pointer to the collection of SenUGCDownloadedMetaData structures that will contain the metadata of the specified UGC items after Sentient invokes the callback.

This should be a pre-allocated array which is nUGCs*sizeof(SenUGCDownloadedMetaData + SenUGCMetaData::BlobSizeLimit) bytes.

out_metaDataCount

[out] A pointer to the size, in bytes, of the out_metaData parameter.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackdata

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

E_POINTER

The out_MetaData or out_metadataCount pointer is NULL.

SENTIENT_E_NO_UGC_USE_PRIVILEGE

The user does not have UGC use privilege.

Remarks

Typically, titles download the metadata blob and display attributes of the UGC item, and then download the UGC data blob only after the player selects it. The data blobs are large and should not be downloaded randomly.

Note that the returned metadata structure is a superset of the metadata uploaded in the call to SenUGCUpload.

A UGC item may have up to 4 data blobs but only 1 set of metadata.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCDownloadMainDataBlob

SenUGCEnumerate


SenUGCDownloadMainDataBlob Function

Downloads one of the main data blobs for the specified UGC item.

Syntax

C ++
HRESULT SenUGCDownloadMainDataBlob(
   int userIndex,
   SenSysTitleID titleID,
   SenUGCID ugcID,
   int mainDataBlobID,
   size_t bufferSize,
   void *outBuffer,
   size_t *outSize,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is NOT a XUID.

titleID

[in] A SenSysTitleID that defines the title to search for.

Internally, Sentient assigns a title identifier to each title that is within the 32 bit range specified by the SenSysTitleID enumeration.

ugcID

[in] A SenUGCID that identifies the UGC item to return. This ID is created in the call to SenUGCCreatePublishingUGCID.

mainDataBlobID

[in] The index of the data blob to retrieve.

The maximum number of data blobs associated with a UGC item is defined by SenUGCMainData_NrBlobs as 4.

This number comes from the SenUGCDownloadedMetaData structure that was previously downloaded from SenUGCDownloadMetaData function.

bufferSize

[in] The size, in bytes, of the buffer that receives the metadata blob.

This size is (sizeof)(SenUGCDownloadedMetaData ::mainDataSizes[SenUGCMainData_NrBlobs]) bytes.

outBuffer

[in] A pointer to the buffer that will contain the metadata blob after the Sentient invokes the callback.

The is a pre-allocated buffer which should be bufferSize bytes.

outSize

[in] The size, in bytes, of the returned data blob.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackdata

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

The download to outBuffer contained zero bytes.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

E_POINTER

The outBuffer or outSize pointer is NULL.

SENTIENT_E_NO_UGC_USE_PRIVILEGE

The user does not have UGC use privilege.

Remarks

Typically, titles download the metadata blob and display attributes of the UGC, and then download the UGC data blob only after the player selects it.

Before you call this function, you must call SenUGCDownloadMetaData to retrieve the SenUGCDownloadedMetaData structure for the UGC item. Titles can upload as many as 4 different data blobs for a UGC item. You can retrieve the size of the data blob from the mainDataSizes[SenUGCMainData_NrBlobs] member of SenUGCDownloadedMetaData.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCDownloadMetaData

SenUGCEnumerate


SenUGCEnumerateFeeds Function

Returns a collection of the types of feeds that are available for download by the specified user and title.

Syntax

C ++
HRESULT SenUGCEnumerateFeeds(
   int userIndex,
   size_t maxResults,
   SenUGCFeedInfo *out_feedInfo,
   size_t *out_resultCount,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is NOT a XUID.

maxResults

[in] The maximum number of items that can be returned in the out_feedInfo parameter. If the number of items available exceeds this number, this function returns an error. The maximum number of feed types supported is defined in the SenUGCFeedType enumeration.

out_feedInfo

[out] A pointer to SenUGCFeedInfo structure that will contain a collection of the types of UGC available after the callback function returns successfully.

out_resultCount

[out] The number of SenUGCFeedInfo structures returned by this call.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackdata

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

E_POINTER

The out_feedInfo or out_resultCount pointer is NULL.

SENTIENT_E_NO_UGC_USE_PRIVILEGE

The user does not have UGC use privilege.

Remarks

To get the list of the types of feeds available for a title, titles call SenEnumerateFeeds.

Titles call SenUGCGetFeed to get a list of UGC items for a specific feed type. Sentient limits the number of UGC items returned by SenUGCGetFeed to 100.

Sentient may dynamically add new feeds or feed items to an existing feed at any time. Call this function at regular intervals to determine if new feeds are available.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCGetFeed


SenUGCGetFeed Function

Retrieves the list of feed items for the specified type of feed and title.

Syntax

C ++
HRESULT SenUGCGetFeed(
   int userIndex,
   SenSysTitleID titleID,
   SenUGCFeedType feedType,
   size_t maxNumberOfFeedItems,
   SenUGCFeedItem *out_buffer,
   unsigned int *out_buffersize,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

titleID

[in] A SenSysTitleID that uniquely identifies an Xbox LIVE title. Internally, Sentient assigns a title identifier to each title that is within the 32 bit range specified by the SenSysTitleID enumeration.

feedType

[in] A member of the SenUGCFeedType enumeration that identifies the type of feed items returned by this function.

maxNumberOfFeedItems

[in] The maximum number of items that can be returned in the out_buffer parameter. If the number of items available exceeds this number, this function returns an error.

out_buffer

[out] A pointer to a collection of SenUGCFeedItem structures that will contain the UGC items after the callback function returns successfully.

out_buffersize

[out] The number of SenUGCFeedItem structures returned by this call.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

E_POINTER

The out_buffer or out_buffersize pointer is NULL.

SENTIENT_E_NO_UGC_USE_PRIVILEGE

The user does not have UGC use privilege.

Remarks

To get the list of the types of feeds available for a title, titles call SenEnumerateFeeds.

Titles call SenUGCGetFeed to get a list of UGC items for a specific type of feed. Sentient limits the number of UGC items returned by SenUGCGetFeed to 100. Sentient sorts the returned UGC items, for example, by date in the newest items feed.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCEnumerateFeeds


SenUGCSetReviewScore Function

Sets a review score for the specified UGC item.

Syntax

C ++
HRESULT SenUGCSetReviewScore(
   int userIndex,
   SenUGCID ugcId,
   SenUGCReviewScoreType type,
   unsigned int score,
   bool isFavorite,
   SenSysCompletedCallback callback,
   void *callbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is NOT a XUID.

ugcID

[in] A SenUGCID that identifies the UGC item to rate.

type

[in] A member of the SenUGCReviewScoreType that identifies the type of review to set.

score

[in] The rating for this UGC item based on the type of review.

isFavorite

[in] true, if this is a favorite; otherwise false.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackdata

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_E_NO_UGC_USE_PRIVILEGE

The user does not have UGC use privilege.

Remarks

To retrieve review scores set by this function, call SenUGGetReviewScore.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCGetReviewScore

SenUGCSetFavoriteFlag

SenUGCGetFavoriteFlag

SenuUGCGetFriendsFavoriteCount


SenUGCSetFavoriteFlag Function

Allows players to flag their favorite UGC items for a specific title.

Syntax

C ++
HRESULT SenUGCSetFavoriteFlag(
   int userIndex,
   SenSysTitleID titleID,
   SenUGCID ugcID,
   BOOL isFavorite,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is NOT a XUID.

titleID

[in] A SenSysTitleID that identifies the title associated with this UGC item. Internally, Sentient assigns a title identifier to each title that is within the 32 bit range specified by the SenSysTitleID enumeration.

ugcID

[in] A SenUGCID that identifies the UGC item to set as a favorite.

isFavorite

[in] true, if this is a favorite of the specified player; otherwise false.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackdata

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

TBD

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION*

A guest and may not spawn this call.

SENTIENT_E_NO_UGC_USE_PRIVILEGE

The user does not have UGC use privilege.

Remarks

You can search for favorites by calling SenUGCGetFavoriteFlag or SenuUGCGetFriendsFavoriteCount.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCGetFavoriteFlag

SenuUGCGetFriendsFavoriteCount

SenUGCSetReviewScore

SenUGCGetReviewScore


SenUGCGetReviewScore Function

Retrieves the players review score for the specified UGC item.

Syntax

C ++
HRESULT SenUGCGetReviewScore(
   int userIndex,
   SenUGCID ugcId,
   SenUGCReviewScoreType type,
   unsigned int *out_score,
   SenSysCompletedCallback callback,
   void *callbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is NOT a XUID.

ugcID

[in] A SenUGCID that identifies the UGC item to rate.

type

[in] A member of the SenUGCReviewScoreType that identifies the type of review to retrieve.

out_score

[in] A pointer to the specified player's rating for this UGC item. This is the score previously set in the call to SenUGSetReviewScore.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackdata

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

E_POINTER

The out_score pointer is NULL.

SENTIENT_E_NO_UGC_USE_PRIVILEGE

The user does not have UGC use privilege.

Remarks

To set the review scores retrieved by this function, call SenUGSetReviewScore.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCSetReviewScore

SenUGCSetFavoriteFlag

SenUGCGetFavoriteFlag

SenUGCGetFriendFavoriteCount


SenUGCGetFavoriteFlag Function

Retrieves whether the player flagged the specified UGC item as a favorite.

Syntax

C ++
HRESULT SenUGCGetFavoriteFlag(
   int userIndex,
   SenSysTitleID titleID,
   SenUGCID ugcID,
   BOOL *outResult,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is NOT a XUID.

titleID

[in] A SenSysTitleID that identifies the title associated with this UGC item. Internally, Sentient assigns a title identifier to each title that is within the 32 bit range specified by the SenSysTitleID enumeration.

ugcID

[in] A SenUGCID that identifies the UGC item to return the favorite flag for.

outResult

[in] true, if this UGC item is a favorite of the specified player; otherwise false.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackdata

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

E_POINTER

The outResult pointer is NULL.

SENTIENT_E_NO_UGC_USE_PRIVILEGE

The user does not have UGC use privilege.

Remarks

You set the favorite flag for a player using SenUGCSetFavoriteFlag. You can search for friends' favorites with SenUGCGetFriendFavoriteCount.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCSetFavoriteFlag

SenUGCSetReviewScore

SenUGCGetReviewScore

SenUGCGetFriendFavoriteCount


SenUGCGetFriendFavoriteCount Function

Retrieves the number of friends that flagged the specified UGC item as a favorite.

Syntax

C ++
HRESULT SenUGCGetFriendFavoriteCount(
   int userIndex,
   SenSysTitleID titleID,
   SenUGCID ugcID,
   int *outResult,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is NOT a XUID.

titleID

[in] A SenSysTitleID that identifies the title associated with this UGC item. Internally, Sentient assigns a title identifier to each title that is within the 32 bit range specified by the SenSysTitleID enumeration.

ugcID

[in] A SenUGCID that identifies the UGC item to retrieve the favorite count for.

outResult

[in] A pointer to the number of Xbox LIVE friends who flagged this UGC item as a favorite. The number also includes the player's favorite flag.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackdata

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

E_POINTER

The outResult pointer is NULL.

SENTIENT_E_NO_UGC_USE_PRIVILEGE

The user does not have UGC use privilege.

Remarks

The returned favorite count (in outResult) also includes the players favorite flag, if set.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCSetFavoriteFlag

SenUGCGetFavoriteFlag

SenUGCSetReviewScore

SenUGCGetReviewScore


SenUGCAddToCustomCounters Function

Creates custom counters to record game play statistics.

Syntax

C ++
HRESULT SenUGCAddToCustomCounters(
   int userIndex,
   SenSysTitleID titleID,
   SenUGCID ugcID,
   INT64 customCounters[SenUGCDownloadedMetaData_NrCustomCounters],
   SenSysCompletedCallback userCallback,
   void* userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is NOT a XUID.

titleID

[in] A SenSysTitleID that identifies the title associated with this UGC item. Internally, Sentient assigns a title identifier to each title that is within the 32 bit range specified by the SenSysTitleID enumeration.

ugcID

[in] A SenUGCID that identifies the UGC item to add custom counters to.

customCounters

[in] The custom counters for this UGC item. A maximum of 4 custom counters may be added as defined by SenUGCDownloadedMetaData_NrCustomCounters.

Titles retrieve custom counters in the SenUGCDownloadedMetaData structure in the call to SenUGCDownloadMetaData.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackdata

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_E_NO_UGC_USE_PRIVILEGE

The user does not have UGC use privilege.

Remarks

Titles can define up to SenUGCDownloadedMetaData_NrCustomCounters counters to store statistics such as number of enemies killed or total playtime on the Sentient servers. You can retrieve custom counters in the SenUGCDownloadedMetaData structure in the call to SenUGCDownloadMetaData.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference


SenUGCSetOffensivenessFlag Function

Flags the specified UGC as offensive.

Syntax

C ++
HRESULT SenUGCSetOffensivenessFlag(
   int userIndex,
   SenUGCID ugcID,
   SenUGCOffensivenessFlag offensivenessFlag,
   const wchar_t *reason,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

ugcID

[in] A SenUGCID that uniquely identifies a UGC.

offensivenessFlag

[in] A member of the SenUGCOffensivenessFlag enumeration member that defines the type of offensiveness.

reason

[in] A string that contains the reason for the offensiveness flag.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_E_NO_UGC_USE_PRIVILEGE

The user does not have UGC use privilege.

Remarks

Using this function, players can flag a UGC item that they consider offensive. After enough players tag an item as offensive, either Sentient or the moderators will remove the item from publication. Moderators review the offensiveness statistics collected by Sentient to confirm or deny that an item is offensive. Internally, Sentient considers the following criteria to determine whether to remove offensive items:

  • The number of votes.
  • The reliability of the reviewer. Review reliability is based on statistics such as the number of offensiveness flags and the number of downloads for the reviewer.
  • The number of offensive uploads by the creator

The SenUGCOffensivenessFlag_None should only be used by moderators to reset the publish state from "Awaiting Moderator Review" back to "Published;" players should not use this flag.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCIsBanned


SenUGCIsBanned Function

Returns whether the specified UGC item has been banned.

Syntax

C ++
HRESULT SenUGCIsBanned(
   int userIndex,
   SenUGCID ugcID,
   BOOL *out_result,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

ugcID

[in] A SenUGCID that uniquely identifies a UGC.

out_result

[out] true if the content is banned; otherwise false.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

E_POINTER

The out_result pointer is NULL.

Remarks

When enough players flag a UGC item as offensive, a moderator (or moderator engine) can ban the content. Banned content should not be presented to players for viewing. Sentient provides a moderator feed to monitor UGC items that players have identified as offensive. For more information, see SenUGCFeedType and SenUGCEnumerateFeeds.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCCreatePublishingUGCID

SenUGCSetOffensivenessFlag

SenUGCPublish


UGC Structures

This section contains structures that you use with the Microsoft Sentient APIs.

In This Section

Structure | Description
SenUGCSearchResult | Contains the results of the search for UGC items.
SenUGCMetaData | Contains the metadata associated with a UGC item.
SenUGCDownloadedMetaData | Contains the original uploaded metadata plus any statistics gathered from the Sentient server.
SenUGCFeedInfo | Contains the name and description of a feed.
SenUGCFeedItem | Contains the information that uniquely identifies a UGC item.


SenUGCSearchResult Structure

Contains the results of the search for UGC items.

Syntax

C ++
struct SenUGCSearchResult{
   XUID  author;
   SenUGCID  ID;
   int  revision;
};

Members

author

The author of the UGC item.

ID

A SenUGCID that identifies the UGC item.

revision

The revision number of this item.

Remarks

This structure is returned in the call to SenUGCEnumerate.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCEnumerate


SenUGCMetaData Structure

Contains the metadata associated with a UGC item.

Syntax

C ++
struct SenUGCMetaData{
   SenUGCID  parentID;
   SenUGCType  type;
   SenUGCMetaDataFlags  flags;
   static const int  NameLength = 64;
   wchar_t  name[NameLength];
   static const int  ShortNameLength = 12;
   wchar_t  shortName[ShortNameLength];
   static const int  NrUgcDescriptors = 4;
   SenUGCDescriptor  descriptors[NrUgcDescriptors];
   static const int  BlobSizeLimit = 1024;
   size_t  metaDataBlobSize;
   void*  metaDataBlob;
};

Members

parentID

A SenUGCID that identifies the parent of the UGC item. This ID is created in the call to SenUGCCreatePublishingUGCID. This member may be set to SenUGCID_None.

type

A SenUGCType that defines the type of UGC item.

flags

A SenUGCMetaDataFlags that defines custom flags to search for UGC items.

NameLength

The maximum length of the name of the UGC data blob.

name

The name of the UGC data blob.

ShortNameLength

The maximum length of the short name of the UGC data blob.

shortName

The short name of the UGC data blob.

NrUgcDescriptors

The number of descriptors in the descriptors member.

descriptors

A SenUGCDescriptor that describes the UGC item.

BlobSizeLimit

The maximum size of the metaDataBlob member.

metaDataBlobSize

The size of the metaDataBlob member.

metaDataBlob

A pointer to the metadata blob.

Remarks

The metadata associated with a UGC item is uploaded in the call to SenUGCUpload and retrieved in the SenUGCDownloadedMetadata structure in the call to SenUGCDownloadMetaData.

A UGC item may have up to 4 main data blobs but only 1 set of metadata. Typically, titles download the metadata blob and display attributes of the UGC item, and then download the UGC data blob only after the player selects it, as the data blobs are large and should not be downloaded randomly.

Using the parent UGC member you can nest related UGC items. For example, if you want to create a separate UGC item that has screenshots of the parent UGC content, you can link it to the parent using the parentID member.

Note: Sentient does not support referential integrity on parent and child UGC items. If a parent of a UGC item is banned, this does not affect the publish state of the child UGC item.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCDownloadMetaData

SenUGCUpload


SenUGCDownloadedMetaData Structure

Contains the original uploaded metadata plus any statistics gathered from the Sentient server.

Syntax

C ++
struct SenUGCDownloadedMetaData{
   XUID  author;
   SenUGCMetaData  base;
   SenUGCID  ID;
   SYSTEMTIME  authorTime;
   int  revision;
   SenUGCPublishState  publishState;
   int  averageReviewScore;
   int  nrReviews;
   int  nrFavoriteFlags;
   #define SenUGCDownloadedMetaData_NrCustomCounters 4
   INT64  customCounters[SenUGCDownloadedMetaData_NrCustomCounters];
   int  nrDownloads;
   size_t  mainDataSizes[SenUGCMainData_NrBlobs];
   SenLeaderboardId  leaderboardId;
};

Members

author

The XUID of the author of the UGC.

base

The SenUGCMetaData structure that contains the original metadata uploaded to the Sentient server in the call to SenUGCUpload.

ID

A SenUGCID that identifies the UGC item. This ID is created in the call to SenUGCCreatePublishingUGCID.

authorTime

A SYSTEMTIME that contains the creation time for this UGC item.

revision

The revision of the UGC item.

publishState

A member of the SenUGCPublishState enumeration that describes the state of the UGC item.

averageReviewScore

The average review score for the UGC item.

nrReviews

The number of reviews for the UGC item.

nrFavoriteFlags

The number of favorite flags for the UGC item.

#define SenUGCDownloadedMetaData_NrCustomCounters 4

The maximum number of UGC items.

customCounters

The array of custom counters.

nrDownloads

The number of times that the main data blob (MainDataBlob 0) has been downloaded.

mainDataSizes[SenUGCMainData_NrBlobs]

The size, in bytes, of each data blob in the array of main data blobs. There can be SenUGCMainData_NrBlobs main data blobs.

Use this number to allocate the buffer that receives the downloaded data in the call to SenUGCDownloadMainDataBlob.

leaderboardId

A SenLeaderboardId that uniquely identifies the leaderboard that displays the UGC item.

Remarks

This structure is retrieved in the call to SenUGCDownloadMetaData. This structure contains the original metadata uploaded in the call to SenUGCUpload plus any statistics gathered from the UGC server. Because statistics are aggregated on the Sentient server, they may not be current at any given time.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCDownloadMetaData


SenUGCFeedInfo Structure

Contains the name and description of a feed.

Syntax

C ++
struct SenUGCFeedInfo{
   SenUGCFeedType feedType;
   wchar_t Name[32];
   wchar_t Description[128];
};

Members

feedType

A SenUGCFeedType that identifies the type of feed.

Name

The user friendly name of the feed type.

Description

A user friendly description of the feed type.

Remarks

The SenEnumerateFeeds function uses this structure to return information about the types of feeds that can be retrieved by SenUGCGetFeed.

Requirements

Header: SenClientUGC.h

Library: SenUGC.lib

See Also

UGC Structures

SenEnumerateFeeds

SenUGCGetFeed


SenUGCFeedItem Structure

Contains the information that uniquely identifies a UGC item.

Syntax

C ++
struct SenUGCFeedItem{
   XUID Author;
   SenUGCID UgcId;
   SYSTEMTIME DateCreated;
};

Members

Author

The author of the UGC.

UgcId

A SenUGCID that identifies the UGC.

DateCreated

The date that the UGC was created.

Remarks

This structure is returned by SenUGCGetFeed to identify the returned feed.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

UGC Structures

SenUGCGetFeed


UGC Enumerations

This section contains API reference enumeration types that you use with the Microsoft Sentient APIs.

In This Section

Enumeration | Description
SenUGCID | Defines the unique ID that Sentient generates and provisions for a UGC item. This identifier is unique across all titles.
SenUGCType | Defines the type of UGC items on which to filter a search.
SenUGCPublishState | Defines the publish states for UGC content.
SenUGCSortBy | Defines the sort order for UGC items returned from a search.
SenUGCAuthorType | Identifies the type of author that created the UGC item.
SenUGCDescriptor | Defines custom flags that identify a UGC item for search.
SenUGCMetaDataFlags | Defines the metadata flags to filter the search for UGC items.
SenUGCFeedType | Defines the types of feeds available to download.
SenUGCReviewScoreType | Defines the type of review score.
SenUGCOffensivenessFlag | Defines the types of offensiveness flags for UGC items.


SenUGCDescriptor Enumeration

Defines custom flags that identify a UGC item for search.

Syntax

C ++
enum SenUGCDescriptor{
   SenUGCDescriptor_Illegal     = 0xffff,
   SenUGCDescriptor_None        = 0x0000,
   SenUGCDescriptor_FirstCustom = 0x0100
};

Constants

SenUGCDescriptor_Illegal

This descriptor is reserved.

SenUGCDescriptor_None

This descriptor is reserved.

SenUGCDescriptor_FirstCustom

A custom title-defined descriptor that is used in the SenUGCEnumerate function to search for UGC items. You can define up to NrUgcDescriptors custom descriptors.

Remarks

When you upload a UGC item with SenUGCUpload, you can define custom descriptors in the SenUGCMetadata structure. These descriptors can be used to filter the search for UGC items in the call to SenUGCEnumerate.

Descriptors are used to identify different tags for the UGC item such as difficulty, jumps, or some other descriptor of the item.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCUpload

SenUGCEnumerate


SenUGCReviewScoreType Enumeration

Defines the type of review score.

Syntax

C ++
enum SenUGCReviewScoreType{
   SenUGCReviewScoreType_Quality = 0x00,
   SenUGCReviewScoreType_Difficulty = 0x10
};

Constants

SenUGCReviewScoreType_Quality

A quality rating for a UGC item.

SenUGCReviewScoreType_Difficulty

A level of difficulty rating for a UGC item.

Remarks

This is used by the SenUGCSetReviewScore to review UGC items, and by SenUGGetReviewScore to retrieve reviews. Sentient averages the review scores over all players and titles can display them on leaderboards by calling SenGetLeaderboardTop.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCSetReviewScore

SenUGCGetReviewScore


SenUGCSortBy Enumeration

Defines the sort order for UGC items returned from a search.

Syntax

C ++
enum SenUGCSortBy{
   SenUGCSortBy_CreationDate,
   SenUGCSortBy_TopFavorites,
   SenUGCSortBy_TopReviewScoreAverage,
   SenUGCSortBy_TopDownloadsTotal
};

Constants

SenUGCSortBy_CreationDate

The UGC items are sorted by creation data.

SenUGCSortBy_TopFavorites

The UGC items are sorted by top favorites. This is the aggregated number of favorites from the UGC metadata.

SenUGCSortBy_TopReviewScoreAverage

The UGC items are sorted by top review scores. Top rated is determined by the average review score for all UGC items.

SenUGCSortBy_TopDownloadsTotal

The UGC items are sorted by top number of downloads. This is the sum of all downloads for individual UGC items.

Remarks

This enumeration is used in the call to SenUGCEnumerate to sort the returned UGC items.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCEnumerate


SenUGCType Enumeration

Defines the type of UGC items on which to filter a search.

Syntax

C ++
enum SenUGCType{
   SenUGCType_Movie = 0,
   SenUGCType_Audio,
   SenUGCType_Image,
   SenUGCType_FirstCustom = 0x20
};

Constants

SenUGCType_Movie

The type of UGC filter is "movie."

SenUGCType_Audio

The type of UGC filter is "audio."

SenUGCType_Image

The type of UGC filter is "image."

SenUGCType_FirstCustom

The type of UGC filter is "custom." Titles can create custom UGC types and use this to filter searches fo UGC items.

Remarks

The UGC type is specified in the SenUGCMetaData structure when you upload it in the call to SenUGCUpload.

This enumeration is used in the call to SenUGCEnumerate to filter the search for UGC items.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCUpload

SenUGCEnumerate


SenUGCPublishState Enumeration

Defines the publish states for UGC content.

Syntax

C ++
enum SenUGCPublishState{
   SenUGCPublishState_Deleted     = 0x00,
   SenUGCPublishState_Banned      = 0x01,
   SenUGCPublishState_Unpublished = 0x10,
   SenUGCPublishState_Published   = 0x30,
   SenUGCPublishState_PendingModeratorReview = 0x31
};

Constants

SenUGCPublishState_Deleted

The publish state is deleted. UGC items can only be deleted by the user that created them.

SenUGCPublishState_Banned

The UGC item has been banned by the moderator.

SenUGCPublishState_Unpublished

The UGC item is not published.

SenUGCPublishState_Published

The UGC item is published and available to everyone.

SenUGCPublishState_PendingModeratorReview

The UGC item is pending review by the moderator.

Note: Do not display UGC items flagged as pending to players.

Remarks

When you upload a UGC item to the Sentient servers, the item remains in the unpublished state until you call SenUGCPublish. When you retrieve the metadata for a UGC item in the call to SenUGCDownloadMetadata, the publish state is in the SenUGCDownloadedMetaData structure.

Moderators can ban UGC items when enough players flag an item as offensive. For more information, see UGC Publish States.

Note that the main data blob can only be uploaded or modified when the UGC state is unpublished. For more information, see the remarks section of SenUGCUpload.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCEnumerate


SenUGCAuthorType Enumeration

Identifies the type of author that created the UGC item.

Syntax

C ++
enum SenUGCAuthorType{
   SenUGCAuthorType_Everyone,
   SenUGCAuthorType_LocalUsers,
   SenUGCAuthorType_Friends,
   SenUGCAuthorType_List
};

Constants

SenUGCAuthorType_Everyone

The type of author is "all authors."

SenUGCAuthorType_LocalUsers

The type of author is "local users" (everyone currently logged in to Xbox LIVE).

SenUGCAuthorType_Friends

The type of author is the user's Xbox LIVE friends.

SenUGCAuthorType_List

The type of author is specified in a list of authors.

Remarks

This enumeration is used in SenUGCEnumerate to filter the search for UGC items.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCEnumerate


SenUGCMetaDataFlags Enumeration

Defines the metadata flags to filter the search for UGC items.

Syntax

C ++
typedef unsigned int SenUGCMetaDataFlags;
enum {
   SenUGCMetaDataFlags_NoFlags         = 0x00000000,
   SenUGCMetaDataFlags_FriendsCanEdit  = 0x00000001,
   SenUGCMetaDataFlags_EveryoneCanEdit = 0x00000002,
   SenUGCMetaDataFlags_Reserved1       = 0x00000004,
   SenUGCMetaDataFlags_Reserved2       = 0x00000008,
   SenUGCMetaDataFlags_Reserved3       = 0x00000010,
   SenUGCMetaDataFlags_Reserved4       = 0x00000020,
   SenUGCMetaDataFlags_Reserved5       = 0x00000040,
   SenUGCMetaDataFlags_Reserved6       = 0x00000080,
   SenUGCMetaDataFlags_FirstCustom     = 0X00000100
};

Constants

SenUGCMetaDataFlags_NoFlags

This flag is reserved by Sentient.

SenUGCMetaDataFlags_FriendsCanEdit

This flag is reserved by Sentient.

SenUGCMetaDataFlags_EveryoneCanEdit

This flag is reserved by Sentient.

SenUGCMetaDataFlags_Reserved1

This flag is reserved by Sentient.

SenUGCMetaDataFlags_Reserved2

This flag is reserved by Sentient.

SenUGCMetaDataFlags_Reserved3

This flag is reserved by Sentient.

SenUGCMetaDataFlags_Reserved4

This flag is reserved by Sentient.

SenUGCMetaDataFlags_Reserved5

This flag is reserved by Sentient.

SenUGCMetaDataFlags_Reserved6

This flag is reserved by Sentient.

SenUGCMetaDataFlags_FirstCustom

This is a custom (title defined) flag used by the title to filter the search for UGC items in the call to SenUGCEnumerate.

Remarks

When you call SenUGCUpload, you can define UGC metadata flags in the SenUGCMetaData structure. This structure is then used in the call to SenUGCEnumerate to filter the search for UGC items.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

UGC Reference

SenUGCUpload

SenUGCEnumerate


SenUGCFeedType Enumeration

Defines the types of feeds available to download.

Syntax

C ++
enum SenUGCFeedType{
   SenUGCFeedType_Unknown     = 0x00,
   SenUGCFeedType_NewestItems = 0x10,
   SenUGCFeedType_TopReviewed = 0x20,
   SenUGCFeedType_TopDownloaded = 0x30,
   SenUGCFeedType_PendingModeratorReview = 0x60,
   SenUGCFeedType_Custom      = 0x90
};

Constants

SenUGCFeedType_Unknown

The type of feed is unknown.

SenUGCFeedType_NewestItems

This type of feed returns the most recent UGC items.

SenUGCFeedType_TopReviewed

The type of feed returns the top-rated UGC items for all ratings before the current date.

SenUGCFeedType_TopDownloaded

The type of feed returns the top downloaded UGC items for all time.

SenUGCFeedType_PendingModeratorReview

The type of feed is pending moderator review. UGC items flagged as "Pending Moderator Review" are removed from feeds and search results.

Note: This feed is for moderator review only; do not display UGC items flagged as pending to players.

SenUGCFeedType_Custom

The base type of feed for all custom feeds. For more information, see the Remarks section.

Remarks

This enumeration is contained in the SenUGCFeedInfo structure and is used by SenUGCGetFeed to retrieve a specific type of feed.

To get the list of the types of feeds available for a title, titles call SenEnumerateFeeds.

Titles call SenUGCGetFeed to get a list of UGC items for a specific feed type. Sentient limits the number of UGC items returned by SenUGCGetFeed to 100.

To create a custom feed (SenUGCFeedType_Custom), email the Sentient team at senhelp@microsoft.com. Sentient will create the new feed type and send you the custom feed ID.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

UGC Enumerations

SenEnumerateFeeds

SenUGCGetFeed


SenUGCID Enumeration

Defines the unique ID that Sentient generates and provisions for a UGC item. This identifier is unique across all titles.

Syntax

C ++
enum SenUGCID{
   SenUGCID_None                    = 0x00000000,
   SenUGCID_FirstDeveloperGenerated = 0x01000000,
   SenUGCID_FirstLocal              = 0x02000000,
   SenUGCID_FirstGlobal             = 0x03000000,
};

Constants

SenUGCID_None

The UGC ID does not exist.

SenUGCID_FirstDeveloperGenerated

This UGC ID is reserved.

SenUGCID_FirstLocal

This UGC ID is reserved.

SenUGCID_FirstGlobal

This UGC ID is reserved.

Remarks

Sentient generates and provisions a unique identifier for each UGC item when you call SenUGCCreatePublishingUGCID. This UGC ID is used in the UGC search and feed structures, as well as in the publish, upload and rating functions to identify the UGC item.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

UGC Enumerations

SenUGCCreatePublishingUGCID

SenUGCFeedType

SenUGCPublish

SenUGCUpload

SenUGCSetReviewScore


SenUGCOffensivenessFlag Enumeration

Defines the types of offensiveness flags for UGC items.

Syntax

C ++
enum SenUGCOffensivenessFlag{
   SenUGCOffensivenessFlag_None = 0x00000000,
   SenUGCOffensivenessFlag_Discriminating = 0x00000001,
   SenUGCOffensivenessFlag_Explicit = 0x00000002,
   SenUGCOffensivenessFlag_Obscene = 0x00000004,
   SenUGCOffensivenessFlag_FoulLanguage = 0x00000008,
   SenUGCOffensivenessFlag_LicenseInfringement = 0x00000010,
   SenUGCOffensivenessFlag_IllegalAdvertising = 0x00000020,
   SenUGCOffensivenessFlag_Illegal = 0x00000040,
};

Constants

SenUGCOffensivenessFlag_None

The UGC is not offensive. This flag is reserved for moderators to reset the publish state from "Pending Moderation" to "Published."

SenUGCOffensivenessFlag_Discriminating

The UGC is discriminating.

SenUGCOffensivenessFlag_Explicit

The UGC has explicit content.

SenUGCOffensivenessFlag_Obscene

The UGC is obscene.

SenUGCOffensivenessFlag_FoulLanguage

The UGC contains foul language.

SenUGCOffensivenessFlag_LicenseInfringement

The UGC infringes on licensing agreements.

SenUGCOffensivenessFlag_IllegalAdvertising

The UGC has illegal advertising.

SenUGCOffensivenessFlag_Illegal

The UGC is illegal.

Remarks

These constants are used by the SenUGCSetOffensivenessFlag function to flag a UGC item as offensive.

Requirements

Header: SenClientUGTTypes.h

Library: SenUGC.lib

See Also

UGC Enumerations


UGC Types

The Sentient API defines the following types and constants.

Types

Type | Description
typedef int SenUGCFeedID | A Sentient-generated constant that uniquely identifies a UGC feed.

Constants

Sentient provides the following predefined constants.

Type | Value | Description
const int SenUGCMainData_NrBlobs | 4 | The number of main data blobs associated with a UGC item. Note: This is currently limited to 4 data blobs.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

UGC Reference


Leaderboards

Using the Sentient leaderboard feature, you can create and populate leaderboards with the entries that are based on user scores or levels. Sentient supplies two predefined leaderboards populated with the user’s friends and the top-scoring users for a title.

Creating the Leaderboard

The leaderboard is defined by the SenLeaderBoardDefinition structure which contains the name and type of sort. When you create a leaderboard, Sentient returns a handle to the leaderboard (the leaderboard ID).

To create the leaderboard ID:

  • Call SenCreateLeaderboard to create the leaderboard ID. This is the ID that you use to identify the leaderboard in all other API calls. You can optionally specify custom metadata for the leaderboard.

SenCreateLeaderboard can be used to update the metadata for any leaderbaord, including an existing UGC leaderbaord. To update an existing leaderboard with metadata:

  • Call SenCreateLeaderboard on an existing leaderboard ID with a metadata blob.

Note: SenCreateLeaderboard does not create leaderboards for UGC items. To create leaderboard for UGC items, call SenUGCPublish.

Creating Leaderboard Entries

Leaderboards are populated with rows of leaderboard entries. Each leaderboard entry consists of an actor XUID and value and optionally includes metadata.

To create a leaderboard entry:

  • Call SenSetUserLeaderboardValue. This adds the leaderboard entry to the specified leaderboard.

To create a leaderboard entry with metadata:

  • Call the overloaded SenSetUserLeaderboardValue. This adds the leaderboard entry to the specified leaderboard.
Retrieving Leaderboard Entries

You can get leaderboard entries for a specified user or a different actor.

To get leaderboard entries for a user:

  • Call SenGetLeaderboardEntry.

To get the leaderboard entries for a specific player (not the user that inititated the call):

  • Call the overloaded SenGetLeaderboardEntry.
Retrieving Ranked Leaderboards

Using the Sentient leaderboard feature, you can design leaderboards with the entries and the ranking system. Sentient creates two ranked leaderboards for you: one with the user's Xbox LIVE friends and another with the collection of top-ranked users.

To create friends leaderboards:

  • Call SenGetLeaderboardFriends.

To create top-ranked leaderboards:

  • Call SenGetLeaderboardTop.


Leaderboard Reference

This section contains reference information for the Microsoft Sentient APIs.

In This Section

  • Leaderboard Functions
  • Leaderboard Structures
  • Leaderboards Enumerations
  • Leaderboard Types


Leaderboard Functions

This section contains API reference functions that you use with the Microsoft Sentient APIs.

In This Section

Function | Description
SenCreateLeaderboard | Creates a dynamic leaderboard based on the specified definition.
SenGetLeaderboardEntry | Retrieves a single leaderboard entry for the specified user and leaderboard.
SenGetLeaderboardEntry (overloaded) | Retrieves a single leaderboard entry for the specified actor.
SenSetUserLeaderboardValue | Creates or updates a leaderboard entry for the specified user and leaderboard.
SenSetUserLeaderboardValue (overloaded) | Creates or updates a leaderboard entry (with metadata) for the specified user and leaderboard.
SenGetLeaderboardTop | Returns a collection of the top-ranked leaderboard entries.
SenGetLeaderboardFriends | Returns a ranked collection of leaderboard entries for the user's Xbox LIVE friends.


SenCreateLeaderboard Function

Creates a dynamic leaderboard based on the specified definition.

Note: This does not create a leaderboard for UGC items. To create a UGC leaderboard, call SenUGCPublish.

Syntax

C ++
HRESULT SenCreateLeaderboard(
   int userIndex,
   const SenLeaderboardDefinition &definition,
   const void *metadataBlob,
   size_t metadataBlobSize,
   SenLeaderboardId *out_leaderboardId,
   SenSysCompletedCallback callback,
   void *callbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

definition

[in] A SenLeaderboardDefinition structure that describes the behavior of the leaderboard.

metadataBlob

[in] A pointer to a binary metadata blob that stores information associated with this leaderboard. This parameter is optional and may be set to NULL.

metadataBlobSize

[in] The size, in bytes, of the buffer that contains the metadata blob.

out_leaderboardId

[in/out] If this pointer does not refer to a valid leaderboard ID, Sentient creates a new leaderboard and returns a pointer to the SenLeaderboardId after Sentient invokes the callback associated with this call.

If this pointer points to a valid leaderboard ID, this parameter specifies the leaderboard ID on which to set the metadata. If the supplied leaderboard ID is not recognized, this function creates a new leaderboard and returns a new ID.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

E_POINTER

The out_leaderboardId pointer is NULL.

SENTIENT_E_USERINDEX_IS_ANY

The user index of ANY (0xFF) is not valid.

SENTIENT_E_USERINDEX_IS_FOCUS

The user index FOCUS (0xFD) is not valid.

SENTIENT_E_USERINDEX_IS_NONE

The user index of NONE (0xFE) is not valid.

SENTIENT_E_USERINDEX_IS_INVALID

The user index is outside the range 0 to 3.

Remarks

Sentient generates a unique ID for every leaderboard; titles must not generate their leaderboard IDs. To create a new leaderboard, call this function with an undefined leaderbaord ID.

Note: Currently, there is no way to update the metadata on an existing leaderboard.

Requirements

Header: SenClientUGCCLeaderboards.h

Library: SenUGC.lib

See Also

Leaderboard Functions


SenGetLeaderboardEntry Function

Retrieves a single leaderboard entry for the specified user and leaderboard.

Syntax

C ++
HRESULT SenGetLeaderboardEntry(
   int userIndex,
   SenLeaderboardId leaderboardId,
   SenLeaderboardMetadataFlag leaderboardFlag,
   SenLeaderboardMetadataFlag entryFlag,
   SenLeaderboardEntry *out_leaderboardEntry,
   size_t maxLeaderboardMetadataBlobSize,
   void *out_leaderboardMetadataBlob,
   size_t *out_leaderboardMetadataBlobSize,
   SenSysCompletedCallback callback,
   void *callbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

leaderboardId

[in] A SenLeaderboardId that identifies the leaderboard that stores the leaderboard entry. This is the leaderboard ID returned in the call to SenCreateLeaderboard or SenUGCPublish.

leaderboardFlag

[in] A member of the SenLeaderboardMetadataFlag enumeration that specifies how to retrieve the leaderboard metadata.

entryFlag

[in] A member of the SenLeaderboardMetadataFlag enumeration that specifies how to retrieve the leaderboard entry (in out_leaderboardEntry) metadata.

out_leaderboardEntry

[out] A pointer to the SenLeaderboardEntry structure that will contain the leaderboard entry for this user after Sentient invokes the callback associated with this call.

The leaderboard value is set in the call to SenSetUserLeaderboardValue or SenSetUserLeaderboardValue.

maxLeaderboardMetadataBlobSize

[in] The size, in bytes, of the buffer that receives the leaderboard metadata blob. This function returns an error if the size of the data exceeds the size of the buffer.

out_leaderboardMetadataBlob

[out] A pointer to a buffer that will contain the leaderboard metadata blob associated with the specified leaderboard after Sentient invokes the callback associated with this call.

out_leaderboardMetadataBlobSize

[out] A pointer to the size, in bytes, of the leaderboard metadata blob. The size is available after Sentient invokes the callback associated with this call.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

The size of the metadata blob exceeds the size of the buffer allocate to receive the data.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

E_POINTER

The out_LeaderboardEntry pointer is not valid.

If the leaderboardFlag is not SenLeaderboardmetadataFlag_BypassRetrieval, the out_leaderboardMetadataBlobSize pointer is not valid.

If the leaderboardFlag is SenLeaderboardmetadataFlag_RetrieveData, the out_leaderboardMetadataBlob pointer is not valid.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_E_USERINDEX_IS_ANY

The user index of ANY (0xFF) is not valid.

SENTIENT_E_USERINDEX_IS_FOCUS

The user index FOCUS (0xFD) is not valid.

SENTIENT_E_USERINDEX_IS_NONE

The user index of NONE (0xFE) is not valid.

SENTIENT_E_USERINDEX_IS_INVALID

The user index is outside the range 0 to 3.

Remarks

This function returns the leaderboard entry that is associated with the specified user. To retrieve a leaderboard entry for an actor that is not associated with the specified user, call the overloaded version of SenGetLeaderboardEntry.

Requirements

Header: SenClientUGCCLeaderboards.h

Library: SenUGC.lib

See Also

Leaderboard Functions

SenGetLeaderboardEntry (overloaded)

SenSetUserLeaderboardValue

SenSetUserLeaderboardValue (overloaded)


SenGetLeaderboardEntry Function (overloaded)

Retrieves a single leaderboard entry for the specified actor.

Syntax

C ++
HRESULT SenGetLeaderboardEntry(
   int userIndex,
   SenLeaderboardActorId actorId,
   SenLeaderboardId leaderboardId,
   SenLeaderboardMetadataFlag leaderboardFlag,
   SenLeaderboardMetadataFlag entryFlag,
   SenLeaderboardEntry *out_leaderboardEntry,
   size_t maxLeaderboardMetadataBlobSize,
   void *out_leaderboardMetadataBlob,
   size_t *out_leaderboardMetadataBlobSize,
   SenSysCompletedCallback callback,
   void *callbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

actorId

[in] A SenLeaderboardActorId that identifies the actor associated with this leaderboard entry.

leaderboardId

[in] A SenLeaderboardId that identifies the leaderboard that stores the leaderboard entry. This is the leaderboard ID returned in the call to SenCreateLeaderboard or SenUGCPublish.

leaderboardFlag

[in] A member of the SenLeaderboardMetadataFlag enumeration that specifies how to retrieve the leaderboard metadata.

entryFlag

[in] A member of the SenLeaderboardMetadataFlag enumeration that specifies how to retrieve the leaderboard entry (in out_leaderboardEntry) metadata.

out_leaderboardEntry

[out] A pointer to the SenLeaderboardEntry structure that will contain the leaderboard entry for this user after Sentient invokes the callback associated with this call.

The leaderboard value is set in the call to SenSetUserLeaderboardValue or SenSetUserLeaderboardValue.

maxLeaderboardMetadataBlobSize

[in] The size, in bytes, of the buffer that receives the leaderboard metadata blob. This function returns an error if the size of the data exceeds the size of the buffer.

out_leaderboardMetadataBlob

[out] A pointer to a buffer that will contain the leaderboard metadata blob associated with the specified leaderboard after Sentient invokes the callback associated with this call.

out_leaderboardMetadataBlobSize

[out] A pointer to the size, in bytes, of the leaderboard metadata blob. The size is available after Sentient invokes the callback associated with this call.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

The size of the metadata blob exceeds the size of the buffer allocate to receive the data.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

E_POINTER

The out_LeaderboardEntry pointer is not valid.

If the leaderboardFlag is not SenLeaderboardmetadataFlag_BypassRetrieval, the out_leaderboardMetadataBlobSize pointer is not valid.

If the leaderboardFlag is SenLeaderboardmetadataFlag_RetrieveData, the out_leaderboardMetadataBlob pointer is not valid.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_E_USERINDEX_IS_ANY

The user index of ANY (0xFF) is not valid.

SENTIENT_E_USERINDEX_IS_FOCUS

The user index FOCUS (0xFD) is not valid.

SENTIENT_E_USERINDEX_IS_NONE

The user index of NONE (0xFE) is not valid.

SENTIENT_E_USERINDEX_IS_INVALID

The user index is outside the range 0 to 3.

Remarks

This function retrieves the leaderboard entry for the specified actor, not the specified user. Use this function when you want to retrieve items for the user's friends or for top reviewers. To retrieve a leaderboard entry for the specified user, call this SenGetLeaderboardEntry version.

Requirements

Header: SenClientUGCCLeaderboards.h

Library: SenUGC.lib

See Also

Leaderboard Functions

SenGetLeaderboardEntry

SenSetUserLeaderboardValue

SenSetUserLeaderboardValue (overloaded)


SenSetUserLeaderboardValue Function

Creates or updates a leaderboard entry for the specified user and leaderboard.

Syntax

C ++
HRESULT SenSetUserLeaderboardValue(
   int   userIndex,
   SenLeaderboardId   leaderboardId,
   SenLeaderboardEntryValue   value,
   LONGLONG   descriptor,
   SenSysCompletedCallback   callback,
   void   *callbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

leaderboardId

[in] A SenLeaderboardId that Sentient generates to identify the leaderboard to set the leaderboard entry on. This is the leaderboard ID returned in the call to SenCreateLeaderboard or SenUGCPublish.

value

[in] A SenLeaderboardEntryValue that defines the value for the leaderboard entry.

descriptor

[in] A custom descriptor that identifies a leaderboard entry.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_E_USERINDEX_IS_ANY

The user index of ANY (0xFF) is not valid.

SENTIENT_E_USERINDEX_IS_FOCUS

The user index FOCUS (0xFD) is not valid.

SENTIENT_E_USERINDEX_IS_NONE

The user index of NONE (0xFE) is not valid.

SENTIENT_E_USERINDEX_IS_INVALID

The user index is outside the range 0 to 3.

Remarks

This overloaded function both creates and updates the leaderboard entry for the specified user. If this is a new leaderboard entry, it is added to the specified leaderboard. The value of an existing leaderboard entry can be updated at any time by calling this function with a new value.

Note: In all cases, Sentient replaces the value of the existing entry with the supplied value; Sentient does not compare previous values to the new value to determine which is better.

This function sets a leaderboard entry without metadata. To set a leaderboard entry with metadata, call the overloaded version of SenSetUserLeaderboardValue.

Requirements

Header: SenClientUGCCLeaderboards.h

Library: SenUGC.lib

See Also

Leaderboard Functions

SenGetLeaderboardEntry

SenGetLeaderboardEntry (overloaded)

SenSetUserLeaderboardValue (overloaded)


SenSetUserLeaderboardValue Function (overloaded)

Creates or updates a leaderboard entry (with metadata) for the specified user and leaderboard.

Syntax

C ++
HRESULT SenSetUserLeaderboardValue(
   int userIndex
   SenLeaderboardId leaderboardId,
   SenLeaderboardEntryValue value,
   LONGLONG descriptor,
   SenSysCompletedCallback callback,
   void *callbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

leaderboardId

[in] A SenLeaderboardId that identifies the leaderboard to set the leaderboard entry on. This is the leaderboard ID returned in the call to SenCreateLeaderboard or SenUGCPublish.

value

[in] A SenLeaderboardEntryValue that defines the value for the leaderboard entry.

descriptor

[in] A custom descriptor that identifies a leaderboard entry.

metadataBlob

[in] A pointer to the metadata blob that is associated with this leaderboard entry.

Note: The metadata can be uploaded at any time. To upload new metadata for this leaderboard entry, call this function again with a new metadata blob.

metadataBlobSize

[in] The size, in bytes, of the metadata blob. This function returns an error if the size of the metadata blob exceeds the size in this parameter.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

The size of the metadata blob exceeds the specified size.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_E_USERINDEX_IS_ANY

The user index of ANY (0xFF) is not valid.

SENTIENT_E_USERINDEX_IS_FOCUS

The user index FOCUS (0xFD) is not valid.

SENTIENT_E_USERINDEX_IS_NONE

The user index of NONE (0xFE) is not valid.

SENTIENT_E_USERINDEX_IS_INVALID

The user index is outside the range 0 to 3.

Remarks

This overloaded function both creates and updates the leaderboard entry for the specified user. The value and metadata for this leaderboard entry can be updated at any time by calling this function with a new value. The leaderboard entry is added to the specified leaderboard.

This function sets a leaderboard entry with metadata. To set a leaderboard entry without metadata, call this SenSetUserLeaderboardValue version.

Requirements

Header: SenClientUGCCLeaderboards.h

Library: SenUGC.lib

See Also

Leaderboard Functions

SenGetLeaderboardEntry

SenGetLeaderboardEntry (overloaded)

SenSetUserLeaderboardValue


SenGetLeaderboardTop Function

Returns a collection of the top-ranked leaderboard entries.

Syntax

C ++
HRESULT SenGetLeaderboardTop(
   int  userIndex,
   SenLeaderboardId  leaderboardId,
   size_t  maxLeaderboardEntries,
   SenLeaderboardEntry  *out_leaderboardEntries,
   size_t  *out_leaderboardEntriesSize,
   SenSysCompletedCallback  callback,
   void  *callbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

leaderboardId

[in] A SenLeaderboardId that identifies the leaderboard that stores the entry items. This is the leaderboard ID returned in the call to SenCreateLeaderboard or SenUGCPublish.

maxLeaderboardEntries

[in] The maximum number of SenLeaderboadEntry structures that can be returned in the out_leaderboardEntries parameter. This function returns an error if the size of the entries returned in out_leaderboardEntries exceeds the size of the buffer.

out_leaderboardEntries

[out] A pointer to the collection of SenLeaderboardEntry structures that will contain the leaderboard entry information after Sentient invokes the callback associated with this call.

out_leaderboardEntriesSize

[out] A pointer to the size, in bytes, of the collection of leaderboard entries. The size is available after Sentient invokes the callback associated with this call.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

E_POINTER

The out_LeaderboardEntriesSize or out_LeaderboardEntries pointer is not valid.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_E_USERINDEX_IS_ANY

The user index of ANY (0xFF) is not valid.

SENTIENT_E_USERINDEX_IS_FOCUS

The user index FOCUS (0xFD) is not valid.

SENTIENT_E_USERINDEX_IS_NONE

The user index of NONE (0xFE) is not valid.

SENTIENT_E_USERINDEX_IS_INVALID

The user index is outside the range 0 to 3.

Remarks

Sentient averages the review scores over all players and then publishes them in the SenGetLeaderboardTop leaderboard.

Requirements

Header: SenClientUGCCLeaderboards.h

Library: SenUGC.lib

See Also

Leaderboard Functions

SenGetLeaderboardFriends


SenGetLeaderboardFriends Function

Returns a ranked collection of leaderboard entries for the user's Xbox LIVE friends.

Syntax

C ++
HRESULT SenGetLeaderboardFriends(
   int userIndex,
   SenLeaderboardId leaderboardId,
   SenLeaderboardMetadataFlag leaderboardFlag,
   SenLeaderboardMetadataFlag entryFlag,
   size_t maxLeaderboardEntries,
   SenLeaderboardEntry *out_leaderboardEntries,
   size_t *out_leaderboardEntriesSize,
   size_t maxLeaderboardMetadataBlobSize,
   void *out_leaderboardMetadataBlob,
   size_t *out_leaderboardMetadataBlobSize,
   SenSysCompletedCallback callback,
   void *callbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

leaderboardId

[in] A SenLeaderboardId that identifies the leaderboard that stores the entry items. This is the leaderboard ID returned in the call to SenCreateLeaderboard or SenUGCPublish.

leaderboardFlag

[in] A member of the SenLeaderboardMetadataFlag enumeration that specifies how to retrieve the leaderboard metadata.

entryFlag

[in] A member of the SenLeaderboardMetadataFlag enumeration that specifies how to retrieve the leaderboard entry metadata.

maxLeaderboardEntries

[in] The maximum number of SenLeaderboardEntry structures that can be returned in the out_leaderboardEntries parameter. This function returns an error if the size of the entry items returned in out_leaderboardEntries exceeds the size of the buffer.

out_leaderboardEntries

[out] A pointer to the collection of SenLeaderboardEntry structures that will contain the leaderboard entry information after Sentient invokes the callback associated with this call.

out_leaderboardEntriesSize

[out] A pointer to the size, in bytes, of the collection of leaderboard entries. The size is available after Sentient invokes the callback associated with this call.

maxLeaderboardMetadataBlobSize

[in] The size, in bytes, of the buffer that receives the leaderboard metadata blob. This function returns an error if the size of the data exceeds the size of the buffer.

out_leaderboardMetadataBlob

[out] A pointer to a buffer that will contain the leaderboard metadata blob associated with the specified leaderboard after Sentient invokes the callback associated with this call.

out_leaderboardMetadataBlobSize

[out] A pointer to the size, in bytes, of the leaderboard metadata blob. The size is available after Sentient invokes the callback associated with this call.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

E_POINTER

The out_LeaderboardEntries or out_leaderboardEntriesSize pointer is not valid.

If the leaderboardFlag is not SenLeaderboardmetadataFlag_BypassRetrieval, the out_leaderboardMetadataBlobSize pointer is not valid.

If the leaderboardFlag is SenLeaderboardmetadataFlag_RetrieveData, the out_leaderboardMetadataBlob pointer is not valid

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_E_USERINDEX_IS_ANY

The user index of ANY (0xFF) is not valid.

SENTIENT_E_USERINDEX_IS_FOCUS

The user index FOCUS (0xFD) is not valid.

SENTIENT_E_USERINDEX_IS_NONE

The user index of NONE (0xFE) is not valid.

SENTIENT_E_USERINDEX_IS_INVALID

The user index is outside the range 0 to 3.

Remarks

None.

Requirements

Header: SenClientUGCCLeaderboards.h

Library: SenUGC.lib

See Also

Leaderboard Functions

SenGetLeaderboardTop


Leaderboard Structures

This section contains structures that you use with the Microsoft Sentient API.

In This Section

Structure | Description
SenLeaderboardDefinition | Contains the properties of the leaderboard.
SenLeaderboardEntry | Contains the information to create a leaderboard entry.


SenLeaderboardDefinition Structure

Contains the properties of the leaderboard.

Syntax

C ++
struct SenLeaderboardDefinition{
   static const int  NameLength = 50;
   WCHAR  Name[NameLength];
   SenLeaderboardSortType  SortType;
};

Members

NameLength

The length of the name of the leaderboard.

Name

The name of the leaderboard.

SortType

A member of the SenLeaderboardSortType enumeration that defines the sort order for this leaderboard. This order is used for APIs that rank leaderboard entries such as SenGetLeaderboardFriends or SenGetLeaderboardTop.

Remarks

This structure is used by SenCreateLeaderboard to create a leaderboard and by SenUGCPublish to create a leaderboard for UGC items.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

Leaderboard Structures


SenLeaderboardEntry Structure

Contains the information to create a leaderboard entry.

Syntax

C ++
struct SenLeaderboardEntry{
   SenLeaderboardActorId   ActorId;
   SenLeaderboardEntryValue   Value;
   LONGLONG   Descriptor;
   unsigned int   Rank;
   size_t   metaDataBlobSize;
   size_t   reserved_metaDataBlobCount;
   void   *metaDataBlob;
};

Members

ActorId

The SenLeaderboardActorId of the actor associated with this leaderboard entry.

Note: The actor ID is the XUID associated with the user specified in the call to SenSetUserLeaderboardValue or SenSetUserLeaderboardValue (overloaded).

Value

The SenLeaderboardEntryValue that defines the entry value.

Descriptor

A custom descriptor that identifies a leaderboard entry.

Rank

The rank of the leaderboard entry.

metaDataBlobSize

The size, in bytes, of the metadata blob.

reserved_metaDataBlobCount

This parameter is reserved for future use.

metaDataBlob

A pointer to the metadata blob associated with the leaderboard.

Remarks

This structure contains the leaderboard entry values populated in the call to SenSetUserLeaderboardValue and SenSetUserLeaderboardValue (overloaded).

The following functions return this structure:

  • SenGetLeaderboardEntry
  • SenGetLeaderboardEntry (overloaded)
  • SenGetLeaderboardFriends
  • SenGetLeaderboardTop

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

Leaderboard Structures


Leaderboard Enumerations

This section contains API reference enumeration types that you use with the Microsoft Sentient APIs.

In This Section

Enumeration | Description
SenLeaderboardMetadataFlag | Defines how to return the metadata.
SenLeaderboardSortType | Defines the types of sorts performed on leaderboards.


SenLeaderboardMetadataFlag Enumeration

Defines how to return the metadata.

Syntax

C ++
enum SenLeaderboardMetadataFlag{
   SenLeaderboardmetadataFlag_BypassRetrieval = 0x00000000,
   SenLeaderboardmetadataFlag_RetrieveSizeOnly = 0x00000001,
   SenLeaderboardmetadataFlag_RetrieveData = 0x00000002,
};

Constants

SenLeaderboardmetadataFlag_BypassRetrieval

Does not return the metadata blob or the size of the metadata blob.

SenLeaderboardmetadataFlag_RetrieveSizeOnly

Returns the size of the metadata blob .

SenLeaderboardmetadataFlag_RetrieveData

Returns both the size of the metadata blob and the metadata blob.

Remarks

These enumeration values define how to return the metadata from the following functions:

  • SenGetLeaderboardEntry
  • SenGetLeaderboardEntry (overloaded)
  • SenGetLeaderboardFriends

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

Leaderboard Enumerations


SenLeaderboardSortType Enumeration

Defines the types of sorts performed on leaderboards.

Syntax

C ++
enum SenLeaderboardSortType{
   SenLeaderboardSortType_Ascending = 0x00,
   SenLeaderboardSortType_Descending = 0x10
};

Constants

SenLeaderboardSortType_Ascending

The type of sort is "ascending."

SenLeaderboardSortType_Descending

The type of sort is "descending."

Remarks

This enumeration member is contained in the SenLeaderboardDefinition structure.

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

Leaderboard Enumerations


Leaderboard Types

The Sentient API defines the following types and constants.

Types

Type Description
typedef ULONGLONG SenLeaderboardId

A Sentient-generated constant that uniquely identifies the leaderboard.

These constants are used in:

  • SenUGCDownloadedMetaData structure
  • SenCreateLeaderboard function
  • SenSetUserLeaderboardValue function
  • SenSetUserLeaderboardValue function (overloaded)
  • SenGetLeaderboardEntry function
  • SenGetLeaderboardEntry function (overloaded)
  • SenGetLeaderboardFriends function
  • SenGetLeaderboardTop function
typedef __int64 SenLeaderboardEntryValue

The numeric value of the leaderboard entry.

These constants are used in:

  • SenSetUserLeaderboardValue function
  • SenSetUserLeaderboardValue function (overloaded)
  • SenLeaderboardEntry structure
typedef ULONGLONG SenLeaderboardActorId

The XUID that identifies the leaderboard entry.

These constants are used in:

  • SenGetLeaderboardEntry function (overloaded)

Requirements

Header: SenClientUGCTypes.h

Library: SenUGC.lib

See Also

Leaderboard Reference


Fame

Avatar Superstars is a social, participation-based reward system where avatars are the primary stars of the game. To unlock Avatar Superstar rewards (and the various levels of VIP status), players must accumulate Fame points. Players earn Fame points when they compete in Fame challenges such as playing games, purchasing products, or playing with other VIP players.

Fame Challenges

There are two types of Fame challenges: Sentient-defined challenges and custom title-defined challenges. Sentient challenges include the purchase of games and playing mulitplayer games with friends. Challenges that are specific to your title can include unlocking a treasure or winning a hand of cards.

For more information, see Fame Challenges.

Progress

Titles periodically send a player's progress toward milestones within a challenge to Sentient for long term storage and aggregation. Titles do not need to send progress for challenges that Sentient tracks and aggregates directly such as purchasing a new title.

For more information on Fame challenges, see SenFameProgressID.

To send progress to the Sentient server:

  • Send progress in a Fame category to Sentient in the call to SenFameUpdateProgress.

Players also get Fame points for playing in multi-player games. To register participants in a multi-player game:

  • Call SenRegisterFameMPGame.

Progress is buffered on the client for a time before committing it to the Sentient servers. Only under exceptional circumstances where an immediate commit is required should you call SenFlushFameProgress to commit progress to the Sentient servers.

Displaying Fame Progress and Awards

Titles can display progress toward Fame challenges to players, for example, on a Fame Challenge menu or a Fame VIP display.

To display progress:

  • First call SenGetFameDisplayDataCount to get the number of Fame challenges available to display, and then call SenGetFameDisplayData to retrieve the progress in all Fame challenges.

Some milestones are defined in the Challenge Definition Schema to rotate on a weekly basis. To display the time left in the Fame week:

  • Call SenGetTimeLeftInFameWeek.

Sentient tracks progress on the server for progress that titles report in the call to SenUpdateFameProgress. When players accumulate enough progress to earn Fame points, Sentient reports these points to the title when you call SenGetAwardMessage. Titles should call SenGetAwardMessage at regular intervals to poll for possible awards and then display awards at the next opportunity within the game.

Displaying Fame VIP Levels

Titles should display the players VIP level, for example, on the Fame VIP menu or a VIP progress bar.

To populate the VIP display:

  • Call SenGetFameVIPLevel to retrieve the VIP information for the current player.

You can also display information such as the current VIP level or the number of points needed to reach the next VIP level.

To retrieve a friendly name for the VIP level:

  • Call SenGetVIPLevelName.

To display VIP information for the player’s Xbox LIVE friends or for participants in a multiplayer game:

  • Call the overloaded SenGetFameVIPLevel.

When players achieve a new VIP level, you should display a message at an appropriate time in the game. After you display the award, call SenAcknowledgeVIPLevelChange to let Sentient know the VIP level was displayed.

VIP level 5, also known as Avatar Superstar, expires one week after the player achieves this level. To determine the time left in this VIP level:

  • Call SenGetTimeLeftInVIPLevel.
Fame Leaderboards

You can create a Fame leaderboard that filters players by their rank in a game, or by the players Xbox LIVE friends.

To retrieve leaderboard entries:

  • Call SenGetFameLeaderboard.


Uploading Fame Challenges to the Sentient Developer Website

Download the Challenge Definition Schema to define Fame challenges for your title. To access this tool and download the schema from the Sentient Developer Website (https://sentient.msgamestudios.com/Default.aspx):

  1. On the Management Tools menu, select Fame Management.
  2. Click on the Challenge Definition Schema link to download it.

Create your Fame challenges and enter them into your Challenge Definition XML document. To upload this document:

  1. On the Management Tools menu, select Fame Management.
  2. Select your title from the drop-down list (if you only have one title, the UI to upload your XML document appears immediately).
  3. Click Browse to upload a new XML document.

After you uploaded the challenge document, they appear in a list on this page.

Form more information on defining Fame challenges, see Fame Challenges.


Fame Challenges

Fame challenges are the activities through which players earn Fame points. There are two types of Fame challenges:

  • Sentient-defined challenges: These challenges are defined across all titles and include purchasing a game or playing a mulitplayer game with friends.
  • Custom title-defined challenges: Challenges that are specific to your title such as unlocking a treasure in a game or winning a hand of cards.

Producers can choose which Sentient-defined challenges to add to their game. More interesting however, are the custom challenges that you define for your title using the Challenge Definition Schema.

Note: Both Sentient-defined and title-defined challenges must be included in the Challenge Definition XML document to enable their collection on the Sentient sever.

All Fame challenges are defined in the Challenge Definition XML document which titles upload to the Sentient Developer Website (https://sentient.msgamestudios.com/FameChallenges.aspx).

Milestones

Milestones are the measure of progress through the defined challenges. When players pass a milestone within a challenge they earn Fame points. Typically, there are multiple milestones repeated within a challenge. For example, every time a player wins five games, they earn a prescribed number of Fame points. Challenges can also be one-time awards such as when players purchase a game.

Milestones that reset weekly are defined as "Weekly Challenges" in the schema while one-time challenges are defined as "Bonus Challenges." For more information, see the Challenge Definition Schema.

The diagram below shows the milestones for a challenge called Games Won. In this challenge, players earn 50 Fame points when they win five games. A milestone is therefore defined as winning five games. The number of milestones for this challenge is unbounded, meaning that players can win an unlimited amount of Fame points.

In this example, the player has a progress of two games toward the first milestone in this challenge.

For more information, see the remarks section of SenFameDisplayData.


Using the Sentient-Defined Challenges

Sentient defines a set of basic Fame challenges that are available to all titles. Sentient collects statistics for some of the Sentient-defined challenges, such as first time play or purchasing a title, and notifies titles when players receive Fame points. For other Sentient-defined challenges, such as participation in multiplayer games or earning avatar awards, titles are required to send progress to Sentient by calling SenUpdateFameProgress.

The Sentient-defined challenges must be included in your title’s Challenge Definition XML document to be included in the game. For more information on the types of challenges available to all titles, see the SenFameProgressID enumeration. For more information on the schema, see the Challenge Definition Schema.

Sentient Challenges in the XML Document

Players receive Fame points for Sentient-defined challenges only after you add them to your Challenge Definition XML document. The following example adds the Sentient challenges to the game and defines the number of Fame points players receive.

<BonusChallenges>

<ChallengeDefinition id="FirstPlay">

<description language="en">Play a game the first time.</description>

<milestone target="1" famePoints="50">

<description language="en">Play a game the first time.</description>

</milestone>

</ChallengeDefinition>

<ChallengeDefinition id="AvatarAward1">

<description language="en">First level avatar award</description>

<milestone target="1" famePoints="50">

<description language="en">First level avatar award</description>

</milestone>

</ChallengeDefinition>

<ChallengeDefinition id="AvatarAward2">

<description language="en">Second level avatar award</description>

<milestone target="1" famePoints="50">

<description language="en">Second level avatar award</description>

</milestone>

</ChallengeDefinition>

<ChallengeDefinition id="FriendsOwnTitle">

<description language="en">An Xbox LIVE friend purchased this game</description>

<milestone target="1" famePoints="50">

<description language="en">An Xbox LIVE friend purchased this game</description>

</milestone>

</ChallengeDefinition>

</BonusChallenges>

In this example, players receive 50 Fame points the first time they play a game. Sentient tracks the challenges defined above and notifies titles when players earn Fame points. Titles poll Sentient for Fame point awards by calling SenGetAwardMessage.


Defining Custom Fame Challenges

Fame challenges are the activities through which players earn Fame points. Players earn points when they pass a milestone within a challenge. Typically there are multiple milestones within a Fame challenge; however, Sentient also defines challenges for which players receive a one-time award (i.e., Fame points) such as when they purchase a game. For an example of a milestone that repeats, see Weekly Challenges below. For more information on milestones in a challenge, see the remarks in SenFameDisplayData.

Sentient defines a set of basic Fame challenges that are available to all titles. For some of these challenges, Sentient collects the statistics on their server and notifies titles when players receive Fame points. The basic Fame challenges collected for all titles include playing a game the first time and friends who own the title. All Sentient defined challenges must be included in the Challenge Definition Schema to be included in the game. For more information on the types of challenges available to all titles, see the SenFameProgressID enumeration.

Using the Challenge Definition Schema, you can also define up to 1024 custom challenges for your title. You can schedule title specific challenges to rotate on a weekly basis or create bonus challenges that never expire. The following types of Fame challenges are defined in the schema:

  • Weekly Challenges: Challenges for which progress is reset weekly.
  • Bonus Challenges: Challenges that do not expire and are never reset.

In addition, the schema also defines the Schedule element to specify a weekly rotation for Weekly challenge types. Weekly and Bonus challenges are assigned integer IDs in the range of 0 to 1023.

Titles send updates to Sentient via SenUpdateFameProgess when players earn progress toward Fame points. To download the Challenge Definition Schema, log into the Fame management page on the Sentient Developer Website (https://sentient.msgamestudios.com/FameChallenges.aspx).

Click on the Challenge Definition Schema link to download the schema and start defining challenges for your title.

Weekly Challenges

Below is an example of a title-defined weekly challenge using the schema. In this example, players earn 75 Fame points when they win five mulitplayer games.

<WeeklyChallenges>

<!-- Title-specific progress -->

<ChallengeDefinition id="11" name="game winner">

<description language="en">Win five games</description>

<milestone target="5" famePoints="75">

<description language="en">You won five games!</description>

</milestone>

</ChallengeDefinition>

<WeeklyChallenges>

To send player progress for these challenges to Sentient:

  • Call SenUpdateFameProgess with the milestoneTypeID set to 11, and the xpGained set to 1 every time a player wins a game.

Sentient aggregates this data on the server and awards 75 Fame points each time the player passes a milestone (i.e., wins five games).

Bonus Challenges

Below is an example Bonus challenge where players receive Fame points for wearing an Avatar Superstar costume. Players receive 25 Fame points the first time they wear a costume in the game.

<BonusChallenges>

<ChallengeDefinition id="22">

<description language="en">Wear a Superstar costume in the game</description>

<description language="fr">[Superstar_Costume_French]</description>

<milestone target="1" famePoints="25">

<description language="en">Wear a Superstar costume in the game</description>

<description language="fr">[Superstar_Costume_French]</description>

</milestone>

</ChallengeDefinition>

<BonusChallenges>

To send player progress for this challenge to Sentient:

  • Call SenUpdateFameProgess with the milestoneTypeID set to 22, and the xpGained set to 1 the first time a player wears a costume.
Schedule Challenges

To schedule title defined challenges on a weekly rotation, use the challenge IDs defined in your xml document as shown in the example below. In this example, challenges IDs 1, 2, and 3 are active the first week and challenge IDs 10, 11, and 12 are active the second week. After the third week completes, the challenge rotations start over at week one.

<Schedule>

<WeekDefinition>

<WeeklyChallenge ChallengeID="1" />

<WeeklyChallenge ChallengeID="2" />

<WeeklyChallenge ChallengeID="3" />

</WeekDefinition>

<WeekDefinition>

<WeeklyChallenge ChallengeID="10" />

<WeeklyChallenge ChallengeID="11" />

<WeeklyChallenge ChallengeID="12" />

</WeekDefinition>

<WeekDefinition>

<WeeklyChallenge ChallengeID="20" />

<WeeklyChallenge ChallengeID="21" />

<WeeklyChallenge ChallengeID="22" />

</WeekDefinition>

</Schedule>


Fame Reference

This section contains reference information for the Microsoft Sentient APIs.

In This Section

Fame Functions

Fame Structures

Fame Enumerations

Challenge Definition Schema


Fame Functions

This section contains API reference functions that you use with the Microsoft Sentient APIs.

In This Section

Progress Functions
Function | Description
SenGetFameDisplayDataCount | Returns the maximum number of items that will be returned in the call to SenGetFameDisplayData.
SenGetFameDisplayData | Returns a collection of structures that contain a player's progress toward a Fame challenge. For display on the Fame progress screen.
SenUpdateFameProgress | Sends player's progress toward a Fame challenge to the Sentient server.
SenFlushFameProgress | Manually commits Fame progress writes to the Sentient servers.
SenGetTimeLeftInFameWeek | Retrieves the time remaining before progress in a Fame challenge is reset.
SenGetAwardMessage | Polls the Sentient Service for an award message.
SenRegisterFameMPGame | Registers the participants in a multiplayer game and reports the results to Sentient.

VIP Rewards Functions
Function | Description
SenGetFameVIPLevel | Returns a summary of the players VIP information.
SenGetFameVIPLevel (overloaded) | Returns the Fame and VIP information for a collection of players.
SenAcknowledgeVIPLevelChange | Acknowledges a change in the VIP level reported by the Sentient server.
SenGetTimeLeftInVIPLevel | Retrieves the time left before a transient VIP level is reset.
SenGetVIPLevelName | Returns the localized name of the specified VIP level.
Leaderboards Functions
Function | Description
SenGetFameLeaderboard | Returns a ranked and filtered collection of Fame leaderboard entries.


SenGetFameDisplayDataCount Function

Returns the maximum number of items that will be returned in the call to SenGetFameDisplayData.

Syntax

C ++
HRESULT SenGetFameDisplayDataCount(
   size_t  *out_count
);

Parameters

out_count

[out] A pointer to the maximum number of SenFameDisplayData structures that will be returned in the call to SenGetFameDisplayData.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The operation completed successfully.

E_FAIL

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_count pointer is NULL.

SENTIENT_S_OPERATION_IN_PROGRESS

The call could not be completed immediately and out_count has not been filled in. Try this call again later.

Remarks

Titles can call this function to determine the size of the buffer required for the call to SenGetFameDisplayData.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Functions

SenGetFameDisplayData

SenGetTimeLeftInFameWeek

SenGetAwardMessage


SenGetFameDisplayData Function

Returns a collection of structures that contains a player's progress toward a Fame challenge. For display on the Fame progress screen.

Syntax

C ++
HRESULT SenGetFameDisplayData(
   int  userIndex,
   size_t  startIndex,
   size_t  maxDisplayDataCount,
   size_t  *out_dataCount,
   SenFameDisplayData  *out_displayData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

startIndex

[in] The index of the first item returned in out_displayData. This parameter is only used for paged results and may be set to 0 for non-paged results.

maxDisplayDataCount

[in] The maximum number of items that can be returned in out_displayData. For non-paged results, this is the number of items returned in the call to SenGetFameDisplayDataCount.

out_dataCount

[out] A pointer to the number of items returned in out_displayData after Sentient invokes the callback.

out_displayData

[out] A pointer to a collection of SenFameDisplayData structures that will contain the player's Fame progress toward a challenge after Sentient invokes the callback.

This parameter must be allocated to maxDisplayDataCount*(sizeof)SenFameDisplayData bytes.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The operation completed successfully.

E_FAIL

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_INVALIDARG

startIndex is greater than the total number of items available.

E_POINTER

The out_dataCount or out_displayData pointer is NULL.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_S_OPERATION_IN_PROGRESS

This call could not be completed immediately and the output parameters have not been filled in. Try this call again later.

Remarks

Before you call this function, call SenGetFameDisplayDataCount to determine the size of the out_displayData buffer. Alternately, you can use the start index parameter to page Fame challenge results in multiple calls to this function.

To page Fame challenge results:

  1. Call SenGetFameDisplayData with the startIndex = 0 and maxDisplaydataCount = 10.
  2. Then call to SenGetFameDisplayData with the startIndex = 10 and maxDisplaydataCount = 10.
  3. Repeat this sequence until you reach the maximum number of display items.

This function returns a SenFameDisplayData structure for every type of Fame challenge tracked by a title. If your titles rotates challenges on a weekly basis, this function only returns milestones that are active for the current week.

The Fame display data returned from this function is displayed to players on the Fame progress screen.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Functions

SenGetFameDisplayDataCount

SenGetTimeLeftInFameWeek

SenGetAwardMessage


SenUpdateFameProgress Function

Sends player's progress toward a Fame challenge to the Sentient server.

Syntax

C ++
HRESULT SenUpdateFameProgress(
   int  userIndex,
   unsigned int  milestoneTypeID,
   unsigned int  xpGained
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

milestoneTypeID

[in] The ID of the challenge for which progress is reported.

This can be one of the Sentient-defined SenFameProgressIDs or a challenge defined by the title. Title-defined challenges are in the range 0 to 1023.

xpGained

[in] The amount of progress earned toward a milestone. For binary milestones such as events, this can be set to 1 each call.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The operation completed successfully.

E_FAIL

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_E_BUFFER_EXHAUSTED

The progress update failed because Sentient's internal buffer is full.

Remarks

Titles should call this function when a player achieves progress towards a Fame milestone. For example, if you define a "Games Won" challenge in your title's Challenge Definition Schema, you call SenUpdateFameProgress with xpGained set to 1 every time a player wins a game. If your challenge defines a milestone as winning five games, each time you call SenUpateFameProgress, players earn one progress toward the five they need to earn Fame points. After five games, the player receives 200 Fame Points. For more information, see the Defining Custom Fame Challenges topic.

Sentient may buffer progress on the client for a time before sending it to the server for long term storage and aggregation. To commit the progress on the Sentient servers, titles should call SenFlushFameProgress at appropriate times in the game such as a game save event.

When

Note: Titles do not submit progress for milestones such as game purchase that Sentient tracks directly. Challenges that are defined by the title must track progress by calling this function. For more information on milestones tracked by Sentient, see SenFameProgressID.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Functions

SenRegisterFameMPGame

SenFlushFameProgress

Challenge Definition Schema

Defining Custom Fame Challenges


SenFlushFameProgress Function

Manually commits Fame progress writes to the Sentient servers.

Syntax

C ++
HRESULT SenFlushFameProgress(
   int  userIndex,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

There is no data to flush on the client.

E_FAIL

Sentient failed to spawn the call to the server (there may already be a flush in progress).

E_POINTER

The userCallback pointer is NULL.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_E_TOO_MANY_CALLS

This request was rejected to avoid excessive server load; try again later.

Remarks

Sentient aggregates Fame progress on the server; however, to prevent excessive server load, progress may be buffered on the client for a time before it is sent to the server. Call this function to ensure that all progress updates (from call to SenUpdateFameProgress) are committed to the server. Sentient invokes the callback function when the server call completes and the Fame data has been updated. If there is no data to flush on the client, the callback is invoked before this function returns with the status code S_OK.

You should call this function only on appropriate events such when the game initiates a game save on the client.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Functions

SenRegisterFameMPGame

SenUpdateFameProgress


SenGetTimeLeftInFameWeek Function

Retrieves the time remaining before progress in a Fame challenge is reset.

Syntax

C ++
HRESULT SenGetTimeLeftInFameWeek(
   SenFameTime  *out_timeRemaining
);

Parameters

out_timeRemaining

[out] A pointer to the SenFameTime structure that contains the time remaining in the challenge.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The operation completed successfully and out_timeRemaining has been filled in.

E_FAIL

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_timeRemaining pointer is NULL.

SENTIENT_S_OPERATION_IN_PROGRESS

The call could not be completed immediately and out_timeRemaining has not been filled in. Try this call again later.

Remarks

You can define custom Fame challenges that rotate weekly in the Challenge Definition Schema. Use the time remaining returned from this function to display a timer for weekly Fame challenges on the Fame Progress Menu.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Functions

SenGetFameDisplayDataCount

SenGetFameDisplayData

SenGetAwardMessage


SenGetAwardMessage Function

Polls the Sentient Service for an award message.

Syntax

C ++
HRESULT SenGetAwardMessage(
   int  userIndex,
   SenAwardMessageData  *out_awardData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

out_awardData

[out] A pointer to a SenAwardMessageData structure that contains the award information.

Note: If there is no award, this structure is not filled in.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The operation completed successfully and out_awardData contains a valid award.

S_FALSE

The operation completed successfully but there is no valid award to report (out_awardData is not filled in).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_awardData pointer is NULL.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_S_OPERATION_IN_PROGRESS

The call could not be completed immediately and out_awardData has not been filled in. Try this call again later.

Remarks

When players earn Fame points, Sentient creates an award message and stores it on the server. Titles poll Sentient on a regular basis to retrieve these award messages. You should only call this function when the game is able to display an award message. For example, do not call this function when the game is in the "On Game Load" state. You may call this function as often as you need to poll for possible awards. After this call, Sentient removes the award message from the internal queue.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Functions

SenGetFameDisplayDataCount

SenGetFameDisplayData

SenGetTimeLeftInFameWeek


SenRegisterFameMPGame Function

Registers the participants in a multiplayer game and reports the results to Sentient.

Syntax

C ++
HRESULT SenRegisterFameMPGame(
   int  userIndex,
   size_t  participantCount,
   const SenFameMPGameParticipant  *participants,
   SenHandle  *out_senHandle,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

participantCount

[in] The number of valid participants in the game.

participants

[in] A pointer to a collection of SenFameMPGameParticipant structures that contain information about every participant in a game.

out_senHandle

[out] A handle to the asynchronous task that can be used to call SentientCancel on this operation. This parameter is optional and may be set to NULL.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

E_POINTER

The participants pointer is NULL.

E_INVALIDARG

The userCallback parameter is NULL and out_SenHandle is non-NULL.

The participantCount is less than 2.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

Remarks

Using this function, titles report the results of a multiplayer game to Sentient for tracking players' progress toward certain Fame challenges.

For proper tracking, titles must call this function independently for each player when the game completes.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Functions

SenUpdateFameProgress

SenFlushFameProgress


SenGetFameVIPLevel Function

Returns a summary of the players VIP information.

Syntax

C ++
HRESULT SenGetFameVIPLevel(
   int  userIndex,
   SenFameVIPData  *out_fameVIPData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

out_fameVIPData

[in] A pointer to the SenFameVIPData structure that contains the VIP information. This structure is pre-allocated to the size of at least one structure.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The operation completed successfully.

E_FAIL

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_fameVIPData pointer is NULL.

SENTIENT_E_GUEST_ACCESS_VIOLATION*

A guest and may not spawn this call.

SENTIENT_S_OPERATION_IN_PROGRES

The call could not be completed immediately and out_fameVIPData has not been filled in.

Remarks

Call this function frequently to continuously update the player's VIP level while it is displayed on the game screen.

To track changes in the VIP level, call this function at regular intervals and examine the current VIP level against the last acknowledged VIP level in the SenFameVIPData structure. If the VIP levels are different, display a message to the player and then call SenAcknowledgeVIPLevelChange to reset the VIP level returned in the SenFameVIPData structure.

To retrieve the VIP information for a player's Xbox LIVE friends or participants in a multiplayer game, call SenGetFameVIPLevel.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Functions

SenGetFameVIPLevel (overloaded)

SenGetFameVIPLevelName

SenGetTimeLeftInVIPLevel

SenAcknowledgeVIPLevelChange


SenGetFameVIPLevel Function (overloaded)

Returns the Fame and VIP information for a collection of players.

Syntax

C ++
HRESULT SenGetFameVIPLevel(
   int  userIndex,
   size_t  userIDCount,
   const XUID  *userIDArray,
   SenFameVIPData  *out_userFameVIPArray,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

userIDCount

[in] The number of valid XUIDs in the out_userFameVIPArray parameter.

userIDArray

[in] A pointer to an array of XUIDs for whom VIP data is retrieved.

out_userFameVIPArray

[out] A pointer to a collection of SenFameVIPData structures that will contain the VIP information after Sentient invokes the callback.

This is a pre-allocated array of size userIDCount*(sizeof)SenFameVIPData bytes.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_userFameVIPArray pointer is NULL.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT__E_TOO_MANY_CALLS

This call has been rejected to avoid excessive server load. Try again later.

Remarks

This overloaded function can be used to retrieve VIP status for a player's XBox LIVE friends or participants in a multiplayer game for example. Call this when you enter the Fame VIP menu to display the VIP status of the requested players.

To retrieve only the local players VIP information, call SenGetFameVIPLevel.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Functions

SenGetFameVIPLevel

SenGetFameVIPLevelName

SenGetTimeLeftInVIPLevel

SenAcknowledgeVIPLevelChange


SenAcknowledgeVIPLevelChange Function

Acknowledges a change in the VIP level reported by the Sentient server.

Syntax

C ++
HRESULT SenAcknowledgeVIPLevelChange(
   int  userIndex
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenSuperstarD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

Remarks

Titles are required to display a message to players when their VIP level changes. Sentient tracks the players current and last acknowledged VIP level in the SenFameVIPData structure and returns this information in the call to SenGetFameVIPLevel. When the players VIP level changes, you should display this information to the player and then call this function to reset the last acknowledged VIP level.

Note: Only call this function after you display the new VIP level to the player.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

SenGetFameVIPLevel (overloaded)

Fame Functions

SenGetFameVIPLevel

SenGetFameVIPLevelName

SenGetTimeLeftInVIPLevel


SenGetTimeLeftInVIPLevel Function

Retrieves the time left before a transient VIP level is reset.

Syntax

C ++
HRESULT SenGetTimeLeftInVIPLevel(
   int  userIndex,
   SenFameTime  *out_timeRemaining
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

out_timeRemaining

[out] A pointer to the SenFameTime structure that contains the remaining time.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The operation completed successfully and out_timeRemaining has been filled in.

S_FALSE

The VIP level of the supplied user does not expire; out_timeRemaining has not been filled in.

E_FAIL

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_timeRemaining pointer is NULL.

SENTIENT_S_OPERATION_IN_PROGRESS

The call could not be completed immediately and out_timeRemaining has not been filled in. Try this call again later.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

Remarks

Call this function to display a timer with the time remaining in a VIP level. Currently, only the Fame Superstar status, VIP level 5, expires every week. The timer for this VIP level starts when the player achieves level 5.

Requirements

Header: SenClientFame.h

Library: SenCore.lib

See Also

Fame Functions

SenGetFameVIPLevel

SenGetFameVIPLevel (overloaded)

SenGetFameVIPLevelName

SenAcknowledgeVIPLevelChange


SenGetVIPLevelName Function

Returns the localized name of the specified VIP level.

Syntax

C ++
HRESULT SenGetVIPLevelName(
   unsigned  int vipLevel,
   size_t  maxNameLength,
   wchar_t  *out_name
);

Parameters

vipLevel

[in] The VIP level whose name is returned. This is a member of the SenFameVIPLevel enumeration.

maxNameLength

[in] The maximum length (including null terminators) of the returned string.

out_name

[out] A pointer to a string that contains the localized name of the VIP level. This parameter is pre-allocated to maxNameLength characters.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The operation completed successfully.

E_POINTER

The out_name pointer is NULL.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_INVALIDARG

vipLevel is outside the range of known VIP levels.

SENTIENT_S_OPERATION_IN_PROGRESS

The call could not be completed immediately and out_name has not been filled in. Try this call again later.

Remarks

This function returns the Sentient-defined name for the specified VIP level.

If this function returns SENTIENT_S_OPERATION_IN_PROGRESS, call it again on the next iteration of the update loop to try again.

To return localized strings, Sentient uses the system language and locale settings on the local machine. To retrieve the localization settings on the machine, call XGetLocale or XGetLanguage.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Functions

SenGetFameVIPLevel

SenGetFameVIPLevel (overloaded)

SenGetTimeLeftInVIPLevel

SenAcknowledgeVIPLevelChange


SenGetFameLeaderboard Function

Returns a ranked and filtered collection of Fame leaderboard entries.

Syntax

C ++
HRESULT SenGetFameLeaderboard(
   int  userIndex,
   const SenFameLeaderboardRequest  &leaderboardRequest,
   size_t  entryCountMax,
   SenFameLeaderboardEntry  *out_entryArray,
   SenFameLeaderboardResults  *out_leaderboardResults,
   SenHandle  *out_senHandle,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

leaderboardRequest

[in] A pointer to a SenFameLeaderboardRequest structure that defines the parameters for this query.

entryCountMax

[in] The maximum number of leaderboard entries to return.

out_entryArray

[out] A pointer to a collection of SenFameLeaderboardEntry structures that will contain the leaderboard entries after Sentient invokes the callback.

This is a pre-allocated array of size entryCountMax*(sizeof) SenFameLeaderboardEntry bytes.

out_leaderboardResults

[out] A pointer to a collection of SenFameLeaderboardResults that will contain the leaderboard entries after Sentient invokes the callback.

out_senHandle

[out] A handle to the asynchronous task that can be used to call SentientCancel on this operation. This parameter is optional and may be set to NULL.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

E_INVALIDARG

The userCallback is NULL and out_senHandle is non-NULL. Task handles are not supported for synchronous requests.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_entryArray or out_leaderboardResults pointer is NULL.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

SENTIENT_E_TOO_MANY_CALLS

This call was rejected to avoid excessive server load. Try again later.

Remarks

Call this function when you enter the Fame leaderboard menu to retrieve the leaderboard entries.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Functions

SenFameLeaderboardEntry

SenFameLeaderboardRequest

SenFameLeaderboardResults

SenFameLeaderboardRankType

SenFameLeaderboardFilter


Fame Structures

This section contains API reference structures that you use with the Microsoft Sentient APIs.

In This Section

Structure | Description
SenAwardMessageData | Contains information about an award achieved by a player.
SenFameDisplayData | SenFameDisplayData Structure
SenFameLeaderboardEntry | Contains a single leaderboard entry for a Fame leaderboard.
SenFameLeaderboardRequest | Contains the information about a Fame leaderboard query.
SenFameLeaderboardResults | Contains information about the results of a leaderboard query.
SenFameMPGameParticipant | Contains information about the participants in a multiplayer game.
SenFameTime | Contains the measure of a period of time.
SenFameVIPData | Contains a summary of the player's VIP information.


SenFameDisplayData Structure

Contains information about a player's progress toward a Fame challenge.

Syntax

C ++
struct SenFameDisplayData{
   wchar_t  milestoneTypeDescription[128];
   SenFameProgressID  milestoneTypeID;
   unsigned int  milestoneCount;
   unsigned int  currentMilestone;
   unsigned int  xpSinceLastMilestone;
   unsigned int  xpToNextMilestone;
   unsigned int  famePointsSoFar;
   unsigned int  famePointsMaximum;
   bool  isWeekly;
};

Members

milestoneTypeDescription

A localized string that describes the challenge tracked by this structure.

milestoneTypeID

A member of the SenFameProgressID enumeration that describes the Fame challenge tracked by this structure.

This can also be one of the title-specific challenges defined in the Challenge Definition Schema. Title-defined ids are in the range 0-1023.

milestoneCount

The number of milestones, and associated awards, available for this challenge. This may be unbounded (SenFameCount_Unbounded).

currentMilestone

The zero-based index of the current milestone in this Fame challenge.

xpSinceLastMilestone

The progress achieved since the last milestone in this Fame challenge.

xpToNextMilestone

The progress required to achieve the next milestone in this Fame challenge.

famePointsSoFar

The total lifetime Fame points achieved in this challenge.

famePointsMaximum

The number of Fame points available in this challenge. This may be unbounded (SenFameCount_Unbounded).

isWeekly

true if the progress for this challenge is reset weekly; otherwise false.

Remarks

SenGetFameDisplayData returns a SenFameDisplayData structure for each Fame challenge tracked for a player.

Use the information in this structure to populate the progress toward a specific milestone in this Fame challenge.

The diagram below shows the milestones for a challenge called Games Won. In this challenge, players earn 50 Fame points when they win five games. Given this, a milestone is defined as winning five games, and progress toward this milestone is the actual number of games that a player has won since the last milestone. There are three milestones shown in the diagram below; however, the number of milestones for this challenge is unbounded, meaning that players can win an unlimited amount of Fame points.

Consider the example where a player has won two games. In this example, the display data is as follows:

Milestone Description: Number of Games Won.

Milestone Type ID: This is a title-defined challenge. The Challenge ID is defined in the Challenge Definition Schema.

Milestone Count: Unbounded (SenFameCount_Unbounded).

Current Milestone: 0.

Experience Since Last Milestone: 2.

Experience to next Milestone: 3.

Fame Points so Far: 0.

Fame Points Maximum: Unbounded (SenFameCount_Unbounded).

Is Weekly: False .

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Structures

SenGetFameDisplayData


SenFameMPGameParticipant Structure

Contains information about the participants in a multiplayer game.

Syntax

C ++
struct SenFameMPGameParticipant{
   XUID  user;
   bool  winner;
};

Members

user

The XUID of the player who should get credit for playing in multi-player game.

winner

true if the specified player is the winner; otherwise false.

Remarks

Players receive Fame points for playing in a multiplayer game. This structure identifies a multiplayer game participant registered in the call to SenRegisterFameMPGame.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Structures

SenRegisterFameMPGame


SenAwardMessageData Structure

Contains information about an award achieved by a player.

C ++
struct SenAwardMessageData{
   wchar_t  awardDesc[128];
   unsigned int  awardPoints;
   unsigned int  awardTrigger;
};

Members

awardDesc

A localized string that contains the award message to display. For title-defined challenges, this description is defined in the Challenge Definition Schema.

awardPoints

The number of Fame points that the player receives for this award.

awardTrigger

The progress in the challenge that triggered this award.

Remarks

This structure is returned from the SenGetAwardMessage function. Titles should display an award message to players at an appropriate time in game play.

To return localized strings, Sentient uses the system language and locale settings on the local machine. To retrieve the localization settings on the machine, call XGetLocale or XGetLanguage.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Structures

SenGetAwardMessage


SenFameVIPData Structure

Contains a summary of the player's VIP information.

Syntax

C ++
struct SenFameVIPData{
   XUID  user;
   unsigned int  vipLevel;
   unsigned int  lastAckedVIPLevel;
   unsigned int  famePointsCurrent;
   unsigned int  famePointsWeek;
   unsigned int  famePointsLifetime;
   unsigned int  pointsToNextLevel;
   unsigned int  superstarCounter;
   SYSTEMTIME  vipLevelExpiresAt;
   bool  vipLevelExpires;
};

Members

user

The XUID of the player whose status is described in this structure.

vipLevel

The current VIP level of the player. This is an integer between 0 and 5.

lastAckedVIPLevel

The last acknowledged VIP level of the player. If this value is different than the current VIP level, you must acknowledge a change in the VIP level by calling SenAcknowledgeVIPLevelChange.

famePointsCurrent

The Fame points accrued across all Fame titles since the last VIP level.

famePointsWeek

The Fame points accrued across all Fame titles this week.

famePointsLifetime

The Fame points accrued across all Fame titles over the user's history.

pointsToNextLevel

The Fame points required to reach the next VIP level.

superstarCounter

The number of times the player reached Avatar Superstar status (VIP level 5).

vipLevelExpiresAt

The date that the current VIP level expires. This is relevant only when vipLevelExpires is set to true.

vipLevelExpires

true if the current VIP levels expires; otherwise false.

Remarks

This structure is returned by SenGetFameVIPLevel and SenGetFameVIPLevel (overloaded).

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Structures

SenGetTimeLeftInVIPLevel

SenGetFameVIPLevel

SenGetFameVIPLevel (overloaded)

SenGetFameVIPLevelName

SenAcknowledgeVIPLevelChange

SenFameVIPLevel


SenFameLeaderboardEntry Structure

Contains a single leaderboard entry for a Fame leaderboard.

Syntax

C ++
struct SenFameLeaderboardEntry{
   XUID  user;
   unsigned int  vipLevel;
   unsigned int  famePoints;
   unsigned int  superstarCounter;
   unsigned int  rank;
};

Members

user

The XUID of the player on the leaderboard.

vipLevel

The VIP level of the player. This can be 0 through 5.

famePoints

The number of Fame points for this player. Fame points may be weekly or lifetime depending on the challenge.

rank

The rank of this player on the leaderboard. If this is a filtered leaderboard, this is the rank within the global list, not the filtered list.

superstarCounter

The number of times this player has achieved Avatar Superstar status (VIP level 5).

Remarks

This is returned in the call to SenGetFameLeaderboard to retrieve the information about the entries on a Fame leaderboard.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Structures

SenGetFameLeaderboard

SenFameLeaderboardRequest

SenFameLeaderboardResults

SenFameLeaderboardFilter

SenFameLeaderboardRankType


SenFameLeaderboardResults Structure

Contains information about the results of a leaderboard query.

Syntax

C ++
struct SenFameLeaderboardResults{
   unsigned int  playerIndex;
   size_t  numEntriesReturned;
   size_t  numLeaderboardEntries;
};

Members

playerIndex

The index (or row) of the player that initiated this call on the leaderboard.

numEntriesReturned

The number of entries returned by this query.

numLeaderboardEntries

The number of entries (or rows) on the leaderboard. This may be greater than the number of entries returned for paged results.

Remarks

This structure is returned in the call to SenGetFameLeaderboard to summarize the leaderboard.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Structures

SenGetFameLeaderboard

SenFameLeaderboardEntry

SenFameLeaderboardRequest

SenFameLeaderboardFilter

SenFameLeaderboardRankType


SenFameLeaderboardRequest Structure

Contains the information about a Fame leaderboard query.

Syntax

C ++
struct SenFameLeaderboardRequest{
   SenFameLeaderboardRankType  type;
   SenFameLeaderboardFilter  filter;
   int  startIndex;
};

Members

type

A member of the SenFameLeaderboardRankType enumeration that describes the rank option for this leaderboard.

filter

A member of the SenFameLeaderboardFilter enumeration that describes the filter for this leaderboard.

startIndex

The starting rank for the leaderboard query. Set this to -1 to center the leaderboard on the player associated with this leaderboard.

Remarks

This is used in the call to SenGetFameLeaderboard to specify the properties of the leaderboard.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Structures

SenGetFameLeaderboard

SenFameLeaderboardEntry

SenFameLeaderboardResults

SenFameLeaderboardFilter

SenFameLeaderboardRankType


SenFameTime Structure

Contains the measure of a period of time.

Syntax

C ++
struct SenFameTime{
   int days;
   int hours;
   int minutes;
   int seconds;
};

Members

days

The number of days.

hours

The number of hours.

minutes

The number of minutes.

seconds

The number of seconds.

Remarks

This structure provides a display-friendly way to report the time remaining in a Fame week or VIP level. It is returned from SenGetTimeLeftInFameWeek and SenGetTimeLeftInVIPLevel.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Structures

SenGetTimeLeftInFameWeek

SenGetTimeLeftInVIPLevel


Fame Enumerations

This section contains API reference enumerations that you use with the Microsoft Sentient APIs.

In This Section

Enumeration | Description
SenFameCount | Defines the constants returned when a Sentient API returns a count.
SenFameLeaderbaordFilter | Defines the filter for a Fame leaderboard.
SenFameLeaderbaordRankType | Defines the ranking options for a Fame leaderboard.
SenFameProgressID | Defines the types of Fame challenges for which progress is being tracked.


SenFameCount Enumeration

Defines the constants returned when a Sentient API returns a count.

Syntax

C ++
enum SenFameCount : unsigned int{
   SenFameCount_Unbounded = 0xffffffff
};

Constants

SenFameCount_Unbounded

There is no fixed limit on the number of items returned.

Remarks

The following functions returns a count such as the SenFameDisplayData structure returned in the call to SenGetFameDisplayData.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Enumerations

SenGetFameDisplayData

SenFameDisplayData


SenFameProgressID Enumeration

Defines the types of Fame challenges for which progress is being tracked.

Syntax

C ++
enum SenFameProgressID{
   SenFameProgressID_TitleDefinedFirst = 0,
   SenFameProgressID_TitleDefinedLast  = 1023,
   SenFameProgressID_FirstPlay         = 1024,
   SenFameProgressID_AvatarAward1,
   SenFameProgressID_AvatarAward2,
   SenFameProgressID_FriendsOwnTitle,
   SenFameProgressID_MPWithFriend,
   SenFameProgressID_MPWithVIP1,
   SenFameProgressID_MPWithVIP2,
   SenFameProgressID_MPWithVIP3,
   SenFameProgressID_MPWithVIP4,
   SenFameProgressID_MPWithVIP5,
   SenFameProgressID_FriendsAtVIP1,
   SenFameProgressID_FriendsAtVIP2,
   SenFameProgressID_FriendsAtVIP3,
   SenFameProgressID_FriendsAtVIP4,
   SenFameProgressID_FriendsAtVIP5,
   SenFameProgressID_Invalid          = 0xffffffff
};

Constants

SenFameProgressID_TitleDefinedFirst

The ID of the first title-defined challenge. Titles submit progress toward this challenge in the call to SenUpdateFameProgress.

SenFameProgressID_TitleDefinedLast

The last possible ID for a title-defined challenge. Titles submit progress toward this challenge in the call to SenUpdateFameProgress.

SenFameProgressID_FirstPlay

The ID for a challenge that tracks the first time a user plays a game.

Note: This challenge is implemented on the Sentient Server; titles do no submit updates for this.

SenFameProgressID_AvatarAward1

The ID for an Avatar level 1 award challenge. Titles submit progress toward this challenge in the call to SenUpdateFameProgress.

SenFameProgressID_AvatarAward2

The ID for an Avatar level 2 award challenge. Titles submit progress toward this challenge in the call to SenUpdateFameProgress.

SenFameProgressID_FriendsOwnTitle

The ID for a challenge that tracks the players Xbox LIVE friends who purchase the game.

Note: This milestone is tracked on the Sentient Server; titles do not submit updates.

SenFameProgressID_MPWithFriend

This challenge is currently not implemented. For more information, contact senhelp@microsoft.com.

SenFameProgressID_MPWithVIP1

This challenge is currently not implemented. For more information, contact senhelp@microsoft.com.

SenFameProgressID_MPWithVIP2

This challenge is currently not implemented. For more information, contact senhelp@microsoft.com.

SenFameProgressID_MPWithVIP3

This challenge is currently not implemented. For more information, contact senhelp@microsoft.com.

SenFameProgressID_MPWithVIP4

This challenge is currently not implemented. For more information, contact senhelp@microsoft.com.

SenFameProgressID_MPWithVIP5

This challenge is currently not implemented. For more information, contact senhelp@microsoft.com.

SenFameProgressID_FriendsAtVIP1

This challenge is currently not implemented. For more information, contact senhelp@microsoft.com.

SenFameProgressID_FriendsAtVIP1

This challenge is currently not implemented. For more information, contact senhelp@microsoft.com.

SenFameProgressID_FriendsAtVIP3

This challenge is currently not implemented. For more information, contact senhelp@microsoft.com.

SenFameProgressID_FriendsAtVIP4

This milestone is currently not implemented. For more information, contact senhelp@microsoft.com.

SenFameProgressID_FriendsAtVIP5

This milestone is currently not implemented. For more information, contact senhelp@microsoft.com.

SenFameProgressID_Invalid

This challenge is reserved, do not use.

Remarks

The members of this enumeration must be in the Challenge Definition Schema to be included in the challenges tracked for a title.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Enumerations

SenUpdateFameProgress

Challenge Definition Schema

Defining Custom Fame Challenges


SenFameVIPLevel Enumeration

Defines the Fame VIP levels.

Syntax

C ++
enum SenFameVIPLevel{
   SenFameVIPLevel_Unknown     = 0xFFFFFFFF,
   SenFameVIPLevel_Fan         = 0,
   SenFameVIPLevel_Newcomer    = 1,
   SenFameVIPLevel_UpAndComing = 2,
   SenFameVIPLevel_Headliner   = 3,
   SenFameVIPLevel_Star        = 4,
   SenFameVIPLevel_Superstar   = 5,
};

Members

SenFameVIPLevel_Unknown

This VIP level is reserved, do not use.

SenFameVIPLevel_Fan

The first VIP level.

SenFameVIPLevel_Newcomer

The second VIP level.

SenFameVIPLevel_UpAndComing

The third VIP level.

SenFameVIPLevel_Headliner

The fourth VIP level.

SenFameVIPLevel_Star

The fifth VIP level.

SenFameVIPLevel_Superstar

The sixth VIP level. This is also referred to as Avatar Superstar. This VIP level expires weekly and players then return to SenFameVIPLevel_Star.

Remarks

Players earn Fame points to achieve VIP levels. These VIP levels are used in the SenFameVIPData structure to report a player's VIP level.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Enumerations

SenGetTimeLeftInVIPLevel

SenGetFameVIPLevel

SenGetFameVIPLevel (overloaded)

SenGetFameVIPLevelName

SenAcknowledgeVIPLevelChange

SenFameVIPData


SenFameLeaderboardFilter Enumeration

Defines the filter for a Fame leaderboard.

Syntax

C ++
enum SenFameLeaderboardFilter{
   SenFameLeaderboardFilter_Everyone = 0,
   SenFameLeaderboardFilter_Friends,
};

Constants

SenFameLeaderboardFilter_Everyone

The leaderboard is not filtered.

SenFameLeaderboardFilter_Friends

The leaderboard is filtered by the player's Xbox LIVE friends.

Remarks

This is used in the SenFameLeaderboardRequest to filter the leaderboard. Titles retrieve the leaderboard entries in the call to SenGetFameLeaderboard.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Enumerations

SenGetFameLeaderboard

SenFameLeaderboardEntry

SenFameLeaderboardRequest

SenFameLeaderboardResults

SenFameLeaderboardRankType


SenFameLeaderboardRankType Enumeration

Defines the ranking options for a Fame leaderboard.

Syntax

C ++
enum SenFameLeaderboardRankType{
   SenFameLeaderboardRankType_Week
   SenFameLeaderboardRankType_Lifetime,
   SenFameLeaderboardRankType_Superstar
};

Constants

SenFameLeaderboardRankType_Week

The leaderboard is ranked by Fame points earned this week.

SenFameLeaderboardRankType_Lifetime

The leaderboard is ranked by Fame points earned for all time.

SenFameLeaderboardRankType_Superstar

The leaderboard is ranked by Avatar Superstar status.

Remarks

This is used in the SenFameLeaderboardRequest to specify the type of rank for the leaderboard returned in the call to SenGetFameLeaderboard.

Requirements

Header: SenClientFame.h

Library: SenSuperstars.lib

See Also

Fame Enumerations

SenGetFameLeaderboard

SenFameLeaderboardEntry

SenFameLeaderboardRequest

SenFameLeaderboardResults

SenFameLeaderboardFilter


Challenge Definition Schema

Defines the elements and types to create custom Fame challenges for your title.

Syntax

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:fc="urn:microsoft:games:sentient:fame:common" attributeFormDefault="unqualified" elementFormDefault="unqualified">

<xs:import namespace="urn:microsoft:games:sentient:fame:common" schemaLocation="FameCommon.xsd"/>

<xs:simpleType name="IDType">

<xs:union>

<xs:simpleType>

<xs:restriction base="xs:integer">

<xs:minInclusive value="0"/>

<xs:maxInclusive value="1023"/>

</xs:restriction>

</xs:simpleType>

<xs:simpleType>

<xs:restriction base="xs:string">

<xs:enumeration value="FirstPlay"/>

<xs:enumeration value="AvatarAward1"/>

<xs:enumeration value="AvatarAward2"/>

<xs:enumeration value="FriendsOwnTitle"/>

<xs:enumeration value="MPWithFriend"/>

<xs:enumeration value="MPWithVIP1"/>

<xs:enumeration value="MPWithVIP2"/>

<xs:enumeration value="MPWithVIP3"/>

<xs:enumeration value="MPWithVIP4"/>

<xs:enumeration value="MPWithVIP5"/>

<xs:enumeration value="FriendsAtVIP1"/>

<xs:enumeration value="FriendsAtVIP2"/>

<xs:enumeration value="FriendsAtVIP3"/>

<xs:enumeration value="FriendsAtVIP4"/>

<xs:enumeration value="FriendsAtVIP5"/>

</xs:restriction>

</xs:simpleType>

</xs:union>

</xs:simpleType>

<xs:complexType name="MilestoneType">

<xs:sequence>

<xs:element name="description" type="fc:DescriptionType" minOccurs="1" maxOccurs="unbounded">

<xs:annotation>

<xs:documentation>

A user-friendly, localizable string describing the criteria for this milestone, as achieved, e.g. 'Gained 500 Experience Points'

</xs:documentation>

</xs:annotation>

</xs:element>

</xs:sequence>

<xs:attribute name="target" type="xs:integer" use="required">

<xs:annotation>

<xs:documentation>

Defines the progress required within the enclosing Challenge to achieve this milestone.

</xs:documentation>

</xs:annotation>

</xs:attribute>

<xs:attribute name="famePoints" type="xs:integer" use="required">

<xs:annotation>

<xs:documentation>

Defines the Fame Points awarded when this milestone is achieved.

</xs:documentation>

</xs:annotation>

</xs:attribute>

</xs:complexType>

<xs:complexType name="RepeatableMilestoneType">

<xs:complexContent>

<xs:extension base="MilestoneType">

<xs:attribute name="repeatAt" type="xs:integer" use="required">

<xs:annotation>

<xs:documentation>

Defines the progress interval within the enclosing Challenge at which this milestone will re-fire.

</xs:documentation>

</xs:annotation>

</xs:attribute>

</xs:extension>

</xs:complexContent>

</xs:complexType>

<xs:complexType name="FameChallengeType">

<xs:sequence>

<xs:element name="description" type="fc:DescriptionType" minOccurs="1" maxOccurs="unbounded">

<xs:annotation>

<xs:documentation>

A user-friendly, localizable string describing the challenge, e.g. 'Gain Experience Points'

</xs:documentation>

</xs:annotation>

</xs:element>

<xs:element name="milestone" type="MilestoneType" minOccurs="0" maxOccurs="unbounded">

<xs:annotation>

<xs:documentation>

Defines a milestone within a challenge category at which Fame Points are awarded. These milestones can be achieved once within a given reset period.

</xs:documentation>

</xs:annotation>

<xs:unique name="UniqueMilestoneLanguages">

<xs:annotation>

<xs:documentation>

A milestone should contain, at most, one description element per language.

</xs:documentation>

</xs:annotation>

<xs:selector xpath="description"/>

<xs:field xpath="@language"/>

</xs:unique>

</xs:element>

<xs:element name="repeatableMilestone" type="RepeatableMilestoneType" minOccurs="0" maxOccurs="1">

<xs:annotation>

<xs:documentation>

Defines a milestone within a challenge category at which Fame Points are awarded. These milestones can be achieved multiple times within a given reset period. A repeatable milestone must be the final milestone defined for a challenge category, and, at most, one such milestone can be defined.

</xs:documentation>

</xs:annotation>

<xs:unique name="UniqueRepeatableMilestoneLanguages">

<xs:annotation>

<xs:documentation>

A milestone should contain, at most, one description element per language.

</xs:documentation>

</xs:annotation>

<xs:selector xpath="description"/>

<xs:field xpath="@language"/>

</xs:unique>

</xs:element>

</xs:sequence>

<xs:attribute name="id" type="IDType" use="required">

<xs:annotation>

<xs:documentation>

Challenge IDs are either title-assigned integers in the range [0-1023] or strings that map to a set of server-defined challenges.

</xs:documentation>

</xs:annotation>

</xs:attribute>

<xs:attribute name="name" type="xs:string" use="optional">

<xs:annotation>

<xs:documentation>

Optional attribute that can be used to provide human-readable identification for challenges. This string is not displayed to end users.

</xs:documentation>

</xs:annotation>

</xs:attribute>

</xs:complexType>

<xs:complexType name="WeekDefinitionType">

<xs:sequence>

<xs:element name="WeeklyChallenge" minOccurs="1" maxOccurs="unbounded">

<xs:complexType>

<xs:attribute name="ChallengeID" type="IDType" use="required">

<xs:annotation>

<xs:documentation>

References a challenge from the WeeklyChallenges section that should be included in this week's schedule.

</xs:documentation>

</xs:annotation>

</xs:attribute>

</xs:complexType>

<xs:keyref name="CheckChallengeIDRef" refer="ChallengeKey">

<xs:selector xpath="."/>

<xs:field xpath="@ChallengeID"/>

</xs:keyref>

</xs:element>

</xs:sequence>

</xs:complexType>

<xs:element name="FameChallenges">

<xs:complexType>

<xs:sequence>

<xs:element name="BonusChallenges" minOccurs="1" maxOccurs="1">

<xs:annotation>

<xs:documentation>

Challenges that are not time-limited and will never reset.

</xs:documentation>

</xs:annotation>

<xs:complexType>

<xs:sequence>

<xs:element name="ChallengeDefinition" type="FameChallengeType" minOccurs="1" maxOccurs="unbounded">

<xs:unique name="UniqueBonusChallengeLanguages">

<xs:annotation>

<xs:documentation>

A challenge should contain, at most, one description element per language.

</xs:documentation>

</xs:annotation>

<xs:selector xpath="description"/>

<xs:field xpath="@language"/>

</xs:unique>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="WeeklyChallenges" minOccurs="1" maxOccurs="1">

<xs:annotation>

<xs:documentation>

Challenges for which progress is reset at the weekly reset point.

</xs:documentation>

</xs:annotation>

<xs:complexType>

<xs:sequence>

<xs:element name="ChallengeDefinition" type="FameChallengeType" minOccurs="1" maxOccurs="unbounded">

<xs:unique name="UniqueWeeklyChallengeLanguages">

<xs:annotation>

<xs:documentation>

A challenge should contain, at most, one description element per language.

</xs:documentation>

</xs:annotation>

<xs:selector xpath="description"/>

<xs:field xpath="@language"/>

</xs:unique>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="Schedule" minOccurs="1" maxOccurs="1">

<xs:annotation>

<xs:documentation>

Defines a weekly rotation for active challenges.

</xs:documentation>

</xs:annotation>

<xs:complexType>

<xs:sequence>

<xs:element name="WeekDefinition" type="WeekDefinitionType" minOccurs="1" maxOccurs="unbounded">

<xs:annotation>

<xs:documentation>

Defines the collection of challenges for a single week in the challenge rotation.

</xs:documentation>

</xs:annotation>

<xs:unique name="UniqueWeeklyChallenges">

<xs:annotation>

<xs:documentation>

A single challenge should not appear more than once in the schedule for a given week.

</xs:documentation>

</xs:annotation>

<xs:selector xpath="WeeklyChallenge"/>

<xs:field xpath="@ChallengeID"/>

</xs:unique>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:sequence>

</xs:complexType>

<xs:key name="ChallengeKey">

<xs:selector xpath="./WeeklyChallenges/ChallengeDefinition"/>

<xs:field xpath="@id"/>

</xs:key>

</xs:element>

</xs:schema>

Fame Challenge Elements

The following elements are defined in the schema:

FameChallenges

The base Fame challenge element that contains the elements that define Fame challenges.

BonusChallenges

A FameChallengeType element that is not time limited, meaning that progress toward this challenge is never reset.

WeeklyChallenges

A FameChallengeType element for which progress is reset on a weekly basis.

Schedule

A FameChallengeType element that defines the weekly rotation of Fame challenges.

Fame Challenge Types

The following types are defined in the schema:

IDType

A simple enumeration type that defines the range of title-defined challenge IDs (0 to 1023) and the basic Sentient-defined challenge IDs.

MilestoneType

A complex type that defines the milestones upon which Fame challenges are built.

RepeatableMilestoneType

A complex type that derives from MilestoneType and defines a milestone in a Fame challenge that repeats.

FameChallengeType

The base Fame challenge type upon which all Fame challenges are built. Fame challenges can be one-time milestones (MilestonType) or repeatable milestones (RepeatableMilstoneType).

WeeklyDefinitionType

A complex type that defines how to schedule Fame challenges to rotate weekly.

Remarks

For more information, see Defining Custom Fame Challenges.

See Also

Fame Reference


Avatar Superstars

Avatar Superstars is an award system for games that feature avatars as the primary star of play. Players receive special avatar costumes when they earn Fame points through a variety of game challenges and participation in social games.

Sentient provides a selection of avatar costumes that are available globally across all Sentient avatar games. In addition to these basic costumes, titles can also provide special costumes available only to their title. Contact the Sentient team (senhelp@microsoft.com) to upload your title-specific costumes to the Sentient Server.

Use the avatar API to search the Sentient database for avatar costumes, and then download the costume icons to display on the costume selection menu and then download the costumes for the player's avatar.

Searching for Avatar Costumes

To search for all the avatar costumes available to a title:

  • Call SenAvatarEnumerate to get all of the costumes in a collection of SenAvatarInfo structures. This includes the global costumes as well as the title-specific costumes.
Displaying Avatar Costumes

When players accumulate a sufficient number of Fame points, they earn and select special avatar costumes in Avatar Superstar (AVSS) enabled games. The costumes they are eligible to wear are based on their current VIP level. However, the collection of costumes returned from SenAvatarEnumerate is not filtered by VIP level, but you can display all the avatar costumes and the VIP level required to wear a specific costume on a separate menu.

To display all costumes:

  • Call SenAvatarDownloadIcon with the costumes enumerated from SenAvatarEnumerate, and then display the icons to players on the avatar costume menu.

To display only the avatar costume available for the player's VIP level:

  • Filter the costumes by the player’s VIP level specified in the SenAvatarInfo structure, and then display those costumes on the costume selection menu.

Additionally, you can call SenAvatarDownloadExtraInfo to get the names and descriptions of the costumes as well as the colors available to each costume. This information is also displayed on the costume selection menu.

Downloading Costumes to Wear

After the player selects an avatar costume and color, you then download the costume and information required to dress the player. To download a costume:

  • Call SenAvatarDownloadAssets to get the raw data of the costume and SenAvatarDownloadMetadata to get the information you need to dress the avatar.
Download Costumes in a Multiplayer Game

When playing in a multiplayer game, the player on the initiating console may be playing with someone on another console that is wearing an avatar awards costume. To display that player in his or her avatar costume on the initiating player's console, you must retrieve the costume from Sentient. To retrieve another player's costume:

  • Call SenAvatarFind with the Sentient resource ID of the costume. It is the responsibility of the title to get the resource ID of the costume out-of-band for this call.


Avatar Reference

This section contains API reference functions that you use with the Microsoft Sentient API.

In This Section

Avatar Functions

Avatar Structures

Avatar Enumerations


Avatar Functions

This section contains API reference functions that you use with the Microsoft Sentient APIs.

In This Section

Search Functions
Function | Description
SenAvatarEnumerate | Searches the database for all the avatar costumes that are available to the title.
SenAvatarFind | Searches the Sentient database for a specific avatar costume.
Download Functions
Function | Description
SenAvatarDownloadAssets | Downloads the assets of the avatar costume to the client.
SenAvatarDownloadExtraInfo | Downloads the extra information about an avatar costume to the client.
SenAvatarDownloadIcon | Downloads the icon of the avatar costume to the client.
SenAvatarDownloadMetadata | Downloads the metadata for the specified avatar costume to the client.


SenAvatarEnumerate Function

Searches the database for all the avatar costumes that are available to the title.

Syntax

C ++
HRESULT SenAvatarEnumerate(
   int  userIndex,
   size_t  avatarInfoCountMax,
   size_t  *out_avatarInfoCount,
   SenAvatarInfo  *out_avatarInfoList,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
);

Parameters

userIndex

[in] The index of the user who initiated this call on the console.

Note: This is not a XUID.

avatarInfoCountMax

[in] The maximum number of SenAvatarInfo structures in the out_avatarInfoList parameter.

out_avatarInfoCount

[out] A pointer to the number of SenAvatarInfo structures enumerated in this call.

out_avatarInfoList

[out] A pointer to a collection of SenAvatarInfo structures that will contain the avatar information after Sentient invokes the callback.

This is pre-allocated to avatarInfoCountMax*(sizeof)SenAvatarInfo bytes.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_avatarInfoList pointer is NULL.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

Remarks

Players can earn special avatar costumes in AVSS-enabled games based on their VIP level. The results returned from this function contain the global avatar costumes for all VIP levels; they are not filtered by the player's current VIP level. In addition to the global costumes available to all AVSS titles, this function returns any title-specific avatar costumes. Titles contact the Sentient team (senhelp@microsoft.com) to upload their specific avatar costumes to the Sentient server.

Titles can display all the avatar costumes for players to use as a reference to the costumes they can earn in the future. However, you must determine the VIP level of the player before you display costumes on the costume selection menu. The VIP level required to wear an avatar costume is in the SenAvatarInfo structure returned from this call.

Requirements

Header: SenClientAvatar.h

Library: SenSuperstars.lib

See Also

Avatar Functions

SenAvatarEnumerate

SenAvatarFind

SenAvatarDownloadAssets

SenAvatarDownloadExtraInfo

SenAvatarDownloadMetadata

SenAvatarDownloadIcon

SenAvatarInfo


SenAvatarFind Function

Searches the Sentient database for a specific avatar costume.

Syntax

C ++
HRESULT SenAvatarFind(
   SenSysTitleID  titleID,
   SenResourceID  resourceID,
   SenAvatarInfo  *out_avatarInfo,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
);

Parameters

titleID

[in] A SenSysTitleID that uniquely identifies the Xbox Live title associated with the avatar costume.

Internally, Sentient assigns a title identifier to each title that is within the 32 bit range specified by the SenSysTitleID enumeration.

resourceID

[in] A member of the SenResourceID enumeration that identifies the avatar asset that is requested.

out_avatarInfo

[out] A pointer to a single SenAvatarInfo structure that will contain the avatar information after Sentient invokes the callback.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_avatarInfo pointer is NULL.

SENTIENT_E_GUEST_ACCESS_VIOLATION

A guest and may not spawn this call.

Remarks

This function is only used in multiplayer games when an avatar costume is displayed on a console other than the owners console to retrieve the special avatar costume.

Requirements

Header: SenClientAvatar.h

Library: SenSuperstars.lib

See Also

Avatar Functions

SenAvatarEnumerate

SenAvatarFind

SenAvatarDownloadAssets

SenAvatarInfo


SenAvatarDownloadIcon Function

Downloads the icon of the avatar costume to the client.

Syntax

C ++
HRESULT SenAvatarDownloadIcon(
   const SenAvatarInfo  &avatarInfo,
   bool  male,
   size_t  dataSizeMax,
   void  *out_data,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
);

Parameters

avatarInfo

[in] A pointer to the SenAvatarInfo structure that describes the attributes and data of the avatar icon that is downloaded in this call. This structure was previously returned in the call to SenAvatarFind or SenAvatarEnumerate.

male

[in] true to retrieve information for the male avatar; otherwise false to retrieve the female avatar.

dataSizeMax

[in] The maximum size of the out_data buffer, in bytes.

out_data

[out] A pointer to the buffer that will contain the binary icon data after Sentient invokes the callback.

This buffer must be pre-allocated to avatarInfo.female.metadata.GetBufferSize() bytes.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

E_INVALIDARG

Either the avatarInfo.resourceID or avatarInfo.[fe]male.icon is invalid.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_data pointer is NULL.

Remarks

Icons are the display version of the avatar costumes, not the actual costume. To save time, download only the icon to display on the costume selection menu. Then after the player selects the costume, download the assets and metadata.

Requirements

Header: SenClientAvatar.h

Library: SenSuperstars.lib

See Also

Avatar Functions

SenAvatarEnumerate

SenAvatarDownloadAssets

SenAvatarDownloadExtraInfo

SenAvatarDownloadMetadata

SenAvatarInfo

SenAvatarGenderInfo

SenAvatarNamedPalette

SenAvatarPalette


SenAvatarDownloadAssets Function

Downloads the assets of the avatar costume to the client.

Syntax

C ++
HRESULT SenAvatarDownloadAssets(
   const SenAvatarInfo  &avatarInfo,
   bool  male,
   size_t  dataSizeMax,
   void  *out_data,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
);

Parameters

avatarInfo

[in] A pointer to the SenAvatarInfo structure that describes the attributes and data of the avatar assets that are downloaded in this call. This structure was previously returned in the call to SenAvatarFind or SenAvatarEnumerate.

male

[in] true to retrieve information for the male avatar; otherwise false to retrieve the female avatar.

dataSizeMax

[in] The maximum size of the out_data buffer, in bytes.

out_data

[out] A pointer to the buffer that will contain the binary asset data after Sentient invokes the callback.

This buffer must be pre-allocated to avatarInfo.female.metadata.GetBufferSize() bytes.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

E_INVALIDARG

Either the avatarInfo.resourceID or avatarInfo.[fe]male.assets is invalid.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_data pointer is NULL.

Remarks

The asset data contains the avatar costume. To save time, only download the assets after the player selects the avatar costume from the costume selection menu. You must download both the assets and the metadata to dress an avatar in a costume.

Requirements

Header: SenClientAvatar.h

Library: SenSuperstars.lib

See Also

Avatar Functions

SenAvatarEnumerate

SenAvatarFind

SenAvatarDownloadExtraInfo

SenAvatarDownloadMetadata

SenAvatarDownloadIcon

SenAvatarInfo


SenAvatarDownloadExtraInfo Function

Downloads the extra information about an avatar costume to the client.

Syntax

C ++
HRESULT SenAvatarDownloadExtraInfo(
   const SenAvatarInfo  &avatarInfo,
   bool  male,
   SenAvatarExtraInfo  *out_avatarExtraInfo,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
);

Parameters

avatarInfo

[in] A pointer to the SenAvatarInfo structure that describes the attributes and data of the avatar extra information that is downloaded in this call. This structure was previously returned in the call to SenAvatarFind or SenAvatarEnumerate.

male

[in] true to retrieve information for the male avatar; otherwise false to retrieve the female avatar.

out_avatarExtraInfo

[out] A pointer to the SenAvatarExtraInfo structure that will contain the extra information after Sentient invokes the callback.

This buffer must be pre-allocated to (sizeof)SenAvatarExtraInfo bytes.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

E_INVALIDARG

Either the avatarInfo.resourceID or avatarInfo.xml is invalid.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_avatarExtraInfo is NULL.

Remarks

The extra information contains the name of the costumes and palettes available for the costume. Download the extra information to display the color options and names of the costumes on the costume selection menu.

Requirements

Header: SenClientAvatar.h

Library: SenSuperstars.lib

See Also

Avatar Functions

SenAvatarEnumerate

SenAvatarFind

SenAvatarDownloadAssets

SenAvatarDownloadMetadata

SenAvatarDownloadIcon

SenAvatarExtraInfo

SenAvatarInfo


SenAvatarDownloadMetadata Function

Downloads the metadata for the specified avatar costume to the client.

Syntax

C ++
HRESULT SenAvatarDownloadMetadata(
   const SenAvatarInfo  &avatarInfo,
   bool  male,
   size_t  dataSizeMax,
   void  *out_data,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
);

Parameters

avatarInfo

[in] A pointer to the SenAvatarInfo structure that describes the attributes of the avatar metadata that is downloaded in this call. This structure was previously returned in the call to SenAvatarFind or SenAvatarEnumerate.

male

[in] true to retrieve information for the male avatar; otherwise false to retrieve the female avatar.

dataSizeMax

[in] The maximum size of the out_data buffer.

out_data

[out] A pointer to the buffer that will contain the binary metadata after Sentient invokes the callback.

This buffer must be pre-allocated to avatarInfo.female.metadata.GetBufferSize() bytes.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The server call was spawned successfully.

E_FAIL

Sentient failed to spawn the call to the server.

An unknown error occurred. For more information, see the debug log that is available when you compile your application against the debug version of the library (SenCoreD.lib).

E_INVALIDARG

Either the avatarInfo.resourceID or avatarInfo.[fe]male.metadata is invalid.

SENTIENT_E_NOT_INITIALIZED

Sentient is not initialized. You must call SentientInitialize before you call this function.

E_POINTER

The out_data pointer is NULL.

Remarks

The metadata contains the information required to use the avatar costume. To save time, first download the icons to display on the costume selection menu. Then download the metadata only after the player selects the avatar costume. You must download both the assets and the metadata to dress an avatar in a costume.

Requirements

Header: SenClientAvatar.h

Library: SenSuperstars.lib

See Also

Avatar Functions

SenAvatarEnumerate

SenAvatarFind

SenAvatarDownloadAssets

SenAvatarDownloadExtraInfo

SenAvatarDownloadIcon

SenAvatarInfo


Avatar Structures

This section contains API reference structures that you use with the Microsoft Sentient APIs.

In This Section

Structure | Description
SenAvatarInfo | Contains the information required to download an avatar costume.
SenAvatarExtraInfo | Contains the additional information about an avatar costume, such as localized strings and palettes.
SenAvatarGenderInfo | Contains the information needed to download the raw data for a given gender.
SenAvatarPalette | Contains the color of the avatar costume.
SenAvatarNamedPalette | Contains a collection of localized names of the palettes available for an avatar costume.


SenAvatarInfo Structure

Contains the information required to download an avatar costume.

Syntax

C ++
struct SenAvatarInfo : public SenResourceInfo{
   int  vipLevel;
   SenAvatarGenderInfo  female;
   SenAvatarGenderInfo  male;
};

Members

vipLevel

The VIP level required to access this avatar costume.

female

A SenAvatarGenderInfo structure that contains the information for a female avatar.

male

A SenAvatarGenderInfo structure that contains the information for a male avatar.

Remarks

Sentient returns both the male and female versions of avatar costumes in this structure in the call to SenAvatarEnumerate.

Sentient has a library of global costumes that are available to all titles. In addition, titles can upload special costumes available only to their title. This structure contains the information for global costumes as well as the original data that titles uploaded to the Sentient servers for their title.

Requirements

Header: SenClientAvatar.h

Library: SenSuperstars.lib

See Also

Avatar Structures

SenAvatarEnumerate

SenAvatarFind


SenAvatarExtraInfo Structure

Contains the additional information about an avatar costume, such as localized strings and palettes.

Syntax

C ++
struct SenAvatarExtraInfo{
   wchar_t  title[XMARKETPLACE_MAX_TITLE_NAME_LENGTH+1];
   wchar_t  name[XMARKETPLACE_MAX_OFFER_NAME_LENGTH+1];
   wchar_t  description[XMARKETPLACE_MAX_OFFER_SELL_TEXT_LENGTH+1];
   size_t  paletteCount;
   SenAvatarNamedPalette  palette[16];
};

Members

title

If this is a title-specific costume, this is the localized title of the game associated with the avatar costume; otherwise this member is undefined.

name

The localized name of the avatar costume.

description

The localized short description of the avatar costume.

paletteCount

The number of palettes in the palette member.

palette

A collection of SenAvatarNamedPalette structures that contains the palettes available for this avatar costume.

Remarks

This information is returned in the call to SenAvatarDownloadExtraInfo to retrieve the localized names and colors available for an avatar costume. Use this information to display the color options on the costume selection menu.

To return localized strings, Sentient uses the system language and locale settings on the local machine. To retrieve the localization settings on the machine, call XGetLocale or XGetLanguage.

Requirements

Header: SenClientAvatar.h

Library: SenSuperstars.lib

See Also

Avatar Structures

SenAvatarDownloadExtraInfo

SenAvatarPalette

SenAvatarNamedPalette


SenAvatarGenderInfo Structure

Contains the information needed to download the raw data for a given gender.

Syntax

C ++
struct SenAvatarGenderInfo{
   SenRawDataTransferInfo  metadata;
   SenRawDataTransferInfo  assets;
   SenRawDataTransferInfo  xml;
   SenRawDataTransferInfo  icon;
};

Members

metadata

A SenRawDataTransferInfo structure that contains the metadata of the avatar costume. This structure is used in the call to SenAvatarDownloadMetadata.

assets

A SenRawDataTransferInfo structure that contains the assets of the avatar costume. This structure is used in the call to SenAvatarDownloadAssets.

xml

A SenRawDataTransferInfo structure that contains the extra information of the avatar costume. This structure is used in the call to SenAvatarDownloadExtraInfo.

icon

A SenRawDataTransferInfo structure that contains the icon of the avatar costume. This structure is used in the call to SenAvatarDownloadIcon.

Remarks

The gender structure is contained in the SenAvatarInfo structure, which is supplied in the calls to SenAvatarDownloadMetadata, SenAvatarDownloadExtraInfo, SenAvatarDownloadAssets and SenAvatarDownloadIcon to download the various resources associated with an avatar costume.

Requirements

Header: SenClientAvatar.h

Library: SenSuperstars.lib

See Also

Avatar Structures

SenAvatarEnumerate

SenAvatarInfo


SenAvatarPalette Structure

Contains the color of the avatar costume.

Syntax

C ++
struct SenAvatarPalette{
   XMCOLOR  entry[3];
};

Members

entry

An XMCOLOR structure that contains the color of the avatar costume.

Remarks

The SenAvatarNamedPalette structure inherits from this structure.

Requirements

Header: SenClientAvatar.h

Library: SenSuperstars.lib

See Also

Avatar Structures

SenAvatarDownloadExtraInfo

SenAvatarExtraInfo

SenAvatarNamedPalette


SenAvatarNamedPalette Structure

Contains a collection of localized names of the palettes available for an avatar costume.

Syntax

C ++
struct SenAvatarNamedPalette : SenAvatarPalette{
   wchar_t  name[57+1];
};

Members

name

The localized name of the color.

Remarks

Costumes that are available in different colors use this structure to specify the color selection. This structure is part of the SenAvatarExtraInfo structure that is returned in the call to SenAvatarDownloadExtraInfo.

To return localized strings, Sentient uses the system language and locale settings on the local machine. To retrieve the localization settings on the machine, call XGetLocale or XGetLanguage.

This structure inherits from SenAvatarPalette.

Requirements

Header: SenClientAvatar.h

Library: SenSuperstars.lib

See Also

Avatar Structures

SenAvatarDownloadExtraInfo

SenAvatarExtraInfo

SenAvatarPalette


Avatar Enumerations

This section contains API reference enumerations that you use with the Microsoft Sentient APIs.

In This Section

Enumeration | Description
SenAvatarSortBy | Defines the sort options for enumerating avatar costumes. Note: This enumeration is reserved for future use.


SenAvatarSortBy Enumeration

Defines the sort options for enumerating avatar costumes.

Note: This enumeration is reserved for future use.

Syntax

C ++
enum SenAvatarSortBy{
   SenAvatarSortBy_Default = 0,
};

Constants

SenAvatarSortBy_Default

[in] The returned results are not sorted.

Remarks

Note: Sorting search results from SenAvatarEnumerate is currently not implemented.

Requirements

Header: SenClientAvatar.h

Library: SenSuperstars.lib

See Also

Avatar Enumerations

SenAvatarEnumerate


Glossary

A - B - C - D - F - L - N - O - R - S - T - U - X

A

Avatar Superstar

A social, cross title, participation based reward system for high quality games, where avatars are featured as the primary stars of game play. Users can earn points through a variety of play milestones, events, and weekly challenges, and those points can go toward Avatar Superstar awards or Fame VIP status across all Sentient titles.

B

Box Art

See Cross Title Promotional.

C

content

Generic term for downloadable material, such as Cross Title Promotional, Dynamic Configuration, or User Generated Content (UGC).

Cross Title Promotional

A Sentient feature that dynamically upsells additional, curated content offered in the Xbox LIVE Marketplace, using custom marketing text and box art delivered from Sentient.

culture

The language and locale settings used to display content to users. Sentient uses the culture settings on the local machine to present localized content to players.

D

Dynamic Configuration

A Sentient feature that hosts custom data to modify game behaviors for online players.

F

file ID

Sentient assigns a 32-bit identifier to files stored on the server such as configuration files. Internally, Sentient uses the file ID to locate the file on the server. The SenFileID enumeration defines the file identifiers.

friend

On Xbox LIVE, a gamer on your friends list.

friends list

Your list of friends on Xbox LIVE.

Fame Terms:

milestone

The point at which players earn Fame points in a challenge.

challenge

Event or activity through which players can earn Fame points. There are multiple milestones within a Fame challenge.

progress

Players earn progress toward a milestone within a challenge.

awards

Fame points earned when players pass a milestone.

Fame points

Points that are awarded when players pass a milestone within a challenge.

L

leaderboard

An ordered list of players in an Xbox LIVE game or other competition. Sentient leaderboards support friend-based and top-100 leaderboard value tracking for user created content.

leaderboard entry

An single entry on a leaderboard. Entries contain an actor, value, rank and metadata.

value (of a leaderboard entry)

The value associated with a leaderboard entry.

N

News

A Sentient feature that keeps your community informed and engaged. The Sentient News service retrieves localized programmed and system-generated news ticker messages from the server.

O

offer ID

The identifier that the Xbox LIVE Marketplace uses to purchase content. This defined by the SenSysOfferID enumeration.

R

resource ID

The identifiers that Sentient uses to locate a resource such as a configuration file or a box art.

robustification

The act of robustifying your code.

S

scene

A single screen, pane, or dialog box within a title.

T

Telemetry

A Sentient feature that monitors player patterns through title-defined hooks to create business intelligence reports.

title ID

A SenSysTitleID identifier that specifies a unique identifier for each title. Internally, Sentient assigns a title identifier to each title that is within the 32-bit range specified by the SenSysTitleID enumeration.

U

UGC

User Generated Content. Share and search for user created game content. Users can also flag inappropriate content, and moderators can review and take down offensive material.

UGC ID

Internal Sentient identifier for User Generated Content (UGC).

UGC User Trust

A weight assigned to players who flag UGC content. The Sentient Moderation Engine uses this trust in the calculation to determine whether to flag a UGC item. For more information, see The Sentient Moderation Engine.

UGC Threshold

A constant that the Sentient Moderation Engine uses to determine whether to flag a UGC based on community feedback. For more information, see The Sentient Moderation Engine.

user Index

The index of the user on the Xbox console.

X

Xbox LIVE Marketplace

The Xbox 360 client-side application that enables customers to browse, acquire, and install downloadable content, as well as recurring memberships to Xbox LIVE and other game services. This term also covers the APIs in the Xbox 360 XDK that allow games to integrate with the Xbox LIVE Marketplace application.

XLSP

Xbox LIVE Server Platform.

XUID

The identifier of a game player on the Xbox LIVE service.


SenPackageFileTransferInfo Structure

Contains the information required to download content from the Sentient server.

Note: This feature is currently not implemented, do not use.

Syntax

C ++
struct SenPackageInfo;{
   const SenPackageInfo  *package;
   const char   *filename;
   SenSysFileSize   fileSize;
   bool  IsValid() const;
   SenSysFileSize   GetFileSize()  const;
   SenSysFileSize   GetBufferSize() const;
};

Members

package

A pointer to the SenPackageInfo structure that contains the information needed to download the package file to the client.

filename

A pointer to the name of the package file.

fileSize

The size, in bytes, of the package file.

IsValid

The IsValid function returns true if this structure refers to a valid configuration package. This call does not guarantee that the package exists. To determine if the package exists, call to SenConfigFileDownload and verify that the package returns successfully. TBD: Update with the corresponding text in other structs.

GetFileSize

The GetFileSize function returns the size, in bytes, of the data in the package. To download the package, call SenConfigFileDownload. Note that the destination buffer in the call to SenConfigFileDownload must be allocated with GetBufferSize to ensure efficient data transfer. TBD: Update with the corresponding text in other structs.

Note: This function is provided for diagnostic purposes only. Do not call this function in your released code. Instead, call this function from the SenRawDataTransferInfo structure.

GetBufferSize

Returns the size, in bytes, of the buffer that is needed to download the package. Note that for efficient file transfer, this value is greater than or equal to the size, in bytes, of the package. Titles must use GetBufferSize to allocate the destination buffer. TBD: Update with the corresponding text in other structs.

Note: This function is provided for diagnostic purposes only. Do not call this function in your released code. Instead, call this function from the SenRawDataTransferInfo structure.

Remarks

When the SenRawDataTransferInfo structure contains this structure, Sentient downloads a package to the client. This is used to download Xbox LIVE Marketplace packages such as Avatar costumes or BoxArt to the client. The package file download routines from the Marketplace use this structure directly.

Requirements

Header: SenClientPackage.h

Library: SenCore.lib

See Also

Core Reference


SenBoxArtDownloadExtraInfo Function (deprecated)

Build 2025 and later: This function is deprecated, do not use. Instead, call SenBoxArtDownloadExtraInfo.

Syntax

C ++
HRESULT SenBoxArtDownloadExtraInfo(
   const SenBoxArtInfo  &boxArtInfo,
   const SenCultureInfo  *culture,
   SenBoxArtExtraInfo  *out_boxArtExtraInfo,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
);

Parameters

Deprecated, do not use.

Requirements

Header: SenClientBoxArt.h

Library: SenBoxArt.lib

See Also

Core Reference

Box Art Reference


SenBoxArtDownloadImage Function (deprecated)

Build 2025 and later: This function is deprecated, do not use. Instead, call SenBoxArtDownloadImage.

Syntax

C ++
HRESULT SenBoxArtDownloadImage(
   const SenBoxArtInfo &boxArtInfo,
   size_t dataSizeMax,
   void *out_data,
   SenSysCompletedCallback userCallback,
   void *userCallbackData
);

Parameters

Deprecated, do not use.

Requirements

Header: SenClientBoxArt.h

Library: SenBoxArt.lib

See Also

Box Art Reference


SenBoxArtEnumerate Function (deprecated)

Build 2025 and later: This function is deprecated, do not use. Instead, call SenBoxArtEnumerate.

Syntax

C ++
HRESULT SenBoxArtEnumerate(
   int  userIndex,
   size_t  boxArtInfoCountMax,
   size_t  *out_boxArtInfoCount,
   SenBoxArtInfo  *out_boxArtInfoList,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
);

Parameters

Deprecated, do not use.

Requirements

Header: SenClientBoxArt.h

Library: SenBoxArt.lib

See Also

Box Art Reference


SenConfigFileDownload Function

Downloads the raw configuration file to the Sentient client.

Syntax

C ++
HRESULT SenConfigFileDownload(
   const SenConfigInfo  configInfo,
   size_t  dataSizeMax,
   void  *out_data,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
);

Parameters

configInfo

[in] The SenConfigInfo structure that was returned in the corresponding call to SenConfigFileFind.

dataSizeMax

[out] A pointer to the number of bytes available in the out_data parameter, including the buffer.

out_data

[out] A pointer to the buffer that will contain the returned information after the search operation completes and the callback function returns successfully.

Note: The number of bytes allocated by the title for this data must be at least configInfo.config.GetBufferSize() bytes.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to the SenSysCompletedCallback function. This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The call to the Sentient server to retrieve the file was spawned successfully.

SENTIENT_E_NOT_INITIALIZED

The Sentient Service is not currently initialized. For more information, see SentientInitialize.

E_POINTER

The out_data parameter is NULL.

E_INVALIDARG

The configInfo argument is not valid.

E_FAIL

Sentient encountered and unspecified error.

Remarks

The SenConfigInfo structure returned in the call to SenConfigFileFind contains the information that Sentient needs to download the configurations file. Sentient treats the configuration file as a generic block of data and does not process or alter the contents in any way. For more information, see Retrieving a Configuration File and Uploading a Configuration File.

Requirements

Header: SenClientConfig.h

Library: SenCore.lib

See Also

Dynamic Configuration Reference

SenConfigFileFind


SenConfigFileFind Function

Searches the configuration file database on the Sentient server for the specified configuration file.

Syntax

C ++
HRESULT SenConfigFileFind(
   SenResourceID  resourceID,
   SenConfigInfo  *out_configInfo,
   SenSysCompletedCallback  userCallback,
   void  *userCallbackData
)

Parameters

resourceID

[in] The SenResourceID of the configuration file that is requested. This ID is an offset of the SenResourceID_config_0 member of the SenResourceID enumeration. The offset is in the range of 0 to 0xFFFFFF and is set when you upload the file on the Sentient Developer Website (https://sentient.msgamestudios.com).

out_configInfo

[out] A pointer to a SenConfigInfo structure that will contain the information about the configuration file after the callback function returns successfully.

Note: The memory allocated for this structure must persist until the callback function returns.

userCallback

[in] The SenSysCompletedCallback function that Sentient calls when the search operation completes. Sentient does not invoke the callback function if this function returns an error.

userCallbackData

[in] A pointer to the callback data that is passed to SenSysCompletedCallback . This parameter is optional and may be set to NULL.

Return Values

This function returns an HRESULT. Possible values include, but are not limited to, the following:

S_OK

The call to the Sentient server to search for the file was spawned successfully.

SENTIENT_E_NOT_INITIALIZED

The Sentient Service is not currently initialized. For more information, see SentientInitialize.

E_POINTER

The out_configInfo parameter is NULL.

E_FAIL

Sentient encountered and unspecified error.

Remarks

This function returns the SenConfigInfo structure that contains all the information that Sentient needs to download the configuration file. To download the configuration file, call SenConfigFileDownload.

Configuration files are manually uploaded to the Sentient Developer Website (https://sentient.msgamestudios.com). You can upload multiple configuration files to the Sentient servers and request a specific file based on the configuration offset that you specified when you uploaded the file. Sentient does not manage versions of the configuration file or otherwise alter the contents of your configuration data.

For more information, see Retrieving a Configuration File and Uploading a Configuration File.

Requirements

Header: SenClientConfig.h

Library: SenCore.lib

See Also

Dynamic Configuration Reference

SenConfigFileDownload


SenConfigInfo Structure

Contains the attributes of the configuration data.

Inheritance

Inherits from SenResourceInfo.

Syntax

C ++
struct SenConfigInfo: public SenResourceInfo{
   SenRawDataTransferInfo  config;
};

Members

config

A SenRawDataTransferInfo structure that contains the attributes of the configuration file.

Remarks

This structure contains all the information that Sentient needs to download the configuration data to the client. Sentient populates this structure with the attributes of the configuration data when you upload your file to the Sentient Developer Website (https://sentient.msgamestudios.com). For more information, see Retrieving a Configuration File and Uploading a Configuration File.

Requirements

Header: SenClientConfig.h

See Also

Dynamic Configuration Reference

SenConfigFileDownload

SenConfigFileFind

SenResourceInfo


Sentient Configuration File

Configures the connections to the Sentient XLSP and Xbox LIVE servers.

Build 2734 and later: This feature is deprecated, do not use.

Syntax

transport.ini
[Connection]
UseLiveConnection=true
ServiceId=0x4d5308CF
SgMask=sentient.a
TitleID=0x58410A5E
BaseUrl=/Services.Sentient/o.rhbin
[CustomImplementations]
ILogonProvider=SenLogonProvider

Configurations

[Connection]

This section has configurations for the connections to the XLSP and Sentient servers.

UseLiveConnection

If true, the Sentient libraries target the official Sentient XLSP. This configuration should be set to true.

ServiceId

Identifies the Sentient XLSP to the Xbox LIVE service. This configuration must be set to 0x4d5308CF.

SgMask

The Secure Gateway Server through which you connect to the XLSP. This configuration should be set to sentient.a unless otherwise directed by the Sentient team.

TitleID

The title ID of your game.

BaseUrl

The URL of the Sentient server that your title interacts with. This configuration is ignored when UseLiveConnection is set to true. This configuration must be set to /Services.Sentient/o.rhbin.

[CustomImplementations]

This section specifies custom implementations.

ILogonProvider

A type that provides handling for system sign-in and sign-out messages. This configuration must be set to SenLogonProvider.

Remarks

Below is a sample Sentient configuration file, transport.ini. Most of these settings should not be changed:

     [Connection]
     ; Only set UseLiveConnection=false to connect to an unsecured
     ; web server. Possibly used to test your title.
     UseLiveConnection=true
     ServiceId=0x4d5308CF
     SgMask=sentient.a
     TitleID=0x58410A5E

     ; Do not change this setting
     BaseUrl=/Services.Sentient/o.rhbin

     [CustomImplementations]
     ILogonProvider=SenLogonProvid

Requirements

File: transport.ini

See Also

Core Reference

Connect to the Sentient Service