Adding TODOs to C headers (#190)

Author: jasonsandlin

CppSource/External/libHttpClient

@@ -11,6 +11,7 @@
 #if defined(__cplusplus)
 extern "C" {
 #endif
+
 struct XSAPI_ACHIEVEMENT_TITLE_ASSOCIATION_IMPL;
 struct XSAPI_ACHIEVEMENT_REQUIREMENT_IMPL;
 struct XSAPI_ACHIEVEMENT_PROGRESSION_IMPL;
@@ -105,7 +106,6 @@ typedef struct XSAPI_ACHIEVEMENT_MEDIA_ASSET
     XSAPI_ACHIEVEMENT_MEDIA_ASSET_IMPL* pImpl;
 } XSAPI_ACHIEVEMENT_MEDIA_ASSET;
 
-
 typedef struct XSAPI_ACHIEVEMENT_REWARD
 {
     PCSTR name;
@@ -166,6 +166,7 @@ typedef void(*XSAPI_GET_NEXT_COMPLETION_ROUTINE)(
     _In_ XSAPI_ACHIEVEMENTS_RESULT* achievementsResult,
     _In_opt_ void* context
     );
+
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 AchievementsResultGetNext(
     _In_ XSAPI_ACHIEVEMENTS_RESULT* achievementsResult,
@@ -179,6 +180,7 @@ typedef void(*XSAPI_UPDATE_ACVHIEVEMENT_COMPLETION_ROUTINE)(
     _In_ XSAPI_RESULT_INFO result,
     _In_opt_ void* context
     );
+
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 AchievementServiceUpdateAchievement(
     _In_ XSAPI_XBOX_LIVE_CONTEXT* pContext,
@@ -194,9 +196,10 @@ AchievementServiceUpdateAchievement(
 
 typedef void(*XSAPI_GET_ACHIEVEMENTS_FOR_TITLE_ID_COMPLETION_ROUTINE)(
     _In_ XSAPI_RESULT_INFO result,
-    XSAPI_ACHIEVEMENTS_RESULT* achievementsResult,
+    _In_ XSAPI_ACHIEVEMENTS_RESULT* achievementsResult,
     _In_opt_ void* context
     );
+
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 AchievementServiceGetAchievementsForTitleId(
     _In_ XSAPI_XBOX_LIVE_CONTEXT* pContext,
@@ -217,6 +220,7 @@ typedef void(*XSAPI_GET_ACHIEVEMENT_COMPLETION_ROUTINE)(
     _In_ XSAPI_ACHIEVEMENT* achievement,
     _In_opt_ void* context
     );
+
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 AchievementServiceGetAchievement(
     _In_ XSAPI_XBOX_LIVE_CONTEXT* pContext,
@@ -237,9 +241,6 @@ XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 AchievementServiceReleaseAchievement(
     _In_ XSAPI_ACHIEVEMENT* achievement
     ) XSAPI_NOEXCEPT;
-#if !XDK_API
-
-#endif //!XDK_API
 
 #if defined(__cplusplus)
 } // end extern "C"

CppSource/Include/xsapi/achievements_c.h

@@ -8,12 +8,14 @@
 extern "C" {
 #endif
 
+// TODO: rename to XSAPI_ERROR_CONDITION
 typedef enum XSAPI_RESULT
 {
     XSAPI_RESULT_OK = 0,
 
+    // TODO: remove these generic errors and into platformSpecificErrorCode below
     //////////////////////////////////////////////////////////////////////////
-    // LibHttpClient errors
+    // Generic errors
     //////////////////////////////////////////////////////////////////////////
     XSAPI_RESULT_E_HC_FAIL = -1,
     XSAPI_RESULT_E_HC_POINTER = -2,
@@ -23,27 +25,25 @@ typedef enum XSAPI_RESULT
     XSAPI_RESULT_E_HC_NOTINITIALIZED = -6,
     XSAPI_RESULT_E_HC_FEATURENOTPRESENT = -7,
 
-    XSAPI_RESULT_E_HC_MIN = XSAPI_RESULT_E_HC_FEATURENOTPRESENT,
-    XSAPI_RESULT_E_HC_MAX = XSAPI_RESULT_E_HC_FAIL,
-
     //////////////////////////////////////////////////////////////////////////
-    // XSAPI Core error conditions
+    // XSAPI error conditions
     //////////////////////////////////////////////////////////////////////////
-    XSAPI_RESULT_E_GENERIC_ERROR = 1,
-    XSAPI_RESULT_E_OUT_OF_RANGE = 2,
-    XSAPI_RESULT_E_AUTH = 3,
-    XSAPI_RESULT_E_NETWORK = 4,
-    XSAPI_RESULT_E_HTTP = 5,
-    XSAPI_RESULT_E_HTTP_404_NOT_FOUND = 6,
-    XSAPI_RESULT_E_HTTP_412_PRECONDITION_FAILED = 7,
-    XSAPI_RESULT_E_HTTP_429_TOO_MANY_REQUESTS = 8,
-    XSAPI_RESULT_E_HTTP_SERVICE_TIMEOUT = 9,
-    XSAPI_RESULT_E_RTA = 10
+    XSAPI_RESULT_E_GENERIC_ERROR = -1000,
+    XSAPI_RESULT_E_OUT_OF_RANGE = -1001,
+    XSAPI_RESULT_E_AUTH = -1002,
+    XSAPI_RESULT_E_NETWORK = -1003,
+    XSAPI_RESULT_E_HTTP = -1004,
+    XSAPI_RESULT_E_HTTP_404_NOT_FOUND = -1005,
+    XSAPI_RESULT_E_HTTP_412_PRECONDITION_FAILED = -1006,
+    XSAPI_RESULT_E_HTTP_429_TOO_MANY_REQUESTS = -1007,
+    XSAPI_RESULT_E_HTTP_SERVICE_TIMEOUT = -1008,
+    XSAPI_RESULT_E_RTA = -1008
 
 } XSAPI_RESULT;
 
 typedef struct XSAPI_RESULT_INFO
 {
+    // TODO: add platformSpecificErrorCode and change errorCode to errorCondition
     XSAPI_RESULT errorCode;
     PCSTR errorMessage;
 } XSAPI_RESULT_INFO;

CppSource/Include/xsapi/errors_c.h

@@ -66,28 +66,31 @@ typedef struct XSAPI_LEADERBOARD_QUERY
 } XSAPI_LEADERBOARD_QUERY;
 
 XSAPI_DLLEXPORT XSAPI_LEADERBOARD_QUERY* XBL_CALLING_CONV
-LeaderboardQueryCreate(
-);
+LeaderboardQueryCreate();
+
 XSAPI_DLLEXPORT void XBL_CALLING_CONV
 LeaderboardQuerySetSkipResultToMe(
     _In_ XSAPI_LEADERBOARD_QUERY* leaderboardQuery,
     _In_ bool skipResultToMe
-);
+    );
+
 XSAPI_DLLEXPORT void XBL_CALLING_CONV
 LeaderboardQuerySetSkipResultToRank(
     _In_ XSAPI_LEADERBOARD_QUERY* leaderboardQuery,
     _In_ uint32_t skipResultToRank
-);
+    );
+
 XSAPI_DLLEXPORT void XBL_CALLING_CONV
 LeaderboardQuerySetMaxItems(
     _In_ XSAPI_LEADERBOARD_QUERY* leaderboardQuery,
     _In_ uint32_t maxItems
-);
+    );
+
 XSAPI_DLLEXPORT void XBL_CALLING_CONV
 LeaderboardQuerySetOrder(
     _In_ XSAPI_LEADERBOARD_QUERY* leaderboardQuery,
     _In_ XSAPI_SORT_ORDER order
-);
+    );
 
 typedef struct XSAPI_LEADERBOARD_RESULT
 {
@@ -103,7 +106,7 @@ typedef struct XSAPI_LEADERBOARD_RESULT
 XSAPI_DLLEXPORT bool XBL_CALLING_CONV
 LeaderboardResultHasNext(
     _In_ XSAPI_LEADERBOARD_RESULT* leaderboardResult
-);
+    );
 
 #if !defined(XBOX_LIVE_CREATORS_SDK)
 typedef struct XSAPI_GET_NEXT_RESULT_PAYLOAD
@@ -130,20 +133,21 @@ LeaderboardResultGetNext(
     _In_ GET_NEXT_COMPLETION_ROUTINE completionRoutine,
     _In_opt_ void* completionRoutineContext,
     _In_ uint64_t taskGroupId
-);
+    );
 #endif
 
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 LeaderboardResultGetNextQuery(
     _In_ XSAPI_LEADERBOARD_RESULT* leaderboardResult,
     _Out_ XSAPI_LEADERBOARD_QUERY** nextQuery,
     _Out_ PCSTR* errMessage
-);
+    );
 
 typedef struct XSAPI_LEADERBOARD_SERVICE
 {
-    // todo implement
+    // TODO: implement
 } XSAPI_LEADERBOARD_SERVICE;
