1 /* 2 * sfparse 3 * 4 * Copyright (c) 2023 sfparse contributors 5 * Copyright (c) 2019 nghttp3 contributors 6 * Copyright (c) 2015 nghttp2 contributors 7 * 8 * Permission is hereby granted, free of charge, to any person obtaining 9 * a copy of this software and associated documentation files (the 10 * "Software"), to deal in the Software without restriction, including 11 * without limitation the rights to use, copy, modify, merge, publish, 12 * distribute, sublicense, and/or sell copies of the Software, and to 13 * permit persons to whom the Software is furnished to do so, subject to 14 * the following conditions: 15 * 16 * The above copyright notice and this permission notice shall be 17 * included in all copies or substantial portions of the Software. 18 * 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 20 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 21 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 22 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 23 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 24 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 25 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 26 */ 27 #ifndef SFPARSE_H 28 #define SFPARSE_H 29 30 /* Define WIN32 when build target is Win32 API (borrowed from 31 libcurl) */ 32 #if (defined(_WIN32) || defined(__WIN32__)) && !defined(WIN32) 33 # define WIN32 34 #endif 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 #if defined(_MSC_VER) && (_MSC_VER < 1800) 41 /* MSVC < 2013 does not have inttypes.h because it is not C99 42 compliant. See compiler macros and version number in 43 https://sourceforge.net/p/predef/wiki/Compilers/ */ 44 # include <stdint.h> 45 #else /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */ 46 # include <inttypes.h> 47 #endif /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */ 48 #include <sys/types.h> 49 #include <stddef.h> 50 51 /** 52 * @enum 53 * 54 * :type:`sf_type` defines value type. 55 */ 56 typedef enum sf_type { 57 /** 58 * :enum:`SF_TYPE_BOOLEAN` indicates boolean type. 59 */ 60 SF_TYPE_BOOLEAN, 61 /** 62 * :enum:`SF_TYPE_INTEGER` indicates integer type. 63 */ 64 SF_TYPE_INTEGER, 65 /** 66 * :enum:`SF_TYPE_DECIMAL` indicates decimal type. 67 */ 68 SF_TYPE_DECIMAL, 69 /** 70 * :enum:`SF_TYPE_STRING` indicates string type. 71 */ 72 SF_TYPE_STRING, 73 /** 74 * :enum:`SF_TYPE_TOKEN` indicates token type. 75 */ 76 SF_TYPE_TOKEN, 77 /** 78 * :enum:`SF_TYPE_BYTESEQ` indicates byte sequence type. 79 */ 80 SF_TYPE_BYTESEQ, 81 /** 82 * :enum:`SF_TYPE_INNER_LIST` indicates inner list type. 83 */ 84 SF_TYPE_INNER_LIST, 85 /** 86 * :enum:`SF_TYPE_DATE` indicates date type. 87 */ 88 SF_TYPE_DATE 89 } sf_type; 90 91 /** 92 * @macro 93 * 94 * :macro:`SF_ERR_PARSE_ERROR` indicates fatal parse error has 95 * occurred, and it is not possible to continue the processing. 96 */ 97 #define SF_ERR_PARSE_ERROR -1 98 99 /** 100 * @macro 101 * 102 * :macro:`SF_ERR_EOF` indicates that there is nothing left to read. 103 * The context of this error varies depending on the function that 104 * returns this error code. 105 */ 106 #define SF_ERR_EOF -2 107 108 /** 109 * @struct 110 * 111 * :type:`sf_vec` stores sequence of bytes. 112 */ 113 typedef struct sf_vec { 114 /** 115 * :member:`base` points to the beginning of the sequence of bytes. 116 */ 117 uint8_t *base; 118 /** 119 * :member:`len` is the number of bytes contained in this sequence. 120 */ 121 size_t len; 122 } sf_vec; 123 124 /** 125 * @macro 126 * 127 * :macro:`SF_VALUE_FLAG_NONE` indicates no flag set. 128 */ 129 #define SF_VALUE_FLAG_NONE 0x0u 130 131 /** 132 * @macro 133 * 134 * :macro:`SF_VALUE_FLAG_ESCAPED_STRING` indicates that a string 135 * contains escaped character(s). 136 */ 137 #define SF_VALUE_FLAG_ESCAPED_STRING 0x1u 138 139 /** 140 * @struct 141 * 142 * :type:`sf_decimal` contains decimal value. 143 */ 144 typedef struct sf_decimal { 145 /** 146 * :member:`numer` contains numerator of the decimal value. 147 */ 148 int64_t numer; 149 /** 150 * :member:`denom` contains denominator of the decimal value. 151 */ 152 int64_t denom; 153 } sf_decimal; 154 155 /** 156 * @struct 157 * 158 * :type:`sf_value` stores a Structured Field item. For Inner List, 159 * only type is set to :enum:`sf_type.SF_TYPE_INNER_LIST`. In order 160 * to read the items contained in an inner list, call 161 * `sf_parser_inner_list`. 162 */ 163 typedef struct sf_value { 164 /** 165 * :member:`type` is the type of the value contained in this 166 * particular object. 167 */ 168 sf_type type; 169 /** 170 * :member:`flags` is bitwise OR of one or more of 171 * :macro:`SF_VALUE_FLAG_* <SF_VALUE_FLAG_NONE>`. 172 */ 173 uint32_t flags; 174 /** 175 * @anonunion_start 176 * 177 * @sf_value_value 178 */ 179 union { 180 /** 181 * :member:`boolean` contains boolean value if :member:`type` == 182 * :enum:`sf_type.SF_TYPE_BOOLEAN`. 1 indicates true, and 0 183 * indicates false. 184 */ 185 int boolean; 186 /** 187 * :member:`integer` contains integer value if :member:`type` is 188 * either :enum:`sf_type.SF_TYPE_INTEGER` or 189 * :enum:`sf_type.SF_TYPE_DATE`. 190 */ 191 int64_t integer; 192 /** 193 * :member:`decimal` contains decimal value if :member:`type` == 194 * :enum:`sf_type.SF_TYPE_DECIMAL`. 195 */ 196 sf_decimal decimal; 197 /** 198 * :member:`vec` contains sequence of bytes if :member:`type` is 199 * either :enum:`sf_type.SF_TYPE_STRING`, 200 * :enum:`sf_type.SF_TYPE_TOKEN`, or 201 * :enum:`sf_type.SF_TYPE_BYTESEQ`. 202 * 203 * For :enum:`sf_type.SF_TYPE_STRING`, this field contains one or 204 * more escaped characters if :member:`flags` has 205 * :macro:`SF_VALUE_FLAG_ESCAPED_STRING` set. To unescape the 206 * string, use `sf_unescape`. 207 * 208 * For :enum:`sf_type.SF_TYPE_BYTESEQ`, this field contains base64 209 * encoded string. To decode this byte string, use 210 * `sf_base64decode`. 211 * 212 * If :member:`vec.len <sf_vec.len>` == 0, :member:`vec.base 213 * <sf_vec.base>` is guaranteed to be NULL. 214 */ 215 sf_vec vec; 216 /** 217 * @anonunion_end 218 */ 219 }; 220 } sf_value; 221 222 /** 223 * @struct 224 * 225 * :type:`sf_parser` is the Structured Field Values parser. Use 226 * `sf_parser_init` to initialize it. 227 */ 228 typedef struct sf_parser { 229 /* all fields are private */ 230 const uint8_t *pos; 231 const uint8_t *end; 232 uint32_t state; 233 } sf_parser; 234 235 /** 236 * @function 237 * 238 * `sf_parser_init` initializes |sfp| with the given buffer pointed by 239 * |data| of length |datalen|. 240 */ 241 void sf_parser_init(sf_parser *sfp, const uint8_t *data, size_t datalen); 242 243 /** 244 * @function 245 * 246 * `sf_parser_param` reads a parameter. If this function returns 0, 247 * it stores parameter key and value in |dest_key| and |dest_value| 248 * respectively, if they are not NULL. 249 * 250 * This function does no effort to find duplicated keys. Same key may 251 * be reported more than once. 252 * 253 * Caller should keep calling this function until it returns negative 254 * error code. If it returns :macro:`SF_ERR_EOF`, all parameters have 255 * read, and caller can continue to read rest of the values. If it 256 * returns :macro:`SF_ERR_PARSE_ERROR`, it encountered fatal error 257 * while parsing field value. 258 */ 259 int sf_parser_param(sf_parser *sfp, sf_vec *dest_key, sf_value *dest_value); 260 261 /** 262 * @function 263 * 264 * `sf_parser_dict` reads the next dictionary key and value pair. If 265 * this function returns 0, it stores the key and value in |dest_key| 266 * and |dest_value| respectively, if they are not NULL. 267 * 268 * Caller can optionally read parameters attached to the pair by 269 * calling `sf_parser_param`. 270 * 271 * This function does no effort to find duplicated keys. Same key may 272 * be reported more than once. 273 * 274 * Caller should keep calling this function until it returns negative 275 * error code. If it returns :macro:`SF_ERR_EOF`, all key and value 276 * pairs have been read, and there is nothing left to read. 277 * 278 * This function returns 0 if it succeeds, or one of the following 279 * negative error codes: 280 * 281 * :macro:`SF_ERR_EOF` 282 * All values in the dictionary have read. 283 * :macro:`SF_ERR_PARSE_ERROR` 284 * It encountered fatal error while parsing field value. 285 */ 286 int sf_parser_dict(sf_parser *sfp, sf_vec *dest_key, sf_value *dest_value); 287 288 /** 289 * @function 290 * 291 * `sf_parser_list` reads the next list item. If this function 292 * returns 0, it stores the item in |dest| if it is not NULL. 293 * 294 * Caller can optionally read parameters attached to the item by 295 * calling `sf_parser_param`. 296 * 297 * Caller should keep calling this function until it returns negative 298 * error code. If it returns :macro:`SF_ERR_EOF`, all values in the 299 * list have been read, and there is nothing left to read. 300 * 301 * This function returns 0 if it succeeds, or one of the following 302 * negative error codes: 303 * 304 * :macro:`SF_ERR_EOF` 305 * All values in the list have read. 306 * :macro:`SF_ERR_PARSE_ERROR` 307 * It encountered fatal error while parsing field value. 308 */ 309 int sf_parser_list(sf_parser *sfp, sf_value *dest); 310 311 /** 312 * @function 313 * 314 * `sf_parser_item` reads a single item. If this function returns 0, 315 * it stores the item in |dest| if it is not NULL. 316 * 317 * This function is only used for the field value that consists of a 318 * single item. 319 * 320 * Caller can optionally read parameters attached to the item by 321 * calling `sf_parser_param`. 322 * 323 * Caller should call this function again to make sure that there is 324 * nothing left to read. If this 2nd function call returns 325 * :macro:`SF_ERR_EOF`, all data have been processed successfully. 326 * 327 * This function returns 0 if it succeeds, or one of the following 328 * negative error codes: 329 * 330 * :macro:`SF_ERR_EOF` 331 * There is nothing left to read. 332 * :macro:`SF_ERR_PARSE_ERROR` 333 * It encountered fatal error while parsing field value. 334 */ 335 int sf_parser_item(sf_parser *sfp, sf_value *dest); 336 337 /** 338 * @function 339 * 340 * `sf_parser_inner_list` reads the next inner list item. If this 341 * function returns 0, it stores the item in |dest| if it is not NULL. 342 * 343 * Caller can optionally read parameters attached to the item by 344 * calling `sf_parser_param`. 345 * 346 * Caller should keep calling this function until it returns negative 347 * error code. If it returns :macro:`SF_ERR_EOF`, all values in this 348 * inner list have been read, and caller can optionally read 349 * parameters attached to this inner list by calling 350 * `sf_parser_param`. Then caller can continue to read rest of the 351 * values. 352 * 353 * This function returns 0 if it succeeds, or one of the following 354 * negative error codes: 355 * 356 * :macro:`SF_ERR_EOF` 357 * All values in the inner list have read. 358 * :macro:`SF_ERR_PARSE_ERROR` 359 * It encountered fatal error while parsing field value. 360 */ 361 int sf_parser_inner_list(sf_parser *sfp, sf_value *dest); 362 363 /** 364 * @function 365 * 366 * `sf_unescape` copies |src| to |dest| by removing escapes (``\``). 367 * |src| should be the pointer to :member:`sf_value.vec` of type 368 * :enum:`sf_type.SF_TYPE_STRING` produced by either `sf_parser_dict`, 369 * `sf_parser_list`, `sf_parser_inner_list`, `sf_parser_item`, or 370 * `sf_parser_param`, otherwise the behavior is undefined. 371 * 372 * :member:`dest->base <sf_vec.base>` must point to the buffer that 373 * has sufficient space to store the unescaped string. 374 * 375 * If there is no escape character in |src|, |*src| is assigned to 376 * |*dest|. This includes the case that :member:`src->len 377 * <sf_vec.len>` == 0. 378 * 379 * This function sets the length of unescaped string to 380 * :member:`dest->len <sf_vec.len>`. 381 */ 382 void sf_unescape(sf_vec *dest, const sf_vec *src); 383 384 /** 385 * @function 386 * 387 * `sf_base64decode` decodes Base64 encoded string |src| and writes 388 * the result into |dest|. |src| should be the pointer to 389 * :member:`sf_value.vec` of type :enum:`sf_type.SF_TYPE_BYTESEQ` 390 * produced by either `sf_parser_dict`, `sf_parser_list`, 391 * `sf_parser_inner_list`, `sf_parser_item`, or `sf_parser_param`, 392 * otherwise the behavior is undefined. 393 * 394 * :member:`dest->base <sf_vec.base>` must point to the buffer that 395 * has sufficient space to store the decoded byte string. 396 * 397 * If :member:`src->len <sf_vec.len>` == 0, |*src| is assigned to 398 * |*dest|. 399 * 400 * This function sets the length of decoded byte string to 401 * :member:`dest->len <sf_vec.len>`. 402 */ 403 void sf_base64decode(sf_vec *dest, const sf_vec *src); 404 405 #ifdef __cplusplus 406 } 407 #endif 408 409 #endif /* SFPARSE_H */ 410