ISettings#

Fully qualified name: carb::settings::ISettings

Defined in carb/settings/detail/ISettings2.h

class ISettings#

The Carbonite Settings interface.

Carbonite settings are built on top of the carb::dictionary::IDictionary interface. Many dictionary functions are replicated in settings, but explicitly use the settings database instead of a generic carb::dictionary::Item.

ISettings uses keys (or paths) that start with an optional forward-slash and are forward-slash separated (example: “/log/level”). The settings database exists as a root-level carb::dictionary::Item (of type ‘dictionary’) that is created and maintained by the ISettings interface (typically through the carb.settings.plugin plugin). The root level settings carb::dictionary::Item is accessible through ISettings::getSettingsDictionary("/").

See also

carb::dictionary::IDictionary

Thread Safety

All functions in ISettings are thread-safe unless otherwise specified. By “thread-safe,” this means that individual calls to a carb.settings API function will fully completed in a thread-safe manner; however this does not mean that multiple calls together will be threadsafe as another thread may act on the settings database between the API calls. In order to ensure thread-safety across multiple calls, use the ScopedRead and ScopedWrite RAII objects to ensure locking. The settings database uses a global recursive read/write lock to ensure thread safety across the entire settings database.

Subscriptions

Portions of the settings database hierarchy can be subscribed to with ISettings::subscribeToTreeChangeEvents, or individual keys may be subscribed to with ISettings::subscribeToNodeChangeEvents. Subscriptions are called in the context of the thread that triggered the change, and only once that thread has released all settings database locks. Subscription callbacks also follow the principles of Basic Callback Hygiene:

ISettings::unsubscribeFromChangeEvents may be called from within the callback to unregister the called subscription or any other subscription.
Unregistering the subscription ensures that it will never be called again, and any calls in process on another thread will complete before ISettings::unsubscribeFromChangeEvents returns.
The settings database lock is not held while the callback is called, but may be temporarily taken for API calls within the callback.

Public Functions

virtual dictionary::ItemType getItemType( cpp::string_view path, ) const = 0#

Returns dictionary item type of the key at the given path.

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: carb::dictionary::ItemType of value at path; if path does not exist, carb::dictionary::ItemType::eCount is returned.

virtual bool isAccessibleAs( dictionary::ItemType itemType, cpp::string_view path, ) const = 0#

Checks if an item could be accessible as the provided type, either directly, or via conversion.

Parameters:

itemType – The item type to check for. This may not be carb::dictionary::ItemType::eCount.
path – Settings database key path (i.e. “/log/level”).

Returns:

true if accessible, or false otherwise. If the given path does not exist, false is also returned.

virtual void setDictionary(cpp::string_view path) const = 0#

Creates a dictionary (or changes an existing value to a dictionary) at the specified path.

If the setting value previously existed as a dictionary, it is not modified. If the setting value exists as another type, it is destroyed and a new setting value is created as an empty dictionary. If the setting value did not exist, it is created as an empty dictionary. If any levels of the path hierarchy did not exist, they are created as dictionary items.

Parameters:: path – Settings database key path (i.e. “/log/level”). Providing the root level (“/” or an empty path) is undefined behavior.

virtual int64_t getAsInt64(cpp::string_view path) const = 0#

Attempts to get the supplied item as a 64-bit integer, either directly or via conversion.

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: The 64-bit integer value of the value at path. If path is invalid, non-existent, or cannot be converted to an integer, 0 is returned.

virtual void setInt64(cpp::string_view path, int64_t value) const = 0#

Sets a 64-bit integer value at the supplied path.

If an item was already present at the given path, it is changed to type ‘eInt’ item. If the present item is a dictionary with children, all children are destroyed first. If path doesn’t exist, this creates a new integer item and all the required items along the path if necessary.

See also

carb::dictionary::IDictionary::setInt64

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – Integer value that will be stored to the supplied path.

inline int32_t getAsInt(cpp::string_view path) const#

Attempts to get the supplied item as a 32-bit integer, either directly or via conversion.

See also

carb::dictionary::IDictionary::getAsInt

Warning

The value may be truncated by casting to 32-bits. In debug builds, an assert occurs if the value read from the item would be truncated.

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: The 32-bit integer value of the setting value at path. If path is invalid, non-existent, or cannot be converted to a 32-bit integer, 0 is returned.

inline void setInt(cpp::string_view path, int32_t value) const#

Sets the integer value at the supplied path.

If an item was already present at the given path, it is changed to type ‘eInt’. If the present item is a dictionary with children, all children are destroyed first. If path doesn’t exist, this creates a new integer item and all the required items along the path if necessary.

See also

carb::dictionary::IDictionary::setInt

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – The new 32-bit integer value that will be stored to the supplied path.

virtual double getAsFloat64(cpp::string_view path) const = 0#

Attempts to get the supplied item as double, either directly or via conversion.

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: The double value of the setting value at path. If path is invalid, non-existent, or cannot be converted to a double, 0.0 is returned.

virtual void setFloat64(cpp::string_view path, double value) const = 0#

Sets the floating point value at the supplied path.

If an item was already present at the given path, it is changed to type ‘eFloat’. If the present item is a dictionary with children, all children are destroyed first. If path doesn’t exist, this creates a new ‘double’ item and all the required items along the path if necessary.

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – the new 64-bit floating point value that will be stored to the supplied path.

inline float getAsFloat(cpp::string_view path) const#

Attempts to get the supplied item as float, either directly or via conversion.

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: The float value of the setting value at path. If path is invalid, non-existent, or cannot be converted to a float, 0.0f is returned.

inline void setFloat(cpp::string_view path, float value) const#

Sets the floating point value at the supplied path.

If an item was already present at the given path, it is changed to type ‘eFloat’. If the present item is a dictionary with children, all children are destroyed first. If path doesn’t exist, this creates a new ‘float’ item and all the required items along the path if necessary.

