carb::settings::ISettings

Defined in carb/settings/ISettings.h

struct 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 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 call to a carb.settings API function will fully complete 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:

  1. ISettings::unsubscribeToChangeEvents may be called from within the callback to unregister the called subscription or any other subscription.

  2. Unregistering the subscription ensures that it will never be called again, and any calls in process on another thread will complete before ISettings::unsubscribeToChangeEvents returns.

  3. 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

inline int32_t getAsInt(const char *path)

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

See also

carb::dictionary::IDictionary::getAsInt

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”). Must not be nullptr.

Returns

The int32_t value of the setting value at path. If path is invalid, non-existent, or cannot be converted to an int32_t, 0 is returned.

inline void setInt(const char *path, int32_t value)

Sets the integer value at the supplied path.

If an item was already present, changes its original type to ‘integer’. If the present item is a dictionary with children, all children are destroyed. If path doesn’t exist, creates 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”). Must not be nullptr.

  • value – Integer value that will be stored to the supplied path.

inline float getAsFloat(const char *path)

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

See also

carb::dictionary::IDictionary::getAsFloat

Parameters

path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

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(const char *path, float value)

Sets the floating point value at the supplied path.

If an item was already present, changes its original type to ‘float’. If the present item is a dictionary with children, all children are destroyed. If path doesn’t exist, creates ‘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”). Must not be nullptr.

  • value – Floating point value that will be stored to the supplied path.

inline const char *createStringBufferFromItemValue(const char *path, size_t *pStringLen = nullptr) const

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”). Must not be nullptr.

  • pStringLen – (optional) Receives the length of the string. This can be useful if the string contains NUL characters (i.e. byte data).

Returns

Pointer to the created string buffer if applicable, nullptr otherwise.

inline const char *getStringBuffer(const char *path, size_t *pStringLen = nullptr) const

Returns internal raw data pointer to the string value of an item.

Thus, doesn’t perform any conversions.

See also

carb::dictionary::IDictionary::getStringBuffer() carb::settings::getString()

Warning

This function returns the internal string buffer. Another thread may change the setting value which can cause the string buffer to be destroyed. 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”). Must not be nullptr.

  • pStringLen – (optional) Receives the length of the string. This can be useful if the string contains NUL characters (i.e. byte data).

Returns

Raw pointer to the internal string value if applicable, nullptr otherwise.

inline void setString(const char *path, const char *value, size_t stringLen = size_t(-1)) const

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. If value is nullptr, the string item will store an empty string.

Parameters

  • path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

  • value – String value that will be stored to the supplied path. nullptr is interpreted as an empty string.

  • stringLen – (optional) 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 (i.e. byte data). The default value of size_t(-1) treats value as a NUL-terminated string.

template<typename T>
T get(const char *path)

Reads the value from a path, converting if necessary.

Template Parameters

T – The type of item to read. Must be a supported type.

Parameters

path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

Returns

The value read from the path.

template<typename T>
void set(const char *path, T value)

Sets the value at a path.

Template Parameters

T – The type of item to read. Must be a supported type.

Parameters

  • path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

  • value – The value to store in the item at path.

inline int32_t getAsIntAt(const char *path, size_t index)

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. Default value (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”). Must not be nullptr.

  • index – Index of the element in array.

Returns

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

inline void setIntAt(const char *path, size_t index, int32_t value)

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”). Must not be nullptr.

  • index – Index of the element in array.

  • value – Integer value that will be stored to the supplied path.

inline float getAsFloatAt(const char *path, size_t index)

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. Default value (0.0f) is returned if path doesn’t exist, index doesn’t exist, or there is a conversion failure.

See also

carb::dictionary::IDictionary::getAsFloatAt()

Parameters

  • path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

  • index – Index of the element in array.

Returns

float value, either raw value or cast from the real item type.

inline void setFloatAt(const char *path, size_t index, float value)

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.

See also

carb::dictionary::IDictionary::setFloatAt()

Parameters

  • path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

  • index – Index of the element in array.

  • value – Floating point value that will be stored to the supplied path.

inline const char *createStringBufferFromItemValueAt(const char *path, size_t index, size_t *pStringLen = nullptr) const

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.

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

See also

carb::dictionary::IDictionary::createStringBufferFromItemValueAt()

Note

It is undefined to create std::string out of nullptr. For using the value as std::string, see carb::settings::getStringFromItemValueAt()

Parameters

  • path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

  • index – Index of the element in array.

  • pStringLen – (optional) Receives the length of the string. This can be useful if the string contains NUL characters (i.e. byte data). Undefined if the function returns nullptr.

