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