git.ozlabs.org Git - ccan/blob - ccan/json_out/json_out.h

   1 /* MIT (BSD) license - see LICENSE file for details */
   2 #ifndef CCAN_JSON_OUT_H
   3 #define CCAN_JSON_OUT_H
   4 #include <ccan/compiler/compiler.h>
   5 #include <ccan/tal/tal.h>
   6 #include <ccan/typesafe_cb/typesafe_cb.h>
   7 #include <stddef.h>
   8
   9 struct json_out;
  10
  11 /**
  12  * json_out_new - allocate a json_out stream.
  13  * @ctx: the tal_context to allocate from, or NULL
  14  *
  15  * Returns NULL if tal allocation fails.
  16  */
  17 struct json_out *json_out_new(const tal_t *ctx);
  18
  19 /**
  20  * json_out_call_on_move - callback for when buffer is reallocated.
  21  * @jout: the json_out object to attach to.
  22  * @cb: the callback to call.
  23  * @arg: the argument to @cb (must match type).
  24  *
  25  * A NULL @cb disables.  You can't currently have more than one callback.
  26  * The @delta argument to @cb is the difference between the old location
  27  * and the new one, and is never zero.
  28  */
  29 #define json_out_call_on_move(jout, cb, arg)                            \
  30         json_out_call_on_move_((jout),                                  \
  31                                typesafe_cb_preargs(void, void *,        \
  32                                                    (cb), (arg),         \
  33                                                    struct json_out *,   \
  34                                                    ptrdiff_t),          \
  35                                (arg))
  36
  37 void json_out_call_on_move_(struct json_out *jout,
  38                             void (*cb)(struct json_out *jout, ptrdiff_t delta,
  39                                        void *arg),
  40                             void *arg);
  41
  42 /**
  43  * json_out_dup - duplicate a json_out stream.
  44  * @ctx: the tal_context to allocate from, or NULL
  45  * @src: the json_out to copy.
  46  */
  47 struct json_out *json_out_dup(const tal_t *ctx, const struct json_out *src);
  48
  49 /**
  50  * json_out_start - start an array or object.
  51  * @jout: the json_out object to write into.
  52  * @fieldname: the fieldname, if inside an object, or NULL if inside an array.
  53  * @type: '[' or '{' to start an array or object, respectively.
  54  *
  55  * Returns true unless tal_resize() fails.
  56  * Literally writes '"@fieldname": @type' or '@type ' if fieldname is NULL.
  57  * @fieldname must not need JSON escaping.
  58  */
  59 bool json_out_start(struct json_out *jout, const char *fieldname, char type);
  60
  61 /**
  62  * json_out_end - end an array or object.
  63  * @jout: the json_out object to write into.
  64  * @type: '}' or ']' to end an array or object, respectively.
  65  *
  66  * Returns true unless tal_resize() fails.
  67  *
  68  * Literally writes ']' or '}', keeping track of whether we need to append
  69  * a comma.
  70  */
  71 bool json_out_end(struct json_out *jout, char type);
  72
  73 /**
  74  * json_out_add - add a formatted member.
  75  * @jout: the json_out object to write into.
  76  * @fieldname: optional fieldname to prepend (must not need escaping).
  77  * @quote: if true, surround fmt by " and ".
  78  * @fmt...: the printf-style format
  79  *
  80  * Returns true unless tal_resize() fails.
  81  *
  82  * If you're in an array, @fieldname must be NULL.  If you're in an
  83  * object, @fieldname must be non-NULL.  This is checked if
  84  * CCAN_JSON_OUT_DEBUG is defined.
  85  * @fieldname must not need JSON escaping.
  86  *
  87  * If the resulting string requires escaping, and @quote is true, we
  88  * call json_escape().
  89  */
  90 PRINTF_FMT(4,5)
  91 bool json_out_add(struct json_out *jout,
  92                   const char *fieldname,
  93                   bool quote,
  94                   const char *fmt, ...);
  95
  96 /**
  97  * json_out_addv - add a formatted member (vararg variant)
  98  * @jout: the json_out object to write into.
  99  * @fieldname: optional fieldname to prepend.
 100  * @quote: if true, surround fmt by " and ".
 101  * @fmt: the printf-style format
 102  * @ap: the argument list.
 103  *
 104  * See json_out_add() above.
 105  */
 106 bool json_out_addv(struct json_out *jout,
 107                    const char *fieldname,
 108                    bool quote,
 109                    const char *fmt,
 110                    va_list ap);
 111
 112 /**
 113  * json_out_addstr - convenience helper to add a string field.
 114  * @jout: the json_out object to write into.
 115  * @fieldname: optional fieldname to prepend.
 116  * @str: the string to add (must not be NULL).
 117  *
 118  * Equivalent to json_out_add(@jout, @fieldname, true, "%s", @str);
 119  */
 120 bool json_out_addstr(struct json_out *jout,
 121                      const char *fieldname,
 122                      const char *str);
 123
 124 /**
 125  * json_out_member_direct - add a field, with direct access.
 126  * @jout: the json_out object to write into.
 127  * @fieldname: optional fieldname to prepend.
 128  * @extra: how many bytes to allocate.
 129  *
 130  * @fieldname must not need JSON escaping.  Returns a direct pointer into
 131  * the @extra bytes, or NULL if tal_resize() fails.
 132  *
 133  * This allows you to write your own efficient type-specific helpers.
 134  */
 135 char *json_out_member_direct(struct json_out *jout,
 136                              const char *fieldname, size_t extra);
 137
 138 /**
 139  * json_out_direct - make room in output and access directly.
 140  * @jout: the json_out object to write into.
 141  * @len: the length to allocate.
 142  *
 143  * This lets you access the json_out stream directly, to save a copy,
 144  * if you know exactly how much you will write.
 145  *
 146  * Returns a pointer to @len bytes at the end of @jout, or NULL if
 147  * tal_resize() fails.
 148  *
 149  * This is dangerous, since it doesn't automatically prepend a ","
 150  * like the internal logic does, but can be used (carefully) to add
 151  * entire objects, or whitespace.
 152  */
 153 char *json_out_direct(struct json_out *jout, size_t extra);
 154
 155 /**
 156  * json_out_add_splice - copy a field from another json_out.
 157  * @jout: the json_out object to write into.
 158  * @fieldname: optional fieldname to prepend.
 159  * @src: the json_out object to copy from.
 160  *
 161  * This asserts that @src is well-formed (as per json_out_finished()),
 162  * then places it into @jout with optional @fieldname prepended.  This
 163  * can be used to assemble sub-objects for your JSON and then copy
 164  * them in.
 165  *
 166  * Note that it will call json_out_contents(@src), so it expects that
 167  * object to be unconsumed.
 168  *
 169  * Returns false if tal_resize() fails.
 170  */
 171 bool json_out_add_splice(struct json_out *jout,
 172                          const char *fieldname,
 173                          const struct json_out *src);
 174
 175 /**
 176  * json_out_finished - assert that the json buffer is finished.
 177  * @jout: the json_out object written to.
 178  *
 179  * This simply causes internal assertions that all arrays and objects are
 180  * finished.  It needs CCAN_JSON_OUT_DEBUG defined to have any effect.
 181  */
 182 void json_out_finished(const struct json_out *jout);
 183
 184 /**
 185  * json_out_contents - read contents from json_out stream.
 186  * @jout: the json_out object we want to read from.
 187  * @len: set to the length of the buffer returned.
 188  *
 189  * This returns a pointer into the JSON written so far.  Returns NULL
 190  * and sets @len to 0 if there's nothing left in the buffer.
 191  */
 192 const char *json_out_contents(const struct json_out *jout, size_t *len);
 193
 194 /**
 195  * json_out_consume - discard contents from json_out stream.
 196  * @jout: the json_out object we read from.
 197  * @len: the length to consume (must be <= @len from json_out_contents)
 198  */
 199 void json_out_consume(struct json_out *jout, size_t len);
 200 #endif /* CCAN_JSON_OUT_H */