/** @file
 * IPRT - JavaScript Object Notation (JSON) Parser.
 */

/*
 * Copyright (C) 2016-2025 Oracle and/or its affiliates.
 *
 * This file is part of VirtualBox base platform packages, as
 * available from https://www.virtualbox.org.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation, in version 3 of the
 * License.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, see <https://www.gnu.org/licenses>.
 *
 * The contents of this file may alternatively be used under the terms
 * of the Common Development and Distribution License Version 1.0
 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
 * in the VirtualBox distribution, in which case the provisions of the
 * CDDL are applicable instead of those of the GPL.
 *
 * You may elect to license modified versions of this file under the
 * terms and conditions of either the GPL or the CDDL or both.
 *
 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
 */

#ifndef IPRT_INCLUDED_json_h
#define IPRT_INCLUDED_json_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif

#include <iprt/types.h>

RT_C_DECLS_BEGIN


/** @defgroup grp_json      RTJson - JavaScript Object Notation (JSON) Parser
 * @ingroup grp_rt
 * @{
 */

/**
 * JSON value types.
 */
typedef enum RTJSONVALTYPE
{
    /** Invalid first value. */
    RTJSONVALTYPE_INVALID = 0,
    /** Value containing an object. */
    RTJSONVALTYPE_OBJECT,
    /** Value containing an array. */
    RTJSONVALTYPE_ARRAY,
    /** Value containing a string. */
    RTJSONVALTYPE_STRING,
    /** Value containg an integer number. */
    RTJSONVALTYPE_INTEGER,
    /** Value containg an floating point number. */
    RTJSONVALTYPE_NUMBER,
    /** Value containg the special null value. */
    RTJSONVALTYPE_NULL,
    /** Value containing true. */
    RTJSONVALTYPE_TRUE,
    /** Value containing false. */
    RTJSONVALTYPE_FALSE,
    /** 32-bit hack. */
    RTJSONVALTYPE_32BIT_HACK = 0x7fffffff
} RTJSONVALTYPE;
/** Pointer to a JSON value type. */
typedef RTJSONVALTYPE *PRTJSONVALTYPE;

/** JSON value handle. */
typedef struct RTJSONVALINT *RTJSONVAL;
/** Pointer to a JSON value handle. */
typedef RTJSONVAL *PRTJSONVAL;
/** NIL JSON value handle. */
#define NIL_RTJSONVAL ((RTJSONVAL)~(uintptr_t)0)

/** JSON iterator handle. */
typedef struct RTJSONITINT  *RTJSONIT;
/** Pointer to a JSON iterator handle. */
typedef RTJSONIT *PRTJSONIT;
/** NIL JSON iterator handle. */
#define NIL_RTJSONIT ((RTJSONIT)~(uintptr_t)0)

/** Allow JSON5 extensions. */
#define RTJSON_PARSE_F_JSON5            RT_BIT_32(0)
/** Mask of valid flags. */
#define RTJSON_PARSE_F_VALID            RTJSON_PARSE_F_JSON5



/**
 * Parses a JSON document in the provided buffer returning the root JSON value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_MALFORMED if the document does not conform to the spec.
 * @param   phJsonVal       Where to store the handle to the JSON value on success.
 * @param   fFlags          Combination of RTJSON_PARSE_F_XXX.
 * @param   pbBuf           The byte buffer containing the JSON document.
 * @param   cbBuf           Size of the buffer.
 * @param   pErrInfo        Where to store extended error info. Optional.
 *
 * @todo    r=bird: The use of uint8_t makes no sense here since the parser
 *          expects ASCII / UTF-8.  What's more, if this is a real buffer the
 *          type should be 'const void *' rather than 'const uint8_t *'.
 *          This function should be modified to reflect that it's really for
 *          handling unterminated strings.
 */
RTDECL(int) RTJsonParseFromBuf(PRTJSONVAL phJsonVal, uint32_t fFlags, const uint8_t *pbBuf, size_t cbBuf, PRTERRINFO pErrInfo);

/**
 * Parses a JSON document from the provided string returning the root JSON value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_MALFORMED if the document does not conform to the spec.
 * @param   phJsonVal       Where to store the handle to the JSON value on success.
 * @param   fFlags          Combination of RTJSON_PARSE_F_XXX.
 * @param   pszStr          The string containing the JSON document.
 * @param   pErrInfo        Where to store extended error info. Optional.
 */
RTDECL(int) RTJsonParseFromString(PRTJSONVAL phJsonVal, uint32_t fFlags, const char *pszStr, PRTERRINFO pErrInfo);

/**
 * Parses a JSON document from the file pointed to by the given filename
 * returning the root JSON value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_MALFORMED if the document does not conform to the spec.
 * @param   phJsonVal       Where to store the handle to the JSON value on success.
 * @param   fFlags          Combination of RTJSON_PARSE_F_XXX.
 * @param   pszFilename     The name of the file containing the JSON document.
 * @param   pErrInfo        Where to store extended error info. Optional.
 */