See also

carb::dictionary::IDictionary::setFloat

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – Floating point value that will be stored to the supplied path.

virtual bool getAsBool(cpp::string_view path) const = 0#

Attempts to get the supplied item as a bool, either directly or via conversion.

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: The bool value of the setting value at path. If path is invalid, non-existent, or cannot be converted to a bool, false is returned. See carb::dictionary::IDictionary::getAsBool() for an explanation of how different item types are converted.

virtual void setBool(cpp::string_view path, bool value) const = 0#

Sets the boolean value at the supplied path.

If an item was already present at the given path, it is changed to type ‘eBool’. If the present item is a dictionary with children, all children are destroyed first. If path doesn’t exist, this creates a new ‘bool’ item and all the required items along the path if necessary.

See also

carb::dictionary::IDictionary::setBool

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – Boolean value that will be stored to the supplied path.

virtual cpp::optional<omni::string> createStringFromItemValue( cpp::string_view path, ) const = 0#

Attempts to create a new string buffer with a value, either the real string value or a string resulting from converting the item value to a string.

See also

carb::dictionary::IDictionary::createStringBufferFromItemValue() carb::settings::getStringFromItemValue()

Note

Please use destroyStringBuffer() to free the created buffer.

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: Pointer to a string if it is successfully created. Returns carb::cpp::nullopt on failure.

virtual cpp::optional<cpp::zstring_view> getStringView( cpp::string_view path, ) const = 0#

Returns a view of the internal string of an item.

No conversions will occur; this function only works for setting values that are strings.

Warning

This function returns a view of an item’s internal string. Another thread may change the setting value which can cause the string to be destroyed, rendering the view as dangling. It is recommended to take a ScopedRead lock around calling this function and using the return value.

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: Raw pointer to the internal string value if applicable, nullptr otherwise.

virtual void setString( cpp::string_view path, cpp::string_view value, ) const = 0#

Sets a string value at the given path.

The given path is walked and any dictionary items are changed or created to create the path. If the path item itself exists but is not of type eString it is changed to be eString. Change notifications for subscriptions are queued. The given string is then set in the item at path.

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – String value that will be stored to the supplied path.

template<typename T> T get(cpp::string_view path) const = delete#

Reads the value from a path, converting if necessary.

See also

getOpt

Template Parameters:: T – The type of item to read. Must be a supported type. The supported types are int, int64_t, float, double, bool, ‘std::string’, ‘omni::string’, and carb::cpp::zstring_view. Any values that should be treated as unsigned will still be returned as signed values. It is up to the caller to cast the returned value appropriately.
Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: The value read from the path. If path is not a valid path, the returned value will be default- constructed. Note that if a carb::cpp::zstring_view is retrieved, the returned value will be a pointer to the item’s internal string buffer. See the warning in getStringView() for more information on how this could be dangerous to use.

template<typename T> cpp::optional<T> getOpt( cpp::string_view path, ) const = delete#

Optionally reads the value from a path, converting if necessary.

If the given path does not exist, carb::cpp::nullopt is returned.

Template Parameters:: T – The type of item to read. Must be a supported type. The supported types are int, int64_t, float, double, bool, ‘std::string’, ‘omni::string’, and carb::cpp::zstring_view. Any values that should be treated as unsigned will still be returned as signed values. It is up to the caller to cast the returned value appropriately.
Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: the value read from the path if path is valid. Otherwise, returns carb::cpp::nullopt. Note that if a carb::cpp::zstring_view is retrieved, the returned value will be a pointer to the item’s internal string buffer. See the warning in getStringView() for more information on how this could be dangerous to use.

template<typename T, std::enable_if_t<!cpp::is_std_string_view_like_v<T>, bool> = true> void set( cpp::string_view path, T value, ) const = delete#

Sets the value at a path.

Template Parameters:

T – The type of item to read. Must be a supported type. The supported types are int32_t, int64_t, float, double, bool, and string-view-like. Any unsigned values must instead be stored as their signed counterparts.

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – The value to store in the item at path.

void set(cpp::string_view path, cpp::string_view value) const#

Sets the value at a path.

Template Parameters:

T – The type of item to read. Must be a supported type. The supported types are int32_t, int64_t, float, double, bool, and string-view-like. Any unsigned values must instead be stored as their signed counterparts.

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – The value to store in the item at path.

virtual bool isAccessibleAsArray(cpp::string_view path) const = 0#

Checks if the item could be accessible as array.

An array item is one where all child items’ names are valid contiguous non-negative integers starting with zero.

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: true if accessible as an array, or false otherwise.

virtual bool isAccessibleAsArrayOf( dictionary::ItemType itemType, cpp::string_view path, ) const = 0#

Checks if the item could be accessible as the array of items of provided type, either directly, or via conversion of all elements.

An array item is one where all child items’ names are valid contiguous non-negative integers starting with zero.

Parameters:

itemType – Item type to check for. Each item in the array must be convertible to this type in order for this call to succeed.
path – Settings database key path (i.e. “/log/level”).

Returns:

true if the item at the given path is a valid array with all items accessible as the given type, or false otherwise.

virtual size_t getArrayLength(cpp::string_view path) const = 0#

Checks if the all the children of the item have array-style indices.

If yes, returns the number of children (array elements).

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: Number of array elements if applicable, or 0 otherwise.

virtual dictionary::ItemType getPreferredArrayType( cpp::string_view path, ) const = 0#

Runs through all the array elements and infers a type that is most suitable for the array.

The rules are thus:

Strings attempt to convert to float or bool if possible.
The converted type of the first element is the initial type.
If the initial type is a dictionary::ItemType::eBool and later elements can be converted to dictionary::ItemType::eBool without losing precision, dictionary::ItemType::eBool is kept. A string can be converted to a boolean without losing precision if it is a variant of “true”/”false” or has a value exactly equal to 0 or 1.
Elements of type dictionary::ItemType::eFloat can convert to dictionary::ItemType::eInt if they don’t lose precision.

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: dictionary::ItemType that is most suitable for the array, or dictionary::ItemType::eCount on failure.

virtual int64_t getAsInt64At( cpp::string_view path, size_t index, ) const = 0#

Attempts to read an array item as a 64-bit integer.

Attempts to read the path and array index as an integer, either directly or via conversion, considering the item at path to be an array, and using the supplied index to access its child. The default value of (0) is returned if path doesn’t exist, index doesn’t exist, or there is a conversion failure.

See also

dictionary::IDictionary::getAsInt64At

Parameters:

path – Settings database key path (i.e. “/log/level”).
index – Zero based index of the element in array to retrieve.

Returns:

The 64-bit integer value, either raw value or cast from the real item type. Zero is returned if path doesn’t exist, the item at the given path is not an array, index doesn’t exist in the array, or a conversion error occurs.

virtual void setInt64At( cpp::string_view path, size_t index, int64_t value, ) const = 0#

Attempts to set a 64-bit integer value in an array item.

Ensures that the given path exists as an eDictionary, changing types as the path is walked (and triggering subscription notifications). index is converted to a string and appended to path as a child path name. The child path is created as eInt or changed to be eInt, and the value is set from value. Subscription notifications are triggered when the current thread no longer has any settings locks.

See also

dictionary::IDictionary::setInt64At

Note

This may be used to set array values out of order in an array item. It is best practice to set array values starting from index 0 and adding each contiguous item. Failing to do this (ie: leaving gaps in the indices) could result in the array not being properly detected or treated as an array for some operations.

Parameters:

path – Settings database key path (i.e. “/log/level”).
index – Zero based index of the element in the array.
value – 64-bit integer value that will be stored to the supplied path and index.

inline int32_t getAsIntAt(cpp::string_view path, size_t index) const#

Attempts to read an array item as a 32-bit integer.

Attempts to read the path and array index as an integer, either directly or via conversion, considering the item at path to be an array, and using the supplied index to access its child. The default value of (0) is returned if path doesn’t exist, index doesn’t exist, or there is a conversion failure.

See also

dictionary::IDictionary::getAsIntAt()

Warning

The value is truncated by casting to 32-bits. In debug builds, an assert occurs if the value read from the item would be truncated.

Parameters:

path – Settings database key path (i.e. “/log/level”).
index – Zero based index of the element to retrieve in the array.

Returns:

The 32-bit integer value, either raw value or cast from the real item type. Zero is returned if path doesn’t exist, the item at the given path is not an array, index doesn’t exist in the array, or a conversion error occurs.

inline void setIntAt( cpp::string_view path, size_t index, int32_t value, ) const#

Attempts to set a 32-bit integer value in an array item.

Ensures that the given path exists as an eDictionary, changing types as the path is walked (and triggering subscription notifications). index is converted to a string and appended to path as a child path name. The child path is created as eInt or changed to be eInt, and the value is set from value. Subscription notifications are triggered when the current thread no longer has any settings locks.

See also

dictionary::IDictionary::setIntAt()

Parameters:

path – Settings database key path (i.e. “/log/level”).
index – Zero based index of the element in array.
value – 32-bit integer value that will be stored to the supplied path and index.

virtual void getAsInt64Array( cpp::string_view path, int64_t *arrayOut, size_t arrayBufferLength, ) const = 0#

Fills the given buffer with the array values from the given path.

If the provided path is not a dictionary item, arrayOut is not modified. If the array item contains more items than arrayBufferLength, a warning message is logged and items past the end are ignored.

Warning

Dictionary items that are not arrays will only have child keys which are convertible to array indices written to arrayOut. For example, if path is the location of a dictionary item with keys ‘5’ and ‘10’, only those items will be written into arrayOut; the other indices will not be written. It is highly recommended to take a ScopedRead lock around calling this function, and call only if isAccessibleAsArray() or isAccessibleAsArrayOf() return true.

Parameters:

path – Settings database key path (i.e. “/log/level”).
arrayOut – Array buffer to fill with integer values. This Note that the entries in this buffer will not be initialized before retrieving values. The caller should make sure to initialize all entries in the buffer to suitable default values before calling in case some indices are missing in the item’s array.
arrayBufferLength – Maximum number of values that can fit in arrayOut.

virtual void setInt64Array( cpp::string_view path, const cpp::span<const int64_t> array, ) const = 0#

Creates or updates an item to be an integer array.

Ensures that the given path exists as an eDictionary, changing types as the path is walked (and triggering subscription notifications). If path already exists as a eDictionary it is cleared (change notifications will be queued for any child items that are destroyed). New child items are created for all elements of the given array.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – Integer array to copy values from.

virtual void getAsIntArray( cpp::string_view path, int32_t *arrayOut, size_t arrayBufferLength, ) const = 0#

Fills the given buffer with the array values from the given path.

If the provided path is not a dictionary item, arrayOut is not modified. If the array item contains more items than arrayBufferLength, a warning message is logged and items past the end are ignored.

Warning

Dictionary items that are not arrays will only have child keys which are convertible to array indices written to arrayOut. For example, if path is the location of a dictionary item with keys ‘5’ and ‘10’, only those items will be written into arrayOut; the other indices will not be written. It is highly recommended to take a ScopedRead lock around calling this function, and call only if isAccessibleAsArray() or isAccessibleAsArrayOf() return true.

Warning

Any integer element that does not fit within int32_t is truncated by casting.

Parameters:

path – Settings database key path (i.e. “/log/level”).
arrayOut – Array buffer to fill with integer values. This Note that the entries in this buffer will not be initialized before retrieving values. The caller should make sure to initialize all entries in the buffer to suitable default values before calling in case some indices are missing in the item’s array.
arrayBufferLength – Maximum number of values that can fit in arrayOut.

