1 
2 #ifndef _json_c_json_visit_h_
3 #define _json_c_json_visit_h_
4 
5 /**
6  * @file
7  * @brief Methods for walking a tree of objects.
8  */
9 #include "json_object.h"
10 
11 typedef int (json_c_visit_userfunc)(json_object *jso, int flags,
12                                      json_object *parent_jso,                                                        const char *jso_key,
13                                      size_t *jso_index, void *userarg);
14 
15 /**
16  * Visit each object in the JSON hierarchy starting at jso.
17  * For each object, userfunc is called, passing the object and userarg.
18  * If the object has a parent (i.e. anything other than jso itself)
19  * its parent will be passed as parent_jso, and either jso_key or jso_index
20  * will be set, depending on whether the parent is an object or an array.
21  *
22  * Nodes will be visited depth first, but containers (arrays and objects)
23  * will be visited twice, the second time with JSON_C_VISIT_SECOND set in
24  * flags.
25  *
26  * userfunc must return one of the defined return values, to indicate
27  * whether and how to continue visiting nodes, or one of various ways to stop.
28  *
29  * Returns 0 if nodes were visited successfully, even if some were
30  *  intentionally skipped due to what userfunc returned.
31  * Returns <0 if an error occurred during iteration, including if
32  *  userfunc returned JSON_C_VISIT_RETURN_ERROR.
33  */
34 JSON_EXPORT int json_c_visit(json_object *jso, int future_flags,
35                  json_c_visit_userfunc *userfunc, void *userarg);
36 
37 /**
38  * Passed to json_c_visit_userfunc as one of the flags values to indicate
39  * that this is the second time a container (array or object) is being
40  * called, after all of it's members have been iterated over.
41  */
42 #define JSON_C_VISIT_SECOND  0x02
43 
44 /**
45  * This json_c_visit_userfunc return value indicates that iteration
46  * should proceed normally.
47  */
48 #define JSON_C_VISIT_RETURN_CONTINUE 0
49 
50 
51 /**
52  * This json_c_visit_userfunc return value indicates that iteration
53  * over the members of the current object should be skipped.
54  * If the current object isn't a container (array or object), this
55  * is no different than JSON_C_VISIT_RETURN_CONTINUE.
56  */
57 #define JSON_C_VISIT_RETURN_SKIP 7547
58 
59 /**
60  * This json_c_visit_userfunc return value indicates that iteration
61  * of the fields/elements of the <b>containing</b> object should stop
62  * and continue "popped up" a level of the object hierarchy.
63  * For example, returning this when handling arg will result in
64  * arg3 and any other fields being skipped.   The next call to userfunc
65  * will be the JSON_C_VISIT_SECOND call on "foo", followed by a userfunc
66  * call on "bar".
67  * <pre>
68  * {
69  *   "foo": {
70  *     "arg1": 1,
71  *     "arg2": 2,
72  *     "arg3": 3,
73  *     ...
74  *   },
75  *   "bar": {
76  *     ...
77  *   }
78  * }
79  * </pre>
80  */
81 #define JSON_C_VISIT_RETURN_POP 767
82 
83 /**
84  * This json_c_visit_userfunc return value indicates that iteration
85  * should stop immediately, and cause json_c_visit to return success.
86  */
87 #define JSON_C_VISIT_RETURN_STOP 7867
88 
89 /**
90  * This json_c_visit_userfunc return value indicates that iteration
91  * should stop immediately, and cause json_c_visit to return an error.
92  */
93 #define JSON_C_VISIT_RETURN_ERROR -1
94 
95 #endif /* _json_c_json_visit_h_ */
96