include/json-c/json_visit.h

0001
0002 #ifndef _json_c_json_visit_h_
0003 #define _json_c_json_visit_h_
0004
0005 /**
0006  * @file
0007  * @brief Methods for walking a tree of objects.
0008  */
0009 #include "json_object.h"
0010
0011 #ifdef __cplusplus
0012 extern "C" {
0013 #endif
0014
0015 typedef int(json_c_visit_userfunc)(json_object *jso, int flags, json_object *parent_jso,
0016                                    const char *jso_key, size_t *jso_index, void *userarg);
0017
0018 /**
0019  * Visit each object in the JSON hierarchy starting at jso.
0020  * For each object, userfunc is called, passing the object and userarg.
0021  * If the object has a parent (i.e. anything other than jso itself)
0022  * its parent will be passed as parent_jso, and either jso_key or jso_index
0023  * will be set, depending on whether the parent is an object or an array.
0024  *
0025  * Nodes will be visited depth first, but containers (arrays and objects)
0026  * will be visited twice, the second time with JSON_C_VISIT_SECOND set in
0027  * flags.
0028  *
0029  * userfunc must return one of the defined return values, to indicate
0030  * whether and how to continue visiting nodes, or one of various ways to stop.
0031  *
0032  * Returns 0 if nodes were visited successfully, even if some were
0033  *  intentionally skipped due to what userfunc returned.
0034  * Returns <0 if an error occurred during iteration, including if
0035  *  userfunc returned JSON_C_VISIT_RETURN_ERROR.
0036  */
0037 JSON_EXPORT int json_c_visit(json_object *jso, int future_flags, json_c_visit_userfunc *userfunc,
0038                              void *userarg);
0039
0040 /**
0041  * Passed to json_c_visit_userfunc as one of the flags values to indicate
0042  * that this is the second time a container (array or object) is being
0043  * called, after all of it's members have been iterated over.
0044  */
0045 #define JSON_C_VISIT_SECOND 0x02
0046
0047 /**
0048  * This json_c_visit_userfunc return value indicates that iteration
0049  * should proceed normally.
0050  */
0051 #define JSON_C_VISIT_RETURN_CONTINUE 0
0052
0053 /**
0054  * This json_c_visit_userfunc return value indicates that iteration
0055  * over the members of the current object should be skipped.
0056  * If the current object isn't a container (array or object), this
0057  * is no different than JSON_C_VISIT_RETURN_CONTINUE.
0058  */
0059 #define JSON_C_VISIT_RETURN_SKIP 7547
0060
0061 /**
0062  * This json_c_visit_userfunc return value indicates that iteration
0063  * of the fields/elements of the <b>containing</b> object should stop
0064  * and continue "popped up" a level of the object hierarchy.
0065  * For example, returning this when handling arg will result in
0066  * arg3 and any other fields being skipped.   The next call to userfunc
0067  * will be the JSON_C_VISIT_SECOND call on "foo", followed by a userfunc
0068  * call on "bar".
0069  * <pre>
0070  * {
0071  *   "foo": {
0072  *     "arg1": 1,
0073  *     "arg2": 2,
0074  *     "arg3": 3,
0075  *     ...
0076  *   },
0077  *   "bar": {
0078  *     ...
0079  *   }
0080  * }
0081  * </pre>
0082  */
0083 #define JSON_C_VISIT_RETURN_POP 767
0084
0085 /**
0086  * This json_c_visit_userfunc return value indicates that iteration
0087  * should stop immediately, and cause json_c_visit to return success.
0088  */
0089 #define JSON_C_VISIT_RETURN_STOP 7867
0090
0091 /**
0092  * This json_c_visit_userfunc return value indicates that iteration
0093  * should stop immediately, and cause json_c_visit to return an error.
0094  */
0095 #define JSON_C_VISIT_RETURN_ERROR -1
0096
0097 #ifdef __cplusplus
0098 }
0099 #endif
0100
0101 #endif /* _json_c_json_visit_h_ */