virtual void setIntArray( cpp::string_view path, const cpp::span<const int32_t> array, ) const = 0#

Creates or updates an item to be an integer array.

Ensures that the given path exists as an eDictionary, changing types as the path is walked (and triggering subscription notifications). If path already exists as a eDictionary it is cleared (change notifications will be queued for any child items that are destroyed). New child items are created for all elements of the given array.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – Integer array to copy values from.

virtual double getAsFloat64At( cpp::string_view path, size_t index, ) const = 0#

Attempts to read an array item as a double.

Attempts to read the path and array index as a double, either directly or via conversion, considering the item at path to be an array, and using the supplied index to access its child. The default value of (0.0) is returned if path doesn’t exist, index doesn’t exist, or there is a conversion failure.

Parameters:

path – Settings database key path (i.e. “/log/level”).
index – Zero based index of the element to retrieve in the array.

Returns:

The double value, either raw value or cast from the real item type. Zero is returned if path doesn’t exist, the item at the given path is not an array, index doesn’t exist in the array, or a conversion error occurs.

virtual void setFloat64At( cpp::string_view path, size_t index, double value, ) const = 0#

Attempts to set a double value in an array item.

Ensures that the given path exists as an eDictionary, changing types as the path is walked (and triggering subscription notifications). index is converted to a string and appended to path as a child path name. The child path is created as eFloat or changed to be eFloat, and the value is set from value. Subscription notifications are triggered when the current thread no longer has any settings locks.

Parameters:

path – Settings database key path (i.e. “/log/level”).
index – Zero based index of the element in array.
value – The new double value that will be stored to the supplied path and index.

inline float getAsFloatAt(cpp::string_view path, size_t index) const#

Attempts to read an array item as a float.

Attempts to read the path and array index as a float, either directly or via conversion, considering the item at path to be an array, and using the supplied index to access its child. The default value of (0.0) is returned if path doesn’t exist, index doesn’t exist, or there is a conversion failure.

Parameters:

path – Settings database key path (i.e. “/log/level”).
index – Zero based index of the element to retrieve in the array.

Returns:

The float value, either raw value or cast from the real item type. Zero is returned if path doesn’t exist, the item at the given path is not an array, index doesn’t exist in the array, or a conversion error occurs.

inline void setFloatAt( cpp::string_view path, size_t index, float value, ) const#

Attempts to set a float value in an array item.

Ensures that the given path exists as an eDictionary, changing types as the path is walked (and triggering subscription notifications). index is converted to a string and appended to path as a child path name. The child path is created as eFloat or changed to be eFloat, and the value is set from value. Subscription notifications are triggered when the current thread no longer has any settings locks.

Parameters:

path – Settings database key path (i.e. “/log/level”).
index – Zero based index of the element in array.
value – The new float value that will be stored to the supplied path and index.

virtual void getAsFloat64Array( cpp::string_view path, double *arrayOut, size_t arrayBufferLength, ) const = 0#

Fills the given buffer with the array values from the given path.

If the provided path is not a dictionary item, arrayOut is not modified. If the array item contains more items than arrayBufferLength, a warning message is logged and items past the end are ignored.

Warning

Dictionary items that are not arrays will only have child keys which are convertible to array indices written to arrayOut. For example, if path is the location of a dictionary item with keys ‘5’ and ‘10’, only those items will be written into arrayOut; the other indices will not be written. It is highly recommended to take a ScopedRead lock around calling this function, and call only if isAccessibleAsArray() or isAccessibleAsArrayOf() return true.

Parameters:

path – Settings database key path (i.e. “/log/level”).
arrayOut – Array buffer to fill with floating point values. This Note that the entries in this buffer will not be initialized before retrieving values. The caller should make sure to initialize all entries in the buffer to suitable default values before calling in case some indices are missing in the item’s array.
arrayBufferLength – Maximum number of values that can fit in arrayOut.

virtual void setFloat64Array( cpp::string_view path, const cpp::span<const double> array, ) const = 0#

Creates or updates an item to be a double array.

Ensures that the given path exists as an eDictionary, changing types as the path is walked (and triggering subscription notifications). If path already exists as a eDictionary it is cleared (change notifications will be queued for any child items that are destroyed). New child items are created for all elements of the given array.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – Floating point array to copy values from.

virtual void getAsFloatArray( cpp::string_view path, float *arrayOut, size_t arrayBufferLength, ) const = 0#

Fills the given buffer with the array values from the given path.

If the provided path is not a dictionary item, arrayOut is not modified. If the array item contains more items than arrayBufferLength, a warning message is logged and items past the end are ignored.

Warning

Dictionary items that are not arrays will only have child keys which are convertible to array indices written to arrayOut. For example, if path is the location of a dictionary item with keys ‘5’ and ‘10’, only those items will be written into arrayOut; the other indices will not be written. It is highly recommended to take a ScopedRead lock around calling this function, and call only if isAccessibleAsArray() or isAccessibleAsArrayOf() return true.

Warning

Any element that does not fit within float is truncated by casting.

Parameters:

path – Settings database key path (i.e. “/log/level”).
arrayOut – Array buffer to fill with floating point values. This may not be nullptr.
arrayBufferLength – Maximum number of values that can fit in arrayOut.

virtual void setFloatArray( cpp::string_view path, const cpp::span<const float> array, ) const = 0#

Creates or updates an item to be a float array.

Ensures that the given path exists as an eDictionary, changing types as the path is walked (and triggering subscription notifications). If path already exists as a eDictionary it is cleared (change notifications will be queued for any child items that are destroyed). New child items are created for all elements of the given array.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – Floating point array to copy values from.

virtual bool getAsBoolAt( cpp::string_view path, size_t index, ) const = 0#

Attempts to read an array item as a bool.

Attempts to read the path and array index as a bool, either directly or via conversion, considering the item at path to be an array, and using the supplied index to access its child. The default value of (false) is returned if path doesn’t exist, index doesn’t exist, or there is a conversion failure.

Parameters:

path – Settings database key path (i.e. “/log/level”).
index – Zero based index of the element to retrieve in the array.

Returns:

The boolean value, either raw value or cast from the real item type. Zero is returned if path doesn’t exist, the item at the given path is not an array, index doesn’t exist in the array, or a conversion error occurs.

virtual void setBoolAt( cpp::string_view path, size_t index, bool value, ) const = 0#

Attempts to set a bool value in an array item.

Ensures that the given path exists as an eDictionary, changing types as the path is walked (and triggering subscription notifications). index is converted to a string and appended to path as a child path name. The child path is created as eBool or changed to be eBool, and the value is set from value. Subscription notifications are triggered when the current thread no longer has any settings locks.

Parameters:

path – Settings database key path (i.e. “/log/level”).
index – Zero based index of the element in array.
value – The new boolean value that will be stored to the supplied path and index.

virtual void getAsBoolArray( cpp::string_view path, bool *arrayOut, size_t arrayBufferLength, ) const = 0#

Fills the given buffer with the array values from the given path.

If the provided path is not a dictionary item, arrayOut is not modified. If the array item contains more items than arrayBufferLength, a warning message is logged and items past the end are ignored.

Warning

Dictionary items that are not arrays will only have child keys which are convertible to array indices written to arrayOut. For example, if path is the location of a dictionary item with keys ‘5’ and ‘10’, only those items will be written into arrayOut; the other indices will not be written. It is highly recommended to take a ScopedRead lock around calling this function, and call only if isAccessibleAsArray() or isAccessibleAsArrayOf() return true.

Parameters:

path – Settings database key path (i.e. “/log/level”).
arrayOut – Array buffer to fill with floating point values. This Note that the entries in this buffer will not be initialized before retrieving values. The caller should make sure to initialize all entries in the buffer to suitable default values before calling in case some indices are missing in the item’s array.
arrayBufferLength – Maximum number of values that can fit in arrayOut.

virtual void setBoolArray( cpp::string_view path, const cpp::span<const bool> array, ) const = 0#

Creates or updates an item to be a bool array.

Ensures that the given path exists as an eDictionary, changing types as the path is walked (and triggering subscription notifications). If path already exists as a eDictionary it is cleared (change notifications will be queued for any child items that are destroyed). New child items are created for all elements of the given array.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – Boolean array to copy values from.

virtual cpp::optional<omni::string> createStringFromItemValueAt( cpp::string_view path, size_t index, ) const = 0#

Attempts to create a string containing either a copy of the internal string value (if a string), or the converted string value.

This function effectively converts index to a string, appends it to path after a path separator (‘/’), and calls createStringFromItemValue().

Parameters:

path – Settings database key path (i.e. “/log/level”).
index – Zero base index of the element in array to retrieve the string from.

Returns:

A string value if applicable. Returns carb::cpp::nullopt on failure.

virtual cpp::optional<cpp::zstring_view> getStringViewAt( cpp::string_view path, size_t index, ) const = 0#

Returns a view of the internal raw string value of an item in an array.

No conversions will occur.

Warning

This function returns a view of an item’s internal string. Another thread may change or destroy the setting value which can cause the string view to be dangling. It is recommended to take a ScopedRead lock around calling this function and using the return value.

Parameters:

path – Settings database key path of an array item (i.e. “/log/level”).
index – Zero based index of the element in array.

Returns:

View of the internal string value if applicable, carb::cpp::nullopt otherwise.

virtual void setStringAt( cpp::string_view path, size_t index, cpp::string_view value, ) const = 0#

Sets a string value in an array at the given path.

The given path is walked and any dictionary items are changed or created to create the path. index is converted to a string and appended to path. If the item at this composite path exists but is not of type eString it is changed to be eString. Change notifications for subscriptions are queued. The given string is then set in the item at the composite path path.

Parameters:

path – Settings database key path (i.e. “/log/level”).
index – Zero based index of the element in array.
value – String value that will be stored to the supplied path.

virtual size_t getStringArray( cpp::string_view path, cpp::string_view *arrayOut, size_t arrayBufferLength, ) const = 0#

Returns views of the raw internal string values of all child items of an array.

Thus, doesn’t perform any conversions.

If the provided path is not a dictionary item, arrayOut is not modified. If the array item contains more items than arrayBufferLength, a warning message is logged and items past the end are ignored.

See also

carb::dictionary::IDictionary::getStringBufferArray carb::settings::getStringArray()

Warning

This function returns views of the internal strings for several items. Another thread may change the setting value which can cause the string_view to be dangling. It is recommended to take a ScopedRead lock around calling this function and use of the filled items in arrayOut.

Warning

Dictionary items that are not arrays will only have child keys which are convertible to array indices written to arrayOut. For example, if path is the location of a dictionary item with keys ‘5’ and ‘10’, only those items will be written into arrayOut; the other indices will not be written. It is highly recommended to take a ScopedRead lock around calling this function, and call only if isAccessibleAsArray() or isAccessibleAsArrayOf() return true.

Parameters:

path – Settings database key path (i.e. “/log/level”).
arrayOut – Array buffer to fill with char buffer pointer values. This may not be nullptr.
arrayBufferLength – The length of the string at value to copy. This can be useful if only a portion of the string should be copied or if value contains NUL characters (ie: byte data).

Returns:

The number of values that were read into arrayOut. This may be less than arrayBufferLength if the array item contains fewer items.

virtual void setStringArray( cpp::string_view path, const cpp::span<const cpp::string_view> array, ) const = 0#

Creates or updates an item as a string array.

