VirtualBox

source: vbox/trunk/include/iprt/json.h

Last change on this file was 106061, checked in by vboxsync, 7 weeks ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 14.2 KB
Line 
1/** @file
2 * IPRT - JavaScript Object Notation (JSON) Parser.
3 */
4
5/*
6 * Copyright (C) 2016-2024 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_json_h
37#define IPRT_INCLUDED_json_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/types.h>
43
44RT_C_DECLS_BEGIN
45
46
47/** @defgroup grp_json RTJson - JavaScript Object Notation (JSON) Parser
48 * @ingroup grp_rt
49 * @{
50 */
51
52/**
53 * JSON value types.
54 */
55typedef enum RTJSONVALTYPE
56{
57 /** Invalid first value. */
58 RTJSONVALTYPE_INVALID = 0,
59 /** Value containing an object. */
60 RTJSONVALTYPE_OBJECT,
61 /** Value containing an array. */
62 RTJSONVALTYPE_ARRAY,
63 /** Value containing a string. */
64 RTJSONVALTYPE_STRING,
65 /** Value containg an integer number. */
66 RTJSONVALTYPE_INTEGER,
67 /** Value containg an floating point number. */
68 RTJSONVALTYPE_NUMBER,
69 /** Value containg the special null value. */
70 RTJSONVALTYPE_NULL,
71 /** Value containing true. */
72 RTJSONVALTYPE_TRUE,
73 /** Value containing false. */
74 RTJSONVALTYPE_FALSE,
75 /** 32-bit hack. */
76 RTJSONVALTYPE_32BIT_HACK = 0x7fffffff
77} RTJSONVALTYPE;
78/** Pointer to a JSON value type. */
79typedef RTJSONVALTYPE *PRTJSONVALTYPE;
80
81/** JSON value handle. */
82typedef struct RTJSONVALINT *RTJSONVAL;
83/** Pointer to a JSON value handle. */
84typedef RTJSONVAL *PRTJSONVAL;
85/** NIL JSON value handle. */
86#define NIL_RTJSONVAL ((RTJSONVAL)~(uintptr_t)0)
87
88/** JSON iterator handle. */
89typedef struct RTJSONITINT *RTJSONIT;
90/** Pointer to a JSON iterator handle. */
91typedef RTJSONIT *PRTJSONIT;
92/** NIL JSON iterator handle. */
93#define NIL_RTJSONIT ((RTJSONIT)~(uintptr_t)0)
94
95/**
96 * Parses a JSON document in the provided buffer returning the root JSON value.
97 *
98 * @returns IPRT status code.
99 * @retval VERR_JSON_MALFORMED if the document does not conform to the spec.
100 * @param phJsonVal Where to store the handle to the JSON value on success.
101 * @param pbBuf The byte buffer containing the JSON document.
102 * @param cbBuf Size of the buffer.
103 * @param pErrInfo Where to store extended error info. Optional.
104 *
105 * @todo r=bird: The use of uint8_t makes no sense here since the parser
106 * expects ASCII / UTF-8. What's more, if this is a real buffer the
107 * type should be 'const void *' rather than 'const uint8_t *'.
108 * This function should be modified to reflect that it's really for
109 * handling unterminated strings.
110 */
111RTDECL(int) RTJsonParseFromBuf(PRTJSONVAL phJsonVal, const uint8_t *pbBuf, size_t cbBuf, PRTERRINFO pErrInfo);
112
113/**
114 * Parses a JSON document from the provided string returning the root JSON value.
115 *
116 * @returns IPRT status code.
117 * @retval VERR_JSON_MALFORMED if the document does not conform to the spec.
118 * @param phJsonVal Where to store the handle to the JSON value on success.
119 * @param pszStr The string containing the JSON document.
120 * @param pErrInfo Where to store extended error info. Optional.
121 */
122RTDECL(int) RTJsonParseFromString(PRTJSONVAL phJsonVal, const char *pszStr, PRTERRINFO pErrInfo);
123
124/**
125 * Parses a JSON document from the file pointed to by the given filename
126 * returning the root JSON value.
127 *
128 * @returns IPRT status code.
129 * @retval VERR_JSON_MALFORMED if the document does not conform to the spec.
130 * @param phJsonVal Where to store the handle to the JSON value on success.
131 * @param pszFilename The name of the file containing the JSON document.
132 * @param pErrInfo Where to store extended error info. Optional.
133 */
134RTDECL(int) RTJsonParseFromFile(PRTJSONVAL phJsonVal, const char *pszFilename, PRTERRINFO pErrInfo);
135
136/**
137 * Parses a JSON document from the given VFS file
138 * returning the root JSON value.
139 *
140 * @returns IPRT status code.
141 * @retval VERR_JSON_MALFORMED if the document does not conform to the spec.
142 * @param phJsonVal Where to store the handle to the JSON value on success.
143 * @param hVfsFile The VFS file to parse.
144 * @param pErrInfo Where to store extended error info. Optional.
145 */
146RTDECL(int) RTJsonParseFromVfsFile(PRTJSONVAL phJsonVal, RTVFSFILE hVfsFile, PRTERRINFO pErrInfo);
147
148/**
149 * Retain a given JSON value.
150 *
151 * @returns New reference count.
152 * @param hJsonVal The JSON value handle.
153 */
154RTDECL(uint32_t) RTJsonValueRetain(RTJSONVAL hJsonVal);
155
156/**
157 * Release a given JSON value.
158 *
159 * @returns New reference count, if this drops to 0 the value is freed.
160 * @param hJsonVal The JSON value handle.
161 */
162RTDECL(uint32_t) RTJsonValueRelease(RTJSONVAL hJsonVal);
163
164/**
165 * Return the type of a given JSON value.
166 *
167 * @returns Type of the given JSON value.
168 * @param hJsonVal The JSON value handle.
169 */
170RTDECL(RTJSONVALTYPE) RTJsonValueGetType(RTJSONVAL hJsonVal);
171
172/**
173 * Translates value type to a name.
174 *
175 * @returns Readonly name string
176 * @param enmType The JSON value type to name.
177 */
178RTDECL(const char *) RTJsonValueTypeName(RTJSONVALTYPE enmType);
179
180/**
181 * Returns the string from a given JSON string value.
182 *
183 * @returns Pointer to the string of the JSON value, NULL if the value type
184 * doesn't indicate a string.
185 * @param hJsonVal The JSON value handle.
186 */
187RTDECL(const char *) RTJsonValueGetString(RTJSONVAL hJsonVal);
188
189/**
190 * Returns the string from a given JSON string value, extended.
191 *
192 * @returns IPRT status code.
193 * @retval VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not a string.
194 * @param hJsonVal The JSON value handle.
195 * @param ppszStr Where to store the pointer to the string on success.
196 */
197RTDECL(int) RTJsonValueQueryString(RTJSONVAL hJsonVal, const char **ppszStr);
198
199/**
200 * Returns the integer from a given JSON integer value.
201 *
202 * @returns IPRT status code.
203 * @retval VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not a number.
204 * @param hJsonVal The JSON value handle.
205 * @param pi64Num WHere to store the number on success.
206 * @sa RTJsonValueQueryNumber
207 */
208RTDECL(int) RTJsonValueQueryInteger(RTJSONVAL hJsonVal, int64_t *pi64Num);
209
210/**
211 * Returns the floating point value from a given JSON number value.
212 *
213 * @returns IPRT status code.
214 * @retval VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not a number.
215 * @param hJsonVal The JSON value handle.
216 * @param prdNum WHere to store the floating point number on success.
217 * @sa RTJsonValueQueryInteger
218 */
219RTDECL(int) RTJsonValueQueryNumber(RTJSONVAL hJsonVal, double *prdNum);
220
221/**
222 * Returns the value associated with a given name for the given JSON object value.
223 *
224 * @returns IPRT status code.
225 * @retval VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an object.
226 * @retval VERR_NOT_FOUND if the name is not known for this JSON object.
227 * @param hJsonVal The JSON value handle.
228 * @param pszName The member name of the object.
229 * @param phJsonVal Where to store the handle to the JSON value on success.
230 */
231RTDECL(int) RTJsonValueQueryByName(RTJSONVAL hJsonVal, const char *pszName, PRTJSONVAL phJsonVal);
232
233/**
234 * Returns the number of a number value associated with a given name for the given JSON object value.
235 *
236 * @returns IPRT status code.
237 * @retval VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an object or
238 * the name does not point to an integer value.
239 * @retval VERR_NOT_FOUND if the name is not known for this JSON object.
240 * @param hJsonVal The JSON value handle.
241 * @param pszName The member name of the object.
242 * @param pi64Num Where to store the number on success.
243 */
244RTDECL(int) RTJsonValueQueryIntegerByName(RTJSONVAL hJsonVal, const char *pszName, int64_t *pi64Num);
245
246/**
247 * Returns the number of a number value associated with a given name for the given JSON object value.
248 *
249 * @returns IPRT status code.
250 * @retval VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an object or
251 * the name does not point to a number value.
252 * @retval VERR_NOT_FOUND if the name is not known for this JSON object.
253 * @param hJsonVal The JSON value handle.
254 * @param pszName The member name of the object.
255 * @param prdNum WHere to store the floating point number on success.
256 */
257RTDECL(int) RTJsonValueQueryNumberByName(RTJSONVAL hJsonVal, const char *pszName, double *prdNum);
258
259/**
260 * Returns the string of a string value associated with a given name for the given JSON object value.
261 *
262 * @returns IPRT status code.
263 * @retval VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an object or
264 * the name does not point to a string value.
265 * @retval VERR_NOT_FOUND if the name is not known for this JSON object.
266 * @param hJsonVal The JSON value handle.
267 * @param pszName The member name of the object.
268 * @param ppszStr Where to store the pointer to the string on success.
269 * Must be freed with RTStrFree().
270 */
271RTDECL(int) RTJsonValueQueryStringByName(RTJSONVAL hJsonVal, const char *pszName, char **ppszStr);
272
273/**
274 * Returns the boolean of a true/false value associated with a given name for the given JSON object value.
275 *
276 * @returns IPRT status code.
277 * @retval VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an object or
278 * the name does not point to a true/false value.
279 * @retval VERR_NOT_FOUND if the name is not known for this JSON object.
280 * @param hJsonVal The JSON value handle.
281 * @param pszName The member name of the object.
282 * @param pfBoolean Where to store the boolean value on success.
283 */
284RTDECL(int) RTJsonValueQueryBooleanByName(RTJSONVAL hJsonVal, const char *pszName, bool *pfBoolean);
285
286/**
287 * Returns the size of a given JSON array value.
288 *
289 * @returns Size of the JSON array value.
290 * @retval 0 if the array is empty or the JSON value is not an array.
291 * @param hJsonVal The JSON value handle.
292 */
293RTDECL(unsigned) RTJsonValueGetArraySize(RTJSONVAL hJsonVal);
294
295/**
296 * Returns the size of a given JSON array value - extended version.
297 *
298 * @returns IPRT status code.
299 * @retval VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an array.
300 * @param hJsonVal The JSON value handle.
301 * @param pcItems Where to store the size of the JSON array value on success.
302 */
303RTDECL(int) RTJsonValueQueryArraySize(RTJSONVAL hJsonVal, unsigned *pcItems);
304
305/**
306 * Returns the value for the given index of a given JSON array value.
307 *
308 * @returns IPRT status code.
309 * @retval VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an array.
310 * @retval VERR_OUT_OF_RANGE if @a idx is out of bounds.
311 *
312 * @param hJsonVal The JSON value handle.
313 * @param idx The index to get the value from.
314 * @param phJsonVal Where to store the handle to the JSON value on success.
315 */
316RTDECL(int) RTJsonValueQueryByIndex(RTJSONVAL hJsonVal, unsigned idx, PRTJSONVAL phJsonVal);
317
318/**
319 * Creates an iterator for a given JSON array or object value.
320 *
321 * @returns IPRT status code.
322 * @retval VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an array or
323 * object.
324 * @param hJsonVal The JSON value handle.
325 * @param phJsonIt Where to store the JSON iterator handle on success.
326 * @todo Make return VERR_JSON_IS_EMPTY (or remove it).
327 */
328RTDECL(int) RTJsonIteratorBegin(RTJSONVAL hJsonVal, PRTJSONIT phJsonIt);
329
330/**
331 * Creates an iterator for a given JSON array value.
332 *
333 * @returns IPRT status code.
334 * @retval VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an array.
335 * @retval VERR_JSON_IS_EMPTY if no members.
336 * @param hJsonVal The JSON value handle.
337 * @param phJsonIt Where to store the JSON iterator handle on success.
338 */
339RTDECL(int) RTJsonIteratorBeginArray(RTJSONVAL hJsonVal, PRTJSONIT phJsonIt);
340
341/**
342 * Creates an iterator for a given JSON object value.
343 *
344 * @returns IPRT status code.
345 * @retval VERR_JSON_VALUE_INVALID_TYPE if the JSON value is not an object.
346 * @retval VERR_JSON_IS_EMPTY if no members.
347 * @param hJsonVal The JSON value handle.
348 * @param phJsonIt Where to store the JSON iterator handle on success.
349 */
350RTDECL(int) RTJsonIteratorBeginObject(RTJSONVAL hJsonVal, PRTJSONIT phJsonIt);
351
352/**
353 * Gets the value and optional name for the current iterator position.
354 *
355 * @returns IPRT status code.
356 * @param hJsonIt The JSON iterator handle.
357 * @param phJsonVal Where to store the handle to the JSON value on success.
358 * @param ppszName Where to store the object member name for an object.
359 * NULL is returned for arrays.
360 */
361RTDECL(int) RTJsonIteratorQueryValue(RTJSONIT hJsonIt, PRTJSONVAL phJsonVal, const char **ppszName);
362
363/**
364 * Advances to the next element in the referenced JSON value.
365 *
366 * @returns IPRT status code.
367 * @retval VERR_JSON_ITERATOR_END if the end for this iterator was reached.
368 * @param hJsonIt The JSON iterator handle.
369 */
370RTDECL(int) RTJsonIteratorNext(RTJSONIT hJsonIt);
371
372/**
373 * Frees a given JSON iterator.
374 *
375 * @param hJsonIt The JSON iterator to free.
376 */
377RTDECL(void) RTJsonIteratorFree(RTJSONIT hJsonIt);
378
379RT_C_DECLS_END
380
381/** @} */
382
383#endif /* !IPRT_INCLUDED_json_h */
384
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette