blob: 0ee41a4781789f56bf507f5e965283cd2f4f4859 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
/********************************************************
* *
* Copyright (C) Microsoft. All rights reserved. *
* *
********************************************************/
// Sentient Client Stats API
//
// Include this to get access to all Stats-related Sentient features.
#pragma once
#include "SenClientTypes.h"
namespace Sentient
{
/***********************
***** Stats Types *****
***********************/
#define SenStatID_Custom 128
// Stats
#define SenStatFlag_Normal 1
#define SenStatFlag_Time 2
#define SenStatFlag_TimeEnd 4
// Params
#define SenStatValueFlag_Inc 1
#define SenStatValueFlag_Accum 2
#define SenStatValueFlag_Min 4
#define SenStatValueFlag_Max 8
// Enable Logging if we are in debug build
#ifdef _DEBUG
#define SEN_LOGTELEMETRY
#endif
struct SenStat
{
DWORD dwUserID;
DWORD dwStatID;
DWORD dwFlags; // SenStatFlag_*
DWORD dwNumProperties;
CHAR* arrProperties;
DWORD dwNumValues;
CHAR* arrValues;
DWORD* arrValueFlags; // SenStatValueFlag_*
};
/***************************
***** Stats Functions *****
***************************/
/// @brief Submit a stat entry to the sentient system
///
/// @param[in] pStat
/// The pointer to SenStat structure. The SentientStatsSend function is usually called from the autogenerated fuctions
/// which use as [in] parameters the userIndex(0 through 3) and the set of the stat properties/values. The rest of the SenStat structure memebers are
/// created automatically from the stat xml file generated code.
///
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
/// E_FAIL: Failed to spawn server call.
/// S_OK: Server call spawned successfully.
///
/// @details Calls to this function should use generated Telemetry code, rather than
/// calling the function from title code
HRESULT SentientStatsSend( SenStat *pStat );
/// @brief Sets the send interval for Telemetry. Only works in debug builds
///
/// @param[in] dwIntervalMs
/// The new send interval, in milliseconds. This value is capped at a minimum of 250 ms.
///
/// @details The body of this function is conditionally compiled out of non-debug builds.
///
void SentientSetStatSendInterval( DWORD dwIntervalMs );
/// @brief Requests that Sentient immediately send any stats being buffered
///
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
/// SENTIENT_E_TOO_MANY_CALLS: You tried to flush too quickly after a previous flush.
/// S_OK: Buffered stats will be flushed to the server on the next Sentient::Update() call
///
/// @details This API can only be called once every minute. Any attempts to call the API more frequently
/// will result in the call being throttled, and the API returning SENTIENT_E_TOO_MANY_CALLS
/// Data is not actually sent until the next Sentient::Update() call
HRESULT SentientFlushStats( );
/// @brief Requests that Sentient immediately send any stats being buffered because the title is exiting
///
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
/// SENTIENT_E_TOO_MANY_CALLS: You tried to flush on Exit more than once
/// S_OK: Buffered stats will be flushed to the server on the next Sentient::Update() call
///
/// @details This API can only be called ONCE. Any attempts to call the API more frequently
/// will result in the call being throttled, and the API returning SENTIENT_E_TOO_MANY_CALLS
/// Data is not actually sent until the next Sentient::Update() call
HRESULT SentientFlushStatsOnExit( );
/// @brief Requests that Sentient immediately send any stats being buffered because the title is going to the marketplace and may not return
///
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
/// SENTIENT_E_TOO_MANY_CALLS: You tried to flush on MarketPlace too many times
/// S_OK: Buffered stats will be flushed to the server on the next Sentient::Update() call
///
/// @details Any attempts to call the API too frequently will result in the call being throttled,
/// and the API returning SENTIENT_E_TOO_MANY_CALLS
/// Data is not actually sent until the next Sentient::Update() call
HRESULT SentientFlushStatsOnMarketPlace( );
/// @brief Tells Sentient that an important point in the game was hit and that events should be sent as soon as possible
///
/// @return Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success. Specific values include:
/// SENTIENT_E_NOT_INITIALIZED: You did not call SentientInitialize() first.
/// S_OK: Buffered stats will be flushed to the server within the next minute
///
/// @details This API should be caleld when the game hits an important event or point.
/// Sentient Will send the event data to the server within the next minute, calling this method frequently will not cause any additional sends
HRESULT SentientFlushStatsOnKeyEvent( );
#ifdef SEN_LOGTELEMETRY
// if we're in debug build log out the stat to a file for testing
void SentientDebugLogStatSend(const char *statName, const SenStat *pStat);
#endif
} // namespace Sentient
|
