json_out: pass through OOM failures.
[ccan] / 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 */