Ensures that the given path exists as an carb::dictionary::ItemType::eDictionary, changing types as the path is walked (and triggering subscription notifications). If path already exists as a carb::dictionary::ItemType::eDictionary it is cleared (change notifications will be queued for any child items that are destroyed). New child items are created for all elements of the given array.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – Array of string_view objects to copy values from. Each value in this array will be set as a child value under the dictionary item at path.

template<typename SettingArrayType> void setArray( cpp::string_view path, const cpp::span<const SettingArrayType> array, ) const = delete#

Creates or updates an item to be an array of the given type with provided values.

This is a helper function that will call the appropriate API function based on SettingArrayType:

bool: setBoolArray()
int32_t: setIntArray()
int64_t: setInt64Array()
float: setFloatArray()
double: setFloat64Array()
carb::cpp::string_view: setStringArray()

Template Parameters:

SettingArrayType – The type of the elements in array.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – The span to copy values from.

virtual Transaction *createTransaction() const = 0#

Creates a new transaction.

A transaction is an asynchronous settings database that can be applied at a later time as one atomic unit with commitTransaction(). A transaction may be retained and committed several times. No changes are made to the settings database until the transaction is committed. A transaction must be disposed of with destroyTransaction() when it is no longer needed.

Values can be set within the transaction with setInt64Async(), setFloat64Async(), setBoolAsync(), and setStringAsync().

Returns:: On success, returns an opaque Transaction pointer. On failure, nullptr is returned.

virtual void destroyTransaction(Transaction *transaction) const = 0#

Destroys a transaction.

Destroys a transaction previously created with createTransaction().

Warning

After calling this function, the given transaction should no longer be used otherwise undefined behavior will occur.

Parameters:: transaction – The Transaction pointer to destroy.

virtual void commitTransaction(Transaction *transaction) const = 0#

Commits a transaction.

This atomically copies all of the values set in the transaction to the settings database. This is done as via:

// note: transaction->database is expository only.  This cannot be accessed externally.
update("/", transaction->database, nullptr, carb::dictionary::overwriteOriginalWithArrayHandling,
    carb::getCachedInterface<carb::dictionary::IDictionary>());

Values can be set within the transaction with setInt64Async(), setFloat64Async(), setBoolAsync(), and setStringAsync().

This function can be called multiple times for a given transaction that has not been destroyed. Each time a transaction is committed, it will overwrite any exist settings that match the settings contained in the transaction. Change notifications are queued as needed.

Parameters:: transaction – The Transaction to commit. This may not be nullptr.

virtual void setInt64Async( Transaction *transaction, cpp::string_view path, int64_t value, ) const = 0#

Sets a value in a Transaction to be applied at a later time.

The value is not committed to the settings database until commitTransaction() is called.

Note

Values cannot be read or deleted from a Transaction. Values can be overwritten in the transaction however.

Parameters:

transaction – The Transaction previously created with createTransaction().
path – Settings database key path (i.e. “/log/level”). The settings database is not modified until commitTransaction() is called with the same transaction object.
value – The new value to store in the transaction.

virtual void setFloat64Async( Transaction *transaction, cpp::string_view path, double value, ) const = 0#

Sets a value in a Transaction to be applied at a later time.

The value is not committed to the settings database until commitTransaction() is called.

Note

Values cannot be read or deleted from a Transaction. Values can be overwritten in the transaction however.

Parameters:

transaction – The Transaction previously created with createTransaction().
path – Settings database key path (i.e. “/log/level”). The settings database is not modified until commitTransaction() is called with the same transaction object.
value – The new value to store in the transaction.

virtual void setBoolAsync( Transaction *transaction, cpp::string_view path, bool value, ) const = 0#

Sets a value in a Transaction to be applied at a later time.

The value is not committed to the settings database until commitTransaction() is called.

Note

Values cannot be read or deleted from a Transaction. Values can be overwritten in the transaction however.

Parameters:

transaction – The Transaction previously created with createTransaction().
path – Settings database key path (i.e. “/log/level”). The settings database is not modified until commitTransaction() is called with the same transaction object.
value – The new value to store in the transaction.

virtual void setStringAsync( Transaction *transaction, cpp::string_view path, cpp::string_view value, ) const = 0#

Sets a value in a Transaction to be applied at a later time.

The value is not committed to the settings database until commitTransaction() is called.

Note

Values cannot be read or deleted from a Transaction. Values can be overwritten in the transaction however.

Parameters:

transaction – The Transaction previously created with createTransaction().
path – Settings database key path (i.e. “/log/level”). The settings database is not modified until commitTransaction() is called with the same transaction object.
value – The new value to store in the transaction.

virtual dictionary::SubscriptionId *subscribeToNodeChangeEvents( cpp::string_view path, dictionary::OnNodeChangeEventFn onChangeEventFn, void *userData, ) const = 0#

Subscribes to change events about a specific item in the settings database.

When the item at the specified path changes, the provided callback function will be called to inform the caller of the event. Changes include item creation, deletion, and its value being modified. When finished with the subscription, call unsubscribeFromChangeEvents() to dispose of the subscription ID and ensure the callback function will never be called again for this item.

Parameters:

path – Settings database key path (i.e. “/log/level”). This must not be nullptr. This path may point to a value item or a dictionary item. This path can be an item that has not been created yet in the settings database and will receive events starting when the item is first created.
onChangeEventFn – The callback function to call when a change event occurs on the specified item path. This may not be nullptr.
userData – Opaque user data pointer that will be provided to the callback function onChangeEventFn with each change that occurs. This value will not be accessed or interpreted internally. It is the caller’s responsibility to know how to appropriately interpret this value.

Returns:

On success, returns a subscription handle. This must be passed to unsubscribeFromChangeEvents() when the subscription is no longer needed. Returns nullptr on failure.