Returns

Pointer to the created string buffer if applicable, nullptr otherwise. Non-nullptr return values must be passed to destroyStringBuffer to dispose of when finished.

inline const char *getStringBufferAt(const char *path, size_t index, size_t *pStringLen = nullptr) const

Returns internal raw data pointer to the string value of an item in an array.

Thus, doesn’t perform any conversions.

See also

carb::dictionary::IDictionary::getStringBufferAt()

See also

carb::settings::getStringAt()

Note

It is undefined to create std::string out of nullptr. For using the value as std::string,

Warning

This function returns the internal string buffer. Another thread may change the setting value which can cause the string buffer to be destroyed. 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”). Must not be nullptr.

  • index – Index of the element in array.

  • pStringLen – (optional) Receives the length of the string. This can be useful if the string contains NUL characters (i.e. byte data). Undefined if the function returns nullptr.

Returns

Raw pointer to the internal string value if applicable, nullptr otherwise.

inline void setStringAt(const char *path, size_t index, const char *value, size_t stringLen = size_t(-1)) const

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. 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. If value is nullptr, the string item will store an empty string.

See also

carb::dictionary::IDictionary::setStringAt()

Parameters

  • path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

  • index – Index of the element in array.

  • value – String value that will be stored to the supplied path.

  • stringLen – (optional) 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 (i.e. byte data). The default value of size_t(-1) treats value as a NUL-terminated string.

template<typename SettingArrayType>
void setArray(const char *path, const SettingArrayType *array, size_t arrayLength)

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

  • const char*: setStringArray

See also

carb::dictionary::IDictionary::setArray()

Template Parameters

SettingArrayType – The type of elements.

Parameters

  • path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

  • array – Array to copy values from.

  • arrayLength – Number of items in array.

inline void setDefaultInt64(const char *path, int64_t value)

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. Otherwise, any required dictionary items are created while walking path and value is stored. Change notifications are queued.

Parameters

  • path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

  • value – Value that will be stored at the given path in the settings database.

inline void setDefaultInt(const char *path, int32_t value)

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. Otherwise, any required dictionary items are created while walking path and value is stored. Change notifications are queued.

Parameters

  • path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

  • value – Value that will be stored at the given path in the settings database.

inline void setDefaultFloat64(const char *path, double value)

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. Otherwise, any required dictionary items are created while walking path and value is stored. Change notifications are queued.

Parameters

  • path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

  • value – Value that will be stored at the given path in the settings database.

inline void setDefaultFloat(const char *path, float value)

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. Otherwise, any required dictionary items are created while walking path and value is stored. Change notifications are queued.

Parameters

  • path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

  • value – Value that will be stored at the given path in the settings database.

inline void setDefaultBool(const char *path, bool value)

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. Otherwise, any required dictionary items are created while walking path and value is stored. Change notifications are queued.

Parameters

  • path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

  • value – Value that will be stored at the given path in the settings database.

inline void setDefaultString(const char *path, const char *value)

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. Otherwise, any required dictionary items are created while walking path and value is stored. Change notifications are queued.

Parameters

  • path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

  • value – Value that will be stored at the given path in the settings database.

template<typename SettingType>
void setDefault(const char *path, SettingType value)

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. Otherwise, any required dictionary items are created while walking path and value is stored. Change notifications are queued.

Parameters

  • path – Settings database key path (i.e. “/log/level”). Must not be nullptr.

  • value – Value that will be stored at the given path in the settings database.

Template Parameters

SettingType – The type of value.

inline void setDefaultsFromDictionary(const char *path, const dictionary::Item *dictionary)

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”). Must not be nullptr. This is the root location at which dictionary is copied in.

  • dictionary – The dictionary::Item to copy defaults from.

inline void setDefaultInt64Array(const char *path, const int64_t *array, size_t arrayLength)

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”). Must not be nullptr.

  • array – Array of values that will be stored at the given path in the settings database.

  • arrayLength – Number of values in array.

inline void setDefaultIntArray(const char *path, const int32_t *array, size_t arrayLength)

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”). Must not be nullptr.

  • array – Array of values that will be stored at the given path in the settings database.

  • arrayLength – Number of values in array.

inline void setDefaultFloat64Array(const char *path, const double *array, size_t arrayLength)

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”). Must not be nullptr.

  • array – Array of values that will be stored at the given path in the settings database.

  • arrayLength – Number of values in array.

