1440 lines
71 KiB
C
1440 lines
71 KiB
C
// This code contains NVIDIA Confidential Information and is disclosed to you
|
||
// under a form of NVIDIA software license agreement provided separately to you.
|
||
//
|
||
// Notice
|
||
// NVIDIA Corporation and its licensors retain all intellectual property and
|
||
// proprietary rights in and to this software and related documentation and
|
||
// any modifications thereto. Any use, reproduction, disclosure, or
|
||
// distribution of this software and related documentation without an express
|
||
// license agreement from NVIDIA Corporation is strictly prohibited.
|
||
//
|
||
// ALL NVIDIA DESIGN SPECIFICATIONS, CODE ARE PROVIDED "AS IS.". NVIDIA MAKES
|
||
// NO WARRANTIES, EXPRESSED, IMPLIED, STATUTORY, OR OTHERWISE WITH RESPECT TO
|
||
// THE MATERIALS, AND EXPRESSLY DISCLAIMS ALL IMPLIED WARRANTIES OF NONINFRINGEMENT,
|
||
// MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE.
|
||
//
|
||
// Information and code furnished is believed to be accurate and reliable.
|
||
// However, NVIDIA Corporation assumes no responsibility for the consequences of use of such
|
||
// information or for any infringement of patents or other rights of third parties that may
|
||
// result from its use. No license is granted by implication or otherwise under any patent
|
||
// or patent rights of NVIDIA Corporation. Details are subject to change without notice.
|
||
// This code supersedes and replaces all information previously supplied.
|
||
// NVIDIA Corporation products are not authorized for use as critical
|
||
// components in life support devices or systems without express written approval of
|
||
// NVIDIA Corporation.
|
||
//
|
||
// Copyright (c) 2020-2021 NVIDIA Corporation. All rights reserved.
|
||
|
||
//
|
||
// ===============================================================================================
|
||
//
|
||
// C API declarations for GFN Runtime SDK
|
||
//
|
||
// ===============================================================================================
|
||
/**
|
||
* @file GfnRuntimeSdk_CAPI.h
|
||
*
|
||
* API definitions
|
||
*/
|
||
///
|
||
/// @mainpage Native Runtime Application Programming Interface Reference
|
||
///
|
||
/// @section introduction Introduction
|
||
/// The NVIDIA GFN Runtime SDK provides an Application Programming Interface (API)
|
||
/// to allow game and application developers to interact with parts of the NVIDIA
|
||
/// GeForce NOW ecosystem. Overall integration is provided by various interfaces,
|
||
/// from the native C interfaces described in this documentation, to RESTful
|
||
/// endpoint calls, depending on the feature of the SDK.
|
||
///
|
||
/// This documenation focuses solely on the native C interfaces, and provides the
|
||
/// specifications of each of the native APIs of GFN Runtime SDK, as well as the
|
||
/// requires to use the APIs. For example usage, refer to the Quick Start
|
||
/// documentation and the sample applications provided in the ./samples folder.
|
||
///
|
||
/// @section overview Overview
|
||
///
|
||
/// The GFN Runtime SDK provides a dynamic library with API exports as defined in
|
||
/// this document, which is distributed with and loaded by the game/application that
|
||
/// utilizes the APIs. The loading of this library should be done in a way that
|
||
/// validates the authenticity of the binary. For example, on Windows, checking for
|
||
/// a valid digital signature, and that signature is from NVIDIA Corporation.
|
||
///
|
||
/// The behavior of the APIs depends on the environment the application is running in;
|
||
/// either on a client/user system or in the GeForce NOW (GFN) cloud environment. Each
|
||
/// API defines which of the environments it is designed to run in. Some of the APIs
|
||
/// can execute in only one of the environments; either the local client or GFN cloud
|
||
/// environment. These APIs will return a well-defined error code "gfnCallWrongEnvironment"
|
||
/// to denote when call was not applicable to the execution environment.
|
||
///
|
||
/// For additional high-level overview, please refer to the SDK primer available as
|
||
/// part of the documentation section of the SDK's repository. For references on
|
||
/// correct API calls for the most common of integration scenarios, please prefer to
|
||
/// the SDK Quick Start Guide.
|
||
///
|
||
/// @section keyconcepts Key Concepts
|
||
///
|
||
/// GFN Runtime API methods are used to make requests from or to notify the GFN
|
||
/// backend.
|
||
///
|
||
/// When your application is operating outside of the GFN environment, these
|
||
/// methods are simple stubs that incur almost no cost, so it's safe to add
|
||
/// these to your main build.
|
||
///
|
||
/// The calling convention differs by which API you've selected to use. In most
|
||
/// cases, the methods return a GfnRuntimeError result, which can be used by the
|
||
/// application to check for errors. In addition, some methods are asynchronous
|
||
/// by nature, but provide synchronous variants when possible.
|
||
///
|
||
/// @section apiReference API Reference
|
||
/// @subsection general_section General / Common methods
|
||
/// @ref general
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnInitializeRuntimeSdk
|
||
///
|
||
/// @copydoc gfnInitializeRuntimeSdk
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnShutdownRuntimeSdk
|
||
///
|
||
/// @copydoc gfnShutdownRuntimeSdk
|
||
///
|
||
/// @subsection launcher_game_section Launcher or Game Specific Methods
|
||
/// @ref launcher
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnIsRunningInCloud
|
||
///
|
||
/// @copydoc gfnIsRunningInCloud
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnIsRunningInCloudSecure
|
||
///
|
||
/// @copydoc gfnIsRunningInCloudSecure
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnCloudCheck
|
||
///
|
||
/// @copydoc gfnCloudCheck
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnFree
|
||
///
|
||
/// @copydoc gfnFree
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnIsTitleAvailable
|
||
///
|
||
/// @copydoc gfnIsTitleAvailable
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnGetTitlesAvailable
|
||
///
|
||
/// @copydoc gfnGetTitlesAvailable
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C sync | @ref gfnSetupTitle
|
||
///
|
||
/// @copydoc gfnSetupTitle
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C sync | @ref gfnTitleExited
|
||
///
|
||
/// @copydoc gfnTitleExited
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnGetClientIp
|
||
///
|
||
/// @copydoc gfnGetClientIp
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnGetClientLanguageCode
|
||
///
|
||
/// @copydoc gfnGetClientLanguageCode
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnGetClientCountryCode
|
||
///
|
||
/// @copydoc gfnGetClientCountryCode
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnGetClientInfo
|
||
///
|
||
/// @copydoc gfnGetClientInfo
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnGetSessionInfo
|
||
///
|
||
/// @copydoc gfnGetSessionInfo
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnStartStream
|
||
///
|
||
/// @copydoc gfnStartStream
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnStartStreamAsync
|
||
///
|
||
/// @copydoc gfnStartStreamAsync
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnStopStream
|
||
///
|
||
/// @copydoc gfnStopStream
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnStopStreamAsync
|
||
///
|
||
/// @copydoc gfnStopStreamAsync
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnGetPartnerData
|
||
///
|
||
/// @copydoc gfnGetPartnerData
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnGetPartnerSecureData
|
||
///
|
||
/// @copydoc gfnGetPartnerSecureData
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnAppReady
|
||
///
|
||
/// @copydoc gfnAppReady
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnSetActionZone
|
||
///
|
||
/// @copydoc gfnSetActionZone
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnSendMessage
|
||
///
|
||
/// @copydoc gfnSendMessage
|
||
///
|
||
/// @subsection callback_section Callback-related Methods
|
||
/// @ref callbacks
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnRegisterExitCallback
|
||
///
|
||
/// @copydoc gfnRegisterExitCallback
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnRegisterPauseCallback
|
||
///
|
||
/// @copydoc gfnRegisterPauseCallback
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnRegisterInstallCallback
|
||
///
|
||
/// @copydoc gfnRegisterInstallCallback
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnRegisterStreamStatusCallback
|
||
///
|
||
/// @copydoc gfnRegisterStreamStatusCallback
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnRegisterSessionInitCallback
|
||
///
|
||
/// @copydoc gfnRegisterSessionInitCallback
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnRegisterClientInfoCallback
|
||
///
|
||
/// @copydoc gfnRegisterClientInfoCallback
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnRegisterNetworkStatusCallback
|
||
///
|
||
/// @copydoc gfnRegisterNetworkStatusCallback
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnRegisterMessageCallback
|
||
///
|
||
/// @copydoc gfnRegisterMessageCallback
|
||
///
|
||
/// Language | API
|
||
/// -------- | -------------------------------------
|
||
/// C | @ref gfnOpenURLOnClient
|
||
///
|
||
/// @copydoc gfnOpenURLOnClient
|
||
|
||
#ifndef GFN_SDK_RUNTIME_CAPI_H
|
||
#define GFN_SDK_RUNTIME_CAPI_H
|
||
|
||
|
||
#include "GfnSdk.h"
|
||
|
||
// Defining GfnRuntimeError for backwards compatibility
|
||
#define GfnRuntimeError GfnError
|
||
|
||
#ifdef __cplusplus
|
||
extern "C"
|
||
{
|
||
#endif
|
||
// ============================================================================================
|
||
// Constants/Enums
|
||
// ============================================================================================
|
||
|
||
/** @brief Returned by callbacks the application registers with the GeForce NOW Runtime SDK, or passes
|
||
* in to asynchronous SDK calls.
|
||
*/
|
||
typedef enum GfnApplicationCallbackResult
|
||
{
|
||
crCallbackSuccess = 0, ///< Return to indicate that a callback has performed the requested operation
|
||
crCallbackFailure = -1 ///< Return to indicate that a callback did not perform the requested operation
|
||
} GfnApplicationCallbackResult;
|
||
|
||
/** @brief Returned from @ref gfnIsRunningInCloudSecure to denote security assurance that the calling application is running, untampered,
|
||
* in the GFN cloud environment.
|
||
*/
|
||
typedef enum GfnIsRunningInCloudAssurance
|
||
{
|
||
gfnNotCloud = 0, ///< Not considered to be running in GFN cloud, as it looks like a client/local system.
|
||
gfnIsCloudLowAssurance = 1, ///< Considered to be running in GFN Cloud, using software heuristics that are not guaranteed against circumvention.
|
||
gfnIsCloudMidAssurance = 2, ///< Considered to be running in GFN Cloud, using software and network heuristics that are difficult to circumvent.
|
||
gfnIsCloudHighAssurance = 3 ///< Considered to be running in GFN Cloud, using software and hardware heuristics that are near impossible to circumvent.
|
||
} GfnIsRunningInCloudAssurance;
|
||
|
||
/// @brief Output response when streaming has started
|
||
typedef struct StartStreamResponse
|
||
{
|
||
bool downloaded; ///< True if GeForce NOW client components were downloaded from the release site.
|
||
} StartStreamResponse;
|
||
|
||
/// @brief Callback function signation for notifications on status of starting a streaming session.
|
||
typedef void(GFN_CALLBACK *StartStreamCallbackSig)(GfnRuntimeError, StartStreamResponse*, void* context);
|
||
|
||
/// @brief Callback function signation for notifications on status of stop a streaming session.
|
||
typedef void(GFN_CALLBACK* StopStreamCallbackSig)(GfnRuntimeError, void* context);
|
||
|
||
/// @brief Input data for gfnStartStream
|
||
typedef struct StartStreamInput
|
||
{
|
||
unsigned int uiTitleId; ///< GFN-sourced game-specific unique identifier.
|
||
const char* pchPartnerData; ///< Optional non-secure partner data that is passed to the streaming cloud instance and can be retrieved in that instance of application.
|
||
const char* pchPartnerSecureData; ///< Optional secure partner data that is guaranteed to be protected through the GFN pipeline.
|
||
} StartStreamInput;
|
||
|
||
/// @brief Input to the function registered via gfnRegisterInstallCallback (if any).
|
||
typedef struct TitleInstallationInformation
|
||
{
|
||
const char* pchPlatformAppId; ///< Platform application ID passed into the API.
|
||
const char* pchBuildPath; ///< The path at which game build files can be found.
|
||
const char* pchMetadataPath; ///< Optionally contains the path at which game metadata can be found, else NULL.
|
||
} TitleInstallationInformation;
|
||
|
||
/// @brief Possible states of the client streamer
|
||
typedef enum GfnStreamStatus
|
||
{
|
||
GfnStreamStatusInit, ///< Initial default state
|
||
GfnStreamStatusNetworkTest, ///< Client is running a network test to determine the best zone
|
||
GfnStreamStatusLoading, ///< Client is loading the game
|
||
GfnStreamStatusStreaming, ///< Client is actively streaming
|
||
GfnStreamStatusDone, ///< Client has successfully finished streaming
|
||
GfnStreamStatusError, ///< Client has stopped streaming and has entered an error state
|
||
GfnStreamStatusGotInputFocus, ///< Client has gained input focus to the streamer window
|
||
GfnStreamStatusLostInputFocus ///< Client has lost input focus to the streamer window
|
||
} GfnStreamStatus;
|
||
|
||
/// @brief Converts a GfnStreamStatus enum to a human-readable string
|
||
inline const char* GfnStreamStatusToString(GfnStreamStatus status)
|
||
{
|
||
switch (status)
|
||
{
|
||
case GfnStreamStatusInit: return "Init";
|
||
case GfnStreamStatusNetworkTest: return "NetworkTest";
|
||
case GfnStreamStatusLoading: return "Loading";
|
||
case GfnStreamStatusStreaming: return "Streaming";
|
||
case GfnStreamStatusDone: return "Done";
|
||
case GfnStreamStatusError: return "Error";
|
||
case GfnStreamStatusGotInputFocus: return "GotInputFocus";
|
||
case GfnStreamStatusLostInputFocus: return "LostInputFocus";
|
||
}
|
||
return "Unknown GfnStreamStatus";
|
||
}
|
||
|
||
|
||
/// @brief Specifies the action in GfnSetActionZone API
|
||
/// Deprecated with SetActionZone removal
|
||
typedef enum GfnActionType
|
||
{
|
||
gfnActionNone = 0, ///< No event
|
||
gfnEditBox = 1, ///< Action to specify an editable text box rect on screen
|
||
gfnActionMAX ///< Sentinel value, do not use
|
||
} GfnActionType;
|
||
|
||
|
||
#define IP_V4_SIZE (17) // INET_ADDRSTRLEN + NULL
|
||
#define IP_V6_SIZE (49) // INET6_ADDRSTRLEN + NULL
|
||
#define CC_SIZE (3) // ISO 3166-1 Alpha-2
|
||
#define LOCALE_SIZE (6) // ISO 639-1 Alpha-2
|
||
#define SESSION_ID_SIZE (38)
|
||
|
||
/// @brief Types of operating systems that can be reported by the SDK
|
||
typedef enum GfnOsType
|
||
{
|
||
gfnUnknownOs = 0,
|
||
gfnWindows = 1,
|
||
gfnMacOs = 2,
|
||
gfnShield = 3,
|
||
gfnAndroid = 4,
|
||
gfnIOs = 5,
|
||
gfnIPadOs = 6,
|
||
gfnChromeOs = 7,
|
||
gfnLinux = 8,
|
||
gfnTizen = 9,
|
||
gfnWebOs = 10,
|
||
gfnTvOs = 11,
|
||
gfnOsTypeMax = 11
|
||
} GfnOsType;
|
||
|
||
/// @brief Client info blob
|
||
typedef struct
|
||
{
|
||
unsigned int version; ///< Deprecated, value will be ignored
|
||
GfnOsType osType; ///< Operating System type
|
||
char ipV4[IP_V4_SIZE]; ///< IPV4 address, example - "192.168.0.1"
|
||
char country[CC_SIZE]; ///< ISO 3166-1 alpha-2 standard country code, example - "us"
|
||
char locale[LOCALE_SIZE]; ///< ISO 639-1 Alpha-2 standard locale, example - "en-us"
|
||
unsigned int RTDAverageLatencyMs; ///< Round Trip Delay - Average Latency in milliseconds
|
||
GfnResolutionInfo clientResolution; ///< Client device's physical resolution, if reported. If client does not report, expect values of zero.
|
||
} GfnClientInfo;
|
||
|
||
/// @brief Type of data which changed. This enum will be expanded over time
|
||
typedef enum GfnClientInfoChangeType
|
||
{
|
||
gfnOs = 0, ///< Change in OS of GFN Client
|
||
gfnIP = 1, ///< Change in IP of GFN Client (due to device switch/reconnect)
|
||
gfnClientResolution = 2, ///< Change in resolution of GFN Client
|
||
gfnSafeZone = 3, ///< Change in safe zone rectangle (due to device switch or rotation)
|
||
gfnClientDataChangeTypeMax = 3 ///< Sentinel value for GfnClientInfoChangeType
|
||
} GfnClientDataChangeType;
|
||
|
||
/// @brief An update notification for a piece of client info data
|
||
typedef struct GfnClientInfoUpdateData
|
||
{
|
||
unsigned int version; ///< Deprecated, value will be ignored
|
||
GfnClientDataChangeType updateType; ///< Type of GFN Client data that changed
|
||
union
|
||
{
|
||
GfnOsType osType; ///< Operating System type
|
||
char ipV4[IP_V4_SIZE]; ///< IPV4 address, example - "192.168.0.1"
|
||
GfnResolutionInfo clientResolution; ///< Client device's physical resolution, if reported. If client does not report, expect values of zero.
|
||
GfnRect safeZone; ///< Client safe zone rectangle (title-safe area), in normalized coordinates. If the entire screen is title-safe because of device type, then expect values of zero.
|
||
} data;
|
||
} GfnClientInfoUpdateData;
|
||
|
||
/// @brief The type of network status data which changed. This enum will likely be expanded over time.
|
||
typedef enum GfnNetworkStatusChangeType
|
||
{
|
||
gfnRTDAverageLatency = 0, ///< Change in RTDAverageLatency
|
||
gfnNetworkStatusChangeTypeMax = 0 ///< Sentinel value for GfnNetworkStatusChangeType
|
||
} GfnNetworkStatusChangeType;
|
||
|
||
/// @brief An update notification for a piece of network status data. This structure will likely be expanded over time.
|
||
typedef struct GfnNetworkStatusUpdateData
|
||
{
|
||
unsigned int version; ///< Deprecated, value will be ignored
|
||
GfnNetworkStatusChangeType updateType; ///< Network Status Update type
|
||
union
|
||
{
|
||
unsigned int RTDAverageLatencyMs; ///< Round Trip Delay - Average Latency in milliseconds
|
||
} data;
|
||
} GfnNetworkStatusUpdateData;
|
||
|
||
|
||
/// @brief Session info blob
|
||
typedef struct
|
||
{
|
||
unsigned int sessionMaxDurationSec; ///< Maximum total time allowed for the session in seconds
|
||
unsigned int sessionTimeRemainingSec; ///< Nominal time remaining in the session in seconds
|
||
char sessionId[SESSION_ID_SIZE]; ///< NVIDIA-defined unique indentifier for the session
|
||
bool sessionRTXEnabled; ///< Defines if RTX support is enabled for the session
|
||
} GfnSessionInfo;
|
||
|
||
/// @brief Challenge data passed in to @ref gfnCloudCheck API
|
||
typedef struct GfnCloudCheckChallenge
|
||
{
|
||
const char* nonce; ///< A pointer to randomly generated data to be used as the payload of the challenge message. If set to nullptr GFN SDK will generate a random challenge on its own.
|
||
unsigned int nonceSize; ///< The size of the data pointed to by nonce. It is recommended that nonce is at least 16 byte (128 bit) long.
|
||
} GfnCloudCheckChallenge;
|
||
|
||
/// @brief Response data received in the @ref gfnCloudCheck API
|
||
typedef struct GfnCloudCheckResponse
|
||
{
|
||
const char* attestationData; ///< If the cloud check is successful, the attestationData is cryptographically signed message containing the same nonce that was provided in the challenge; otherwise, this field is set to nullptr.
|
||
unsigned int attestationDataSize; ///< The size of the attestationData field in case it is not empty; zero otherwise
|
||
} GfnCloudCheckResponse;
|
||
|
||
// ============================================================================================
|
||
// Callback signatures
|
||
// ============================================================================================
|
||
|
||
// Callbacks that client code should implement and register via the appropriate callback
|
||
// registration function (listed as part of the C API below).
|
||
/// @brief Callback function for notification when a game should exit due to session shutdown request. Register via gfnRegisterExitCallback API.
|
||
typedef GfnApplicationCallbackResult(GFN_CALLBACK *ExitCallbackSig)(void* pUserContext);
|
||
/// @brief Callback function for notification when a game should pause due to user changing focus from the session. Register via gfnRegisterPauseCallback API.
|
||
typedef GfnApplicationCallbackResult(GFN_CALLBACK *PauseCallbackSig)(void* pUserContext);
|
||
/// @brief Callback function for notification when a game is being installed to allow for installation actions. Register via gfnRegisterInstallCallback API.
|
||
typedef GfnApplicationCallbackResult(GFN_CALLBACK *InstallCallbackSig)(const TitleInstallationInformation* pInfo, void* pUserContext);
|
||
/// @brief Callback function for notifications on status of starting a streaming session. Register via gfnRegisterStreamStatusCallback API.
|
||
typedef GfnApplicationCallbackResult(GFN_CALLBACK *StreamStatusCallbackSig)(GfnStreamStatus status, void* pUserContext);
|
||
/// @brief Callback function for notifications when a game should save its state. Register via gfnRegisterSaveCallback API.
|
||
typedef GfnApplicationCallbackResult(GFN_CALLBACK* SaveCallbackSig)(void* pUserContext);
|
||
/// @brief Callback function for notifications when a game should continue late-stage initialization. Register via gfnRegisterSessionInitCallback API.
|
||
/// Function should consume or copy the passed-in partnerInfoMutable string
|
||
typedef GfnApplicationCallbackResult(GFN_CALLBACK* SessionInitCallbackSig)(const char* partnerInfoMutable, void* pUserContext);
|
||
/// @brief Callback function for notifications on client info changes. Register via gfnRegisterClientInfoCallback API.
|
||
typedef GfnApplicationCallbackResult(GFN_CALLBACK* ClientInfoCallbackSig)(GfnClientInfoUpdateData* pUpdate, const void* pUserContext);
|
||
/// @brief Callback function for notifications on network status changes. Register via gfnRegisterNetworkStatusCallback API.
|
||
typedef GfnApplicationCallbackResult(GFN_CALLBACK* NetworkStatusCallbackSig)(GfnNetworkStatusUpdateData* pUpdate, const void* pUserContext);
|
||
/// @brief Callback function for notifications when an application receives a custom message.
|
||
typedef GfnApplicationCallbackResult(GFN_CALLBACK* MessageCallbackSig)(const GfnString* pStrData, void* pUserContext);
|
||
|
||
// ============================================================================================
|
||
// C API
|
||
// ============================================================================================
|
||
|
||
// ============================================================================================
|
||
// SDK Initialization / Shutdown
|
||
|
||
/// @defgroup general General / Common Methods
|
||
/// The functions contained in this section control the lifecycle of the SDK.
|
||
/// @{
|
||
|
||
/// @par Description
|
||
/// Should be called at application startup and prior to any other GFN Runtime API methods.
|
||
/// The SDK features which become available as a result of initializing the GeForce NOW
|
||
/// SDK are dependent on the type of environment in which the SDK operates (client or cloud).
|
||
///
|
||
/// @par Environment
|
||
/// Cloud and Client
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Call as soon as possible during application startup.
|
||
///
|
||
/// @param displayLanguage - Language to use for any UI, such as GFN download and install progress dialogs.
|
||
/// Defaults to system language if not defined.
|
||
/// @retval gfnSuccess - If the SDK was initialized and all SDK features are available.
|
||
/// @retval gfnInitSuccessClientOnly - If the SDK was initialized, but only client-side functionality is available, such as
|
||
/// calls to gfnStartStream. By definition, gfnIsRunningInCloud is expected to return false
|
||
/// in this scenario.
|
||
/// @retval gfnUnableToAllocateMemory - SDK initialization failed due to lack of available memory, and no SDK functionality is
|
||
/// available.
|
||
/// @retval gfnInitFailure - SDK initialization failed for any other reason, and no SDK functionality is available.
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnInitializeRuntimeSdk(GfnDisplayLanguage displayLanguage);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Releases the SDK, and frees up memory allocated by GFN and disconnects from GFN backend.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud and Client
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Call during application shutdown or when GFN Runtime API methods are no longer needed.
|
||
NVGFNSDK_EXPORT void NVGFNSDKApi gfnShutdownRuntimeSdk();
|
||
/// @}
|
||
|
||
/// @defgroup callbacks Client Callback Registration
|
||
/// Callback registration functions to receive various messages / requests from the SDK.
|
||
/// Register only after calling gfnInitializeRuntimeSdk().
|
||
/// @{
|
||
|
||
///
|
||
/// @par Description
|
||
/// Register an application function with GeForce NOW that is called when the user has requested
|
||
/// to end the GeForce NOW session to allow the application to perform exit operations during
|
||
/// session shutdown.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Register an application function that is called when GeForce NOW will end the current session.
|
||
/// Note: This callback function allows an application to respond to a user's request to end a session,
|
||
/// for example, to perform a clean exit of the application. The application is given 5 seconds to
|
||
/// perform activities and return from the callback function before session shutdown activities continue.
|
||
///
|
||
/// @param exitCallback - Function pointer to application code to call when GeForce NOW
|
||
/// needs to exit the game.
|
||
/// @param pUserContext - Pointer to user context, which will be passed unmodified to the
|
||
/// registered callback. Can be NULL.
|
||
///
|
||
/// @retval gfnSuccess - On success, when running in a GeForce NOW environment
|
||
/// @retval gfnInternalError - If callback could not be registered
|
||
/// @retval gfnInvalidParameter - If exitCallback function pointer is NULL.
|
||
/// @retval gfnCallWrongEnvironment - If callback could not be registered since this function
|
||
/// was called outside of a cloud execution environment
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnRegisterExitCallback(ExitCallbackSig exitCallback, void* pUserContext);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Register an application callback with GeForce NOW to be called when GeForce NOW
|
||
/// needs to pause the game on the user's behalf. For Multiplayer games, it is
|
||
/// recommended that this is implemented similar to a client disconnect.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Register an application function to call when GeForce NOW needs to pause the game.
|
||
/// Note: Callback should return as soon as the game process is paused.
|
||
/// Resuming should occur when the user interacts with the game UI.
|
||
///
|
||
/// @param pauseCallback - Function pointer to application code to call when
|
||
/// GeForce NOW needs to pause the game
|
||
/// @param pUserContext - Pointer to user context, which will be passed unmodified to the
|
||
/// registered callback. Can be NULL.
|
||
///
|
||
/// @retval gfnSuccess - On success, when running in a GeForce NOW environment
|
||
/// @retval gfnInternalError - If callback could not be registered
|
||
/// @retval gfnInvalidParameter - If pauseCallback function pointer is NULL.
|
||
/// @retval gfnCallWrongEnvironment - If callback could not be registered since this function
|
||
/// was called outside of a cloud execution environment
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnRegisterPauseCallback(PauseCallbackSig pauseCallback, void* pUserContext);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Register an application callback with GeForce NOW to be called after a successful call to
|
||
/// @ref gfnSetupTitle. Typically, the callback would handle any additional installation steps that
|
||
/// are necessary after GeForce NOW performs its own setup for a given title.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Register a function to call after a successful call to gfnSetupTitle.
|
||
///
|
||
/// @param installCallback - Function pointer to application code to call after
|
||
/// GeForce NOW successfully performs its own title setup.
|
||
/// @param pUserContext - Pointer to user context, which will be passed unmodified to the
|
||
/// registered callback. Can be NULL.
|
||
///
|
||
/// @retval gfnSuccess - On success, when running in a GeForce NOW environment
|
||
/// @retval gfnInternalError - If callback could not be registered
|
||
/// @retval gfnInvalidParameter - If installCallback function pointer is NULL.
|
||
/// @retval gfnCallWrongEnvironment - If callback could not be registered since this function
|
||
/// was called outside of a cloud execution environment
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnRegisterInstallCallback(InstallCallbackSig installCallback, void* pUserContext);
|
||
/// @}
|
||
|
||
///
|
||
/// @par Description
|
||
/// Register a callback that gets called on the user's PC when the streaming session state changes
|
||
///
|
||
/// @par Environment
|
||
/// Client
|
||
///
|
||
/// @par Platform
|
||
/// Windows
|
||
///
|
||
/// @par Usage
|
||
/// Register a function to call when stream status changes on the user's client PC
|
||
///
|
||
/// @param streamStatusCallback - Function pointer to application code to call after
|
||
/// the GeForce NOW streamer changes state
|
||
/// @param pUserContext - Pointer to user context, which will be passed unmodified to the
|
||
/// registered callback. Can be NULL.
|
||
///
|
||
/// @retval gfnSuccess - On success, when running on the client PC
|
||
/// @retval gfnCallWrongEnvironment - If callback could not be registered since this function
|
||
/// was called outside of a client execution environment
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnRegisterStreamStatusCallback(StreamStatusCallbackSig streamStatusCallback, void* pUserContext);
|
||
/// @}
|
||
|
||
///
|
||
/// @par Description
|
||
/// Register an application callback with GeForce NOW to be called when GeForce NOW needs the application
|
||
/// to save user progress. It is recommended that this be implemented as an autosave if
|
||
/// such a feature is supported by your application.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Register an application function to call when GeForce NOW needs the application to save game or user data.
|
||
/// The callback function should trigger the save of game state and return when completed.
|
||
///
|
||
/// @param saveCallback - Function pointer to application code to call when GeForce NOW needs
|
||
/// the application to save user data
|
||
/// @param pUserContext - Pointer to user context, which will be passed unmodified to the
|
||
/// callback specified. Can be NULL.
|
||
///
|
||
/// @retval gfnSuccess - On success when running in a GeForce NOW environment
|
||
/// @retval gfnInternalError - If callback was not registered
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnRegisterSaveCallback(SaveCallbackSig saveCallback, void* pUserContext);
|
||
/// @}
|
||
|
||
///
|
||
/// @par Description
|
||
/// Register an application callback with GeForce NOW to be called when a GeForce NOW user has connected to the game seat
|
||
/// to start a streaming session. This callback is used as part of the Pre-warm feature.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Register an application function to call when a GeForce NOW user has connected to the game seat to allow the game to load
|
||
/// user-specific data and start game play for the user. Callback should return once loading is complete and user
|
||
/// can interact with the game.
|
||
/// Note: The callback function is given 30 second to complete and call @ref GfnAppReady. If this time elapses, before the
|
||
/// function is called, the session will begin streaming frames to the user even if the game is still loading user data.
|
||
///
|
||
/// @param sessionInitCallback - Function pointer to application code to call when GFN is
|
||
/// ready for the application to finalize loading
|
||
/// @param pUserContext - Pointer to user context, which will be passed unmodified to the
|
||
/// callback specified. Can be NULL.
|
||
///
|
||
/// @retval gfnSuccess - On success when running in a GeForce NOW environment
|
||
/// @retval gfnInvalidParameter - If callback was NULL
|
||
/// @retval gfnAPINotInit - SDK was not initialized
|
||
/// @retval gfnAPINotFound - If the API was not found in the GeForce NOW SDK Library
|
||
/// @retval gfnCallWrongEnvironment - If the on-seat dll detected that it was not on a game seat
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnRegisterSessionInitCallback(SessionInitCallbackSig sessionInitCallback, void* pUserContext);
|
||
/// @}
|
||
|
||
///
|
||
/// @par Description
|
||
/// Register an application callback with GeForce NOW to be called when a message is sent to the application via the
|
||
/// SendMessage feature as part of GeForce NOW's support for two-way communication between client application and
|
||
/// the game application running in the game seat.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Provide a callback function that will be called when a message is sent to the application from the SendMessage feature.
|
||
///
|
||
/// @param messageCallback - Function pointer to application code to call when a message
|
||
/// has been received.
|
||
/// @param pUserContext - Pointer to user context, which will be passed unmodified to the
|
||
/// callback specified. Can be NULL.
|
||
///
|
||
/// @retval gfnSuccess - On success when running in a GFN environment
|
||
/// @retval gfnInvalidParameter - If callback was NULL
|
||
/// @retval gfnAPINotInit - SDK was not initialized
|
||
/// @retval gfnAPINotFound - If the API was not found in the GeForce NOW SDK Library
|
||
/// @retval gfnCallWrongEnvironment - If the on-seat dll detected that it was not on a game seat
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnRegisterMessageCallback(MessageCallbackSig messageCallback, void* pUserContext);
|
||
///
|
||
/// @par Description
|
||
/// Register an application callback with GeForce NOW to be called when certain client info that is part of @ref gfnGetClientInfo API changes
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Register an application function to call when a the client information from the GeForce NOW user's client system has changed
|
||
///
|
||
/// @param clientInfoCallback - Function pointer to application code to call when client information has changed
|
||
/// @param pUserContext - Pointer to user context, which will be passed unmodified to the
|
||
/// callback specified. Can be NULL.
|
||
///
|
||
/// @retval gfnSuccess - On success when running in a GeForce NOW environment
|
||
/// @retval gfnInvalidParameter - If callback was NULL
|
||
/// @retval gfnAPINotInit - SDK was not initialized
|
||
/// @retval gfnAPINotFound - If the API was not found in the GeForce NOW SDK Library
|
||
/// @retval gfnCallWrongEnvironment - If the on-seat dll detected that it was not on a game seat
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnRegisterClientInfoCallback(ClientInfoCallbackSig clientInfoCallback, void* pUserContext);
|
||
/// @}
|
||
|
||
///
|
||
/// @par Description
|
||
/// Register an application callback with GeForce NOW to be called when client latency changes
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Register an application function to call when a the network latency from the GeForce NOW user's client system has changed
|
||
///
|
||
/// @param networkStatusCallback - Function pointer to application code to call when network latency has changed
|
||
/// @param updateRateMs - The targeted rate at which callbacks should occur
|
||
/// @param pUserContext - Pointer to user context, which will be passed unmodified to the
|
||
/// callback specified. Can be NULL.
|
||
///
|
||
/// @retval gfnSuccess - On success when running in a GeForce NOW environment
|
||
/// @retval gfnInvalidParameter - If callback was NULL
|
||
/// @retval gfnAPINotInit - SDK was not initialized
|
||
/// @retval gfnAPINotFound - If the API was not found in the GFN SDK Library
|
||
/// @retval gfnCallWrongEnvironment - If the on-seat dll detected that it was not on a game seat
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnRegisterNetworkStatusCallback(NetworkStatusCallbackSig networkStatusCallback, unsigned int updateRateMs, void* pUserContext);
|
||
/// @}
|
||
|
||
// ============================================================================================
|
||
// Application -> GeForce NOW SDK communication
|
||
// The application should call these methods at the appropriate locations.
|
||
/// @defgroup launcher Launcher Application Methods
|
||
/// The functions is this section are called from a launcher in either the appropriate
|
||
/// cloud or client environment.
|
||
/// @{
|
||
|
||
///
|
||
/// @par Description
|
||
/// Quickly determines if the calling application is running in GFN environment or not with a low
|
||
/// security assurance, and without requiring process registration.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud and Client
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Use to quickly determine whether to enable / disable any low-value GFN cloud environment
|
||
/// specific application logic, for example, to block any calls to @ref gfnStartStream() to
|
||
/// avoid an error, or to know if @ref gfnGetTitlesAvailable can be called without an error.
|
||
///
|
||
/// @warning
|
||
/// This API is meant to fill the need to quickly determine if the call looks to be in the
|
||
/// GFN cloud environment. It purposefully trades off resource-intensive checks for fast response.
|
||
/// Do not tie any logic or features of value to this API as the call stack could be tampered with.
|
||
/// For that purpose, use @ref gfnIsRunningInCloudSecure.
|
||
///
|
||
/// @retval true - Application is running on a GFN game seat virtual machine
|
||
/// in the GeForce NOW cloud.
|
||
/// @retval false - Application is not running in the GeForce NOW cloud or in a
|
||
/// GeForce NOW test environment. This value will also be returned if
|
||
/// called before gfnInitializeRuntimeSdk().
|
||
///
|
||
NVGFNSDK_EXPORT bool NVGFNSDKApi gfnIsRunningInCloud();
|
||
|
||
///
|
||
/// @par Description
|
||
/// Determines if calling application is running in GFN environment or not, and what degree of security assurance is
|
||
/// assigned to the result.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud and Client
|
||
///
|
||
/// @par Platform
|
||
/// Windows
|
||
///
|
||
/// @par Usage
|
||
/// Call from an NVIDIA-approved process to securely determine whether running in GFN cloud, and use the
|
||
/// GfnIsRunningInCloudAssurance value to decide the risk to enable any application specific logic
|
||
/// for that environment.
|
||
///
|
||
/// @warning
|
||
/// This API must be called from a process that has been registered with NVIDIA, or it will return an error.
|
||
/// Refer to the Cloud Check API Guide on how to get your application registered. To prevent
|
||
/// man-in-the-middle (MiM) attacks, you must also securely load the SDK library, checking the integrity
|
||
/// of the digital signature on the binary. Make sure to use the value returned from GfnIsRunningInCloudAssurance
|
||
/// to decide if the check was certain enough without tampering to enable the logic or feature associated
|
||
/// with the API call.
|
||
///
|
||
/// @param assurance - Level of assurance that API is running in GFN cloud environment
|
||
///
|
||
/// @retval gfnSuccess - On success
|
||
///
|
||
/// @return Otherwise, appropriate error code
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnIsRunningInCloudSecure(GfnIsRunningInCloudAssurance* assurance);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Determines if calling application is running in GFN environment or not. It also provides a
|
||
/// cryptographically signed response if requested, which can be verified either locally or via 3rd party backend.
|
||
/// Refer to the Cloud Check API Guide on how to validate attestation data in response.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud and Client
|
||
///
|
||
/// @par Platform
|
||
/// Windows
|
||
///
|
||
/// @par Usage
|
||
/// This API can be used from any execution context - privileged or not.
|
||
///
|
||
/// @param challenge - Optional input parameter, that can be used to pass in nonce data.
|
||
/// If a non-null challenge is passed in, then the response parameter is mandatory.
|
||
///
|
||
/// @param response - Optional output parameter, that receives the signed attestation response from the API.
|
||
///
|
||
/// @param isCloudEnvironment - Optional output parameter, that receives true value if the caller is in the GFN environment.
|
||
///
|
||
/// @retval gfnSuccess - On success indicates cloud check was performed successfully.
|
||
/// @retval gfnInvalidParameter - NULL pointer passed in response parameter when challenge parameter is nonzero.
|
||
/// @retval gfnNotAuthorized - Indicates the application is either not properly onboarded (missing allow - list),
|
||
/// or the application attempted to perform cloud check in an unsafe environment (patched game seat).
|
||
/// @retval gfnBackendError - Indicates the API could not communicate with the GFN backend services to confirm it is running in GFN environment.
|
||
/// @retval gfnThrottled - API call was throttled for exceeding limit
|
||
NVGFNSDK_EXPORT GfnRuntimeError gfnCloudCheck(const GfnCloudCheckChallenge* challenge, GfnCloudCheckResponse* response, bool* isCloudEnvironment);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Determines if a specific title is available to launch in current streaming session
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Use to determine if a title is available to be streamed from the active GFN cloud instance,
|
||
/// for example, to show a "Play" button in a platform launcher's UI.
|
||
///
|
||
/// @param pchPlatformAppId - Identifier of the requested title to check
|
||
///
|
||
/// @retval true - Title is available for playing
|
||
/// @retval false - Title is not available for playing. The common cases for this is the
|
||
/// title is not supported on GFN, or the GFN servers do not load every
|
||
/// supported game to every system in all cases.
|
||
NVGFNSDK_EXPORT bool NVGFNSDKApi gfnIsTitleAvailable(const char* pchPlatformAppId);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Retrieves all titles that can be launched in the current game streaming session
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Use to retrieve a list of all titles available to launch in the current streaming session,
|
||
/// for example, to add "Play" buttons to all titles instead of calling gfnIsTitleAvailable on
|
||
/// each title.
|
||
///
|
||
/// @param ppchPlatformAppIds - Comma-delimited list of platform identifiers. Memory
|
||
/// is allocated for the list. Call @ref gfnFree to release the memory when done.
|
||
///
|
||
/// @retval gfnSuccess - On success
|
||
/// @retval gfnInvalidParameter - NULL pointer passed in
|
||
/// @retval gfnCallWrongEnvironment - If called in a client environment
|
||
/// @note
|
||
/// To avoid leaking memory, call @ref gfnFree once done with the list
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnGetTitlesAvailable(const char** ppchPlatformAppIds);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Notifies GeForce NOW that an application should be readied for launch. GeForce NOW
|
||
/// will make the build files associated with the application available at the path
|
||
/// returned in the SetupTitleResult struct passed in to the ConfirmTitleSetup callback
|
||
/// provided by the caller. Additionally, GeForce NOW will set all necessary settings to
|
||
/// optimize for the GeForce NOW cloud environment, and download any associated user data,
|
||
/// including save files.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Use to prepare an application for launch on GeForce NOW, and block on the result.
|
||
///
|
||
/// @param pchPlatformAppId - Identifier of the requested application to setup
|
||
///
|
||
/// @retval gfnSuccess - On success
|
||
/// @retval gfnInvalidParameter - NULL pointer passed in
|
||
/// @retval gfnCallWrongEnvironment - If called in a client environment
|
||
/// @retval gfnSetupTitleFailure - The GeForce NOW SDK failed to set up the title
|
||
/// @return Otherwise, appropriate error code
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnSetupTitle(const char* pchPlatformAppId);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Notifies GFN that an application has exited. GFN will then start the
|
||
/// shutdown process for that application. Note that this is for use by
|
||
/// platform clients only and assumes the application has already completed
|
||
/// execution. To shutdown from within an application itself, gfnShutdownRuntimeSDK is used.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Use to notify GFN that your application has exited.
|
||
///
|
||
/// @param pchPlatformId - Identifier of the launcher service, e.g. "Steam"
|
||
/// @param pchPlatformAppId - Identifier of the application that has exited.
|
||
///
|
||
/// @retval gfnSuccess - On success
|
||
/// @retval gfnInvalidParameter - NULL pointer passed in
|
||
/// @retval gfnCallWrongEnvironment - If called in a client environment
|
||
/// @return Otherwise, appropriate error code
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnTitleExited(const char* pchPlatformId, const char* pchPlatformAppId);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Since applications running under GeForce NOW run in the GeForce NOW data centers,
|
||
/// any IP queries made by the Application will return IPs associated
|
||
/// with the data center, not the user's external client IP, as seen by Internet queries.
|
||
/// This SDK call allows the application to obtain the user's client IP in the IPv4 format
|
||
/// so that developers can make regional business decisions for the user based on it versus
|
||
/// the region of the data center the user is connected to for game streaming sessions.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Call this during application start or from the platform client in
|
||
/// order to get the user's external client IP address.
|
||
///
|
||
/// @param ppchClientIp - Output IPv4 in string format. Example: "192.168.0.1".
|
||
/// Call @ref gfnFree to release the memory when done.
|
||
///
|
||
/// @retval gfnSuccess - Successfully retrieved client IP
|
||
/// @retval gfnNoData - No IP data found
|
||
/// @retval gfnCallWrongEnvironment - If called in a client environment
|
||
/// @return Otherwise, appropriate error code
|
||
/// @note
|
||
/// The IP data returned by this API can be subject to various privacy laws depending on how the
|
||
/// the data is used. To avoid the data being considered Personally Identifiable Information and
|
||
/// subject to those laws, the IP should be used for geolocation lookup only and then discarded.
|
||
/// @note
|
||
/// To avoid leaking memory, call @ref gfnFree once done with the list
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnGetClientIp(const char** ppchClientIp);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Gets user's client language code in the form "<lang>-<country>" using
|
||
/// a standard ISO 639-1 language code and ISO 3166-1 Alpha-2 country code.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Call this during application start or from the platform client in
|
||
/// order to get the user's language and country settings.
|
||
///
|
||
/// @param ppchLanguageCode - Language code as a string. Example: "en-US".
|
||
/// Call @ref gfnFree to release the memory when done.
|
||
///
|
||
/// @retval gfnSuccess - Successfully retrieved language code
|
||
/// @retval gfnNoData - No language code found
|
||
/// @retval gfnInvalidParameter - NULL pointer passed in
|
||
/// @retval gfnCallWrongEnvironment - If called in a client environment
|
||
/// @return Otherwise, appropriate error code
|
||
/// @note
|
||
/// To avoid leaking memory, call @ref gfnFree once done with the list
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnGetClientLanguageCode(const char** ppchLanguageCode);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Gets user’s client country code using ISO 3166-1 Alpha-2 country code.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Call this during application start or from the platform client in order to get
|
||
/// the user's country code.
|
||
///
|
||
/// @param pchCountryCode - Country code as a 2 character string. Example: "US".
|
||
/// @param length - Length of pchCountryCode character array, the length
|
||
/// should be at least 3
|
||
///
|
||
/// @retval gfnSuccess - On success
|
||
/// @retval gfnInvalidParameter - NULL pointer passed in or buffer length is too small
|
||
/// @retval gfnCallWrongEnvironment - If called in a client environment
|
||
/// @return Otherwise, appropriate error code
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnGetClientCountryCode(char* pchCountryCode, unsigned int length);
|
||
///
|
||
/// @par Description
|
||
/// Gets various information about the local client system and environment
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Call this during application start or from the platform client in order to get
|
||
/// various information about the client that launched the streaming session.
|
||
///
|
||
/// @param clientInfo - Pointer to a GfnClientInfo struct.
|
||
|
||
///
|
||
/// @retval gfnSuccess - On success
|
||
/// @retval gfnInvalidParameter - NULL pointer passed in or buffer length is too small
|
||
/// @retval gfnCallWrongEnvironment - If called in a client environment
|
||
/// @return Otherwise, appropriate error code
|
||
/// @note
|
||
/// The client data returned by this function is best effort, as not all client devices will report
|
||
/// all information. For example, certain browser and TV clients will not report client resolution or
|
||
/// will incorrect resolution in certain situations. In the cases the data is not reported, the data
|
||
/// returned will be zeroes. Likewise for safezone information, as most clients, such as Windows PC,
|
||
/// do not have screen areas unsafe for rendering or input. For more information about safe zones,
|
||
/// see the the Mobile Integration Guide in the /doc folder.
|
||
NVGFNSDK_EXPORT GfnRuntimeError gfnGetClientInfo(GfnClientInfo* clientInfo);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Gets various information about the current streaming session
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Call this from a streaming session to find out more information about the session, such
|
||
/// as session time remaining, or if RTX is enabled for the current session.
|
||
///
|
||
/// @param sessionInfo - Pointer to a GfnSessionInfo struct.
|
||
|
||
///
|
||
/// @retval gfnSuccess - On success
|
||
/// @retval gfnInvalidParameter - NULL pointer passed in or buffer length is too small
|
||
/// @retval gfnCallWrongEnvironment - If called in a client environment
|
||
/// @return Otherwise, appropriate error code
|
||
/// @note
|
||
/// If the application has called @ref gfnRegisterSessionInitCallback to be notified when a
|
||
/// user connects, then this API should be called after that callback is triggered.
|
||
/// Certain data, such as session time limit or RTX support, can only be defined when a user
|
||
/// connects as the values depend on the user type. Calling before that point can result in
|
||
/// obtaining incorrect data.
|
||
NVGFNSDK_EXPORT GfnRuntimeError gfnGetSessionInfo(GfnSessionInfo* sessionInfo);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Requests GFN client to start a streamed session of an application in an asynchronous fashion
|
||
///
|
||
/// @par Environment
|
||
/// Client
|
||
///
|
||
/// @par Platform
|
||
/// Windows
|
||
///
|
||
/// @par Usage
|
||
/// Use to start a streaming session.
|
||
///
|
||
/// @param pStartStreamInput - Pointer to a StartStreamInput structure.
|
||
/// @param cb - A StartStreamCallbackSig callback to be called with streaming events.
|
||
/// @param context - User context
|
||
/// @param timeoutMs - Time after which attempt to start streaming will be aborted.
|
||
NVGFNSDK_EXPORT void NVGFNSDKApi gfnStartStreamAsync(const StartStreamInput * pStartStreamInput, StartStreamCallbackSig cb, void* context, unsigned int timeoutMs);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Requests GFN client to start a streamed session of an application in a synchronous (blocking) fashion.
|
||
///
|
||
/// @par Environment
|
||
/// Client
|
||
///
|
||
/// @par Platform
|
||
/// Windows
|
||
///
|
||
/// @par Usage
|
||
/// Use to start a streaming session.
|
||
///
|
||
/// @param pStartStreamInput - Pointer to a StartStreamInput structure.
|
||
/// @param response - Start streaming response.
|
||
///
|
||
/// @retval gfnSuccess - On success
|
||
/// @retval gfnInvalidParameter - NULL pointer passed in
|
||
/// @retval gfnCallWrongEnvironment - If called in a cloud environment
|
||
/// @retval gfnStreamFailure - Network failure or other error prevented the stream from starting
|
||
/// @retval gfnCanceled - User canceled the download and install of GFN client during stream initialization
|
||
/// @return Otherwise, appropriate error code
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnStartStream(StartStreamInput* pStartStreamInput, StartStreamResponse* response);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Requests GFN client to stop the active streaming session of an application in a synchronous (blocking) fashion.
|
||
///
|
||
/// @par Environment
|
||
/// Client
|
||
///
|
||
/// @par Platform
|
||
/// Windows
|
||
///
|
||
/// @par Usage
|
||
/// Use to request the streaming session be stopped
|
||
///
|
||
/// @retval gfnSuccess - On success
|
||
/// @retval gfnStreamStopFailure - Failure to stop the streaming session
|
||
/// @retval gfnCallWrongEnvironment - If called in a cloud environment
|
||
/// @retval gfnStreamFailure - Network failure or other error prevented the stream from starting
|
||
/// @return Otherwise, appropriate error code
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnStopStream(void);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Requests GFN client to stop the active streaming session of an application in aynchronous fashion.
|
||
///
|
||
/// @par Environment
|
||
/// Client
|
||
///
|
||
/// @par Platform
|
||
/// Windows
|
||
///
|
||
/// @par Usage
|
||
/// Use to request the streaming session be stopped
|
||
///
|
||
/// @param cb - A StartStreamCallbackSig callback to be called with streaming events.
|
||
/// @param context - User context
|
||
/// @param timeoutMs - Time after which attempt to stop streaming and associated processed to close will be aborted.
|
||
/// A value of 0 signals to immediately return without waiting for processes to close.
|
||
NVGFNSDK_EXPORT void NVGFNSDKApi gfnStopStreamAsync(StopStreamCallbackSig cb, void* context, unsigned int timeoutMs);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Retrieves non-secure partner data that is either a) passed by the client in the gfnStartStream call or b) sent using Deep Link parameter.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Use during cloud session to retrieve partner data based in during session initialization.
|
||
///
|
||
/// @param ppchPartnerData - Populated with the partner data in string form if found
|
||
/// Call @ref gfnFree to release the memory when done with data
|
||
///
|
||
/// @retval gfnSuccess - Partner data successfully retrieved from session data
|
||
/// @retval gfnNoData - No partner data found in session data
|
||
/// @retval gfnInvalidParameter - NULL pointer passed in
|
||
/// @retval gfnCallWrongEnvironment - Called in a client environment
|
||
/// @return Otherwise, appropriate error code
|
||
/// @note
|
||
/// To avoid leaking memory, call @ref gfnFree once done with the data
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnGetPartnerData(const char** ppchPartnerData);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Retrieves secure partner data that is either a) passed by the client in the gfnStartStream call or b) sent in response to Deep Link nonce validation.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Use during cloud session to retrieve secure partner data
|
||
///
|
||
/// @param ppchPartnerSecureData - Populated with the secure partner data in string form if found
|
||
/// Call @ref gfnFree to release the memory when done.
|
||
///
|
||
/// @retval gfnSuccess - Secure partner data successfully retrieved from session data
|
||
/// @retval gfnNoData - No secure partner data found in session data
|
||
/// @retval gfnInvalidParameter - NULL pointer passed in
|
||
/// @retval gfnCallWrongEnvironment - If called in a client environment
|
||
/// @return Otherwise, appropriate error code
|
||
/// @note
|
||
/// To avoid leaking memory, call @ref gfnFree once done with the list
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnGetPartnerSecureData(const char** ppchPartnerSecureData);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Releases memory allocated by Get functions such as, but not limited to, @ref gfnGetPartnerData,
|
||
/// @ref gfnGetPartnerSecureData, or @ref gfnGetTitlesAvailable
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Use to release memory after a call to a memory-allocated function and you are finished with the data.
|
||
/// Should only be called if the memory is populated with valid data. Calling @ref gfnFree with invalid
|
||
/// pointer or data will result in an memory exception being thrown.
|
||
///
|
||
/// @param ppchData - Pointer to allocated string memory
|
||
///
|
||
/// @retval gfnSuccess - Memory successfully released
|
||
/// @retval gfnInvalidParameter - Invalid pointer or data passed in
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnFree(const char** ppchData);
|
||
|
||
|
||
///
|
||
/// @par Description
|
||
/// Notifies GFN that an application is ready to be displayed.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Use to notify GFN that your application is ready to be displayed.
|
||
///
|
||
/// @param success - True if startup has succeeded
|
||
/// @param status - Optional status of startup operations
|
||
///
|
||
/// @retval gfnSuccess - On success
|
||
/// @retval gfnCallWrongEnvironment - If called in a client environment
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnAppReady(bool success, const char * status);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Defines active zone coordinates for GFN to interact with.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Use to invoke special events on the client from the GFN cloud environment
|
||
///
|
||
/// @param type - Populated with relevant GfnActionType
|
||
/// @param id - unique unsigned int type identifier for this action zone
|
||
/// @param zone - To enable action zone set this parameter to GfnRect coordinates of the zone, to disable action zone set this parameter to NULL
|
||
///
|
||
/// @retval gfnSuccess - Call was successful
|
||
/// @retval gfnInputExpected - Expected zone to have a value
|
||
/// @retval gfnComError - There was SDK internal communication error
|
||
/// @retval gfnCallWrongEnvironment - If called in a client environment
|
||
/// @retval gfnAPINotInit - SDK was not initialized
|
||
/// @retval gfnAPINotFound - The API was not found in the GeForce NOW SDK Library
|
||
/// @retval gfnInvalidParameter - Invalid parameters provided
|
||
/// @retval gfnThrottled - API call was throttled for exceeding limit
|
||
/// @retval gfnUnhandledException - API ran into an unhandled error and caught an exception before it returned to client code
|
||
/// @return Otherwise, appropriate error code
|
||
NVGFNSDK_EXPORT GfnRuntimeError NVGFNSDKApi gfnSetActionZone(GfnActionType type, unsigned int id, GfnRect* zone);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Sends a custom message communication from the app to the client. This message
|
||
/// is "fire-and-forget", and does not wait for the message to be delivered to return status.
|
||
/// Latency is best effort and not guaranteed.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud or Client
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Use to communicate between cloud applications and streaming clients.
|
||
///
|
||
/// @param pchMessage - Character string
|
||
/// @param length - Length of pchMessage in characters, which cannot exceed 8K in length
|
||
///
|
||
/// @retval gfnSuccess - Call was successful
|
||
/// @retval gfnComError - There was SDK internal communication error
|
||
/// @retval gfnAPINotInit - SDK was not initialized
|
||
/// @retval gfnAPINotFound - The API was not found in the GeForce NOW SDK Library
|
||
/// @retval gfnInvalidParameter - Invalid parameters provided, or message exceeded allowed length
|
||
/// @retval gfnThrottled - API call was throttled for exceeding limit of 30 messages per second
|
||
/// @retval gfnUnhandledException - API ran into an unhandled error and caught an exception before it returned to client code
|
||
/// @return Otherwise, appropriate error code
|
||
NVGFNSDK_EXPORT GfnRuntimeError gfnSendMessage(const char* pchMessage, unsigned int length);
|
||
|
||
///
|
||
/// @par Description
|
||
/// Requests the client application to open a URL in their local web browser.
|
||
///
|
||
/// These requests are fire-and-forget.
|
||
///
|
||
/// Usage of this API is limited to 5 URL requests every second, with no more than 25 URL requests per minute.
|
||
///
|
||
/// @par Environment
|
||
/// Cloud
|
||
///
|
||
/// @par Platform
|
||
/// Windows, Linux
|
||
///
|
||
/// @par Usage
|
||
/// Use to request that the client application open a URL link in their local web browser.
|
||
///
|
||
/// @param pchUrl - A URL which should be opened on the client's local browser.
|
||
///
|
||
/// @retval gfnSuccess - Call was successful
|
||
/// @retval gfnAPINotInit - SDK was not initialized
|
||
/// @retval gfnAPINotFound - The API was not found in the GeForce NOW SDK Library
|
||
/// @retval gfnCallWrongEnvironment - API was called outside of a cloud execution environment
|
||
/// @retval gfnInvalidParameter - Invalid pointer provided, or message exceeded allowed length
|
||
/// @retval gfnThrottled - API call was throttled for exceeding limit of 5 messages per second or 25 total per session
|
||
/// @retval gfnInternalError - API ran into an internal error
|
||
/// @return Otherwise, appropriate error code
|
||
NVGFNSDK_EXPORT GfnRuntimeError gfnOpenURLOnClient(const char* pchUrl);
|
||
|
||
/// @}
|
||
#ifdef __cplusplus
|
||
} // extern "C"
|
||
#endif
|
||
|
||
|
||
#endif // GFN_SDK_RUNTIME_CAPI_H
|