NVAPI Reference Documentation
NVIDIA
Release 384: June 27
2017

Driver Settings (DRS) APIs

Functions

NVAPI_INTERFACE NvAPI_DRS_CreateProfile (NvDRSSessionHandle hSession, NVDRS_PROFILE *pProfileInfo, NvDRSProfileHandle *phProfile)
 
NVAPI_INTERFACE NvAPI_DRS_DeleteProfile (NvDRSSessionHandle hSession, NvDRSProfileHandle hProfile)
 
NVAPI_INTERFACE NvAPI_DRS_SetCurrentGlobalProfile (NvDRSSessionHandle hSession, NvAPI_UnicodeString wszGlobalProfileName)
 
NVAPI_INTERFACE NvAPI_DRS_GetCurrentGlobalProfile (NvDRSSessionHandle hSession, NvDRSProfileHandle *phProfile)
 
NVAPI_INTERFACE NvAPI_DRS_GetProfileInfo (NvDRSSessionHandle hSession, NvDRSProfileHandle hProfile, NVDRS_PROFILE *pProfileInfo)
 
NVAPI_INTERFACE NvAPI_DRS_SetProfileInfo (NvDRSSessionHandle hSession, NvDRSProfileHandle hProfile, NVDRS_PROFILE *pProfileInfo)
 
NVAPI_INTERFACE NvAPI_DRS_FindProfileByName (NvDRSSessionHandle hSession, NvAPI_UnicodeString profileName, NvDRSProfileHandle *phProfile)
 
NVAPI_INTERFACE NvAPI_DRS_EnumProfiles (NvDRSSessionHandle hSession, NvU32 index, NvDRSProfileHandle *phProfile)
 
NVAPI_INTERFACE NvAPI_DRS_GetNumProfiles (NvDRSSessionHandle hSession, NvU32 *numProfiles)
 
NVAPI_INTERFACE NvAPI_DRS_CreateApplication (NvDRSSessionHandle hSession, NvDRSProfileHandle hProfile, NVDRS_APPLICATION *pApplication)
 
NVAPI_INTERFACE NvAPI_DRS_DeleteApplicationEx (NvDRSSessionHandle hSession, NvDRSProfileHandle hProfile, NVDRS_APPLICATION *pApp)
 
NVAPI_INTERFACE NvAPI_DRS_DeleteApplication (NvDRSSessionHandle hSession, NvDRSProfileHandle hProfile, NvAPI_UnicodeString appName)
 
NVAPI_INTERFACE NvAPI_DRS_GetApplicationInfo (NvDRSSessionHandle hSession, NvDRSProfileHandle hProfile, NvAPI_UnicodeString appName, NVDRS_APPLICATION *pApplication)
 
NVAPI_INTERFACE NvAPI_DRS_EnumApplications (NvDRSSessionHandle hSession, NvDRSProfileHandle hProfile, NvU32 startIndex, NvU32 *appCount, NVDRS_APPLICATION *pApplication)
 
NVAPI_INTERFACE NvAPI_DRS_FindApplicationByName (__in NvDRSSessionHandle hSession, __in NvAPI_UnicodeString appName, __out NvDRSProfileHandle *phProfile, __inout NVDRS_APPLICATION *pApplication)
 
NVAPI_INTERFACE NvAPI_DRS_SetSetting (NvDRSSessionHandle hSession, NvDRSProfileHandle hProfile, NVDRS_SETTING *pSetting)
 
NVAPI_INTERFACE NvAPI_DRS_GetSetting (NvDRSSessionHandle hSession, NvDRSProfileHandle hProfile, NvU32 settingId, NVDRS_SETTING *pSetting)
 
NVAPI_INTERFACE NvAPI_DRS_EnumSettings (NvDRSSessionHandle hSession, NvDRSProfileHandle hProfile, NvU32 startIndex, NvU32 *settingsCount, NVDRS_SETTING *pSetting)
 
NVAPI_INTERFACE NvAPI_DRS_EnumAvailableSettingIds (NvU32 *pSettingIds, NvU32 *pMaxCount)
 
NVAPI_INTERFACE NvAPI_DRS_EnumAvailableSettingValues (NvU32 settingId, NvU32 *pMaxNumValues, NVDRS_SETTING_VALUES *pSettingValues)
 
NVAPI_INTERFACE NvAPI_DRS_GetSettingIdFromName (NvAPI_UnicodeString settingName, NvU32 *pSettingId)
 
NVAPI_INTERFACE NvAPI_DRS_GetSettingNameFromId (NvU32 settingId, NvAPI_UnicodeString *pSettingName)
 
NVAPI_INTERFACE NvAPI_DRS_DeleteProfileSetting (NvDRSSessionHandle hSession, NvDRSProfileHandle hProfile, NvU32 settingId)
 