inline void setDefaultFloatArray(const char *path, const float *array, size_t arrayLength)

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”). Must not be nullptr.

  • array – Array of values that will be stored at the given path in the settings database.

  • arrayLength – Number of values in array.

inline void setDefaultBoolArray(const char *path, const bool *array, size_t arrayLength)

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”). Must not be nullptr.

  • array – Array of values that will be stored at the given path in the settings database.

  • arrayLength – Number of values in array.

inline void setDefaultStringArray(const char *path, const char *const *array, size_t arrayLength)

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”). Must not be nullptr.

  • array – Array of values that will be stored at the given path in the settings database.

  • arrayLength – Number of values in array.

template<typename SettingArrayType>
void setDefaultArray(const char *path, const SettingArrayType *array, size_t arrayLength)

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”). Must not be nullptr.

  • array – Array of values that will be stored at the given path in the settings database.

  • arrayLength – Number of values in array.

Template Parameters

SettingArrayType – The type of the values in array.

Public Members

dictionary::ItemType (*getItemType)(const char *path)

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

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Return

carb::dictionary::ItemType of value at path; if path is nullptr or does not exist, carb::dictionary::ItemType::eCount is returned.

bool (*isAccessibleAs)(dictionary::ItemType itemType, const char *path)

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

Param itemType

Item type to check for.

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Return

True if accessible, or false otherwise.

void (*setDictionary)(const char *path)

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.

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr. Providing the root level (“/” or “”) is undefined behavior.

int64_t (*getAsInt64)(const char *path)

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

See also

carb::dictionary::IDictionary::getAsInt64

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Return

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.

void (*setInt64)(const char *path, int64_t value)

Sets the integer value at the supplied path.

If an item was already present, changes its original type to ‘integer’. If the present item is a dictionary with children, all children are destroyed. If path doesn’t exist, creates integer item, and all the required items along the path if necessary.

See also

carb::dictionary::IDictionary::setInt64

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param value

Integer value that will be stored to the supplied path.

double (*getAsFloat64)(const char *path)

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

See also

carb::dictionary::IDictionary::getAsFloat64

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Return

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.

void (*setFloat64)(const char *path, double value)

Sets the floating point value at the supplied path.

If an item was already present, changes its original type to ‘double’. If the present item is a dictionary with children, all children are destroyed. If path doesn’t exist, creates ‘double’ item, and all the required items along the path if necessary.

See also

carb::dictionary::IDictionary::setFloat64

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param value

Floating point value that will be stored to the supplied path.

bool (*getAsBool)(const char *path)

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

See also

carb::dictionary::IDictionary::getAsBool

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Return

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.

void (*setBool)(const char *path, bool value)

Sets the boolean value at the supplied path.

If an item was already present, changes its original type to ‘bool’. If the present item is a dictionary with children, all children are destroyed. If path doesn’t exist, creates ‘bool’ item, and all the required items along the path if necessary.

See also

carb::dictionary::IDictionary::setBool

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param value

Boolean value that will be stored to the supplied path.

bool (*isAccessibleAsArray)(const char *path)

Checks if the item could be accessible as array, i.e.

all child items names are valid contiguous non-negative integers starting with zero.

See also

carb::dictionary::IDictionary::isAccessibleAsArray

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Return

True if accessible, or false otherwise.

bool (*isAccessibleAsArrayOf)(dictionary::ItemType itemType, const char *path)

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

See also

carb::dictionary::IDictionary::isAccessibleAsArrayOf

Param itemType

Item type to check for.

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Return

True if a valid array and with all items accessible, or false otherwise.

size_t (*getArrayLength)(const char *path)

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

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

See also

carb::dictionary::IDictionary::getArrayLength

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Return

Number of array elements if applicable, or 0 otherwise.

dictionary::ItemType (*getPreferredArrayType)(const char *path)

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

The rules are thus:

See also

dictionary::IDictionary::getPreferredArrayType

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Return

dictionary::ItemType that is most suitable for the array, or dictionary::ItemType::eCount on failure.

int64_t (*getAsInt64At)(const char *path, size_t index)

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. Default value (0) is returned if path doesn’t exist, index doesn’t exist, or there is a conversion failure.

See also

dictionary::IDictionary::getAsInt64At

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param index

Index of the element in array.

Return

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

void (*setInt64At)(const char *path, size_t index, int64_t value)

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

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param index

Index of the element in array.

Param value

Integer value that will be stored to the supplied path.

void (*getAsInt64Array)(const char *path, int64_t *arrayOut, size_t arrayBufferLength)

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.

See also

