source: trunk/libtransmission/variant.h

Last change on this file was 14724, checked in by jordan, 5 years ago

use '#pragma once' instead of #ifndef..#define..#endif guards

  • Property svn:keywords set to Date Rev Author Id
File size: 13.9 KB
Line 
1/*
2 * This file Copyright (C) 2008-2014 Mnemosyne LLC
3 *
4 * It may be used under the GNU GPL versions 2 or 3
5 * or any future license endorsed by Mnemosyne LLC.
6 *
7 * $Id: variant.h 14724 2016-03-29 16:37:21Z mikedld $
8 */
9
10#pragma once
11
12#ifdef __cplusplus
13extern "C" {
14#endif
15
16#include <inttypes.h> /* for int64_t */
17#include "quark.h"
18
19struct evbuffer;
20
21struct tr_error;
22
23/**
24 * @addtogroup tr_variant Variant
25 *
26 * An object that acts like a union for
27 * integers, strings, lists, dictionaries, booleans, and floating-point numbers.
28 * The structure is named tr_variant due to the historical reason that it was
29 * originally tightly coupled with bencoded data. It currently supports
30 * being parsed from, and serialized to, both bencoded notation and json notation.
31 *
32 * @{
33 */
34
35typedef enum
36{
37  TR_STRING_TYPE_QUARK,
38  TR_STRING_TYPE_HEAP,
39  TR_STRING_TYPE_BUF
40}
41tr_string_type;
42
43/* these are PRIVATE IMPLEMENTATION details that should not be touched.
44 * I'll probably change them just to break your code! HA HA HA!
45 * it's included in the header for inlining and composition */
46struct tr_variant_string
47{
48  tr_string_type type;
49  tr_quark quark;
50  size_t len;
51  union { char buf[16]; const char * str; } str;
52};
53
54
55/* these are PRIVATE IMPLEMENTATION details that should not be touched.
56 * I'll probably change them just to break your code! HA HA HA!
57 * it's included in the header for inlining and composition */
58enum
59{
60  TR_VARIANT_TYPE_INT  = 1,
61  TR_VARIANT_TYPE_STR  = 2,
62  TR_VARIANT_TYPE_LIST = 4,
63  TR_VARIANT_TYPE_DICT = 8,
64  TR_VARIANT_TYPE_BOOL = 16,
65  TR_VARIANT_TYPE_REAL = 32
66};
67
68/* These are PRIVATE IMPLEMENTATION details that should not be touched.
69 * I'll probably change them just to break your code! HA HA HA!
70 * it's included in the header for inlining and composition */
71typedef struct tr_variant
72{
73  char type;
74
75  tr_quark key;
76
77  union
78    {
79      bool b;
80
81      double d;
82
83      int64_t i;
84
85      struct tr_variant_string s;
86
87      struct
88        {
89          size_t alloc;
90          size_t count;
91          struct tr_variant * vals;
92        } l;
93    }
94  val;
95}
96tr_variant;
97
98void  tr_variantFree (tr_variant *);
99
100/***
101****  Serialization / Deserialization
102***/
103
104typedef enum
105{
106    TR_VARIANT_FMT_BENC,
107    TR_VARIANT_FMT_JSON,
108    TR_VARIANT_FMT_JSON_LEAN /* saves bandwidth by omitting all whitespace. */
109}
110tr_variant_fmt;
111
112int tr_variantToFile (const tr_variant * variant,
113                      tr_variant_fmt     fmt,
114                      const char       * filename);
115
116char* tr_variantToStr (const tr_variant * variant,
117                       tr_variant_fmt     fmt,
118                       size_t           * len);
119
120struct evbuffer * tr_variantToBuf (const tr_variant * variant,
121                                   tr_variant_fmt     fmt);
122
123/* TR_VARIANT_FMT_JSON_LEAN and TR_VARIANT_FMT_JSON are equivalent here. */
124bool tr_variantFromFile (tr_variant       * setme,
125                         tr_variant_fmt     fmt,
126                         const char       * filename,
127                         struct tr_error ** error);
128
129/* TR_VARIANT_FMT_JSON_LEAN and TR_VARIANT_FMT_JSON are equivalent here. */
130int tr_variantFromBuf (tr_variant     * setme,
131                       tr_variant_fmt   fmt,
132                       const void     * buf,
133                       size_t           buflen,
134                       const char     * optional_source,
135                       const char    ** setme_end);
136
137static inline int
138tr_variantFromBenc (tr_variant * setme,
139                    const void * buf,
140                    size_t       buflen)
141{
142  return tr_variantFromBuf (setme, TR_VARIANT_FMT_BENC,
143                            buf, buflen, NULL, NULL);
144}
145static inline int
146tr_variantFromBencFull (tr_variant  * setme,
147                        const void  * buf,
148                        size_t        buflen,
149                        const char  * source,
150                        const char ** setme_end)
151{
152  return tr_variantFromBuf (setme,
153                            TR_VARIANT_FMT_BENC,
154                            buf,
155                            buflen,
156                            source,
157                            setme_end);
158}
159static inline int
160tr_variantFromJsonFull (tr_variant  * setme,
161                        const void  * buf,
162                        size_t        buflen,
163                        const char  * source,
164                        const char ** setme_end)
165{
166  return tr_variantFromBuf (setme,
167                            TR_VARIANT_FMT_JSON,
168                            buf,
169                            buflen,
170                            source,
171                            setme_end);
172}
173static inline int
174tr_variantFromJson (tr_variant  * setme,
175                    const void  * buf,
176                    size_t        buflen)
177{
178  return tr_variantFromBuf (setme,
179                            TR_VARIANT_FMT_JSON,
180                            buf,
181                            buflen,
182                            NULL,
183                            NULL);
184}
185static inline bool
186tr_variantIsType (const tr_variant * b, int type)
187{
188  return (b != NULL) && (b->type == type);
189}
190
191
192/***
193****  Strings
194***/
195
196static inline bool
197tr_variantIsString (const tr_variant * b)
198{
199  return (b != NULL) && (b->type == TR_VARIANT_TYPE_STR);
200}
201
202bool         tr_variantGetStr          (const tr_variant * variant,
203                                        const char      ** setme_str,
204                                        size_t           * setme_len);
205
206void         tr_variantInitStr         (tr_variant       * initme,
207                                        const void       * str,
208                                        size_t             str_len);
209
210void         tr_variantInitQuark       (tr_variant       * initme,
211                                        const tr_quark     quark);
212
213void         tr_variantInitRaw         (tr_variant       * initme,
214                                        const void       * raw,
215                                        size_t             raw_len);
216
217bool         tr_variantGetRaw          (const tr_variant * variant,
218                                        const uint8_t   ** raw_setme,
219                                        size_t           * len_setme);
220/***
221****  Real Numbers
222***/
223
224static inline bool
225tr_variantIsReal (const tr_variant * v)
226{
227  return (v != NULL) && (v->type == TR_VARIANT_TYPE_REAL);
228}
229
230void         tr_variantInitReal        (tr_variant       * initme,
231                                        double             value);
232
233bool         tr_variantGetReal         (const tr_variant * variant,
234                                        double           * value_setme);
235
236/***
237****  Booleans
238***/
239
240static inline bool
241tr_variantIsBool (const tr_variant * v)
242{
243  return (v != NULL) && (v->type == TR_VARIANT_TYPE_BOOL);
244}
245
246void         tr_variantInitBool        (tr_variant       * initme,
247                                        bool               value);
248
249bool         tr_variantGetBool         (const tr_variant * variant,
250                                        bool             * setme);
251
252
253/***
254****  Ints
255***/
256
257static inline bool
258tr_variantIsInt (const tr_variant * v)
259{
260  return (v != NULL) && (v->type == TR_VARIANT_TYPE_INT);
261}
262
263void         tr_variantInitInt         (tr_variant       * variant,
264                                        int64_t            value);
265
266bool         tr_variantGetInt          (const tr_variant * val,
267                                        int64_t          * setme);
268
269/***
270****  Lists
271***/
272
273static inline bool
274tr_variantIsList (const tr_variant * v)
275{
276  return (v != NULL) && (v->type == TR_VARIANT_TYPE_LIST);
277}
278
279void         tr_variantInitList        (tr_variant       * list,
280                                        size_t             reserve_count);
281
282void         tr_variantListReserve     (tr_variant       * list,
283                                        size_t             reserve_count);
284
285tr_variant * tr_variantListAdd         (tr_variant       * list);
286
287tr_variant * tr_variantListAddBool     (tr_variant       * list,
288                                        bool               addme);
289
290tr_variant * tr_variantListAddInt      (tr_variant       * list,
291                                        int64_t            addme);
292
293tr_variant * tr_variantListAddReal     (tr_variant       * list,
294                                        double             addme);
295
296tr_variant * tr_variantListAddStr      (tr_variant       * list,
297                                        const char       * addme);
298
299tr_variant * tr_variantListAddQuark    (tr_variant       * list,
300                                        const tr_quark     addme);
301
302tr_variant * tr_variantListAddRaw      (tr_variant       * list,
303                                        const void       * addme_value,
304                                        size_t             addme_len);
305
306tr_variant * tr_variantListAddList     (tr_variant       * list,
307                                        size_t             reserve_count);
308
309tr_variant * tr_variantListAddDict     (tr_variant       * list,
310                                        size_t             reserve_count);
311
312tr_variant * tr_variantListChild       (tr_variant       * list,
313                                        size_t             pos);
314
315bool         tr_variantListRemove      (tr_variant       * list,
316                                        size_t             pos);
317
318size_t       tr_variantListSize        (const tr_variant * list);
319
320
321/***
322****  Dictionaries
323***/
324
325static inline bool
326tr_variantIsDict (const tr_variant * v)
327{
328  return (v != NULL) && (v->type == TR_VARIANT_TYPE_DICT);
329}
330
331void         tr_variantInitDict        (tr_variant       * initme,
332                                        size_t             reserve_count);
333
334void         tr_variantDictReserve     (tr_variant       * dict,
335                                        size_t             reserve_count);
336
337bool         tr_variantDictRemove      (tr_variant       * dict,
338                                        const tr_quark     key);
339
340tr_variant * tr_variantDictAdd         (tr_variant       * dict,
341                                        const tr_quark     key);
342
343tr_variant * tr_variantDictAddReal     (tr_variant       * dict,
344                                        const tr_quark     key,
345                                        double             value);
346
347tr_variant * tr_variantDictAddInt      (tr_variant       * dict,
348                                        const tr_quark     key,
349                                        int64_t            value);
350
351tr_variant * tr_variantDictAddBool     (tr_variant       * dict,
352                                        const tr_quark     key,
353                                        bool               value);
354
355tr_variant * tr_variantDictAddStr      (tr_variant       * dict,
356                                        const tr_quark     key,
357                                        const char       * value);
358
359tr_variant * tr_variantDictAddQuark    (tr_variant       * dict,
360                                        const tr_quark     key,
361                                        const tr_quark     val);
362
363tr_variant * tr_variantDictAddList     (tr_variant       * dict,
364                                        const tr_quark     key,
365                                        size_t             reserve_count);
366
367tr_variant * tr_variantDictAddDict     (tr_variant       * dict,
368                                        const tr_quark     key,
369                                        size_t             reserve_count);
370
371tr_variant * tr_variantDictSteal       (tr_variant       * dict,
372                                        const tr_quark     key,
373                                        tr_variant       * value);
374
375tr_variant * tr_variantDictAddRaw      (tr_variant       * dict,
376                                        const tr_quark     key,
377                                        const void       * value,
378                                        size_t             len);
379
380bool         tr_variantDictChild       (tr_variant       * dict,
381                                        size_t             pos,
382                                        tr_quark         * setme_key,
383                                        tr_variant      ** setme_value);
384
385tr_variant * tr_variantDictFind        (tr_variant       * dict,
386                                        const tr_quark     key);
387
388bool         tr_variantDictFindList    (tr_variant       * dict,
389                                        const tr_quark     key,
390                                        tr_variant      ** setme);
391
392bool         tr_variantDictFindDict    (tr_variant       * dict,
393                                        const tr_quark     key,
394                                        tr_variant      ** setme_value);
395
396bool         tr_variantDictFindInt     (tr_variant       * dict,
397                                        const tr_quark     key,
398                                        int64_t          * setme);
399
400bool         tr_variantDictFindReal    (tr_variant       * dict,
401                                        const tr_quark     key,
402                                        double           * setme);
403
404bool         tr_variantDictFindBool    (tr_variant       * dict,
405                                        const tr_quark     key,
406                                        bool             * setme);
407
408bool         tr_variantDictFindStr     (tr_variant       * dict,
409                                        const tr_quark     key,
410                                        const char      ** setme,
411                                        size_t           * len);
412
413bool         tr_variantDictFindRaw     (tr_variant       * dict,
414                                        const tr_quark     key,
415                                        const uint8_t   ** setme_raw,
416                                        size_t           * setme_len);
417
418/* this is only quasi-supported. don't rely on it too heavily outside of libT */
419void         tr_variantMergeDicts      (tr_variant       * dict_target,
420                                        const tr_variant * dict_source);
421
422/***
423****
424****
425***/
426
427/**
428***
429**/
430
431/* @} */
432
433#ifdef __cplusplus
434}
435#endif
436
Note: See TracBrowser for help on using the repository browser.