NVAPI_INTERFACE NvAPI_DRS_RestoreAllDefaults (NvDRSSessionHandle hSession)
 
NVAPI_INTERFACE NvAPI_DRS_RestoreProfileDefault (NvDRSSessionHandle hSession, NvDRSProfileHandle hProfile)
 
NVAPI_INTERFACE NvAPI_DRS_RestoreProfileDefaultSetting (NvDRSSessionHandle hSession, NvDRSProfileHandle hProfile, NvU32 settingId)
 
NVAPI_INTERFACE NvAPI_DRS_GetBaseProfile (NvDRSSessionHandle hSession, NvDRSProfileHandle *phProfile)
 
 NV_DECLARE_HANDLE (NvDRSSessionHandle)
 

Detailed Description

DRS, or DRiver Settings, is a new framework introduced in R256 that handles the storage, management, API layers, and related infrastructure of 3D settings, application profiles, and other settings.

Function Documentation

NV_DECLARE_HANDLE ( NvDRSSessionHandle  )

Macro for constructing the version field of _NVDRS_SETTING_VALUES.

NVAPI_INTERFACE NvAPI_DRS_CreateApplication ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle  hProfile,
NVDRS_APPLICATION pApplication 
)

DESCRIPTION: This API adds an executable name to a profile.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]hProfileInput profile handle.
[in]*pApplicationInput NVDRS_APPLICATION struct with the executable name to be added.
Return values
NVAPI_OKSUCCESS
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_CreateProfile ( NvDRSSessionHandle  hSession,
NVDRS_PROFILE pProfileInfo,
NvDRSProfileHandle *  phProfile 
)

DESCRIPTION: This API creates an empty profile.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]*pProfileInfoInput pointer to NVDRS_PROFILE.
[in]*phProfileReturns pointer to profile handle.
Return values
NVAPI_OKSUCCESS
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_DeleteApplication ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle  hProfile,
NvAPI_UnicodeString  appName 
)

DESCRIPTION: This API removes an executable name from a profile.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]hProfileInput profile handle.
[in]appNameInput the executable name to be removed.
Return values
NVAPI_OKSUCCESS
NVAPI_ERRORFor miscellaneous errors.
NVAPI_EXECUTABLE_PATH_IS_AMBIGUOUSIf the path provided could refer to two different executables, this error will be returned
NVAPI_INTERFACE NvAPI_DRS_DeleteApplicationEx ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle  hProfile,
NVDRS_APPLICATION pApp 
)

DESCRIPTION: This API removes an executable from a profile.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSession- Input to the session handle.
[in]hProfile- Input profile handle.
[in]*pApp- Input all the information about the application to be removed.
Return values
NVAPI_OKSUCCESS
NVAPI_ERRORFor miscellaneous errors.
NVAPI_EXECUTABLE_PATH_IS_AMBIGUOUSIf the path provided could refer to two different executables, this error will be returned.
NVAPI_INTERFACE NvAPI_DRS_DeleteProfile ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle  hProfile 
)

DESCRIPTION: This API deletes a profile or sets it back to a predefined value.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]hProfileInput profile handle.
Return values
NVAPI_OKSUCCESS if the profile is found
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_DeleteProfileSetting ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle  hProfile,
NvU32  settingId 
)

DESCRIPTION: This API deletes a setting or sets it back to predefined value.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]hProfileInput profile handle.
[in]settingIdInput settingId to be deleted.
Return values
NVAPI_OKSUCCESS if the profile is found
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_EnumApplications ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle  hProfile,
NvU32  startIndex,
NvU32 appCount,
NVDRS_APPLICATION pApplication 
)

DESCRIPTION: This API enumerates all the applications in a given profile from the starting index to the maximum length.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]hProfileInput profile handle.
[in]startIndexIndicates starting index for enumeration.
[in,out]*appCountInput maximum length of the passed in arrays. Returns the actual length.
[out]*pApplicationReturns NVDRS_APPLICATION struct with all the attributes.
Return values
NVAPI_OKSUCCESS
NVAPI_ERRORFor miscellaneous errors.
NVAPI_END_ENUMERATIONstartIndex exceeds the total appCount.
NVAPI_INTERFACE NvAPI_DRS_EnumAvailableSettingIds ( NvU32 pSettingIds,
NvU32 pMaxCount 
)

DESCRIPTION: This API enumerates all the Ids of all the settings recognized by NVAPI.

SUPPORTED OS: Windows XP and higher