+
 #endif //!XDK_API
 
 #if defined(__cplusplus)

CppSource/Include/xsapi/leaderboard_c.h

@@ -10,8 +10,6 @@
 extern "C" {
 #endif
 
-#if !XDK_API
-
 typedef enum XSAPI_PRESENCE_DEVICE_TYPE
 {
     XSAPI_PRESENCE_DEVICE_TYPE_UNKNOWN,
@@ -66,8 +64,6 @@ typedef enum XSAPI_TITLE_PRESENCE_STATE
     XSAPI_TITLE_PRESENCE_STATE_ENDED
 } XSAPI_TITLE_PRESENCE_STATE;
 
-#endif //!XDK_API
-
 #if defined(__cplusplus)
 } // end extern "C"
 #endif // defined(__cplusplus)

CppSource/Include/xsapi/presence_c.h

@@ -13,7 +13,7 @@ extern "C" {
 #endif
 
 #if !XDK_API
-    
+
 struct XSAPI_PREFERRED_COLOR_IMPL;
 struct XSAPI_SOCIAL_MANAGER_PRESENCE_TITLE_RECORD_IMPL;
 struct XSAPI_XBOX_USER_ID_CONTAINER_IMPL;

CppSource/Include/xsapi/social_manager_c.h

@@ -68,80 +68,80 @@ XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 StatsManagerAddLocalUser(
     _In_ XSAPI_XBOX_LIVE_USER* user,
     _Out_ PCSTR* errMessage
-);
+    );
 
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 StatsManagerRemoveLocalUser(
     _In_ XSAPI_XBOX_LIVE_USER* user,
     _Out_ PCSTR* errMessage
-);
+    );
 
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 StatsManagerRequestFlushToService(
     _In_ XSAPI_XBOX_LIVE_USER* user,
     _In_ bool isHighPriority,
     _Out_ PCSTR* errMessage
-);
+    );
 
 XSAPI_DLLEXPORT XSAPI_STAT_EVENT** XBL_CALLING_CONV
 StatsManagerDoWork(
     _Out_ uint32_t* statEventsCount
-);
+    );
 
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 StatsManagerSetStatisticNumberData(
     _In_ XSAPI_XBOX_LIVE_USER* user,
     _In_ PCSTR statName,
     _In_ double statValue,
     _Out_ PCSTR* errMessage
-);
+    );
 
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 StatsManagerSetStatisticIntegerData(
     _In_ XSAPI_XBOX_LIVE_USER* user,
     _In_ PCSTR statName,
     _In_ int64_t statValue,
     _Out_ PCSTR* errMessage
-);
+    );
 
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 StatsManagerSetStatisticStringData(
     _In_ XSAPI_XBOX_LIVE_USER* user,
     _In_ PCSTR statName,
     _In_ PCSTR statValue,
     _Out_ PCSTR* errMessage
-);
+    );
 
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 StatsManagerGetStatNames(
     _In_ XSAPI_XBOX_LIVE_USER* user,
     _Out_ PCSTR** statNameList,
     _Out_ uint32_t* statNameListCount,
     _Out_ PCSTR* errMessage
-);
+    );
 
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 StatsManagerGetStat(
     _In_ XSAPI_XBOX_LIVE_USER* user,
     _In_ PCSTR statName,
     _Out_ XSAPI_STAT_VALUE** statValue,
     _Out_ PCSTR* errMessage
-);
+    );
 
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 StatsManagerDeleteStat(
     _In_ XSAPI_XBOX_LIVE_USER* user,
     _In_ PCSTR statName,
     _Out_ PCSTR* errMessage
-);
+    );
 
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 StatsManagerGetLeaderboard(
     _In_ XSAPI_XBOX_LIVE_USER* user,
     _In_ PCSTR statName,
     _In_ XSAPI_LEADERBOARD_QUERY* query,
     _Out_ PCSTR* errMessage
-);
+    );
 
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 StatsManagerGetSocialLeaderboard(
@@ -150,7 +150,8 @@ StatsManagerGetSocialLeaderboard(
     _In_ PCSTR socialGroup,
     _In_ XSAPI_LEADERBOARD_QUERY* query,
     _Out_ PCSTR* errMessage
-);
+    );
+
 #endif //!XDK_API
 
 #if defined(__cplusplus)

