| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| |
| /** |
| * @file celix_properties.h |
| * @brief Header file for the Celix Properties API. |
| * |
| * The Celix Properties API provides a means for storing and manipulating key-value pairs, called properties, |
| * which can be used to store configuration data or metadata for a service, component, or framework configuration. |
| * Functions are provided for creating and destroying property sets, loading and storing properties from/to a file |
| * or stream, and setting, getting, and unsetting individual properties. There are also functions for converting |
| * property values to various types (e.g. long, bool, double) and for iterating over the properties in a set. |
| * |
| * Supported property value types include: |
| * - string (char*) |
| * - long |
| * - double |
| * - bool |
| * - celix_version_t* |
| */ |
| |
| #ifndef CELIX_PROPERTIES_H_ |
| #define CELIX_PROPERTIES_H_ |
| |
| #include <stdio.h> |
| |
| #include "celix_properties_type.h" |
| #include "celix_cleanup.h" |
| #include "celix_compiler.h" |
| #include "celix_errno.h" |
| #include "celix_utils_export.h" |
| #include "celix_version.h" |
| #include "celix_array_list.h" |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /** |
| * @brief Enum representing the possible types of a property value. |
| */ |
| typedef enum celix_properties_value_type { |
| CELIX_PROPERTIES_VALUE_TYPE_UNSET = 0, /**< Property value is not set. */ |
| CELIX_PROPERTIES_VALUE_TYPE_STRING = 1, /**< Property value is a UTF-8 encoded string. */ |
| CELIX_PROPERTIES_VALUE_TYPE_LONG = 2, /**< Property value is a long integer. */ |
| CELIX_PROPERTIES_VALUE_TYPE_DOUBLE = 3, /**< Property value is a double. */ |
| CELIX_PROPERTIES_VALUE_TYPE_BOOL = 4, /**< Property value is a boolean. */ |
| CELIX_PROPERTIES_VALUE_TYPE_VERSION = 5, /**< Property value is a Celix version. */ |
| CELIX_PROPERTIES_VALUE_TYPE_ARRAY_LIST = |
| 6, /**< Property value is an array list. The element type of the array list can be |
| CELIX_ARRAY_LIST_ELEMENT_TYPE_STRING, CELIX_ARRAY_LIST_ELEMENT_TYPE_LONG, |
| CELIX_ARRAY_LIST_ELEMENT_TYPE_DOUBLE, CELIX_ARRAY_LIST_ELEMENT_TYPE_BOOL or |
| CELIX_ARRAY_LIST_ELEMENT_TYPE_VERSION. */ |
| } celix_properties_value_type_e; |
| |
| /** |
| * @brief A structure representing a single value entry in a property set. |
| */ |
| typedef struct celix_properties_entry { |
| const char* value; /**< The string value or string representation of a non-string |
| typed value.*/ |
| celix_properties_value_type_e valueType; /**< The type of the value of the entry */ |
| |
| union { |
| const char* strValue; /**< The string value of the entry. */ |
| long longValue; /**< The long integer value of the entry. */ |
| double doubleValue; /**< The double-precision floating point value of the entry. */ |
| bool boolValue; /**< The boolean value of the entry. */ |
| const celix_version_t* versionValue; /**< The Celix version value of the entry. */ |
| const celix_array_list_t* |
| arrayValue; /**< The array list of longs, doubles, bools, strings or versions value of the entry. */ |
| } typed; /**< The typed values of the entry. Only valid if valueType |
| is not CELIX_PROPERTIES_VALUE_TYPE_UNSET and only the matching |
| value types should be used. E.g typed.boolValue if valueType is |
| CELIX_PROPERTIES_VALUE_TYPE_BOOL. */ |
| } celix_properties_entry_t; |
| |
| /** |
| * @brief Represents an iterator for iterating over the entries in a celix_properties_t object. |
| */ |
| typedef struct celix_properties_iterator { |
| /** |
| * @brief The current key. |
| */ |
| const char* key; |
| |
| /** |
| * @brief The current value entry. |
| */ |
| celix_properties_entry_t entry; |
| |
| /** |
| * @brief Private data used to implement the iterator. |
| */ |
| char _data[56]; |
| } celix_properties_iterator_t; |
| |
| /** |
| * @brief Create a new empty property set. |
| * |
| * If the return status is an error, an error message is logged to celix_err. |
| * |
| * @return A new empty property set. |
| */ |
| CELIX_UTILS_EXPORT celix_properties_t* celix_properties_create(); |
| |
| /** |
| * @brief Destroy a property set, freeing all associated resources. |
| * |
| * @param[in] properties The property set to destroy. If properties is NULL, this function will do nothing. |
| */ |
| CELIX_UTILS_EXPORT void celix_properties_destroy(celix_properties_t* properties); |
| |
| CELIX_DEFINE_AUTOPTR_CLEANUP_FUNC(celix_properties_t, celix_properties_destroy) |
| |
| /** |
| * @brief Get the entry for a given key in a property set. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key to search for. |
| * @return The entry for the given key, or a NULL if the key is not found. |
| */ |
| CELIX_UTILS_EXPORT const celix_properties_entry_t* celix_properties_getEntry(const celix_properties_t* properties, |
| const char* key); |
| |
| /** |
| * @brief Get the string value or string representation of a property. |
| * |
| * @note identical to celix_properties_getAsString |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @param[in] defaultValue The value to return if the property is not set. |
| * @return The value of the property, or the default value if the property is not set. |
| */ |
| CELIX_UTILS_EXPORT const char* |
| celix_properties_get(const celix_properties_t* properties, const char* key, const char* defaultValue); |
| |
| /** |
| * @brief Get the type of a property value. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get the type of. |
| * @return The type of the property value, or CELIX_PROPERTIES_VALUE_TYPE_UNSET if the property is not set. |
| */ |
| CELIX_UTILS_EXPORT celix_properties_value_type_e celix_properties_getType(const celix_properties_t* properties, |
| const char* key); |
| |
| /** |
| * @brief Check if the properties set has the provided key. |
| * @param[in] properties The property set to search. |
| * @param[in] key The key to search for. |
| * @return True if the property set has the provided key, false otherwise. |
| */ |
| CELIX_UTILS_EXPORT bool celix_properties_hasKey(const celix_properties_t* properties, const char* key); |
| |
| /** |
| * @brief Set the string value of a property. |
| * |
| * @note Identical to celix_properties_setString. |
| * |
| * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_STRING. |
| * |
| * If the return status is an error, an error message is logged to celix_err. |
| * |
| * @param[in] properties The property set to modify. |
| * @param[in] key The key of the property to set. |
| * @param[in] value The value to set the property to. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if there was not enough memory to set the entry |
| * and CELIX_ILLEGAL_ARGUMENT if the provided key is NULL. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_set(celix_properties_t* properties, |
| const char* key, |
| const char* value); |
| |
| /** |
| * @brief Set the value of a property without copying the value string. |
| * |
| * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_STRING. |
| * |
| * If the return status is an error, an error message is logged to celix_err. |
| * |
| * @param[in] properties The property set to modify. |
| * @param[in] key The key of the property to set. This callee will take ownership of the key, so the key must not be |
| * used after calling this function. The key should be deallocated with free. |
| * @param[in] value The value to set the property to. This callee will take ownership of the value, so the value must |
| * not be used after calling this function. The value should be deallocated with free. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if there was not enough memory to set the entry |
| * and CELIX_ILLEGAL_ARGUMENT if the provided key or value is NULL. |
| * When an error status is returned, the key and value will be freed by this function. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_assign(celix_properties_t* properties, |
| char* key, |
| char* value); |
| |
| /** |
| * @brief Get the value of a property, if the property is set and the underlying type is a string. |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @return The value of the property, or NULL if the property is not set or the value is not of the requested type. |
| */ |
| CELIX_UTILS_EXPORT const char* |
| celix_properties_getString(const celix_properties_t* properties, const char* key); |
| |
| /** |
| * @brief Get the string value or string representation of a property. |
| * |
| * @note identical to celix_properties_get |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @param[in] defaultValue The value to return if the property is not set. |
| * @return The value of the property, or the default value if the property is not set. |
| */ |
| CELIX_UTILS_EXPORT const char* |
| celix_properties_getAsString(const celix_properties_t* properties, const char* key, const char* defaultValue); |
| |
| /** |
| * @brief Set the string value of a property. |
| * |
| * @note Identical to celix_properties_set. |
| * |
| * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_STRING. |
| * |
| * If the return status is an error, an error message is logged to celix_err. |
| * |
| * @param[in] properties The property set to modify. |
| * @param[in] key The key of the property to set. |
| * @param[in] value The value to set the property to. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if there was not enough memory to set the entry |
| * and CELIX_ILLEGAL_ARGUMENT if the provided key is NULL. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_setString(celix_properties_t* properties, |
| const char* key, |
| const char* value); |
| |
| /** |
| * @brief Assign the value of a property with the provided string pointer. |
| * |
| * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_STRING. |
| * |
| * This function take ownership of the provided string. |
| * If the return status is an error, an error message is logged to celix_err. |
| * |
| * @param[in] properties The property set to modify. |
| * @param[in] key The key of the property to set. |
| * @param[in] value The value to assign. The function take ownership of the provided version. Cannot be NULL. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if there was not enough memory to set the entry |
| * and CELIX_ILLEGAL_ARGUMENT if the provided key is NULL. When an error status is returned, |
| * the string will be free by this function. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_assignString(celix_properties_t* properties, |
| const char* key, |
| char* value); |
| |
| /** |
| * @brief Get the value of a property, if the property is set and the underlying type is a long. |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @param[in] defaultValue The value to return if the property is not set or the value is not a long. |
| * @return The value of the property, or the default value if the property is not set or the value is not of the |
| * requested type. |
| */ |
| CELIX_UTILS_EXPORT long |
| celix_properties_getLong(const celix_properties_t* properties, const char* key, long defaultValue); |
| |
| /** |
| * @brief Get the value of a property as a long integer. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @param[in] defaultValue The value to return if the property is not set, the value is not a long integer, |
| * or if the value cannot be converted to a long integer. |
| * @return The value of the property as a long integer, or the default value if the property is not set, |
| * the value is not a long integer, or if the value cannot be converted to a long integer. |
| * If the value is a string, it will be converted to a long integer if possible. |
| */ |
| CELIX_UTILS_EXPORT long |
| celix_properties_getAsLong(const celix_properties_t* properties, const char* key, long defaultValue); |
| |
| /** |
| * @brief Set the value of a property to a long integer. |
| * |
| * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_LONG. |
| * |
| * If the return status is an error, an error message is logged to celix_err. |
| * |
| * @param[in] properties The property set to modify. |
| * @param[in] key The key of the property to set. |
| * @param[in] value The long value to set the property to. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if there was not enough memory to set the entry |
| * and CELIX_ILLEGAL_ARGUMENT if the provided key is NULL. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_setLong(celix_properties_t* properties, const char* key, long value); |
| |
| /** |
| * @brief Get the value of a property, if the property is set and the underlying type is a boolean. |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @param[in] defaultValue The value to return if the property is not set or the value is not a boolean. |
| * @return The value of the property, or the default value if the property is not set or the value is not of the |
| * requested type. |
| */ |
| CELIX_UTILS_EXPORT bool |
| celix_properties_getBool(const celix_properties_t* properties, const char* key, bool defaultValue); |
| |
| /** |
| * @brief Get the value of a property as a boolean. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @param[in] defaultValue The value to return if the property is not set, the value is not a boolean, or if the value |
| * cannot be converted to a boolean. |
| * @return The value of the property as a boolean, or the default value if the property is not set, the value is not a |
| * boolean, or if the value cannot be converted to a boolean. If the value is a string, it will be converted |
| * to a boolean if possible. |
| */ |
| CELIX_UTILS_EXPORT bool |
| celix_properties_getAsBool(const celix_properties_t* properties, const char* key, bool defaultValue); |
| |
| /** |
| * @brief Set the value of a property to a boolean. |
| * |
| * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_BOOL. |
| * |
| * If the return status is an error, an error message is logged to celix_err. |
| * |
| * @param[in] properties The property set to modify. |
| * @param[in] key The key of the property to set. |
| * @param[in] val The boolean value to set the property to. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if there was not enough memory to set the entry |
| * and CELIX_ILLEGAL_ARGUMENT if the provided key is NULL. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_setBool(celix_properties_t* properties, const char* key, bool val); |
| |
| /** |
| * @brief Set the value of a property to a double. |
| * |
| * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_DOUBLE. |
| * |
| * If the return status is an error, an error message is logged to celix_err. |
| * |
| * @param[in] properties The property set to modify. |
| * @param[in] key The key of the property to set. |
| * @param[in] val The double value to set the property to. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if there was not enough memory to set the entry |
| * and CELIX_ILLEGAL_ARGUMENT if the provided key is NULL. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_setDouble(celix_properties_t* properties, |
| const char* key, |
| double val); |
| |
| /** |
| * @brief Get the value of a property, if the property is set and the underlying type is a double. |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @param[in] defaultValue The value to return if the property is not set or the value is not a double. |
| * @return The value of the property, or the default value if the property is not set or the value is not of the |
| * requested type. |
| */ |
| CELIX_UTILS_EXPORT double |
| celix_properties_getDouble(const celix_properties_t* properties, const char* key, double defaultValue); |
| |
| /** |
| * @brief Get the value of a property as a double. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @param[in] defaultValue The value to return if the property is not set, the value is not a double, |
| * or if the value cannot be converted to a double. |
| * @return The value of the property as a double, or the default value if the property is not set, the value is not |
| * a double, or if the value cannot be converted to a double. If the value is a string, it will be converted |
| * to a double if possible. |
| */ |
| CELIX_UTILS_EXPORT double |
| celix_properties_getAsDouble(const celix_properties_t* properties, const char* key, double defaultValue); |
| |
| /** |
| * @brief Set the value of a property as a Celix version. |
| * |
| * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_VERSION. |
| * |
| * This function will make a copy of the provided celix_version_t object and store it in the property set. |
| * If the return status is an error, an error message is logged to celix_err. |
| * |
| * @param[in] properties The property set to modify. |
| * @param[in] key The key of the property to set. |
| * @param[in] version The value to set. The function will make a copy of this object and store it in the property set. |
| * Cannot be NULL. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if there was not enough memory to set the entry |
| * and CELIX_ILLEGAL_ARGUMENT if the provided key is NULL. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_setVersion(celix_properties_t* properties, |
| const char* key, |
| const celix_version_t* version); |
| |
| /** |
| * @brief Assign the value of a property with the provided Celix version pointer. |
| * |
| * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_VERSION. |
| * |
| * This function will store a reference to the provided celix_version_t object in the property set and takes |
| * ownership of the provided version. |
| * If the return status is an error, an error message is logged to celix_err. |
| * |
| * @param[in] properties The property set to modify. |
| * @param[in] key The key of the property to set. |
| * @param[in] version The value to assign. The function will store a reference to this object in the property set and |
| * takes ownership of the provided version. Cannot be NULL. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if there was not enough memory to set the entry |
| * and CELIX_ILLEGAL_ARGUMENT if the provided key is NULL. When an error status is returned, |
| * the version will be destroy with celix_version_destroy by this function. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_assignVersion(celix_properties_t* properties, |
| const char* key, |
| celix_version_t* version); |
| |
| /** |
| * @brief Get the Celix version value of a property without copying. |
| * |
| * This function provides a non-owning, read-only access to a Celix version contained in the properties. |
| * It returns a const pointer to the Celix version value associated with the specified key. |
| * This function does not perform any conversion from a string property value to a Celix version. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @return A const pointer to the Celix version if it is present and valid, or NULL if the |
| * property is not set or the value is not a valid Celix version. The returned pointer should not be modified or freed. |
| */ |
| CELIX_UTILS_EXPORT const celix_version_t* celix_properties_getVersion(const celix_properties_t* properties, |
| const char* key); |
| |
| /** |
| * @brief Get a value of a property as a copied Celix version. |
| * |
| * If the property value is a Celix version, a copy of the found version will be returned. |
| * If the property value is present, but not a Celix version, this function will attempt to convert the property value |
| * to a new Celix version. |
| * If the property is not set or is not a valid Celix version string, a copy of the provided defaultValue is returned. |
| * |
| * @note The caller is responsible for deallocating the memory of the returned version. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @param[in] defaultValue The value to return if the property is not set or if the value is not a Celix version. |
| * @param[out] version A copy of the found version, a new parsed version, or a copy of the default value if the |
| * property is not set, its value is not an version or its value cannot be converted to an version. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if there was not enough memory to create the |
| * version. Note if the key is not found, the return status is still CELIX_SUCCESS. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_getAsVersion(const celix_properties_t* properties, |
| const char* key, |
| const celix_version_t* defaultValue, |
| celix_version_t** version); |
| |
| /** |
| * @brief Set a pointer, long, double, bool, string or version array list array for a property value. |
| * |
| * The set property type cannot be CELIX_ARRAY_LIST_ELEMENT_TYPE_UNDEFINED or CELIX_ARRAY_LIST_ELEMENT_TYPE_POINTER |
| * |
| * This function will make a copy of the provided celix_array_list_t object, using the celix_arrayList_copy function. |
| * |
| * If an error occurs, the error status is returned and a message is logged to celix_err. |
| * |
| * @param[in] properties The property set to modify. |
| * @param[in] key The key of the property to set. |
| * @param[in] values An array list of types values to set for the property. Cannot be NULL. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if there was not enough memory to set the entry, |
| * and CELIX_ILLEGAL_ARGUMENT if the provided key or values is NULL or if the array list type is |
| * valid. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_setArrayList(celix_properties_t* properties, |
| const char* key, |
| const celix_array_list_t* values); |
| |
| /** |
| * @brief Assign a pointer, long, double, bool, string or version array list array for a property value. |
| * |
| * The set property type cannot be CELIX_ARRAY_LIST_ELEMENT_TYPE_UNDEFINED or CELIX_ARRAY_LIST_ELEMENT_TYPE_POINTER |
| * |
| * This function stores a reference to the provided celix_array_list_t object in the property set and takes |
| * ownership of the array. |
| * If an error occurs, the error status is returned, the provided array is destroyed and a |
| * message is logged to celix_err. |
| * |
| * @param[in] properties The property set to modify. |
| * @param[in] key The key of the property to set. |
| * @param[in] values An array list of long values to assign to the property. Ownership of the array is transferred |
| * to the properties set. Cannot be NULL. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if there was not enough memory to set the entry, |
| * and CELIX_ILLEGAL_ARGUMENT if the provided key is NULL, values is NULL or the array list type is |
| * invalid. On error, the provided array list is destroyed. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_assignArrayList(celix_properties_t* properties, |
| const char* key, |
| celix_array_list_t* values); |
| |
| /** |
| * @brief Get the property value as an array without copying. |
| * |
| * This function provides a non-owning, read-only access to a array property value. |
| * It returns a const pointer to the array. If the property is not set or its value is not an array, NULL is returned. |
| * |
| * The returned array will have a element type of: |
| * - CELIX_ARRAY_LIST_ELEMENT_TYPE_STRING |
| * - CELIX_ARRAY_LIST_ELEMENT_TYPE_LONG |
| * - CELIX_ARRAY_LIST_ELEMENT_TYPE_DOUBLE |
| * - CELIX_ARRAY_LIST_ELEMENT_TYPE_BOOL |
| * - CELIX_ARRAY_LIST_ELEMENT_TYPE_VERSION |
| * |
| * Note that users should check the element type of the returned array list to determine the type of the elements. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @return A const pointer to the array list property value, or NULL if the property is not set or its value is not |
| * an array list. The returned pointer should not be modified or freed. |
| */ |
| CELIX_UTILS_EXPORT const celix_array_list_t* celix_properties_getArrayList(const celix_properties_t* properties, |
| const char* key); |
| |
| /** |
| * @brief Get a property value as an array of longs. |
| * |
| * This function retrieves the value of a property, interpreting it as an array of longs. If the underlying type of the |
| * property value is a long array, a copy of the array is returned. If the underlying type is a string, the string is |
| * converted to an array of longs if possible. |
| * If the property is not set, its value is not an array of longs or its value cannot be converted to a long array, |
| * the default value is returned as a copy. |
| * |
| * An celix err is logged if the default value is needed and not an array list with long values. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @param[in] defaultValue The default value to return if the property is not set or its value is not an array of longs. |
| * @param[out] list A copy of the found list, a new array list with long values or a copy of the default value if the |
| * property is not set, its value is not an array of longs or its value cannot be converted to an array |
| * of longs. |
| * @return CELIX_SUCCESS if the operation was successful. Note if the key is not found or the value cannot be converted |
| * to an array of longs, the return status is still CELIX_SUCCESS. |
| * @returnval CELIX_ENOMEM if there was not enough memory to create the array list. |
| * @returnval CELIX_ILLEGAL_ARGUMENT if the provided default value is not NULL and not an array list with long values. |
| * In this case an error message is also logged to celix_err. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_getAsLongArrayList(const celix_properties_t* properties, |
| const char* key, |
| const celix_array_list_t* defaultValue, |
| celix_array_list_t** list); |
| |
| /** |
| * @brief Get the property value as an array of longs without copying. |
| * |
| * This function provides a non-owning, read-only access to an array of longs property value. |
| * It returns a const pointer to the array. If the property is not set or its value is not an array of longs, |
| * NULL is returned. |
| * |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @return A const pointer to the property value interpreted as an array of longs, or NULL if the property |
| * is not set or its value is not an array of longs. The returned pointer should not be modified or freed. |
| */ |
| CELIX_UTILS_EXPORT const celix_array_list_t* celix_properties_getLongArrayList(const celix_properties_t* properties, |
| const char* key); |
| |
| /** |
| * @brief Get a property value as an array of doubles, making a copy of the array. |
| * |
| * This function retrieves the value of a property, interpreting it as an array of doubles. If the underlying type of |
| * the property value is a double array, a copy of the array is returned. If the underlying type is a string, the string |
| * is converted to an array of doubles if possible. If the property is not set, its value is not an array of doubles or |
| * its value cannot be converted to a double array, the default value is returned as a copy. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @param[in] defaultValue The default value to return if the property is not set or its value is not an array of |
| * doubles. |
| * @param[out] list A copy of the found list, a new array list with double values or a copy of the default value if the |
| * property is not set, its value is not an array doubles longs or its value cannot be converted to an |
| * array of doubles. |
| * @return CELIX_SUCCESS if the operation was successful. Note if the key is not found or the value cannot be converted |
| * to an array of doubles, the return status is still CELIX_SUCCESS. |
| * @returnval CELIX_ENOMEM if there was not enough memory to create the array list. |
| * @returnval CELIX_ILLEGAL_ARGUMENT if the provided default value is not NULL and not an array list with double values. |
| * In this case an error message is also logged to celix_err. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_getAsDoubleArrayList(const celix_properties_t* properties, |
| const char* key, |
| const celix_array_list_t* defaultValue, |
| celix_array_list_t** list); |
| |
| /** |
| * @brief Get the property value as an array of doubles without copying. |
| * |
| * This function provides a non-owning, read-only access to an array of doubles property value. |
| * It returns a const pointer to the array. If the property is not set or its value is not an array of doubles, |
| * NULL is returned. |
| * |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @return A const pointer to the property value interpreted as an array of doubles, or NULL if the |
| * property is not set or its value is not an array of doubles. The returned pointer should not be modified or freed. |
| */ |
| CELIX_UTILS_EXPORT const celix_array_list_t* celix_properties_getDoubleArrayList(const celix_properties_t* properties, |
| const char* key); |
| |
| /** |
| * @brief Get a property value as an array of booleans, making a copy of the array. |
| * |
| * This function retrieves the value of a property, interpreting it as an array of booleans. If the underlying type of |
| * the property value is a boolean array, a copy of the array is returned. If the underlying type is a string, the |
| * string is converted to an array of booleans if possible. If the property is not set, its value is not an array of |
| * booleans or its value cannot be converted to a boolean array, the default value is returned as a copy. |
| * |
| * An celix err is logged if the default value is needed and not an array list with boolean values. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @param[in] defaultValue The default value to return if the property is not set or its value is not an array of |
| * booleans. |
| * @param[out] list A copy of the found list, a new array list with boolean values or a copy of the default value if the |
| * property is not set, its value is not an array of booleans or its value cannot be converted to an |
| * array of booleans. |
| * @return CELIX_SUCCESS if the operation was successful. Note if the key is not found or the value cannot be converted |
| * to an array of booleans, the return status is still CELIX_SUCCESS. |
| * @returnval CELIX_ENOMEM if there was not enough memory to create the array list. |
| * @returnval CELIX_ILLEGAL_ARGUMENT if the provided default value is not NULL and not an array list with bool values. |
| * In this case an error message is also logged to celix_err. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_getAsBoolArrayList(const celix_properties_t* properties, |
| const char* key, |
| const celix_array_list_t* defaultValue, |
| celix_array_list_t** list); |
| |
| /** |
| * @brief Get the property value as an array of booleans without copying. |
| * |
| * This function provides a non-owning, read-only access to a array of booleans property value. |
| * It returns a const pointer to the array. If the property is not set or its value is not an array of booleans, |
| * NULL is returned. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @return A const pointer to the property value interpreted as an array of booleans, or NULL if the |
| * property is not set or its value is not an array of booleans. The returned pointer should not be modified or freed. |
| */ |
| CELIX_UTILS_EXPORT const celix_array_list_t* celix_properties_getBoolArrayList(const celix_properties_t* properties, |
| const char* key); |
| |
| /** |
| * @brief Get a property value as an array of strings, making a copy of the array. |
| * |
| * This function retrieves the value of a property, interpreting it as an array of strings. If the underlying type of |
| * the property value is a string array, a copy of the array is returned. If the underlying type is a string, the string |
| * is converted to an array of strings if possible. If the property is not set, its value is not an array of strings or |
| * its value cannot be converted to a string array, the default value is returned as a copy. |
| * |
| * The returned array list is configured with a remove callback so that the destruction of the array list will also |
| * free the strings in the array list. |
| * |
| * An celix err is logged if the default value is needed and not an array list with string values. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @param[in] defaultValue The default value to return if the property is not set or its value is not an array of |
| * strings. |
| * @param[out] list A copy of the found list, a new array list with string values or a copy of the default value if the |
| * property is not set, its value is not an array of strings or its value cannot be converted to an |
| * array of strings. |
| * @return CELIX_SUCCESS if the operation was successful. Note if the key is not found or the value cannot be converted |
| * to an array of strings, the return status is still CELIX_SUCCESS. |
| * @returnval CELIX_ENOMEM if there was not enough memory to create the array list. |
| * @returnval CELIX_ILLEGAL_ARGUMENT if the provided default value is not NULL and not an array list with string values. |
| * In this case an error message is also logged to celix_err. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_getAsStringArrayList(const celix_properties_t* properties, |
| const char* key, |
| const celix_array_list_t* defaultValue, |
| celix_array_list_t** list); |
| |
| /** |
| * @brief Get the property value as an array of strings without copying. |
| * |
| * This function provides a non-owning, read-only access to an array of string property value. |
| * It returns a const pointer to the array. If the property is not set or its value is not an array of strings, |
| * NULL is returned. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @return A const pointer to the property value interpreted as an array of strings, or NULL if the |
| * property is not set or its value is not an array of strings. The returned pointer should not be modified or freed. |
| */ |
| CELIX_UTILS_EXPORT const celix_array_list_t* celix_properties_getStringArrayList(const celix_properties_t* properties, |
| const char* key); |
| |
| /** |
| * @brief Get a property value as an array of celix_version_t entries, making a copy of the array. |
| * |
| * |
| * This function retrieves the value of a property, interpreting it as an array of celix_version_t* entries. If the |
| * underlying type of the property value is a celix_version_t* array, a copy of the array is returned. If the underlying |
| * type is a string, the string is converted to an array of celix_version_t* if possible. If the property is not set, |
| * its value is not an array of celix_version_t* entries or its value cannot be converted to a celix_version_t* array, |
| * the default value is returned as a copy. |
| * |
| * The returned array list is configured with a remove callback so that the destruction of the array list will also |
| * free the celix_version_t entries in the array list. |
| * |
| * An celix err is logged if the default value is needed and not an array list with celix_version_t values. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @param[in] defaultValue The default value to return if the property is not set or its value is not an array of |
| * celix_version_t entries. |
| * @param[out] list A copy of the found list, a new array list with celix_version_t values or a copy of the default |
| * value if the property is not set, its value is not an array of celix_version_t entries or its value cannot be |
| * converted to an array of celix_version_t entries. |
| * @return CELIX_SUCCESS if the operation was successful. Note if the key is not found or the value cannot be converted |
| * to an array of celix_version_t, the return status is still CELIX_SUCCESS. |
| * @returnval CELIX_ENOMEM if there was not enough memory to create the array list. |
| * @returnval CELIX_ILLEGAL_ARGUMENT if the provided default value is not NULL and not an array list with |
| * celix_version_t values. In this case an error message is also logged to celix_err. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_getAsVersionArrayList(const celix_properties_t* properties, |
| const char* key, |
| const celix_array_list_t* defaultValue, |
| celix_array_list_t** list); |
| |
| /** |
| * @brief Get the property value as an array of celix_version_t entries without copying. |
| * |
| * This function provides a non-owning, read-only access to an array of celix_version_t property value. |
| * entries. It returns a const pointer to the array. If the property is not set or its value is not an array of |
| * celix_version_t entries, NULL is returned. |
| * |
| * @param[in] properties The property set to search. |
| * @param[in] key The key of the property to get. |
| * @return A const pointer to the property value interpreted as an array of celix_version_t entries, or NULL if the |
| * property is not set or its value is not an array of celix_version_t entries. The returned pointer should |
| * not be modified or freed. |
| */ |
| CELIX_UTILS_EXPORT const celix_array_list_t* celix_properties_getVersionArrayList(const celix_properties_t* properties, |
| const char* key); |
| |
| /** |
| * @brief Set the value of a property based on the provided property entry, maintaining underlying type. |
| * |
| * The typed entry value will be copied, which means that this function will use the entry.typed.strValue, |
| * entry.typed.longValue, entry.typed.doubleValue, entry.typed.boolValue or entry.typed.versionValue depending on |
| * the entry.valueType. The entry.strValue will be ignored. |
| * |
| * If the return status is an error, an error message is logged to celix_err. |
| * |
| * @param[in] properties The property set to modify. |
| * @param[in] key The key of the property to set. |
| * @param[in] entry The entry to set the property to. The typed entry will be copied, so it can be freed after calling |
| * this function. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if there was not enough memory to set the entry |
| * and CELIX_ILLEGAL_ARGUMENT if the provided key is NULL. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_setEntry(celix_properties_t* properties, |
| const char* key, |
| const celix_properties_entry_t* entry); |
| |
| /** |
| * @brief Unset a property, removing it from the property set. |
| * |
| * @param[in] properties The property set to modify. |
| * @param[in] key The key of the property to unset. |
| */ |
| CELIX_UTILS_EXPORT void celix_properties_unset(celix_properties_t* properties, const char* key); |
| |
| /** |
| * @brief Make a copy of a properties set. |
| * |
| * If the return status is an error, an error message is logged to celix_err. |
| * |
| * @param[in] properties The property set to copy. |
| * @return A copy of the given property set. |
| */ |
| CELIX_UTILS_EXPORT celix_properties_t* celix_properties_copy(const celix_properties_t* properties); |
| |
| /** |
| * @brief Get the number of properties in a property set. |
| * |
| * @param[in] properties The property set to get the size of. |
| * @return The number of properties in the property set. |
| */ |
| CELIX_UTILS_EXPORT size_t celix_properties_size(const celix_properties_t* properties); |
| |
| /** |
| * @brief Check whether the provided property sets are equal. |
| * |
| * Equals means that both property sets have the same number of properties and that all properties in the first set |
| * are also present in the second set and have the same value. |
| * |
| * @param[in] props1 The first property set to compare. |
| * @param[in] props2 The second property set to compare. |
| * @return true if the property sets are equal, false otherwise. |
| */ |
| CELIX_UTILS_EXPORT bool celix_properties_equals(const celix_properties_t* props1, const celix_properties_t* props2); |
| |
| /** |
| * @brief Construct an iterator pointing to the first entry in the properties object. |
| * |
| * @param[in] properties The properties object to iterate over. |
| * @return The iterator pointing to the first entry in the properties object. |
| */ |
| CELIX_UTILS_EXPORT celix_properties_iterator_t celix_properties_begin(const celix_properties_t* properties); |
| |
| /** |
| * @brief Construct an iterator pointing to the past-the-end entry in the properties object. |
| * |
| * This iterator is used to mark the end of the properties object and is not associated with any element in the |
| * properties object. |
| * |
| * @param[in] properties The properties object to iterate over. |
| * @return The iterator pointing to the past-the-end entry in the properties object. |
| */ |
| CELIX_UTILS_EXPORT celix_properties_iterator_t celix_properties_end(const celix_properties_t* properties); |
| |
| /** |
| * @brief Advance the iterator to the next entry. |
| * |
| * @param[in, out] iter The iterator. |
| */ |
| CELIX_UTILS_EXPORT void celix_propertiesIterator_next(celix_properties_iterator_t* iter); |
| |
| /** |
| * @brief Determine whether the iterator is pointing to an end position. |
| * |
| * An iterator is at an end position if it has no more entries to visit. |
| * |
| * @param[in] iter The iterator. |
| * @return true if the iterator is at an end position, false otherwise. |
| */ |
| CELIX_UTILS_EXPORT bool celix_propertiesIterator_isEnd(const celix_properties_iterator_t* iter); |
| |
| /** |
| * @brief Determine whether two iterators are equal. |
| * |
| * @param[in] a The first iterator to compare. |
| * @param[in] b The second iterator to compare. |
| * @return true if the iterators are equal, false otherwise. |
| */ |
| CELIX_UTILS_EXPORT bool celix_propertiesIterator_equals(const celix_properties_iterator_t* a, |
| const celix_properties_iterator_t* b); |
| |
| /** |
| * @brief Iterate over the entries in the specified celix_properties_t object. |
| * |
| * This macro allows you to easily iterate over the entries in a celix_properties_t object. |
| * The loop variable `iterName` will be of type celix_properties_iterator_t and will contain the current |
| * entry during each iteration. |
| * |
| * @param[in] props The properties object to iterate over. |
| * @param[in] iterName The name of the iterator variable to use in the loop. |
| * |
| * Example usage: |
| * @code{.c} |
| * // Iterate over all entries in the properties object |
| * CELIX_PROPERTIES_ITERATE(properties, iter) { |
| * // Print the key and value of the current entry |
| * printf("%s: %s\n", iter.entry.key, iter.entry.value); |
| * } |
| * @endcode |
| */ |
| #define CELIX_PROPERTIES_ITERATE(props, iterName) \ |
| for (celix_properties_iterator_t iterName = celix_properties_begin((props)); \ |
| !celix_propertiesIterator_isEnd(&(iterName)); \ |
| celix_propertiesIterator_next(&(iterName))) |
| |
| /** |
| * @brief Flag to indicate that the encoded output should be pretty; e.g. encoded with additional whitespaces, |
| * newlines and indentation. |
| * |
| * If this flag is not set, the encoded output will compact; e.g. without additional whitespaces, newlines and |
| * indentation. |
| */ |
| #define CELIX_PROPERTIES_ENCODE_PRETTY 0x01 |
| |
| /** |
| * @brief Flag to indicate that the encoded output should be flat; e.g. all properties entries are written as top level |
| * field entries. |
| * |
| * E.g: |
| * @code{.c} |
| * celix_properties_t* properties = celix_properties_create(); |
| * celix_properties_setString(properties, "key/with/slash", "value1"); |
| * celix_properties_setString(properties, "key", "value2"); |
| * char* json; |
| * celix_properties_saveToString(properties, CELIX_PROPERTIES_ENCODE_FLAT, &json); |
| * // json will be: {"key/with/slash": "value1", "key": "value2"} |
| * @endcode |
| * |
| * Note that encoding with a flat encoding style, all properties keys are unique JSON keys and can be written. |
| * |
| * If no encoding style flag is set, the encoded output will use the default encoding style. |
| */ |
| #define CELIX_PROPERTIES_ENCODE_FLAT_STYLE 0x02 |
| |
| /** |
| * @brief Flag to indicate that the encoded output should be nested; e.g. properties entries are split on '/' and nested |
| * in JSON objects. |
| * |
| * E.g: |
| * @code{.c} |
| * celix_properties_t* properties = celix_properties_create(); |
| * celix_properties_setString(properties, "key/with/slash", "value1"); |
| * celix_properties_setString(properties, "key", "value2"); |
| * char* json; |
| * celix_properties_saveToString(properties, CELIX_PROPERTIES_ENCODE_NESTED, &json); |
| * // json will be: {"key":{"with":{"slash": "value1"}}} |
| * // or |
| * // json will be: {"key": "value2"} |
| * @endcode |
| * |
| * Note that encoding with a nested encoding style, it properties key can collide resulting in missing properties |
| * entries or (if CELIX_PROPERTIES_ENCODE_ERROR_ON_COLLISIONS is set) an error. |
| * |
| * If no encoding style flag is set, the encoded output will use the default encoding style. |
| */ |
| #define CELIX_PROPERTIES_ENCODE_NESTED_STYLE 0x04 |
| |
| /** |
| * @brief Flag to indicate that the encoding should fail if the JSON representation will contain colliding keys. |
| * |
| * Note that colliding keys can only occur when using the nested encoding style. |
| * |
| * E.g. the following will lead to an error: |
| * @code{.c} |
| * celix_properties_t* properties = celix_properties_create(); |
| * celix_properties_setString(properties, "key/with/slash", "value1"); |
| * celix_properties_setString(properties, "key", "value2"); //collision |
| * char* json; |
| * celix_status_t status = celix_properties_saveToString(properties, |
| * CELIX_PROPERTIES_ENCODE_NESTED | | CELIX_PROPERTIES_ENCODE_ERROR_ON_COLLISIONS, &json); |
| * // status will be CELIX_ILLEGAL_ARGUMENT and a error message will be logged to celix_err |
| * @endcode |
| * |
| * If this flag is set, the encoding will fail if the JSON representation will contain colliding keys and if this flag |
| * is not set, the encoding will not fail and the colliding keys will be ignored. |
| */ |
| #define CELIX_PROPERTIES_ENCODE_ERROR_ON_COLLISIONS 0x10 |
| |
| /** |
| * @brief Flag to indicate that the encoding should fail if the JSON representation will contain empty arrays. |
| * |
| * Although empty arrays are valid in JSON, they cannot be decoded to a valid properties array entry and as such |
| * empty arrays properties entries are not encoded. |
| * |
| * If this flag is set, the encoding will fail if the JSON representation will contain empty arrays and if this flag |
| * is not set, the encoding will not fail and the empty arrays will be ignored. |
| */ |
| #define CELIX_PROPERTIES_ENCODE_ERROR_ON_EMPTY_ARRAYS 0x20 |
| |
| /** |
| * @brief Flag to indicate that the encoding should fail if the JSON representation will contain NaN or Inf values. |
| * |
| * NaN, Inf and -Inf are not valid JSON values and as such properties entries with these values are not encoded. |
| * |
| * If this flag is set, the encoding will fail if the JSON representation will contain NaN or Inf values and if this |
| * flag is not set, the encoding will not fail and the NaN and Inf entries will be ignored. |
| */ |
| #define CELIX_PROPERTIES_ENCODE_ERROR_ON_NAN_INF 0x40 |
| |
| /** |
| * @brief Flag to indicate that all encode "error on" flags should be set. |
| */ |
| #define CELIX_PROPERTIES_ENCODE_STRICT \ |
| (CELIX_PROPERTIES_ENCODE_ERROR_ON_COLLISIONS | CELIX_PROPERTIES_ENCODE_ERROR_ON_EMPTY_ARRAYS | \ |
| CELIX_PROPERTIES_ENCODE_ERROR_ON_NAN_INF) |
| |
| /** |
| * @brief Save (encode) as a JSON representation to a stream. |
| * |
| * The stream is expected to be a valid stream and is not reset or closed by this function. |
| * |
| * Properties are encoded as a JSON object. |
| * |
| * If no encoding style flag is set or when the CELIX_PROPERTIES_ENCODE_FLAT_STYLE flag is set, properties |
| * entries are written as top level field entries. |
| * |
| * If the CELIX_PROPERTIES_ENCODE_NESTED_STYLE flag is set, properties entry keys are split on '/' and nested in |
| * JSON objects. This leads to a more natural JSON representation, but if there are colliding properties keys (e.g. |
| * `{"key": "value1", "key/with/slash": "value2"}`), not all properties entries will be written. |
| * |
| * With all encoding styles, the empty array properties entries are ignored, because they cannot be decoded to a valid |
| * properties array entry. |
| * |
| * Properties type entries are encoded as follows: |
| * - CELIX_PROPERTIES_TYPE_STRING: The value is encoded as a JSON string. |
| * - CELIX_PROPERTIES_TYPE_LONG: The value is encoded as a JSON number. |
| * - CELIX_PROPERTIES_TYPE_DOUBLE: The value is encoded as a JSON number. |
| * - CELIX_PROPERTIES_TYPE_BOOL: The value is encoded as a JSON boolean. |
| * - CELIX_PROPERTIES_TYPE_ARRAY: The value is encoded as a JSON array, with each element encoded according to its type. |
| * - CELIX_PROPERTIES_TYPE_VERSION: The value is encoded as a JSON string with a "version<" prefix and a ">" suffix |
| * (e.g. "version<1.2.3>"). |
| * |
| * For a overview of the possible encode flags, see the CELIX_PROPERTIES_ENCODE_* flags documentation. |
| * The default encoding style is a compact and flat JSON representation. |
| * |
| * @param properties The properties object to encode. |
| * @param stream The stream to write the JSON representation of the properties object to. |
| * @param encodeFlags The flags to use when encoding the input properties. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ILLEGAL_ARGUMENT if the provided properties cannot be |
| * encoded to a JSON representation, ENOMEM if there was not enough memory and CELIX_FILE_IO_EXCEPTION if the stream |
| * could not be written to. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_saveToStream(const celix_properties_t* properties, |
| FILE* stream, |
| int encodeFlags); |
| |
| /** |
| * @brief Save (encode) properties as a JSON representation to a file. |
| * |
| * For more information how a properties object is encoded to JSON, see the celix_properties_loadFromStream |
| * |
| * For a overview of the possible encode flags, see the CELIX_PROPERTIES_ENCODE_* flags documentation. |
| * The default encoding style is a compact and flat JSON representation. |
| * |
| * @param[in] properties The properties object to encode. |
| * @param[in] filename The file to write the JSON representation of the properties object to. |
| * @param[in] encodeFlags The flags to use when encoding the input properties. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ILLEGAL_ARGUMENT if the provided properties cannot be |
| * encoded to a JSON representation and ENOMEM if there was not enough memory. CELIX_FILE_IO_EXCEPTION if the file |
| * could not be opened or written to. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_save(const celix_properties_t* properties, |
| const char* filename, |
| int encodeFlags); |
| |
| /** |
| * @brief Save (encode) properties as a JSON representation to a string. |
| * |
| * For more information how a properties object is encoded to JSON, see the celix_properties_loadFromStream |
| * |
| * For a overview of the possible encode flags, see the CELIX_PROPERTIES_ENCODE_* flags documentation. |
| * The default encoding style is a compact and flat JSON representation. |
| * |
| * @param[in] properties The properties object to encode. |
| * @param[in] encodeFlags The flags to use when encoding the input properties. |
| * @param[out] out The JSON string representation of the properties object. The caller is responsible for freeing the |
| * returned string using free. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ILLEGAL_ARGUMENT if the provided properties cannot be |
| * encoded to a JSON representation and ENOMEM if there was not enough memory. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_saveToString(const celix_properties_t* properties, |
| int encodeFlags, |
| char** out); |
| |
| /** |
| * @brief Flag to indicate that the decoding should fail if the input contains duplicate JSON keys. |
| * |
| * E.g. `{"key": "value", "key": "value2"}` is a duplicate key. |
| * |
| * If this flag is set, the decoding will fail if the input contains a duplicate key and if this flag is not set, the |
| * decoding will not fail and the last entry will be used. |
| */ |
| #define CELIX_PROPERTIES_DECODE_ERROR_ON_DUPLICATES 0x01 |
| |
| /** |
| * @brief Flag to indicate that the decoding should fail if the input contains entry that collide on property keys. |
| * |
| * E.g. `{"obj/key": "value", "obj": {"key": "value2"}}` is a collision. |
| * |
| * If this flag is set, the decoding will fail if the input contains a collision and if this flag is not set, the |
| * decoding will not fail and the last entry will be used. |
| */ |
| #define CELIX_PROPERTIES_DECODE_ERROR_ON_COLLISIONS 0x02 |
| |
| /** |
| * @brief Flag to indicate that the decoding should fail if the input contains null values. |
| * |
| * E.g. `{"key": null}` is a null value. |
| * |
| * Note arrays with null values are handled by the CELIX_PROPERTIES_DECODE_ERROR_ON_UNSUPPORTED_ARRAYS flag. |
| * |
| * If this flag is set, the decoding will fail if the input contains a null value and if this flag is not set, the |
| * decoding will not fail and the JSON null entry will be ignored. |
| */ |
| #define CELIX_PROPERTIES_DECODE_ERROR_ON_NULL_VALUES 0x04 |
| |
| /** |
| * @brief Flag to indicate that the decoding should fail if the input contains empty arrays. |
| * |
| * |
| * E.g. `{"key": []}` is an empty array. |
| * |
| * Note that empty arrays are valid in JSON, but not cannot be decoded to a valid properties array entry. |
| * |
| * If this flag is set, the decoding will fail if the input contains an empty array and if this flag is not set, the |
| * decoding will not fail and the JSON empty array entry will be ignored. |
| */ |
| #define CELIX_PROPERTIES_DECODE_ERROR_ON_EMPTY_ARRAYS 0x08 |
| |
| /** |
| * @brief Flag to indicate that the decoding should fail if the input contains unsupported arrays. |
| * |
| * Unsupported arrays are arrays that contain JSON objects, multiple arrays, arrays with null values and |
| * mixed arrays. |
| * E.g. |
| * - `{"key": [{"nested": "value"}]}` (array with JSON object) |
| * - `{"key": [[1,2],[3,4]]}` (array with array) |
| * - `{"key": [null,null]}` (array with null values) |
| * - `{"key": ["value", 1]}` (mixed array) |
| * |
| * If this flag is set, the decoding will fail if the input contains an unsupported array and if this flag is not set, |
| * the decoding will not fail and the unsupported array entries will be ignored. |
| */ |
| #define CELIX_PROPERTIES_DECODE_ERROR_ON_UNSUPPORTED_ARRAYS 0x10 |
| |
| /** |
| * @brief Flag to indicate that the decoding should fail if the input contains empty keys. |
| * |
| * E.g. `{"": "value"}` is an empty key. |
| * |
| * Note that empty keys are valid in JSON and valid in properties, but not always desired. |
| * |
| * If this flag is set, the decoding will fail if the input contains an empty key. |
| */ |
| #define CELIX_PROPERTIES_DECODE_ERROR_ON_EMPTY_KEYS 0x20 |
| |
| /** |
| * @brief Flag to indicate that the decoding should fail if the input contains any of the decode error flags. |
| * |
| * This flag is a combination of all decode error flags. |
| */ |
| #define CELIX_PROPERTIES_DECODE_STRICT \ |
| (CELIX_PROPERTIES_DECODE_ERROR_ON_DUPLICATES | CELIX_PROPERTIES_DECODE_ERROR_ON_COLLISIONS | \ |
| CELIX_PROPERTIES_DECODE_ERROR_ON_NULL_VALUES | CELIX_PROPERTIES_DECODE_ERROR_ON_EMPTY_ARRAYS | \ |
| CELIX_PROPERTIES_DECODE_ERROR_ON_UNSUPPORTED_ARRAYS | CELIX_PROPERTIES_DECODE_ERROR_ON_EMPTY_KEYS) |
| |
| /** |
| * @brief Load properties from a stream. |
| * |
| * The stream is expected to be a valid readable stream and is not reset or closed by this function. |
| * The content of the stream is expected to be in the format of a JSON object. |
| * |
| * For decoding a single JSON object is decoded to a properties object. |
| * |
| * The keys of the JSON object are used as |
| * properties keys and the values of the JSON object are used as properties values. If there are nested |
| * JSON objects, the keys are concatenated with a '/' separator (e.g. `{"key": {"nested": "value"}}` will be |
| * decoded to a properties object with a single entry with key `key/nested` and (string) value `value`). |
| * |
| * Because properties keys are created by concatenating the JSON keys, there there could be collisions |
| * (e.g. `{"obj/key": "value", "obj": {"key": "value2"}}`, two entries with the key `obj/key`. In this case |
| * the last decoded JSON entry will be used. |
| * |
| * Properties entry types are determined by the JSON value type: |
| * - JSON string values are decoded as string properties entries. |
| * - JSON number values are decoded as long or double properties entries, depending on the value. |
| * - JSON boolean values are decoded as boolean properties entries. |
| * - jSON string values with a "version<" prefix and a ">" suffix are decoded as version properties entries (e.g. |
| * "version<1.2.3>"). |
| * - JSON array values are decoded as array properties entries. The array can contain any of the above types, but mixed |
| * arrays are not supported. |
| * - JSON null values are ignored. |
| * |
| * For a overview of the possible decode flags, see the CELIX_PROPERTIES_DECODE_* flags documentation. |
| * |
| * @param[in] stream The input stream to parse. |
| * @param[in] decodeFlags The flags to use when decoding the input string. |
| * @param[out] out The properties object that will be created from the input string. The caller is responsible for |
| * freeing the returned properties object using celix_properties_destroy. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ILLEGAL_ARGUMENT if the provided input cannot be |
| * decoded to a properties object and ENOMEM if there was not enough memory. CELIX_FILE_IO_EXCEPTION if the file |
| * could not be read. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_loadFromStream(FILE* stream, |
| int decodeFlags, |
| celix_properties_t** out); |
| |
| /** |
| * @brief Load properties from a file. |
| * |
| * @warning The name is temporary and will be renamed to celix_properties_load in the future (when |
| * the current celix_properties_load is removed). |
| * |
| * The content of the filename file is expected to be in the format of a JSON object. |
| * For what can and cannot be parsed, see celix_properties_loadFromStream documentation. |
| * |
| * For a overview of the possible decode flags, see the CELIX_PROPERTIES_DECODE_* flags documentation. |
| * |
| * If an error occurs, the error status is returned and a message is logged to celix_err. |
| * |
| * @param[in] filename The file to load the properties from. |
| * @param[in] decodeFlags The flags to use when decoding the input string. |
| * @param[out] out The properties object that will be created from the input string. The caller is responsible for |
| * freeing the returned properties object using celix_properties_destroy. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ILLEGAL_ARGUMENT if the provided input cannot be |
| * decoded to a properties object and ENOMEM if there was not enough memory. CELIX_FILE_IO_EXCEPTION if the file |
| * could not be opened. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_load(const char* filename, |
| int decodeFlags, |
| celix_properties_t** out); |
| |
| /** |
| * @brief Load properties from a string. |
| * |
| * @warning The name is temporary and will be renamed to celix_properties_loadFromString in the future (when |
| * the current celix_properties_loadFromString is removed). |
| * |
| * The input string is expected to be in the format of a JSON object. |
| * For what can and cannot be parsed, see celix_properties_loadFromStream documentation. |
| * |
| * For a overview of the possible decode flags, see the CELIX_PROPERTIES_DECODE_* flags documentation. |
| * |
| * If an error occurs, the error status is returned and a message is logged to celix_err. |
| * |
| * @param[in] input The input string to parse. |
| * @param[in] decodeFlags The flags to use when decoding the input string. |
| * @param[out] out The properties object that will be created from the input string. The caller is responsible for |
| * freeing the returned properties object using celix_properties_destroy. |
| * @return CELIX_SUCCESS if the operation was successful, CELIX_ILLEGAL_ARGUMENT if the provided input cannot be |
| * decoded to a properties object and ENOMEM if there was not enough memory. |
| */ |
| CELIX_UTILS_EXPORT celix_status_t celix_properties_loadFromString(const char* input, |
| int decodeFlags, |
| celix_properties_t** out); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* CELIX_PROPERTIES_H_ */ |
