ls-sfparser.h revision fbc6cc04 
1/* Copyright (c) 2017 - 2020 LiteSpeed Technologies Inc.  See LICENSE. */
2/*
3MIT License
4
5Copyright (c) 2020 LiteSpeed Technologies Inc
6
7Permission is hereby granted, free of charge, to any person obtaining a copy
8of this software and associated documentation files (the "Software"), to deal
9in the Software without restriction, including without limitation the rights
10to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11copies of the Software, and to permit persons to whom the Software is
12furnished to do so, subject to the following conditions:
13
14The above copyright notice and this permission notice shall be included in all
15copies or substantial portions of the Software.
16
17THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23SOFTWARE.
24*/
25
26/* The LiteSpeed Structured Fields Parser parses structured fields decribed in
27 * https://tools.ietf.org/html/draft-ietf-httpbis-header-structure-19
28 *
29 * It provides a simple streaming interface which allows the user to process
30 * structured fields in any manner.
31 */
32
33#ifndef LS_SFPARSER_H
34#define LS_SFPARSER_H 1
35
36enum ls_sf_dt
37{   /* LS SF DT: LiteSpeed Structured Field Data Type */
38    LS_SF_DT_INTEGER,
39    LS_SF_DT_DECIMAL,
40
41    /* Name only applies to dictionary names.  They may repeat: the
42     * parser does not drop duplicates.
43     */
44    LS_SF_DT_NAME,
45
46    /* Parameter name may apply to any applicable preceding Item or
47     * Inner List.
48     */
49    LS_SF_DT_PARAM_NAME,
50
51    /* The returned string does not include enclosing double quotes. */
52    LS_SF_DT_STRING,
53
54    LS_SF_DT_TOKEN,
55
56    /* The byte sequence is not base64-decoded; it is up to the caller
57     * to do so.  The returned string does not include the enclosing
58     * colons.
59     */
60    LS_SF_DT_BYTESEQ,
61
62    /* Note that true boolean values are serialized *without* the values.
63     * The parser makes one up and passes a pointer to its internal buffer.
64     */
65    LS_SF_DT_BOOLEAN,
66
67    /* The Inner List has a beginning and an end.  The returned strings
68     * are opening and closing parentheses.
69     */
70    LS_SF_DT_INNER_LIST_BEGIN,
71    LS_SF_DT_INNER_LIST_END,
72};
73
74
75enum ls_sf_tlt
76{   /* LS SF TLT: LiteSpeed Structured Field Top-Level Type */
77    LS_SF_TLT_DICTIONARY,
78    LS_SF_TLT_LIST,
79    LS_SF_TLT_ITEM,
80};
81
82
83/* Return 0 if parsed correctly, -1 on error, -2 if ran out of memory. */
84int
85ls_sf_parse (
86    /* Expected type of top-level input.  This tells the parser how to
87     * parse the input.
88     */
89    enum ls_sf_tlt,
90
91    /* Input; does not have to be NUL-terminated: */
92    const char *input, size_t input_sz,
93
94    /* Callback function to call each time a token is parsed.  A non-zero
95     * return value indicates that parsing should stop.
96     */
97    int (*callback)(
98        /* The first argument to the callback is user-specified additional
99         * data.
100         */
101        void *user_data,
102        /* The second argument is the data type. */
103        enum ls_sf_dt,
104        /* The third and fourth arguments are NUL-terminated string and
105         * its length, respectively.  The string can be modified, because
106         * the parser makes a copy.
107         */
108        char *str, size_t len,
109        /* Offset to the token in the input buffer.  In the special case
110         * of an implicit boolean value, this value is negative: this is
111         * because this value is not present in the input buffer.
112         */
113        int off),
114
115    /* Additional data to pass to the callback: */
116    void *user_data,
117
118    /* Allocate memory from this memory buffer.  If set to NULL, regular
119     * system memory allocator will be used.
120     */
121    char *mem_buf, size_t mem_buf_sz);
122
123
124
125/* Convenience array with type names. */
126extern const char *const ls_sf_dt2str[];
127
128
129#endif
130