Parameters
[out]pSettingIdsUser-provided array of length *pMaxCount that NVAPI will fill with IDs.
[in,out]pMaxCountInput max length of the passed in array, Returns the actual length.
Return values
NVAPI_OKSUCCESS
NVAPI_ERRORFor miscellaneous errors. NVAPI_END_ENUMERATION: the provided pMaxCount is not enough to hold all settingIds.
NVAPI_INTERFACE NvAPI_DRS_EnumAvailableSettingValues ( NvU32  settingId,
NvU32 pMaxNumValues,
NVDRS_SETTING_VALUES pSettingValues 
)

DESCRIPTION: This API enumerates all available setting values for a given setting.

SUPPORTED OS: Windows XP and higher

Parameters
[in]settingIdInput settingId.
[in,out]*pMaxNumValuesInput max length of the passed in arrays, Returns the actual length.
[out]*pSettingValuesReturns all available setting values and its count.
Return values
NVAPI_OKSUCCESS
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_EnumProfiles ( NvDRSSessionHandle  hSession,
NvU32  index,
NvDRSProfileHandle *  phProfile 
)

DESCRIPTION: This API enumerates through all the profiles in the session.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]indexInput the index for enumeration.
[out]*phProfileReturns profile handle.

RETURN STATUS: NVAPI_OK: SUCCESS if the profile is found NVAPI_ERROR: For miscellaneous errors. NVAPI_END_ENUMERATION: index exceeds the total number of available Profiles in DB.

NVAPI_INTERFACE NvAPI_DRS_EnumSettings ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle  hProfile,
NvU32  startIndex,
NvU32 settingsCount,
NVDRS_SETTING pSetting 
)

DESCRIPTION: This API enumerates all the settings of a given profile from startIndex to the maximum length.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]hProfileInput profile handle.
[in]startIndexIndicates starting index for enumeration.
[in,out]*settingsCountInput max length of the passed in arrays, Returns the actual length.
[out]*pSettingReturns all the settings info.
Return values
NVAPI_OKSUCCESS
NVAPI_ERRORFor miscellaneous errors.
NVAPI_END_ENUMERATIONstartIndex exceeds the total appCount.
NVAPI_INTERFACE NvAPI_DRS_FindApplicationByName ( __in NvDRSSessionHandle  hSession,
__in NvAPI_UnicodeString  appName,
__out NvDRSProfileHandle *  phProfile,
__inout NVDRS_APPLICATION pApplication 
)

DESCRIPTION: This API searches the application and the associated profile for the given application name. If a fully qualified path is provided, this function will always return the profile the driver will apply upon running the application (on the path provided).

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the hSession handle
[in]appNameInput appName. For best results, provide a fully qualified path of the type c:/Folder1/Folder2/App.exe
[out]*phProfileReturns profile handle.
[in,out]*pApplicationReturns NVDRS_APPLICATION struct pointer.
Returns
This API can return any of the error codes enumerated in NvAPI_Status. If there are return error codes with specific meaning for this API, they are listed below:
Return values
::NVAPI_APPLICATION_NOT_FOUNDIf App not found
NVAPI_EXECUTABLE_PATH_IS_AMBIGUOUSIf the input appName was not fully qualified, this error might return in the case of multiple matches
NVAPI_INTERFACE NvAPI_DRS_FindProfileByName ( NvDRSSessionHandle  hSession,
NvAPI_UnicodeString  profileName,
NvDRSProfileHandle *  phProfile 
)

DESCRIPTION: This API finds a profile in the current session.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]profileNameInput profileName.
[out]phProfileInput profile handle.
Return values
NVAPI_OKSUCCESS if the profile is found
NVAPI_PROFILE_NOT_FOUNDif profile is not found
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_GetApplicationInfo ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle  hProfile,
NvAPI_UnicodeString  appName,
NVDRS_APPLICATION pApplication 
)

DESCRIPTION: This API gets information about the given application. The input application name must match exactly what the Profile has stored for the application. This function is better used to retrieve application information from a previous enumeration.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]hProfileInput profile handle.
[in]appNameInput application name.
[out]*pApplicationReturns NVDRS_APPLICATION struct with all the attributes.
Returns
This API can return any of the error codes enumerated in NvAPI_Status. If there are return error codes with specific meaning for this API, they are listed below.
Return values
NVAPI_EXECUTABLE_PATH_IS_AMBIGUOUSThe application name could not single out only one executable.
NVAPI_EXECUTABLE_NOT_FOUNDNo application with that name is found on the profile.
NVAPI_INTERFACE NvAPI_DRS_GetBaseProfile ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle *  phProfile 
)

DESCRIPTION: Returns the handle to the current global profile.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]*phProfileReturns Base profile handle.
Return values
NVAPI_OKSUCCESS if the profile is found
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_GetCurrentGlobalProfile ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle *  phProfile 
)

