/** @file * IPRT - JavaScript Object Notation (JSON) Parser. */ /* * Copyright (C) 2016-2022 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 . * * 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 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) /** * 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 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, 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 pszStr The string containing the JSON document. * @param pErrInfo Where to store extended error info. Optional. */ RTDECL(int) RTJsonParseFromString(PRTJSONVAL phJsonVal, 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 pszFilename The name of the file containing the JSON document. * @param pErrInfo Where to store extended error info. Optional. */ RTDECL(int) RTJsonParseFromFile(PRTJSONVAL phJsonVal, 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 hVfsFile The VFS file to parse. * @param pErrInfo Where to store extended error info. Optional. */ RTDECL(int) RTJsonParseFromVfsFile(PRTJSONVAL phJsonVal, 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 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 */