RTDECL(int) RTJsonParseFromFile(PRTJSONVAL phJsonVal, uint32_t fFlags, const char *pszFilename, PRTERRINFO pErrInfo);

/**
 * Parses a JSON document from the given VFS file
 * returning the root JSON value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_MALFORMED if the document does not conform to the spec.
 * @param   phJsonVal       Where to store the handle to the JSON value on success.
 * @param   fFlags          Combination of RTJSON_PARSE_F_XXX.
 * @param   hVfsFile        The VFS file to parse.
 * @param   pErrInfo        Where to store extended error info. Optional.
 */
RTDECL(int) RTJsonParseFromVfsFile(PRTJSONVAL phJsonVal, uint32_t fFlags, RTVFSFILE hVfsFile, PRTERRINFO pErrInfo);

/**
 * Retain a given JSON value.
 *
 * @returns New reference count.
 * @param   hJsonVal        The JSON value handle.
 */
RTDECL(uint32_t) RTJsonValueRetain(RTJSONVAL hJsonVal);

/**
 * Release a given JSON value.
 *
 * @returns New reference count, if this drops to 0 the value is freed.
 * @param   hJsonVal        The JSON value handle.
 */
RTDECL(uint32_t) RTJsonValueRelease(RTJSONVAL hJsonVal);

/**
 * Return the type of a given JSON value.
 *
 * @returns Type of the given JSON value.
 * @param   hJsonVal        The JSON value handle.
 */
RTDECL(RTJSONVALTYPE) RTJsonValueGetType(RTJSONVAL hJsonVal);

/**
 * Translates value type to a name.
 *
 * @returns Readonly name string
 * @param   enmType             The JSON value type to name.
 */
RTDECL(const char *) RTJsonValueTypeName(RTJSONVALTYPE enmType);

/**
 * Returns the string from a given JSON string value.
 *
 * @returns Pointer to the string of the JSON value, NULL if the value type
 *          doesn't indicate a string.
 * @param   hJsonVal        The JSON value handle.
 */
RTDECL(const char *) RTJsonValueGetString(RTJSONVAL hJsonVal);

/**
 * Returns the string from a given JSON string value, extended.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not a string.
 * @param   hJsonVal        The JSON value handle.
 * @param   ppszStr         Where to store the pointer to the string on success.
 */
RTDECL(int) RTJsonValueQueryString(RTJSONVAL hJsonVal, const char **ppszStr);

/**
 * Returns the integer from a given JSON integer value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not a number.
 * @param   hJsonVal        The JSON value handle.
 * @param   pi64Num         WHere to store the number on success.
 * @sa      RTJsonValueQueryNumber
 */
RTDECL(int) RTJsonValueQueryInteger(RTJSONVAL hJsonVal, int64_t *pi64Num);

/**
 * Returns the floating point value from a given JSON number value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not a number.
 * @param   hJsonVal        The JSON value handle.
 * @param   prdNum          WHere to store the floating point number on success.
 * @sa      RTJsonValueQueryInteger
 */
RTDECL(int) RTJsonValueQueryNumber(RTJSONVAL hJsonVal, double *prdNum);

/**
 * Returns the numberof members of a given JSON object value.
 *
 * @returns Number of members of the given JSON object.
 * @retval  0 if the object has no members or the JSON value is not an object.
 * @param   hJsonVal        The JSON value handle.
 */
RTDECL(unsigned) RTJsonValueGetObjectMemberCount(RTJSONVAL hJsonVal);

/**
 * Returns the numberof members of a given JSON object value - extended version.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an object.
 * @param   hJsonVal        The JSON value handle.
 * @param   pcMembers       Where to store the number of members for the given JSON object on success.
 */
RTDECL(int) RTJsonValueQueryObjectMemberCount(RTJSONVAL hJsonVal, unsigned *pcMembers);

/**
 * Returns the value associated with a given name for the given JSON object value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an object.
 * @retval  VERR_NOT_FOUND if the name is not known for this JSON object.
 * @param   hJsonVal        The JSON value handle.
 * @param   pszName         The member name of the object.
 * @param   phJsonVal       Where to store the handle to the JSON value on success.
 */
RTDECL(int) RTJsonValueQueryByName(RTJSONVAL hJsonVal, const char *pszName, PRTJSONVAL phJsonVal);

/**
 * Returns the number of a number value associated with a given name for the given JSON object value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an object or
 *          the name does not point to an integer value.
 * @retval  VERR_NOT_FOUND if the name is not known for this JSON object.
 * @param   hJsonVal        The JSON value handle.
 * @param   pszName         The member name of the object.
 * @param   pi64Num         Where to store the number on success.
 */
RTDECL(int) RTJsonValueQueryIntegerByName(RTJSONVAL hJsonVal, const char *pszName, int64_t *pi64Num);

