ISettings#

Fully qualified name: 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 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:

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

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

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

• value – The new 32-bit 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 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”). 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 – Receives the length of the string. This can be useful if the string contains NUL characters (i.e. byte data). This may be nullptr if this value is not needed.

Returns:

Pointer to the created string buffer if it is successfully created. This buffer must be destroyed using destroyStringBuffer() when it is no longer needed. Returns nullptr on failure.

inline const char *getStringBuffer(

const char *path,

size_t *pStringLen = nullptr,

) const#

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

No conversions will occur on the returned buffer.

See also

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

Warning

This function returns an item’s 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 – Receives the length of the string. This can be useful if the string contains NUL characters (i.e. byte data). This may be nullptr if this value is not needed.

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 new 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. A value of nullptr is interpreted as an empty string.

• stringLen – 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. The supported types are int, int64_t, float, double, bool, and const char*. 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”). Must not be nullptr.

Returns:

The value read from the path. Note that if a string value is retrieved, the returned value will be a pointer to the item’s internal string buffer. See the warning in getStringBuffer() for more information on how this could be dangerous to use.

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. The supported types are int32_t, int64_t, float, double, bool, and const char*. Any unsigned values must instead be stored as their signed counterparts.

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

• 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(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 – Zero based index of the element in array.

• value – 32-bit integer value that will be stored to the supplied path and index.

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. The default value of (0.0) 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 – 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(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 – Zero based index of the element in array.

• value – The new float value that will be stored to the supplied path and index.

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 – Zero base index of the element in array to retrieve the string from.

• pStringLen – Receives the length of the string. This can be useful if the string contains NUL characters (i.e. byte data). This may be nullptr if this value is not needed. The value in this is undefined if the function returns nullptr.

Returns:

Pointer to the created string buffer if applicable, This buffer must be destroyed using destroyStringBuffer() when it is no longer needed. Returns nullptr on failure.

inline const char *getStringBufferAt(

const char *path,

size_t index,

size_t *pStringLen = nullptr,

) const#

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

No conversions will occur on the returned buffer.

See also

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

See also

carb::settings::getStringAt().

Note

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

Warning

This function returns an item’s 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 – Zero based index of the element in array.

• pStringLen – Receives the length of the string. This can be useful if the string contains NUL characters (i.e. byte data). This may be nullptr if this value is not needed. The value in this is 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 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. 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 – Zero based index of the element in array.

• value – String value that will be stored to the supplied path. If this is nullptr, an empty string will be used instead.

• stringLen – 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 the elements in array.

Parameters:

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

• array – The array to copy values from. This may not be nullptr. In the case of a string array, none of the entries in the array may be nullptr either.

• arrayLength – The total number of values 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. 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”). This 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. 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”). This 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. 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”). This 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. 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”). This 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. 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”). This 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. 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”). This 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. 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”). This 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. Only keys that do not exist in the settings database or exist but have no value will be copied in.

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. This may not be nullptr.

• 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. This may not be nullptr.

• 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. This may not be nullptr.

• 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. This may not be nullptr.

• 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. This may not be nullptr.

• 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. This may not be nullptr.

• 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. This may not be nullptr.

• 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 an item could be accessible as the provided type, either directly, or via conversion.

Param itemType:

The item type to check for. This may not be carb::dictionary::ItemType::eCount.

Param path:

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

Return:

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

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 a 64-bit 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 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

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

See also

carb::dictionary::IDictionary::setFloat64

Param path:

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

Param value:

the new 64-bit floating point value that will be stored to the supplied path.

bool (*getAsBool)(const char *path)#

Attempts to get the supplied item as a 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 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

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.

An array item is one where 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 as an array, 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.

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

See also

carb::dictionary::IDictionary::isAccessibleAsArrayOf

Param itemType:

Item type to check for. Each item in the array must be convertible to this type in order for this call to succeed.

Param path:

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

Return:

true if the item at the given path is a valid array with all items accessible as the given type, 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:

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

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

Param path:

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

Param index:

Zero based index of the element in array to retrieve.

Return:

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.

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

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.

Param path:

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

Param index:

Zero based index of the element in the array.

Param value:

64-bit integer value that will be stored to the supplied path and index.

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. This must not be nullptr. 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.

Param arrayBufferLength:

Maximum number of values that can fit in arrayOut.

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. This must not be nullptr.

Param arrayLength:

The number of items in the array.

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. This must not be nullptr. 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.

Param arrayBufferLength:

Maximum number of values that can fit in arrayOut.

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. This must not be nullptr.

Param arrayLength:

The number of items in the array.

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. The default value of (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.

Param index:

Zero based index of the element to retrieve in the array.

Return:

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.

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:

Zero based index of the element in array.

Param value:

The new double value that will be stored to the supplied path and index.

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. This must not be nullptr. 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.

Param arrayBufferLength:

Maximum number of values that can fit in arrayOut.

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. This must not be nullptr.

Param arrayLength:

The number of items in the array.

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. This must not be nullptr.

Param arrayBufferLength:

Maximum number of values that can fit in arrayOut.

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. This must not be nullptr.

Param arrayLength:

The number of items in the array.

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. The default value of (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.

Param index:

Zero based index of the element to retrieve in the array.

Return:

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.

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:

Zero based index of the element in array.

Param value:

The new boolean value that will be stored to the supplied path and index.

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 floating point values. This must not be nullptr. 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.

Param arrayBufferLength:

Maximum number of values that can fit in arrayOut.

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. This must not be nullptr.

Param arrayLength:

The number of items in the array.

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. This must not be nullptr.

Param 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). The default value of size_t(-1) treats value as a NUL-terminated string.

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

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.

See also

carb::dictionary::IDictionary::setStringArray().

Param path:

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

Param array:

String array to copy values from. This must not be nullptr. Each value in this array will be set as a child value under the dictionary item at path. None of the entries in this array may be nullptr.

Param arrayLength:

The total number of string values in array.

Transaction *(*createTransaction)()#

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

Return:

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

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 otherwise undefined behavior will occur.

Param transaction:

The Transaction pointer to destroy. This must not be nullptr.

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

Param transaction:

The Transaction to commit. This may not be nullptr.

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. Values can be overwritten in the transaction however.

Param transaction:

The Transaction previously created with createTransaction().

Param path:

Settings database key path (i.e. “/log/level”). This must not be nullptr. The settings database is not modified until commitTransaction() is called with the same transaction object.

Param value:

The new 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. Values can be overwritten in the transaction however.

Param transaction:

The Transaction previously created with createTransaction().

Param path:

Settings database key path (i.e. “/log/level”). This must not be nullptr. The settings database is not modified until commitTransaction() is called with the same transaction object.

Param value:

The new 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. Values can be overwritten in the transaction however.

Param transaction:

The Transaction previously created with createTransaction().

Param path:

Settings database key path (i.e. “/log/level”). This must not be nullptr. The settings database is not modified until commitTransaction() is called with the same transaction object.

Param value:

The new 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. Values can be overwritten in the transaction however.

Param transaction:

The Transaction previously created with createTransaction().

Param path:

Settings database key path (i.e. “/log/level”). This must not be nullptr. The settings database is not modified until commitTransaction() is called with the same transaction object.

Param value:

The new 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 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 unsubscribeToChangeEvents() to dispose of the subscription ID and ensure the callback function will never be called again for this item.

See also

carb::dictionary::IDictionary::subscribeToNodeChangeEvents().

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

Param onChangeEventFn:

The callback function to call when a change event occurs on the specified item path. This must not be nullptr.

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

Return:

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

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

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 unsubscribeToChangeEvents() to dispose of the subscription ID and ensure the callback function will never be called again for changes related to this subscription.

See also

carb::dictionary::IDictionary::subscribeToTreeChangeEvents().

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

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

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

Return:

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

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.

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.

Param subscriptionId:

The subscription handle from subscribeToNodeChangeEvents() or subscribeToTreeChangeEvents() to be unsubscribed from.

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

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.

See also

carb::dictionary::IDictionary::update(), carb::dictionary::OnUpdateItemFn().

Param path:

Settings database key path (i.e. “/log/level”). This must not be nullptr. 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.

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

Param dictionaryPath:

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

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

Param userData:

Opaque user data pointer that will be passed into the onUpdateItemFn callback function.

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”). This must not be nullptr. The dictionary item at this specified path in the settings database will be returned. “” or “/” 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.

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.

Param path:

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

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

void (*destroyStringBuffer)(const char *stringBuffer)#

Frees a string buffer returned from one of the createStringBufferFrom*() functions.

The string buffers are returned by createStringBufferFromItemValue() or createStringBufferFromItemValueAt(). When these strings are no longer needed, they must be destroyed using this function.

See also

carb::dictionary::IDictionary::destroyStringBuffer

Param stringBuffer:

The 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. This may not be nullptr.

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.