OpalKelly::DeviceSettings Class Reference

Represents the set of settings stored in the given device. More...

Public Member Functions
	OpalKelly::DeviceSettings ()=default
ErrorCode	GetString (const std::string &key, std::string *value)
ErrorCode	GetInt (const std::string &key, UINT32 *value)
ErrorCode	SetString (const std::string &key, const std::string &value)
ErrorCode	SetInt (const std::string &key, UINT32 value)
ErrorCode	List (std::vector< std::string > &keys)
ErrorCode	Delete (const std::string &key)
ErrorCode	Save ()

Detailed Description

A device settings object is always associated with a device and although multiple setting objects can be created for the same device, all of them manipulate the same set of settings, so usually there should be only a single one of them.

All methods of this class return an error code to indicate success or failure which should be checked by caller, no exceptions are thrown. In particular, until the device settings object was successfully initialized by calling OpalKelly::FrontPanel::GetDeviceSettings(), all methods return InvalidParameter error.

Example:

OpalKelly::DeviceSettings settings;
ret = dev->GetDeviceSettings(settings);      // Should return NoError
settings.GetInt("SOME_INT_VALUE", &val);     // Retrieves the value of SOME_INT_VALUE
settings.SetInt("SOME_INT_VALUE", 532);      // Set SOME_INT_VALUE = 532
settings.GetInt("SOME_INT_VALUE", &val);     // val = 532
settings.Save();                             // Write settings to NVRAM
settings.Delete("SOME_INT_VALUE");           // Removes SOME_INT_VALUE
settings.Save();                             // Write settings to remove from NVRAM

Member Function Documentation

Delete()

ErrorCode OpalKelly::DeviceSettings::Delete ( const std::string & key )

inline

Parameters

[in]

key

- Device setting name to delete.

Returns

NoError - Completed successfully.

DeviceNotOpen - Communication with a device is not established.

Failed - The specified setting could not be found or a communication error occurred.

Deletes a setting from the setting store.

Note

The setting will not be permanently deleted from NVRAM unless OpalKelly::DeviceSettings::Save is subsequently called.

GetInt()

ErrorCode OpalKelly::DeviceSettings::GetInt ( const std::string & key, UINT32 * value )

inline

Parameters

[in]	key	- Device setting name.
[out]	value	- Returned device setting value.

Returns

NoError - Completed successfully.

DeviceNotOpen - Communication with a device is not established.

Failed - The specified setting could not be found or a communication error occurred.

InvalidParameter - If value is NULL

Retrieve an integer setting value by its name.

GetString()

ErrorCode OpalKelly::DeviceSettings::GetString ( const std::string & key, std::string * value )

inline

Parameters

[in]	key	- Device setting name.
[out]	value	- Returned device setting value.

Returns

NoError - Completed successfully.

DeviceNotOpen - Communication with a device is not established.

Failed - The specified setting could not be found or a communication error occurred.

InvalidParameter - If value is NULL

Retrieve a string setting value by its name.

List()

ErrorCode OpalKelly::DeviceSettings::List ( std::vector< std::string > & keys )

inline

Parameters

[out]

keys

- A vector of string names of all keys stored on the device.

Returns

NoError - Completed successfully.

DeviceNotOpen - Communication with a device is not established.

Failed - A device communication error occurred.

This API clears the parameter keys, then fills it with a complete list of all persistent settings on the device. Note that this method will not list non-persistent settings. For a list of non-persistent settings, please see the appropriate device User's Manual.

OpalKelly::DeviceSettings()

OpalKelly::DeviceSettings::OpalKelly::DeviceSettings ( )

default

Default constructor creates an uninitialized object of this class.

Use OpalKelly::FrontPanel::GetDeviceSettings() to initialize it.

Save()

ErrorCode OpalKelly::DeviceSettings::Save ( )

inline

Returns

NoError - Completed successfully.

DeviceNotOpen - Communication with a device is not established.

Failed - A device communication error occurred.

Commits the setting store to non-volatile storage. All setting updates (including delete) are performed in volatile memory on the device until they are committed to NVRAM with this call. The next power cycle will restore NVRAM settings to memory.

SetInt()

ErrorCode OpalKelly::DeviceSettings::SetInt ( const std::string & key, UINT32 value )

inline

Parameters

[in]	key	- Device setting name.
[in]	value	- New setting value.

Returns

NoError - Completed successfully.

DeviceNotOpen - Communication with a device is not established.

Failed - The specified setting could not be found or a communication error occurred.

Set an integer setting value.

Note

The value will not be permanently saved to NVRAM unless OpalKelly::DeviceSettings::Save is subsequently called.

SetString()

ErrorCode OpalKelly::DeviceSettings::SetString ( const std::string & key, const std::string & value )

inline

Parameters

[in]	key	- Device setting name.
[in]	value	- New setting value.

Returns

NoError - Completed successfully.

DeviceNotOpen - Communication with a device is not established.

Failed - The specified setting could not be found or a communication error occurred.

Set a string setting value.

Note

The value will not be permanently saved to NVRAM unless OpalKelly::DeviceSettings::Save is subsequently called.