virtual dictionary::SubscriptionId *subscribeToTreeChangeEvents( cpp::string_view path, dictionary::OnTreeChangeEventFn onChangeEventFn, void *userData, ) const = 0#

Subscribes to change events for all items in a subtree of the settings database.

All items including and under path will trigger change notifications. When a change is detected, the provided callback function will be called to inform the caller of the event. Changes include item creation, deletion, and its value being modified. When finished with the subscription, call unsubscribeFromChangeEvents() to dispose of the subscription ID and ensure the callback function will never be called again for changes related to this subscription.

Parameters:

path – Settings database key path (i.e. “/log/level”). This path may point to a value item or a dictionary item. This path can be an item that has not been created yet in the settings database and will receive events starting when the item is first created.
onChangeEventFn – The callback function to call when a change event occurs on the specified item or any of its children. This must not be nullptr.
userData – Opaque user data pointer that will be provided to the callback function onChangeEventFn() with each change that occurs. This value will not be accessed or interpreted internally. It is the caller’s responsibility to know how to appropriately interpret this value.

Returns:

On success, returns a subscription handle. This must be passed to unsubscribeFromChangeEvents() when the subscription is no longer needed. Returns nullptr on failure.

virtual void unsubscribeFromChangeEvents( dictionary::SubscriptionId *subscriptionId, ) const = 0#

Unsubscribes from change events.

It is safe to call this function from within a subscription callback. Once it returns, this function guarantees that the subscription callback has exited (only if being called from another thread) and will never be called again.

Note

If a module or plugin that holds a subscription is unloaded, undefined behavior will result. It is the responsibility of each plugin/module to ensure that all of its subscription IDs have been destroyed before unloading.

Parameters:: subscriptionId – The subscription handle from subscribeToNodeChangeEvents() or subscribeToTreeChangeEvents() to be unsubscribed from.

virtual void update( cpp::string_view path, const dictionary::Item *dictionary, cpp::string_view dictionaryPath, dictionary::OnUpdateItemFn onUpdateItemFn, void *userData, ) const = 0#

Merges the a dictionary item into into the settings database at a given path.

The destination path does not necessarily need to exist before this operation. If it does not exist, the missing items in the path will be created as dictionaries.

Parameters:

path – Settings database key path (i.e. “/log/level”). This This path is used as the destination location within the settings database for the merge to occur at. “” or “/” is considered to be the root of the settings database.
dictionary – The carb::dictionary::Item that is the base of the items to merge into the setting database. This base item can be offset to a child path using dictionaryPath. This may not be nullptr.
dictionaryPath – A child path of dictionary to use as the root for merging. This may be an empty string in order to use dictionary directly as the root of the merge.
onUpdateItemFn – Function that will tell whether the update should overwrite the destination item with the source item. For more information on this callback, see carb::dictionary::OnUpdateItemFn(). This may use one of the existing callback helper functions such as carb::dictionary::keepOriginal(), carb::dictionary::overwriteOriginal(), or carb::dictionary::overwriteOriginalWithArrayHandling(). If needed, a custom callback function may be used instead.
userData – Opaque user data pointer that will be passed into the onUpdateItemFn callback function.

virtual const dictionary::Item *getSettingsDictionary( cpp::string_view path, ) const = 0#

Accesses the settings database as a dictionary Item.

This allows use of carb::dictionary::IDictionary functions directly.

Note

It is highly recommended to take a ScopedRead or ScopedWrite lock while working with the setting database directly.

Warning

The root dictionary::Item is owned by ISettings and must not be altered or destroyed.

Parameters:: path – Settings database key path (i.e. “/log/level”). The dictionary item at this specified path in the settings database will be returned. “” or “/” is considered to be the root.
Returns:: A carb::dictionary::Item that can be used directly with the carb::dictionary::IDictionary interface.

virtual dictionary::Item *createDictionaryFromSettings( cpp::string_view path, ) const = 0#

Takes a snapshot of a portion of the settings database as a dictionary Item.

This copies a portion of the settings database into a new dictionary item. The copy is done atomically. Since a copy will be returned, there are no restrictions on what the caller may do with the new dictionary. The caller will own the newly created dictionary and is responsible for destroying it when no longer needed.

Parameters:: path – Settings database key path (i.e. “/log/level”) to consider the root for the copy. “” or “/” are considered to be the root; passing these will copy the entire settings database.
Returns:: A carb::dictionary::Item that is a separate copy of the requested portion of the settings database. When no longer needed, this can be passed to carb::dictionary::IDictionary::destroyItem().

virtual void destroyItem(cpp::string_view path) const = 0#

Destroys a setting item and queues change notifications.

Warning

Any string buffers or carb::dictionary::Item pointers to the referenced path become invalid and their use is undefined behavior.

Parameters:: path – Settings database key path (i.e. “/log/level”) to destroy. “/” is considered to be the root and will always exist. If it is passed for path, this will clear the entire settings database but leave the root item intact without any value.

virtual void initializeFromDictionary( const dictionary::Item *dictionary, ) const = 0#

Performs a one-time initialization from a given dictionary item.

Note

This function may only be called once. Subsequent calls will result in an error message logged.

Parameters:: dictionary – The carb::dictionary::Item to initialize the settings database from. The items are copied into the root of the settings database. This item is not retained and may be destroyed immediately after this function returns. This may not be nullptr.

inline void setDefaultInt64( cpp::string_view path, int64_t value, ) const#

Sets a value at the given path if and only if one does not already exist.

Atomically checks if a value exists at the given path, and if so, exits without doing anything. If the value at the given path does not exist, any required dictionary items are created while walking path and value is stored. Change notifications are queued as needed

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – Value that will be stored at the given path in the settings database.

inline void setDefaultInt(cpp::string_view path, int32_t value) const#

Sets a value at the given path if and only if one does not already exist.