/**
 * Returns the number of a number value associated with a given name for the given JSON object value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an object or
 *          the name does not point to a number value.
 * @retval  VERR_NOT_FOUND if the name is not known for this JSON object.
 * @param   hJsonVal        The JSON value handle.
 * @param   pszName         The member name of the object.
 * @param   prdNum          WHere to store the floating point number on success.
 */
RTDECL(int) RTJsonValueQueryNumberByName(RTJSONVAL hJsonVal, const char *pszName, double *prdNum);

/**
 * Returns the string of a string value associated with a given name for the given JSON object value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an object or
 *          the name does not point to a string value.
 * @retval  VERR_NOT_FOUND if the name is not known for this JSON object.
 * @param   hJsonVal        The JSON value handle.
 * @param   pszName         The member name of the object.
 * @param   ppszStr         Where to store the pointer to the string on success.
 *                          Must be freed with RTStrFree().
 */
RTDECL(int) RTJsonValueQueryStringByName(RTJSONVAL hJsonVal, const char *pszName, char **ppszStr);

/**
 * Returns the boolean of a true/false value associated with a given name for the given JSON object value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an object or
 *          the name does not point to a true/false value.
 * @retval  VERR_NOT_FOUND if the name is not known for this JSON object.
 * @param   hJsonVal        The JSON value handle.
 * @param   pszName         The member name of the object.
 * @param   pfBoolean       Where to store the boolean value on success.
 */
RTDECL(int) RTJsonValueQueryBooleanByName(RTJSONVAL hJsonVal, const char *pszName, bool *pfBoolean);

/**
 * Returns the size of a given JSON array value.
 *
 * @returns Size of the JSON array value.
 * @retval  0 if the array is empty or the JSON value is not an array.
 * @param   hJsonVal        The JSON value handle.
 */
RTDECL(unsigned) RTJsonValueGetArraySize(RTJSONVAL hJsonVal);

/**
 * Returns the size of a given JSON array value - extended version.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an array.
 * @param   hJsonVal        The JSON value handle.
 * @param   pcItems         Where to store the size of the JSON array value on success.
 */
RTDECL(int) RTJsonValueQueryArraySize(RTJSONVAL hJsonVal, unsigned *pcItems);

/**
 * Returns the value for the given index of a given JSON array value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an array.
 * @retval  VERR_OUT_OF_RANGE if @a idx is out of bounds.
 *
 * @param   hJsonVal        The JSON value handle.
 * @param   idx             The index to get the value from.
 * @param   phJsonVal       Where to store the handle to the JSON value on success.
 */
RTDECL(int) RTJsonValueQueryByIndex(RTJSONVAL hJsonVal, unsigned idx, PRTJSONVAL phJsonVal);

/**
 * Creates an iterator for a given JSON array or object value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an array or
 *          object.
 * @param   hJsonVal        The JSON value handle.
 * @param   phJsonIt        Where to store the JSON iterator handle on success.
 * @todo    Make return VERR_JSON_IS_EMPTY (or remove it).
 */
RTDECL(int) RTJsonIteratorBegin(RTJSONVAL hJsonVal, PRTJSONIT phJsonIt);

/**
 * Creates an iterator for a given JSON array value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an array.
 * @retval  VERR_JSON_IS_EMPTY if no members.
 * @param   hJsonVal        The JSON value handle.
 * @param   phJsonIt        Where to store the JSON iterator handle on success.
 */
RTDECL(int) RTJsonIteratorBeginArray(RTJSONVAL hJsonVal, PRTJSONIT phJsonIt);

/**
 * Creates an iterator for a given JSON object value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an object.
 * @retval  VERR_JSON_IS_EMPTY if no members.
 * @param   hJsonVal        The JSON value handle.
 * @param   phJsonIt        Where to store the JSON iterator handle on success.
 */
RTDECL(int) RTJsonIteratorBeginObject(RTJSONVAL hJsonVal, PRTJSONIT phJsonIt);

/**
 * Gets the value and optional name for the current iterator position.
 *
 * @returns IPRT status code.
 * @param   hJsonIt         The JSON iterator handle.
 * @param   phJsonVal       Where to store the handle to the JSON value on success.
 * @param   ppszName        Where to store the object member name for an object.
 *                          NULL is returned for arrays.
 */
RTDECL(int) RTJsonIteratorQueryValue(RTJSONIT hJsonIt, PRTJSONVAL phJsonVal, const char **ppszName);

/**
 * Advances to the next element in the referenced JSON value.
 *
 * @returns IPRT status code.
 * @retval  VERR_JSON_ITERATOR_END if the end for this iterator was reached.
 * @param   hJsonIt         The JSON iterator handle.
 */
RTDECL(int) RTJsonIteratorNext(RTJSONIT hJsonIt);

/**
 * Frees a given JSON iterator.
 *
 * @param   hJsonIt         The JSON iterator to free.
 */
RTDECL(void) RTJsonIteratorFree(RTJSONIT hJsonIt);

RT_C_DECLS_END

/** @} */

#endif /* !IPRT_INCLUDED_json_h */