CppSource/Include/xsapi/stats_manager_c.h

@@ -4,6 +4,10 @@
 #pragma once
 #include "types_c.h"
 
+// TODO: Add XML doc comments to this file and elsewhere
+// TODO: Add SAL to structs in this file and elsewhere
+// TODO: Choose consistent naming XSAPI_ or XboxLive_ or Xbl_ here and elsewhere
+// TODO: run and clean code analysis errors
 #if defined(__cplusplus)
 extern "C" {
 #endif
@@ -26,6 +30,7 @@ typedef struct XSAPI_XBOX_LIVE_CONTEXT
 
 #if !(XDK_API | XBOX_UWP)
 
+// TODO: Change to *CreateHandle
 XSAPI_DLLEXPORT XSAPI_RESULT XBL_CALLING_CONV
 XboxLiveContextCreate(
     _In_ CONST XSAPI_XBOX_LIVE_USER* pUser,
@@ -34,6 +39,7 @@ XboxLiveContextCreate(
 
 #endif
 
+// TODO: Change to *CloseHandle, and *DuplicateHandle
 XSAPI_DLLEXPORT void XBL_CALLING_CONV
 XboxLiveContextDelete(
     XSAPI_XBOX_LIVE_CONTEXT* pContext

CppSource/Include/xsapi/xbox_live_context_c.h

@@ -143,10 +143,6 @@ XSAPI_RESULT utils::xsapi_result_from_hc_result(HC_RESULT hcr)
     {
         return XSAPI_RESULT_OK;
     }
-    else if (hcr < XSAPI_RESULT_E_HC_MIN || hcr > XSAPI_RESULT_E_HC_MAX)
-    {
-        return XSAPI_RESULT_E_HC_FAIL;
-    }
     return static_cast<XSAPI_RESULT>(hcr);
 }