DESCRIPTION: This API returns the handle to the current global profile.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[out]*phProfileReturns current Global profile handle.
Return values
NVAPI_OKSUCCESS
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_GetNumProfiles ( NvDRSSessionHandle  hSession,
NvU32 numProfiles 
)

DESCRIPTION: This API obtains the number of profiles in the current session object.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[out]*numProfilesReturns count of profiles in the current hSession.
Return values
NVAPI_OKSUCCESS
NVAPI_API_NOT_INTIALIZEDFailed to initialize.
NVAPI_INVALID_ARGUMENTInvalid Arguments.
NVAPI_INTERFACE NvAPI_DRS_GetProfileInfo ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle  hProfile,
NVDRS_PROFILE pProfileInfo 
)

DESCRIPTION: This API gets information about the given profile. User needs to specify the name of the Profile.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]hProfileInput profile handle.
[out]*pProfileInfoReturn the profile info.
Return values
NVAPI_OKSUCCESS
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_GetSetting ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle  hProfile,
NvU32  settingId,
NVDRS_SETTING pSetting 
)

DESCRIPTION: This API gets information about the given setting.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]hProfileInput profile handle.
[in]settingIdInput settingId.
[out]*pSettingReturns all the setting info
Return values
NVAPI_OKSUCCESS
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_GetSettingIdFromName ( NvAPI_UnicodeString  settingName,
NvU32 pSettingId 
)

DESCRIPTION: This API gets the binary ID of a setting given the setting name.

SUPPORTED OS: Windows XP and higher

Parameters
[in]settingNameInput Unicode settingName.
[out]*pSettingIdReturns corresponding settingId.
Return values
NVAPI_OKSUCCESS if the profile is found
NVAPI_PROFILE_NOT_FOUNDif profile is not found
NVAPI_SETTING_NOT_FOUNDif setting is not found
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_GetSettingNameFromId ( NvU32  settingId,
NvAPI_UnicodeString pSettingName 
)

DESCRIPTION: This API gets the setting name given the binary ID.

SUPPORTED OS: Windows XP and higher

Parameters
[in]settingIdInput settingId.
[in]*pSettingNameReturns corresponding Unicode settingName.
Return values
NVAPI_OKSUCCESS if the profile is found
NVAPI_PROFILE_NOT_FOUNDif profile is not found
NVAPI_SETTING_NOT_FOUNDif setting is not found
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_RestoreAllDefaults ( NvDRSSessionHandle  hSession)

DESCRIPTION: This API restores the whole system to predefined(default) values.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
Return values
NVAPI_OKSUCCESS if the profile is found
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_RestoreProfileDefault ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle  hProfile 
)

DESCRIPTION: This API restores the given profile to predefined(default) values. Any and all user specified modifications will be removed. If the whole profile was set by the user, the profile will be removed.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]hProfileInput profile handle.
Return values
NVAPI_OKSUCCESS if the profile is found
NVAPI_ERRORFor miscellaneous errors.
NVAPI_PROFILE_REMOVEDSUCCESS, and the hProfile is no longer valid.
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_RestoreProfileDefaultSetting ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle  hProfile,
NvU32  settingId 
)

DESCRIPTION: This API restores the given profile setting to predefined(default) values.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]hProfileInput profile handle.
[in]settingIdInput settingId.
Return values
NVAPI_OKSUCCESS if the profile is found
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_SetCurrentGlobalProfile ( NvDRSSessionHandle  hSession,
NvAPI_UnicodeString  wszGlobalProfileName 
)

DESCRIPTION: This API sets the current global profile in the driver.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]wszGlobalProfileNameInput current Global profile name.
Return values
NVAPI_OKSUCCESS
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_SetProfileInfo ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle  hProfile,
NVDRS_PROFILE pProfileInfo 
)

DESCRIPTION: Specifies flags for a given profile. Currently only the NVDRS_GPU_SUPPORT is used to update the profile. Neither the name, number of settings or applications or other profile information can be changed with this function.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]hProfileInput profile handle.
[in]*pProfileInfoInput the new profile info.
Return values
NVAPI_OKSUCCESS
NVAPI_ERRORFor miscellaneous errors.
NVAPI_INTERFACE NvAPI_DRS_SetSetting ( NvDRSSessionHandle  hSession,
NvDRSProfileHandle  hProfile,
NVDRS_SETTING pSetting 
)

DESCRIPTION: This API adds/modifies a setting to a profile.

SUPPORTED OS: Windows XP and higher

Parameters
[in]hSessionInput to the session handle.
[in]hProfileInput profile handle.
[in]*pSettingInput NVDRS_SETTING struct pointer.
Return values
NVAPI_OKSUCCESS
NVAPI_ERRORFor miscellaneous errors.


Copyright (c) 2007-2017 NVIDIA Corporation. All rights reserved.

NVIDIA