- Doxygen updates on core files
[sip-router] / cfg_parser.h
1 /*
2  * $Id$
3  * Standalone Configuration File Parser
4  *
5  * Copyright (C) 2008 iptelorg GmbH
6  * Written by Jan Janak <jan@iptel.org>
7  *
8  * This file is part of SER, a free SIP server.
9  *
10  * SER is free software; you can redistribute it and/or modify it under the
11  * terms of the GNU General Public License as published by the Free Software
12  * Foundation; either version 2 of the License, or (at your option) any later
13  * version.
14  *
15  * SER is distributed in the hope that it will be useful, but WITHOUT ANY
16  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
18  * details.
19  *
20  * You should have received a copy of the GNU General Public License along
21  * with this program; if not, write to the Free Software Foundation, Inc., 
22  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
23  */
24 /*!
25  * \file
26  * \brief SIP-router core :: Standalone Configuration File Parser
27  *
28  * \ingroup core
29  * Module: \ref core
30  *
31  * See \ref ConfigEngine
32  */
33
34 #ifndef _CFG_PARSER_H
35 #define _CFG_PARSER_H
36
37 #include "str.h"
38 #include <stdio.h>
39
40 #define MAX_TOKEN_LEN 512 /*!< Token names cannot be longer than this value */
41
42
43 /*! \brief Configuration flags */
44 typedef enum cfg_flags {
45         /*! \brief Extended tokens can contain also delimiters, in addition to
46          * alpha-numeric characters, this is used on the righ side of assignments
47          * where no quotes are used.
48          */
49         CFG_EXTENDED_ALPHA = (1 << 0),
50
51         /*! \brief The parser performs case-insensitive comparisons of token strings by
52          * default. The parser will use case-sensitive comparison instead if this
53          * flag is set.
54          */
55         CFG_CASE_SENSITIVE = (1 << 1), 
56
57         /*! \brief This is a flag that can be set in the last element of cfg_option
58          * arrays (this is the one with 0 as token name). When this flag is set
59          * then the value or parsing function of the element will be used for
60          * options that do not match any other element in the array.
61          */
62         CFG_DEFAULT = (1 << 2),
63
64
65         /*! \brief When this flag is set then the name of the options is a prefix and all
66          * options that have the same prefix will be matched by this entry.
67          */
68         CFG_PREFIX = (1 << 3),
69
70         /*! \brief The result of cfg_parse_str_val will be in a buffer allocated by
71          * pkg_malloc, if the destination varaiable contains a pointer to a buffer
72          * already then it will be freed with pkg_free first.
73          */
74         CFG_STR_PKGMEM = (1 << 4),
75
76         /*! \brief The result of cfg_parse_str_val will be in a buffer allocated by
77          * shm_malloc, if the destination variable contains a pointer to a buffer
78          * already then it will be freed with shm_free first.
79          */
80         CFG_STR_SHMMEM = (1 << 5),
81
82         /*! \brief The result of cfg_parse_str_val will be in a buffer allocated by
83          * malloc, if the destination variable contains a pointer to a buffer
84          * already then it will be freed with free first.
85          */
86         CFG_STR_MALLOC = (1 << 6),
87
88         /*! \brief The result of cfg_parse_str_val will be copied into a pre-allocated
89          * buffer with a fixed size, a pointer to str variable which contains the
90          * buffer and its size is passed to the function in parameter 'param'.
91          */
92         CFG_STR_STATIC = (1 << 7),
93
94 } cfg_flags_t;
95
96
97 enum cfg_token_type {
98         CFG_TOKEN_EOF    = -1,
99         CFG_TOKEN_ALPHA  = -2,
100         CFG_TOKEN_STRING = -3
101 };
102
103
104 /*! \brief Structure representing a lexical token */
105 typedef struct cfg_token {
106         char buf [MAX_TOKEN_LEN];
107         int type;  /*!< Token type */
108         str val;   /*!< Token value */
109         struct {   /*!< Position of first and last character of token in file */
110                 int line; /*!< The starting/ending line of the token */
111                 int col;  /*!< The starting/ending column of the token */
112         } start, end;
113 } cfg_token_t;
114
115
116 struct cfg_parser;
117
118 typedef int (*cfg_func_f)(void* param, struct cfg_parser* st,
119                                                   unsigned int flags);
120
121
122 /*! \brief Token mapping structure.
123  *
124  * This structure is used to map tokens to values or function calls. Arrays of
125  * such structures are typically provided by the caller of the parser.
126  */
127 typedef struct cfg_option {
128         char* name;    /*!< Token name */
129         unsigned int flags;
130         void* param;   /*!< Pointer to the destination variable */
131         int val;       /*!< Value */
132         cfg_func_f f;  /*!< Parser function to be called */
133 } cfg_option_t;
134
135
136 /*! \brief Parser state */
137 typedef struct cfg_parser {
138         FILE* f;                 /*!< Handle of the currently open file */
139         char* file;              /*!< Current file name */
140         int line;                /*!< Current line */
141         int col;                 /*!< Column index */
142         struct cfg_option* options; /*!< Array of supported options */
143         struct {
144                 cfg_func_f parser;   /*!< Section parser function */
145                 void* param;         /*!< Parameter value for the parser function */
146         } section;
147         struct cfg_token* cur_opt; /*!< Current option */
148 } cfg_parser_t;
149
150
151 extern struct cfg_option cfg_bool_values[];
152
153 struct cfg_parser* cfg_parser_init(str* filename);
154
155 void cfg_section_parser(struct cfg_parser* st, cfg_func_f parser, void* param);
156
157 void cfg_set_options(struct cfg_parser* st, struct cfg_option* options);
158
159 int sr_cfg_parse(struct cfg_parser* st);
160
161 void cfg_parser_close(struct cfg_parser* st);
162
163 struct cfg_option* cfg_lookup_token(struct cfg_option* options, str* token);
164
165 /*! ! \briefInterface to the lexical scanner */
166 int cfg_get_token(struct cfg_token* token, struct cfg_parser* st, unsigned int flags);
167
168 /* Commonly needed parser functions */
169
170 int cfg_eat_equal(struct cfg_parser* st, unsigned int flags);
171
172 int cfg_eat_eol(struct cfg_parser* st, unsigned int flags);
173
174 /*! \brief Parse section identifier of form [section]. The function expects parameter
175  * param to be of type (str*). The result string is allocated using pkg_malloc
176  * and is zero terminated. To free the memory use pkg_free(((str*)param)->s)
177  */
178 int cfg_parse_section(void* param, struct cfg_parser* st, unsigned int flags);
179
180 /*! \brief Parse string parameter value, either quoted or unquoted */
181 int cfg_parse_str_opt(void* param, struct cfg_parser* st, unsigned int flags);
182
183 int cfg_parse_str(void* param, struct cfg_parser* st, unsigned int flags);
184
185 int cfg_parse_enum_opt(void* param, struct cfg_parser* st, unsigned int flags);
186
187 int cfg_parse_enum(void* param, struct cfg_parser* st, unsigned int flags);
188
189 /*! \brief Parser integer parameter value */
190 int cfg_parse_int_opt(void* param, struct cfg_parser* st, unsigned int flags);
191
192 int cfg_parse_int(void* param, struct cfg_parser* st, unsigned int flags);
193
194 /*! \brief Parse boolean parameter value */
195 int cfg_parse_bool_opt(void* param, struct cfg_parser* st, unsigned int flags);
196
197 int cfg_parse_bool(void* param, struct cfg_parser* st, unsigned int flags);
198
199 #endif /* _CFG_PARSER_H */