diff options
Diffstat (limited to 'include/iprt/json.h')
| -rw-r--r-- | include/iprt/json.h | 384 |
1 files changed, 384 insertions, 0 deletions
diff --git a/include/iprt/json.h b/include/iprt/json.h new file mode 100644 index 00000000..df588736 --- /dev/null +++ b/include/iprt/json.h @@ -0,0 +1,384 @@ +/** @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 <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) + +/** + * 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 */ + |