carb::dictionary::IDictionary::getAsInt64Array

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.

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param arrayOut

Array buffer to fill with integer values.

Param arrayBufferLength

Size of the supplied array buffer.

void (*setInt64Array)(const char *path, const int64_t *array, size_t arrayLength)

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.

See also

carb::dictionary::IDictionary::setInt64Array

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param array

Integer array to copy values from.

Param arrayLength

Array length.

void (*getAsIntArray)(const char *path, int32_t *arrayOut, size_t arrayBufferLength)

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.

See also

carb::dictionary::IDictionary::getAsIntArray

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.

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param arrayOut

Array buffer to fill with integer values.

Param arrayBufferLength

Size of the supplied array buffer.

void (*setIntArray)(const char *path, const int32_t *array, size_t arrayLength)

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.

See also

carb::dictionary::IDictionary::setIntArray

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param array

Integer array to copy values from.

Param arrayLength

Array length.

double (*getAsFloat64At)(const char *path, size_t index)

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. Default value (0.0) is returned if path doesn’t exist, index doesn’t exist, or there is a conversion failure.

See also

carb::dictionary::IDictionary::getAsFloat64At

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Return

double value, either raw value or cast from the real item type.

void (*setFloat64At)(const char *path, size_t index, double value)

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.

See also

carb::dictionary::IDictionary::setFloat64At

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param index

Index of the element in array.

Param value

double value that will be stored to the supplied path.

void (*getAsFloat64Array)(const char *path, double *arrayOut, size_t arrayBufferLength)

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.

See also

carb::dictionary::IDictionary::getAsFloat64Array

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.

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param arrayOut

Array buffer to fill with floating point values.

Param arrayBufferLength

Size of the supplied array buffer.

void (*setFloat64Array)(const char *path, const double *array, size_t arrayLength)

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.

See also

carb::dictionary::IDictionary::setFloat64Array

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param array

Floating point array to copy values from.

Param arrayLength

Array length.

void (*getAsFloatArray)(const char *path, float *arrayOut, size_t arrayBufferLength)

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.

See also

carb::dictionary::IDictionary::getAsFloatArray

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.

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param arrayOut

Array buffer to fill with floating point values.

Param arrayBufferLength

Size of the supplied array buffer.

void (*setFloatArray)(const char *path, const float *array, size_t arrayLength)

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.

See also

carb::dictionary::IDictionary::setFloatArray

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param array

Floating point array to copy values from.

Param arrayLength

Array length.

bool (*getAsBoolAt)(const char *path, size_t index)

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. Default value (false) is returned if path doesn’t exist, index doesn’t exist, or there is a conversion failure.

See also

carb::dictionary::IDictionary::getAsBoolAt

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Return

Boolean value, either raw value or cast from the real item type.

void (*setBoolAt)(const char *path, size_t index, bool value)

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.

See also

carb::dictionary::IDictionary::setBoolAt

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param index

Index of the element in array.

Param value

Boolean value that will be stored to the supplied path.

void (*getAsBoolArray)(const char *path, bool *arrayOut, size_t arrayBufferLength)

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.

See also

carb::dictionary::IDictionary::getAsBoolArray

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.

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param arrayOut

Array buffer to fill with boolean values.

Param arrayBufferLength

Size of the supplied array buffer.

void (*setBoolArray)(const char *path, const bool *array, size_t arrayLength)

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.

See also

carb::dictionary::IDictionary::setBoolArray

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param array

Boolean array to copy values from.

Param arrayLength

Array length.

void (*getStringBufferArray)(const char *path, const char **arrayOut, size_t arrayBufferLength)

Returns internal raw data pointers to the string value 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 the internal string buffer(s) for several items. Another thread may change the setting value which can cause the string buffer to be destroyed. 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.

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param arrayOut

Array buffer to fill with char buffer pointer values.

Param arrayBufferLength

Size of the supplied array buffer.

void (*setStringArray)(const char *path, const char *const *array, size_t arrayLength)

Creates or updates an item to be a string 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.

See also

carb::dictionary::IDictionary::setStringArray

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param array

String array to copy values from.

Param arrayLength

Array length.

Transaction *(*createTransaction)()

Creates a 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. 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.

Return

An opaque Transaction pointer.

void (*destroyTransaction)(Transaction *transaction)

Destroys a transaction.

Destroys a transaction previously created with createTransaction.

Warning

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

Param transaction

The Transaction to destroy.

void (*commitTransaction)(Transaction *transaction)

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
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.

Change notifications are queued.

Param transaction

