summaryrefslogtreecommitdiffstats
path: root/include/iprt/json.h
diff options
context:
space:
mode:
Diffstat (limited to 'include/iprt/json.h')
-rw-r--r--include/iprt/json.h384
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 */
+