1/*
2 * libwebsockets - small server side websockets and web server implementation
3 *
4 * Copyright (C) 2010 - 2025 Andy Green <andy@warmcat.com>
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22 * IN THE SOFTWARE.
23 */
24
25#if defined(LWS_WITH_STRUCT_SQLITE3)
26#include <sqlite3.h>
27#endif
28
29/*
30 * lws_struct provides apis for these transforms
31 *
32 * sqlite3 <-> C struct <-> JSON
33 *
34 * in a "structured" way.
35 */
36
37typedef enum {
38 LSMT_SIGNED,
39 LSMT_UNSIGNED,
40 LSMT_BOOLEAN,
41 LSMT_STRING_CHAR_ARRAY,
42 LSMT_STRING_PTR,
43 LSMT_LIST,
44 LSMT_CHILD_PTR,
45 LSMT_SCHEMA,
46 LSMT_BLOB_PTR,
47
48} lws_struct_map_type_eum;
49
50typedef struct lejp_collation {
51 struct lws_dll2 chunks;
52 int len;
53 char buf[LEJP_STRING_CHUNK + 1];
54} lejp_collation_t;
55
56typedef struct lws_struct_map {
57 const char *colname;
58 const struct lws_struct_map *child_map;
59 lejp_callback lejp_cb;
60 size_t ofs; /* child dll2; points to dll2_owner */
61 size_t aux;
62 size_t ofs_clist;
63 size_t child_map_size;
64 lws_struct_map_type_eum type;
65 char json_only;
66} lws_struct_map_t;
67
68typedef int (*lws_struct_args_cb)(void *obj, void *cb_arg);
69
70typedef struct lws_struct_args {
71 const lws_struct_map_t *map_st[LEJP_MAX_PARSING_STACK_DEPTH];
72 lws_struct_args_cb cb;
73 struct lwsac *ac;
74 void *cb_arg;
75 void *dest;
76
77 size_t dest_len;
78 size_t toplevel_dll2_ofs;
79 size_t map_entries_st[LEJP_MAX_PARSING_STACK_DEPTH];
80 size_t ac_block_size;
81 int subtype;
82
83 int top_schema_index;
84
85 /*
86 * temp ac used to collate unknown possibly huge strings before final
87 * allocation and copy
88 */
89 struct lwsac *ac_chunks;
90 struct lws_dll2_owner chunks_owner;
91 size_t chunks_length;
92} lws_struct_args_t;
93
94/*
95 * These types apply to both Sqlite3 and JSON representations
96 */
97
98#define LSM_SIGNED(type, name, qname) \
99 { \
100 qname, \
101 NULL, \
102 NULL, \
103 offsetof(type, name), \
104 sizeof ((type *)0)->name, \
105 0, \
106 0, \
107 LSMT_SIGNED, \
108 0 \
109 }
110
111#define LSM_UNSIGNED(type, name, qname) \
112 { \
113 qname, \
114 NULL, \
115 NULL, \
116 offsetof(type, name), \
117 sizeof ((type *)0)->name, \
118 0, \
119 0, \
120 LSMT_UNSIGNED, \
121 0, \
122 }
123
124#define LSM_BOOLEAN(type, name, qname) \
125 { \
126 qname, \
127 NULL, \
128 NULL, \
129 offsetof(type, name), \
130 sizeof ((type *)0)->name, \
131 0, \
132 0, \
133 LSMT_BOOLEAN, \
134 0, \
135 }
136
137#define LSM_CARRAY(type, name, qname) \
138 { \
139 qname, \
140 NULL, \
141 NULL, \
142 offsetof(type, name), \
143 sizeof (((type *)0)->name), \
144 0, \
145 0, \
146 LSMT_STRING_CHAR_ARRAY, \
147 0, \
148 }
149
150#define LSM_STRING_PTR(type, name, qname) \
151 { \
152 qname, \
153 NULL, \
154 NULL, \
155 offsetof(type, name), \
156 sizeof (((type *)0)->name), \
157 0, \
158 0, \
159 LSMT_STRING_PTR, \
160 0 \
161 }
162
163#define LSM_LIST(ptype, pname, ctype, cname, lejp_cb, cmap, qname) \
164 { \
165 qname, \
166 cmap, \
167 lejp_cb, \
168 offsetof(ptype, pname), \
169 sizeof (ctype), \
170 offsetof(ctype, cname), \
171 LWS_ARRAY_SIZE(cmap), \
172 LSMT_LIST, \
173 0, \
174 }
175
176#define LSM_CHILD_PTR(ptype, pname, ctype, lejp_cb, cmap, qname) \
177 { \
178 qname, \
179 cmap, \
180 lejp_cb, \
181 offsetof(ptype, pname), \
182 sizeof (ctype), \
183 0, \
184 LWS_ARRAY_SIZE(cmap), \
185 LSMT_CHILD_PTR, \
186 0, \
187 }
188
189#define LSM_SCHEMA(ctype, lejp_cb, map, schema_name) \
190 { \
191 schema_name, \
192 map, \
193 lejp_cb, \
194 0, \
195 sizeof (ctype), \
196 0, \
197 LWS_ARRAY_SIZE(map), \
198 LSMT_SCHEMA, \
199 0, \
200 }
201
202#define LSM_SCHEMA_DLL2(ctype, cdll2mem, lejp_cb, map, schema_name) \
203 { \
204 schema_name, \
205 map, \
206 lejp_cb, \
207 offsetof(ctype, cdll2mem), \
208 sizeof (ctype), \
209 0, \
210 LWS_ARRAY_SIZE(map), \
211 LSMT_SCHEMA, \
212 0, \
213 }
214
215/*
216 * These types are the same as above, but they are JSON-ONLY; they
217 * do not apply to sqlite3, do not appear as columns in the table etc.
218 * This is useful when these values are dynamically added to the
219 * struct before creating the JSON representation and do not directly
220 * use information stored in the table associated with the sqlite3
221 * representation
222 */
223
224#define LSM_JO_SIGNED(type, name, qname) \
225 { \
226 qname, \
227 NULL, \
228 NULL, \
229 offsetof(type, name), \
230 sizeof ((type *)0)->name, \
231 0, \
232 0, \
233 LSMT_SIGNED, \
234 1 \
235 }
236
237#define LSM_JO_UNSIGNED(type, name, qname) \
238 { \
239 qname, \
240 NULL, \
241 NULL, \
242 offsetof(type, name), \
243 sizeof ((type *)0)->name, \
244 0, \
245 0, \
246 LSMT_UNSIGNED, \
247 1, \
248 }
249
250#define LSM_JO_BOOLEAN(type, name, qname) \
251 { \
252 qname, \
253 NULL, \
254 NULL, \
255 offsetof(type, name), \
256 sizeof ((type *)0)->name, \
257 0, \
258 0, \
259 LSMT_BOOLEAN, \
260 1, \
261 }
262
263#define LSM_JO_CARRAY(type, name, qname) \
264 { \
265 qname, \
266 NULL, \
267 NULL, \
268 offsetof(type, name), \
269 sizeof (((type *)0)->name), \
270 0, \
271 0, \
272 LSMT_STRING_CHAR_ARRAY, \
273 1, \
274 }
275
276#define LSM_JO_STRING_PTR(type, name, qname) \
277 { \
278 qname, \
279 NULL, \
280 NULL, \
281 offsetof(type, name), \
282 sizeof (((type *)0)->name), \
283 0, \
284 0, \
285 LSMT_STRING_PTR, \
286 1, \
287 }
288
289#define LSM_JO_LIST(ptype, pname, ctype, cname, lejp_cb, cmap, qname) \
290 { \
291 qname, \
292 cmap, \
293 lejp_cb, \
294 offsetof(ptype, pname), \
295 sizeof (ctype), \
296 offsetof(ctype, cname), \
297 LWS_ARRAY_SIZE(cmap), \
298 LSMT_LIST, \
299 1, \
300 }
301
302#define LSM_JO_CHILD_PTR(ptype, pname, ctype, lejp_cb, cmap, qname) \
303 { \
304 qname, \
305 cmap, \
306 lejp_cb, \
307 offsetof(ptype, pname), \
308 sizeof (ctype), \
309 0, \
310 LWS_ARRAY_SIZE(cmap), \
311 LSMT_CHILD_PTR, \
312 1, \
313 }
314
315#define LSM_JO_SCHEMA(ctype, lejp_cb, map, schema_name) \
316 { \
317 schema_name, \
318 map, \
319 lejp_cb, \
320 0, \
321 sizeof (ctype), \
322 0, \
323 LWS_ARRAY_SIZE(map), \
324 LSMT_SCHEMA, \
325 1, \
326 }
327
328#define LSM_JO_SCHEMA_DLL2(ctype, cdll2mem, lejp_cb, map, schema_name) \
329 { \
330 schema_name, \
331 map, \
332 lejp_cb, \
333 offsetof(ctype, cdll2mem), \
334 sizeof (ctype), \
335 0, \
336 LWS_ARRAY_SIZE(map), \
337 LSMT_SCHEMA, \
338 1, \
339 }
340
341
342/*
343 * This is just used to create the table schema, it is not part of serialization
344 * and deserialization. Blobs should be accessed separately.
345 */
346
347#define LSM_BLOB_PTR(type, blobptr_name, qname) \
348 { \
349 qname, /* JSON item, or sqlite3 column name */ \
350 NULL, \
351 NULL, \
352 offsetof(type, blobptr_name), /* member that points to blob */ \
353 sizeof (((type *)0)->blobptr_name), /* size of blob pointer */ \
354 0, /* member holding blob len */ \
355 0, /* size of blob length member */ \
356 LSMT_BLOB_PTR, \
357 0, \
358 }
359
360typedef struct lws_struct_serialize_st {
361 const struct lws_dll2 *dllpos;
362 const lws_struct_map_t *map;
363 const char *obj;
364 size_t map_entries;
365 size_t map_entry;
366 size_t size;
367 char subsequent;
368 char idt;
369} lws_struct_serialize_st_t;
370
371enum {
372 LSSERJ_FLAG_PRETTY = (1 << 0),
373 LSSERJ_FLAG_OMIT_SCHEMA = (1 << 1)
374};
375
376typedef struct lws_struct_serialize {
377 lws_struct_serialize_st_t st[LEJP_MAX_PARSING_STACK_DEPTH];
378
379 size_t offset;
380 size_t remaining;
381
382 int sp;
383 int flags;
384} lws_struct_serialize_t;
385
386typedef enum {
387 LSJS_RESULT_CONTINUE,
388 LSJS_RESULT_FINISH,
389 LSJS_RESULT_ERROR
390} lws_struct_json_serialize_result_t;
391
392/*
393 * JSON -> C struct
394 */
395
396/**
397 * lws_struct_json_init_parse(): prepare to translate JSON to C struct
398 *
399 * \p ctx: JSON parse context
400 * \p cb: the parsing callback
401 * \p user: an opaque user pointer
402 *
403 * Returns 0 if OK else nonzero for error.
404 */
405LWS_VISIBLE LWS_EXTERN int
406lws_struct_json_init_parse(struct lejp_ctx *ctx, lejp_callback cb,
407 void *user);
408
409LWS_VISIBLE LWS_EXTERN signed char
410lws_struct_schema_only_lejp_cb(struct lejp_ctx *ctx, char reason);
411
412LWS_VISIBLE LWS_EXTERN signed char
413lws_struct_default_lejp_cb(struct lejp_ctx *ctx, char reason);
414
415/*
416 * C struct -> JSON
417 */
418
419/**
420 * lws_struct_json_serialize_create(): create a C struct -> JSON renderer
421 *
422 * \p map: the map of members and types
423 * \p map_entries: the count of entries in the map
424 * \p flags: JSON parsing options
425 * \p ptoplevel: the start of the C struct to render
426 *
427 * Returns an object that manages the stateful translation of a C struct
428 * to a JSON representation.
429 *
430 * Returns a pointer to the object, or NULL on failure.
431 */
432LWS_VISIBLE LWS_EXTERN lws_struct_serialize_t *
433lws_struct_json_serialize_create(const lws_struct_map_t *map,
434 size_t map_entries, int flags,
435 const void *ptoplevel);
436
437/**
438 * lws_struct_json_serialize(): output the next buffer of JSON
439 *
440 * \p js: the management object
441 * \p buf: the output fragment buffer
442 * \p len: the max size of \p buf
443 * \p written: pointer to a size_t to be set to the valid about in buf on exit
444 *
445 * This emits the next section of JSON for the object being represented
446 * by \p js. You must refer to the return from the function to understand
447 * what is in the buffer on exit, LSJS_RESULT_ERROR indicates the function
448 * failed and the buffer is invalid, LSJS_RESULT_CONTINUE indicates the
449 * buffer is valid, but is a fragment of the full representation and you
450 * should call this function again later to get another fragment, and
451 * LSJS_RESULT_FINISH indicates the buffer is valid and is the last part
452 * of the representation.
453 *
454 * After seeing LSJS_RESULT_FINISH or LSJS_RESULT_ERROR you should clean
455 * up \js by calling lws_struct_json_serialize_destroy() on it
456 */
457LWS_VISIBLE LWS_EXTERN lws_struct_json_serialize_result_t
458lws_struct_json_serialize(lws_struct_serialize_t *js, uint8_t *buf,
459 size_t len, size_t *written);
460
461/**
462 * lws_struct_json_serialize_destroy(): destruct a C struct -> JSON renderer
463 *
464 * \p pjs: pointer to the object to be destroyed
465 *
466 * The object to be destroyed should have been returned originally from
467 * lws_struct_json_serialize_create()
468 */
469LWS_VISIBLE LWS_EXTERN void
470lws_struct_json_serialize_destroy(lws_struct_serialize_t **pjs);
471
472/*
473 * Sqlite3
474 */
475
476typedef struct sqlite3 sqlite3;
477
478/**
479 * lws_struct_sq3_open(): open an sqlite3 database
480 *
481 * \p context: the lws_context
482 * \p sqlite3_path: the filepath to the database file
483 * \p create_if_missing: flag to control if the database is created or not if absent
484 * \p pdb: pointer to an sqlite3 * to be set to the database handle if successful
485 *
486 * Returns 0 for success, *pdb is valid, else nonzero for failure
487 */
488LWS_VISIBLE LWS_EXTERN int
489lws_struct_sq3_open(struct lws_context *context, const char *sqlite3_path,
490 char create_if_missing, sqlite3 **pdb);
491
492/*
493 * lws_struct_sq3_close(): close db handle
494 *
495 * \p pdb: pointer to sqlite3 * that will be set to NULL
496 *
497 * *pdb will be closed and set to NULL.
498 */
499LWS_VISIBLE LWS_EXTERN int
500lws_struct_sq3_close(sqlite3 **pdb);
501
502/*
503 * lws_struct_sq3_create_table(): ensure table exists with correct schema
504 *
505 * \p pdb: sqlite3 database handle
506 * \p schema: map describing table name and schema details
507 */
508
509LWS_VISIBLE LWS_EXTERN int
510lws_struct_sq3_create_table(sqlite3 *pdb, const lws_struct_map_t *schema);
511
512/*
513 * struct -> sqlite3 (list)
514 */
515
516/**
517 * lws_struct_sq3_serialize(): store objects pointed to by owner in the db
518 *
519 * \p pdb: the open sqlite3 db
520 * \p schema: the schema (and db table) to use
521 * \p owner: the list of objects to store to the db table
522 * \p manual_idx: the starting index for the objects
523 *
524 */
525LWS_VISIBLE LWS_EXTERN int
526lws_struct_sq3_serialize(sqlite3 *pdb, const lws_struct_map_t *schema,
527 lws_dll2_owner_t *owner, uint32_t manual_idx);
528
529/*
530 * struct -> sqlite3 (single)
531 */
532
533
534LWS_VISIBLE LWS_EXTERN int
535lws_struct_sq3_update(sqlite3 *pdb, const char *table,
536 const lws_struct_map_t *map, size_t map_entries, const void *data,
537 const char *where_col);
538
539LWS_VISIBLE LWS_EXTERN int
540lws_struct_sq3_upsert(sqlite3 *pdb, const char *table,
541 const lws_struct_map_t *map, size_t map_entries, const void *data,
542 const char *where_col);
543
544/*
545 * sqlite3 -> struct(s) in lwsac
546 */
547
548LWS_VISIBLE LWS_EXTERN int
549lws_struct_sq3_deserialize(sqlite3 *pdb, const char *filter, const char *order,
550 const lws_struct_map_t *schema, lws_dll2_owner_t *o,
551 struct lwsac **ac, int start, int limit);
552
553
554