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>
12 * json_out_new - allocate a json_out stream.
13 * @ctx: the tal_context to allocate from, or NULL
15 * Returns NULL if tal allocation fails.
17 struct json_out *json_out_new(const tal_t *ctx);
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).
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.
29 #define json_out_call_on_move(jout, cb, arg) \
30 json_out_call_on_move_((jout), \
31 typesafe_cb_preargs(void, void *, \
37 void json_out_call_on_move_(struct json_out *jout,
38 void (*cb)(struct json_out *jout, ptrdiff_t delta,
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.
47 struct json_out *json_out_dup(const tal_t *ctx, const struct json_out *src);
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.
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.
59 bool json_out_start(struct json_out *jout, const char *fieldname, char type);
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.
66 * Returns true unless tal_resize() fails.
68 * Literally writes ']' or '}', keeping track of whether we need to append
71 bool json_out_end(struct json_out *jout, char type);
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
80 * Returns true unless tal_resize() fails.
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.
87 * If the resulting string requires escaping, and @quote is true, we
91 bool json_out_add(struct json_out *jout,
92 const char *fieldname,
94 const char *fmt, ...);
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.
104 * See json_out_add() above.
106 bool json_out_addv(struct json_out *jout,
107 const char *fieldname,
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).
118 * Equivalent to json_out_add(@jout, @fieldname, true, "%s", @str);
120 bool json_out_addstr(struct json_out *jout,
121 const char *fieldname,
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.
130 * @fieldname must not need JSON escaping. Returns a direct pointer into
131 * the @extra bytes, or NULL if tal_resize() fails.
133 * This allows you to write your own efficient type-specific helpers.
135 char *json_out_member_direct(struct json_out *jout,
136 const char *fieldname, size_t extra);
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.
143 * This lets you access the json_out stream directly, to save a copy,
144 * if you know exactly how much you will write.
146 * Returns a pointer to @len bytes at the end of @jout, or NULL if
147 * tal_resize() fails.
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.
153 char *json_out_direct(struct json_out *jout, size_t extra);
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.
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
166 * Note that it will call json_out_contents(@src), so it expects that
167 * object to be unconsumed.
169 * Returns false if tal_resize() fails.
171 bool json_out_add_splice(struct json_out *jout,
172 const char *fieldname,
173 const struct json_out *src);
176 * json_out_finished - assert that the json buffer is finished.
177 * @jout: the json_out object written to.
179 * This simply causes internal assertions that all arrays and objects are
180 * finished. If CCAN_JSON_OUT_DEBUG is defined, it does sanity checks.
182 * This also resets the empty flag, so there will be no comma added if
183 * another JSON object is written.
185 void json_out_finished(struct json_out *jout);
188 * json_out_contents - read contents from json_out stream.
189 * @jout: the json_out object we want to read from.
190 * @len: set to the length of the buffer returned.
192 * This returns a pointer into the JSON written so far. Returns NULL
193 * and sets @len to 0 if there's nothing left in the buffer.
195 const char *json_out_contents(const struct json_out *jout, size_t *len);
198 * json_out_consume - discard contents from json_out stream.
199 * @jout: the json_out object we read from.
200 * @len: the length to consume (must be <= @len from json_out_contents)
202 void json_out_consume(struct json_out *jout, size_t len);
203 #endif /* CCAN_JSON_OUT_H */