json_visit.h

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