The Transaction to commit.

void (*setInt64Async)(Transaction *transaction, const char *path, int64_t value)

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.

Param transaction

The Transaction previously created with createTransaction.

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr. The settings database is not modified until commitTransaction is called.

Param value

The value to store in the transaction.

void (*setFloat64Async)(Transaction *transaction, const char *path, double value)

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.

Param transaction

The Transaction previously created with createTransaction.

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr. The settings database is not modified until commitTransaction is called.

Param value

The value to store in the transaction.

void (*setBoolAsync)(Transaction *transaction, const char *path, bool value)

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.

Param transaction

The Transaction previously created with createTransaction.

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr. The settings database is not modified until commitTransaction is called.

Param value

The value to store in the transaction.

void (*setStringAsync)(Transaction *transaction, const char *path, const char *value)

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.

Param transaction

The Transaction previously created with createTransaction.

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr. The settings database is not modified until commitTransaction is called.

Param value

The value to store in the transaction.

dictionary::SubscriptionId *(*subscribeToNodeChangeEvents)(const char *path, dictionary::OnNodeChangeEventFn onChangeEventFn, void *userData)

Subscribes to change events about a specific item.

When finished with the subscription, call unsubscribeToChangeEvents.

See also

carb::dictionary::IDictionary::subscribeToNodeChangeEvents

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param onChangeEventFn

The function to call when a change event occurs.

Param userData

User-specific data that will be provided to onChangeEventFn.

Return

A subscription handle that can be used with unsubscribeToChangeEvents.

dictionary::SubscriptionId *(*subscribeToTreeChangeEvents)(const char *path, dictionary::OnTreeChangeEventFn onChangeEventFn, void *userData)

Subscribes to change events for all items in a subtree.

All items including and under path will trigger change notifications.

When finished with the subscription, call unsubscribeToChangeEvents.

See also

carb::dictionary::IDictionary::subscribeToTreeChangeEvents

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr.

Param onChangeEventFn

The function to call when a change event occurs.

Param userData

User-specific data that will be provided to onChangeEventFn.

Return

A subscription handle that can be used with unsubscribeToChangeEvents.

void (*unsubscribeToChangeEvents)(dictionary::SubscriptionId *subscriptionId)

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.

Param subscriptionId

The subscription handle from subscribeToNodeChangeEvents or subscribeToTreeChangeEvents

void (*update)(const char *path, const dictionary::Item *dictionary, const char *dictionaryPath, dictionary::OnUpdateItemFn onUpdateItemFn, void *userData)

Merges the source item into the settings database.

Destination path may be non-existing, then missing items in the path will be created as dictionaries.

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr. Used as the destination location within the settings database. “/” is considered to be the root.

Param dictionary

The carb::dictionary::Item that is the base of the items to merge into the setting database.

Param dictionaryPath

A child path of dictionary to use as the root for merging. May be nullptr in order to use dictionary directly as the root.

Param onUpdateItemFn

Function that will tell whether the update should overwrite the destination item with the source item. See carb::dictionary::keepOriginal(), carb::dictionary::overwriteOriginal(), or carb::dictionary::overwriteOriginalWithArrayHandling().

Param userData

User data pointer that will be passed into the onUpdateItemFn.

const dictionary::Item *(*getSettingsDictionary)(const char *path)

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.

Param path

Settings database key path (i.e. “/log/level”). Must not be nullptr. Used as the destination location within the settings database. “/” is considered to be the root.

Return

A carb::dictionary::Item that can be used directly with the carb::dictionary::IDictionary interface.

dictionary::Item *(*createDictionaryFromSettings)(const char *path)

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

Param path

Settings database key path (i.e. “/log/level”) to consider the root for the copy. “/” is considered to be the root (will copy the entire settings database).

Return

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.

void (*destroyItem)(const char *path)

Destroys a setting item and queues change notifications.

See also

carb::dictionary::IDictionary::destroyItem

Warning

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

Param path

Settings database key path (i.e. “/log/level”) to destroy. “/” is considered to be the root (will clear the entire settings database without actually destroying the root).

void (*destroyStringBuffer)(const char *stringBuffer)

Frees a string buffer.

The string buffers are created by createStringBufferFromItemValue() or createStringBufferFromItemValueAt().

See also

carb::dictionary::IDictionary::destroyStringBuffer

Param stringBuffer

String buffer to destroy. Undefined behavior results if this is not a value returned from one of the functions listed above.

void (*initializeFromDictionary)(const dictionary::Item *dictionary)

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.

Param 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.

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.