okCDeviceSettings Class Reference

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

Public Member Functions
	okCDeviceSettings ()=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 okCFrontPanel::GetDeviceSettings(), all methods return InvalidParameter error.

Example:

okCDeviceSettings 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

Constructor & Destructor Documentation

okCDeviceSettings()

okCDeviceSettings::okCDeviceSettings ( )

default

Default constructor creates an uninitialized object of this class.

Use okCFrontPanel::GetDeviceSettings() to initialize it.

Member Function Documentation

Delete()

ErrorCode okCDeviceSettings::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 okCDeviceSettings::Save is subsequently called.

GetInt()

ErrorCode okCDeviceSettings::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 okCDeviceSettings::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 okCDeviceSettings::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.

Save()

ErrorCode okCDeviceSettings::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 okCDeviceSettings::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 okCDeviceSettings::Save is subsequently called.

SetString()

ErrorCode okCDeviceSettings::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 okCDeviceSettings::Save is subsequently called.