Atomically checks if a value exists at the given path, and if so, exits without doing anything. If the value at the given path does not exist, any required dictionary items are created while walking path and value is stored. Change notifications are queued as needed

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – Value that will be stored at the given path in the settings database.

inline void setDefaultFloat64( cpp::string_view path, double value, ) const#

Sets a value at the given path if and only if one does not already exist.

Atomically checks if a value exists at the given path, and if so, exits without doing anything. If the value at the given path does not exist, any required dictionary items are created while walking path and value is stored. Change notifications are queued as needed

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – Value that will be stored at the given path in the settings database.

inline void setDefaultFloat(cpp::string_view path, float value) const#

Sets a value at the given path if and only if one does not already exist.

Atomically checks if a value exists at the given path, and if so, exits without doing anything. If the value at the given path does not exist, any required dictionary items are created while walking path and value is stored. Change notifications are queued as needed

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – Value that will be stored at the given path in the settings database.

inline void setDefaultBool(cpp::string_view path, bool value) const#

Sets a value at the given path if and only if one does not already exist.

Atomically checks if a value exists at the given path, and if so, exits without doing anything. If the value at the given path does not exist, any required dictionary items are created while walking path and value is stored. Change notifications are queued as needed

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – Value that will be stored at the given path in the settings database.

inline void setDefaultString( cpp::string_view path, cpp::string_view value, ) const#

Sets a value at the given path if and only if one does not already exist.

Atomically checks if a value exists at the given path, and if so, exits without doing anything. If the value at the given path does not exist, any required dictionary items are created while walking path and value is stored. Change notifications are queued as needed

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – Value that will be stored at the given path in the settings database.

template<typename SettingType, std::enable_if_t<!cpp::is_std_string_view_like_v<SettingType>, bool> = true> void setDefault( cpp::string_view path, SettingType value, ) const#

Sets a value at the given path if and only if one does not already exist.

Atomically checks if a value exists at the given path, and if so, exits without doing anything. If the value at the given path does not exist, any required dictionary items are created while walking path and value is stored. Change notifications are queued as needed

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – Value that will be stored at the given path in the settings database.

Template Parameters:

SettingType – The type of value.

void setDefault(cpp::string_view path, cpp::string_view value) const#

Sets a value at the given path if and only if one does not already exist.

Atomically checks if a value exists at the given path, and if so, exits without doing anything. If the value at the given path does not exist, any required dictionary items are created while walking path and value is stored. Change notifications are queued as needed

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – Value that will be stored at the given path in the settings database.

inline void setDefaultsFromDictionary( cpp::string_view path, const dictionary::Item *dictionary, ) const#

Copies values into the setting dictionary, if and only if they don’t already exist.

Values are checked and copied atomically, and change notifications are queued.

Parameters:

path – Settings database key path (i.e. “/log/level”). This is the root location at which dictionary is copied in.
dictionary – The dictionary::Item to copy defaults from. Only keys that do not exist in the settings database or exist but have no value will be copied in.

inline void setDefaultInt64Array( cpp::string_view path, const cpp::span<const int64_t> array, ) const#

Sets an array of values at the given path, if and only if one does not already exist.

Atomically checks if a value exists at the given path, and if so, exits without doing anything. Otherwise, any required dictionary items are created while walking path and array is stored. Change notifications are queued.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – Array of values that will be stored at the given path in the settings database.

inline void setDefaultIntArray( cpp::string_view path, const cpp::span<const int32_t> array, ) const#

Sets an array of values at the given path, if and only if one does not already exist.

Atomically checks if a value exists at the given path, and if so, exits without doing anything. Otherwise, any required dictionary items are created while walking path and array is stored. Change notifications are queued.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – Array of values that will be stored at the given path in the settings database.

inline void setDefaultFloat64Array( cpp::string_view path, const cpp::span<const double> array, ) const#

Sets an array of values at the given path, if and only if one does not already exist.

Atomically checks if a value exists at the given path, and if so, exits without doing anything. Otherwise, any required dictionary items are created while walking path and array is stored. Change notifications are queued.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – Array of values that will be stored at the given path in the settings database.

inline void setDefaultFloatArray( cpp::string_view path, const cpp::span<const float> array, ) const#

Sets an array of values at the given path, if and only if one does not already exist.

Atomically checks if a value exists at the given path, and if so, exits without doing anything. Otherwise, any required dictionary items are created while walking path and array is stored. Change notifications are queued.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – Array of values that will be stored at the given path in the settings database.

inline void setDefaultBoolArray( cpp::string_view path, const cpp::span<const bool> array, ) const#

Sets an array of values at the given path, if and only if one does not already exist.

Atomically checks if a value exists at the given path, and if so, exits without doing anything. Otherwise, any required dictionary items are created while walking path and array is stored. Change notifications are queued.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – Array of values that will be stored at the given path in the settings database.

inline void setDefaultStringArray( cpp::string_view path, const cpp::span<const cpp::string_view> array, ) const#

Sets an array of values at the given path, if and only if one does not already exist.

Atomically checks if a value exists at the given path, and if so, exits without doing anything. Otherwise, any required dictionary items are created while walking path and array is stored. Change notifications are queued.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – Array of values that will be stored at the given path in the settings database.

template<typename SettingArrayType> void setDefaultArray( cpp::string_view path, const cpp::span<const SettingArrayType> array, ) const#

Sets an array of values at the given path, if and only if one does not already exist.

Atomically checks if a value exists at the given path, and if so, exits without doing anything. Otherwise, any required dictionary items are created while walking path and array is stored. Change notifications are queued.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – Array of values that will be stored at the given path in the settings database.

Template Parameters:

SettingArrayType – The type of the values in array.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc( ) noexcept#

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns:: The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc( ) noexcept#

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns:: The carb::InterfaceDesc struct with information about the latest version of this interface.