{

public:

// Errors

typedef enum json_tokener_error ErrorCodes;

static const char *domain() { return "JsonObject"; }

virtual const char *getErrorDomain() const { return JsonError::domain(); };

JsonError(ErrorCodes aError) : Error(ErrorCode(aError), json_tokener_error_desc(aError)) {};

{

struct json_object *mJson_obj; ///< the json-c object

struct lh_entry *mNextEntryP; ///< iterator pointer for resetKeyIteration()/nextKeyValue()

/// construct object as wrapper of json-c json_object.

/// @param aObjPassingOwnership json_object, ownership is passed into this JsonObject, caller looses ownership!

JsonObject(struct json_object *aObjPassingOwnership);

/// construct empty object

JsonObject();

public:

/// destructor, releases internally kept json_object (which is possibly owned by other objects)

virtual ~JsonObject();

/// copy constructor

JsonObject(const JsonObject& aObj);

/// assignment operator

JsonObject& operator=(const JsonObject& aObj);

/// factory to return smart pointer to new wrapper of a newly created json_object

/// @param aObjPassingOwnership json_object, ownership is passed into this JsonObject, caller looses ownership!

static JsonObjectPtr newObj(struct json_object *aObjPassingOwnership);

/// get type

/// @return type code

json_type type() const;

/// check type

/// @param aRefType type to check for

/// @return true if object matches given type

bool isType(json_type aRefType) const;

/// return JSON string representation

/// @param aFlags formatting options, see JSON_C_TO_STRING_PRETTY and other constants

/// @return JSON C string representation (valid as long as object exists)

const char *json_c_str(int aFlags=0);

/// return JSON string representation

/// @param aFlags formatting options, see JSON_C_TO_STRING_PRETTY and other constants

/// @return JSON string representation of object.

string json_str(int aFlags=0);

/// Convenience method: return JSON string representation of passed object, which may be NULL

/// @param aFlags formatting options, see JSON_C_TO_STRING_PRETTY and other constants

/// @return JSON C string representation of json aJsonObj, or "<none>" if aJsonObj is NULL

static const char* text(JsonObjectPtr aJsonObj, int aFlags=0);

/// Note: should only be used to pass object to other json-c native APIs

/// Note: Ownership of the jsonobject remains with this JsonObject

/// @return pointer the embedded json-c object structure

const struct json_object *jsoncObj() const { return mJson_obj; }

/// add object for key

/// @param aKey name of key

/// @param aObj object to store in field named aKey

void add(const char* aKey, JsonObjectPtr aObj);

/// get object by key

/// @param aKey key of object

/// @return the value of the object

/// @note to distinguish between having no such key and having the key with

/// a NULL object, use get(aKey,aJsonObject) instead

JsonObjectPtr get(const char *aKey);

/// get object by key

/// @param aKey key of object

/// @param aJsonObject will be set to the value of the key when return value is true

/// @param aIgnoreNullValues if set (default since 2022-11-24, but not before!), existing keys with

/// NULL values will be ignored, that is, return false - as if the key would not exist.

/// In this mode the function returning true guarantees that aJsonObject is not nullPtr,

/// so no testing is needed before trying to extract a value from it.

/// If not set, the method always returns true when the key exists, and aJsonObject will

/// be nullPtr when the key's value is NULL.

/// @return true if key exists and (only if aIgnoreNullValues is set) has a non-null value.

bool get(const char *aKey, JsonObjectPtr &aJsonObject, bool aIgnoreNullValues = true);

/// get object's string value by key

/// @return NULL if key does not exists or actually has NULL value, string object otherwise

/// @note the returned C string pointer is valid only as long as the object is not deleted

const char *getCString(const char *aKey);

/// delete object by key

/// @param aKey key of field to delete

void del(const char *aKey);

/// get array length

/// @return length of array. Returns 0 for empty arrays and all non-array objects

int arrayLength() const;

/// append to array

/// @param aObj object to append to the array

void arrayAppend(JsonObjectPtr aObj);

/// get from a specific position in the array

/// @param aAtIndex index position to return value for

/// @return NULL pointer if element does not exist, value otherwise

JsonObjectPtr arrayGet(int aAtIndex);

/// put at specific position in array

/// @param aAtIndex index position to put value to (overwriting existing value at that position)

/// @param aObj object to store in the array

void arrayPut(int aAtIndex, JsonObjectPtr aObj);

#if !REDUCED_FOOTPRINT

/// delete element(s) at specific position in array

/// @param aAtIndex index position of first element to delete

/// @param aNumElements number of elements to delete

void arrayDel(int aAtIndex, int aNumElements = 1);

#endif // REDUCED_FOOTPRINT

/// reset object iterator

/// @return false if object cannot be iterated

bool resetKeyIteration();

/// get next child object's key and value

/// @param aKey will be assigned the key (name) of the child object

/// @param aValue will be assigned the child object

/// @return false if there are no more key/values (aKey and aValue unchanged)

bool nextKeyValue(string &aKey, JsonObjectPtr &aValue);

/// get number of keys in this object

/// @return number of keys. Returns 0 for empty objects and all non-objects

int numKeys();

/// get key/value by index

/// @param aIndex index into object (internal, non-predictable order)

/// @param aKey will be assigned the key (name) of the child object

/// @param aValueP if not NULL, will be assigned the child object

/// @return false if there is no object with the specified aIndex

bool keyValueByIndex(int aIndex, string &aKey, JsonObjectPtr* aValueP = NULL);

/// @return new empty object

static JsonObjectPtr newObj();

/// @return create new NULL object (does not embed a real JSON-C object, just a NULL pointer)

static JsonObjectPtr newNull();

/// create new object from text

/// @param aJsonText text to be read as JSON

/// @param aMaxChars max chars to read from aJsonText, or -1 to read entire C string (until NUL terminator is found)

/// @param aErrorP where to store parsing error objects, or NULL if no error return is needed

/// @param aAllowCComments if set, C-Style comments /* */ are allowed withing JSON text (not conformant to JSON specs)

/// @param aParsedCharsP where to store the number of chars parsed from aJsonText, or NULL if not needed

/// @return new object or NULL if aJsonText parsing was not succesful

static JsonObjectPtr objFromText(const char *aJsonText, ssize_t aMaxChars = -1, ErrorPtr *aErrorP = NULL, bool aAllowCComments = false, ssize_t* aParsedCharsP = NULL);

/// create new object from text file

/// @param aJsonFilePath path of file to read as JSON

/// @param aErrorP where to store parsing error objects, or NULL if no error return is needed

/// @param aAllowCComments if set, C-Style comments /* */ are allowed withing JSON text (not conformant to JSON specs)

/// @return new object or NULL if aJsonText parsing was not succesful

static JsonObjectPtr objFromFile(const char *aJsonFilePath, ErrorPtr *aErrorP = NULL, bool aAllowCComments = false);

/// save object to text file

/// @param aJsonFilePath path of file to (over)write with text representation of this JSON object

/// @param aFlags formatting options, see JSON_C_TO_STRING_PRETTY and other constants

/// @return ok or error

ErrorPtr saveToFile(const char *aJsonFilePath, int aFlags = 0);

/// @return new array object

static JsonObjectPtr newArray();

/// @return new boolean JSON object

static JsonObjectPtr newBool(bool aBool);

/// @return boolean value

bool boolValue() const;

/// create int JSON object

/// @param aInt32 32 bit integer number

static JsonObjectPtr newInt32(int32_t aInt32);

/// create int JSON object

/// @param aInt64 64 bit integer number

static JsonObjectPtr newInt64(int64_t aInt64);

/// @return int32 value

int32_t int32Value() const;

/// @return int64 value

int64_t int64Value() const;

/// @return double JSON object

/// @param aDouble double float number

static JsonObjectPtr newDouble(double aDouble);

/// @return double value

double doubleValue() const;

/// Create new JSON string object or no object from C string

/// @param aCStr C string to make JSON string of, can be NULL to create no object

/// @return new JSON string object or NULL if aCStr is NULL

static JsonObjectPtr newString(const char *aCStr);

/// Create new JSON string object or no object from part of C string

/// @param aCStr C string to take characters from for JSON string, can be NULL to create no object

/// @param aLen max number of characters to take from aCStr

/// @return new JSON string object or NULL if aCStr is NULL

static JsonObjectPtr newString(const char *aCStr, size_t aLen);

/// @return new JSON string object

/// @param aString string to make JSON string of

/// @param aEmptyIsNull if set, and aString is empty, NULL is returned

/// @return new JSON string object or NULL if aString is empty and aEmptyIsNull is set

static JsonObjectPtr newString(const string &aString, bool aEmptyIsNull = false);

/// @return value of object as string

const char* c_strValue() const;

/// @return length of value of object as string

size_t stringLength() const;

/// @return value of object as string

string stringValue() const;

/// @return value of object as lowercase string

string lowercaseStringValue() const;