release/src/router/transmission/libtransmission/bencode.h

   1 /*
   2  * This file Copyright (C) Mnemosyne LLC
   3  *
   4  * This file is licensed by the GPL version 2. Works owned by the
   5  * Transmission project are granted a special exemption to clause 2(b)
   6  * so that the bulk of its code can remain under the MIT license.
   7  * This exemption does not extend to derived works not owned by
   8  * the Transmission project.
   9  *
  10  * $Id: bencode.h 11709 2011-01-19 13:48:47Z jordan $
  11  */
  12
  13 #ifndef TR_BENCODE_H
  14 #define TR_BENCODE_H 1
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif
  19
  20 #include <inttypes.h> /* for int64_t */
  21
  22 struct evbuffer;
  23
  24 /**
  25  * @addtogroup tr_benc Variant
  26  *
  27  * An object that acts like a union for
  28  * integers, strings, lists, dictionaries, booleans, and floating-point numbers.
  29  * The structure is named tr_benc due to the historical reason that it was
  30  * originally tightly coupled with bencoded data. It currently supports
  31  * being parsed from, and serialized to, both bencoded notation and json notation.
  32  *
  33  * @{
  34  */
  35
  36 /* these are PRIVATE IMPLEMENTATION details that should not be touched.
  37  * I'll probably change them just to break your code! HA HA HA!
  38  * it's included in the header for inlining and composition */
  39 enum
  40 {
  41     TR_TYPE_INT  = 1,
  42     TR_TYPE_STR  = 2,
  43     TR_TYPE_LIST = 4,
  44     TR_TYPE_DICT = 8,
  45     TR_TYPE_BOOL = 16,
  46     TR_TYPE_REAL = 32
  47 };
  48
  49 /* These are PRIVATE IMPLEMENTATION details that should not be touched.
  50  * I'll probably change them just to break your code! HA HA HA!
  51  * it's included in the header for inlining and composition */
  52 typedef struct tr_benc
  53 {
  54     union
  55     {
  56         uint8_t b; /* bool type */
  57
  58         double d;  /* double type */
  59
  60         int64_t i; /* int type */
  61
  62         struct /* string type */
  63         {
  64             size_t len; /* the string length */
  65             union {
  66                 char buf[16]; /* local buffer for short strings */
  67                 char * ptr; /* alloc'ed pointer for long strings */
  68             } str;
  69         } s;
  70
  71         struct /* list & dict types */
  72         {
  73             struct tr_benc * vals; /* nodes */
  74             size_t alloc; /* nodes allocated */
  75             size_t count; /* nodes used */
  76         } l;
  77     } val;
  78
  79     char type;
  80 } tr_benc;
  81
  82 /***
  83 ****
  84 ***/
  85
  86 int       tr_bencParse( const void     * buf,
  87                         const void     * bufend,
  88                         tr_benc        * setme_benc,
  89                         const uint8_t ** setme_end );
  90
  91 int       tr_bencLoad( const void   * buf,
  92                        size_t         buflen,
  93                        tr_benc      * setme_benc,
  94                        char        ** setme_end );
  95
  96 void      tr_bencFree( tr_benc * );
  97
  98 void      tr_bencInitStr( tr_benc *, const void * str, int str_len );
  99
 100 void      tr_bencInitRaw( tr_benc *, const void * raw, size_t raw_len );
 101
 102 void      tr_bencInitInt( tr_benc *, int64_t num );
 103
 104 int       tr_bencInitDict( tr_benc *, size_t reserveCount );
 105
 106 int       tr_bencInitList( tr_benc *, size_t reserveCount );
 107
 108 void      tr_bencInitBool( tr_benc *, int value );
 109
 110 void      tr_bencInitReal( tr_benc *, double value );
 111
 112 /***
 113 ****  Serialization / Deserialization
 114 ***/
 115
 116 typedef enum
 117 {
 118     TR_FMT_BENC,
 119     TR_FMT_JSON,
 120     TR_FMT_JSON_LEAN /* saves bandwidth by omitting all whitespace. */
 121 }
 122 tr_fmt_mode;
 123
 124 int tr_bencToFile( const tr_benc *, tr_fmt_mode, const char * filename );
 125
 126 char* tr_bencToStr( const tr_benc *, tr_fmt_mode, int * len );
 127
 128 void tr_bencToBuf( const tr_benc *, tr_fmt_mode, struct evbuffer * );
 129
 130 /* TR_FMT_JSON_LEAN and TR_FMT_JSON are equivalent in this function. */
 131 int tr_bencLoadFile( tr_benc * setme, tr_fmt_mode, const char * filename );
 132
 133 /***
 134 ****
 135 ***/
 136
 137 int tr_bencListReserve( tr_benc *, size_t reserveCount );
 138
 139 tr_benc * tr_bencListAdd( tr_benc * );
 140
 141 tr_benc * tr_bencListAddBool( tr_benc *, tr_bool val );
 142
 143 tr_benc * tr_bencListAddInt( tr_benc *, int64_t val );
 144
 145 tr_benc * tr_bencListAddReal( tr_benc *, double val );
 146
 147 tr_benc * tr_bencListAddStr( tr_benc *, const char * val );
 148
 149 tr_benc * tr_bencListAddRaw( tr_benc *, const uint8_t * val, size_t len );
 150
 151 tr_benc * tr_bencListAddList( tr_benc *, size_t reserveCount );
 152
 153 tr_benc * tr_bencListAddDict( tr_benc *, size_t reserveCount );
 154
 155 size_t    tr_bencListSize( const tr_benc * list );
 156
 157 tr_benc * tr_bencListChild( tr_benc * list, size_t n );
 158
 159 int       tr_bencListRemove( tr_benc *, size_t n );
 160
 161 /***
 162 ****
 163 ***/
 164
 165 int       tr_bencDictReserve( tr_benc *, size_t reserveCount );
 166
 167 int       tr_bencDictRemove( tr_benc *, const char * key );
 168
 169 tr_benc * tr_bencDictAdd( tr_benc *, const char * key );
 170
 171 tr_benc * tr_bencDictAddReal( tr_benc *, const char * key, double );
 172
 173 tr_benc * tr_bencDictAddInt( tr_benc *, const char * key, int64_t );
 174
 175 tr_benc * tr_bencDictAddBool( tr_benc *, const char * key, tr_bool );
 176
 177 tr_benc * tr_bencDictAddStr( tr_benc *, const char * key, const char * );
 178
 179 tr_benc * tr_bencDictAddList( tr_benc *, const char * key, size_t reserve );
 180
 181 tr_benc * tr_bencDictAddDict( tr_benc *, const char * key, size_t reserve );
 182
 183 tr_benc * tr_bencDictAddRaw( tr_benc *, const char * key,
 184                              const void * raw, size_t rawlen );
 185
 186 tr_bool   tr_bencDictChild( tr_benc *, size_t i, const char ** key, tr_benc ** val );
 187
 188 tr_benc*  tr_bencDictFind( tr_benc *, const char * key );
 189
 190 tr_bool   tr_bencDictFindList( tr_benc *, const char * key, tr_benc ** setme );
 191
 192 tr_bool   tr_bencDictFindDict( tr_benc *, const char * key, tr_benc ** setme );
 193
 194 tr_bool   tr_bencDictFindInt( tr_benc *, const char * key, int64_t * setme );
 195
 196 tr_bool   tr_bencDictFindReal( tr_benc *, const char * key, double * setme );
 197
 198 tr_bool   tr_bencDictFindBool( tr_benc *, const char * key, tr_bool * setme );
 199
 200 tr_bool   tr_bencDictFindStr( tr_benc *, const char * key, const char ** setme );
 201
 202 tr_bool   tr_bencDictFindRaw( tr_benc *, const char * key,
 203                               const uint8_t ** setme_raw, size_t * setme_len );
 204
 205 /***
 206 ****
 207 ***/
 208
 209 /** @brief Get an int64_t from a variant object
 210     @return TRUE if successful, or FALSE if the variant could not be represented as an int64_t  */
 211 tr_bool   tr_bencGetInt( const tr_benc * val, int64_t * setme );
 212
 213 /** @brief Get an string from a variant object
 214     @return TRUE if successful, or FALSE if the variant could not be represented as a string  */
 215 tr_bool   tr_bencGetStr( const tr_benc * val, const char ** setme );
 216
 217 /** @brief Get a boolean from a variant object
 218     @return TRUE if successful, or FALSE if the variant could not be represented as a boolean  */
 219 tr_bool   tr_bencGetBool( const tr_benc * val, tr_bool * setme );
 220
 221 /** @brief Get a floating-point number from a variant object
 222     @return TRUE if successful, or FALSE if the variant could not be represented as a floating-point number  */
 223 tr_bool   tr_bencGetReal( const tr_benc * val, double * setme );
 224
 225 static inline tr_bool tr_bencIsType  ( const tr_benc * b, int type ) { return ( b != NULL ) && ( b->type == type ); }
 226
 227 static inline tr_bool tr_bencIsInt   ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_INT ); }
 228 static inline tr_bool tr_bencIsDict  ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_DICT ); }
 229 static inline tr_bool tr_bencIsList  ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_LIST ); }
 230 static inline tr_bool tr_bencIsString( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_STR ); }
 231 static inline tr_bool tr_bencIsBool  ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_BOOL ); }
 232 static inline tr_bool tr_bencIsReal  ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_REAL ); }
 233
 234 /** @brief Private function that's exposed here only for unit tests */
 235 int tr_bencParseInt( const uint8_t *  buf,
 236                      const uint8_t *  bufend,
 237                      const uint8_t ** setme_end,
 238                      int64_t *        setme_val );
 239
 240 /** @brief Private function that's exposed here only for unit tests */
 241 int tr_bencParseStr( const uint8_t *  buf,
 242                      const uint8_t *  bufend,
 243                      const uint8_t ** setme_end,
 244                      const uint8_t ** setme_str,
 245                      size_t *         setme_strlen );
 246
 247 /**
 248 ***
 249 **/
 250
 251 /* this is only quasi-supported. don't rely on it too heavily outside of libT */
 252 void  tr_bencMergeDicts( tr_benc * target, const tr_benc * source );
 253
 254 /* @} */
 255
 256 #ifdef __cplusplus
 257 }
 258 #endif
 259
 260 #endif