|
1 /* |
|
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
|
3 * |
|
4 * Copyright 2013 Olaf Wintermann. All rights reserved. |
|
5 * |
|
6 * Redistribution and use in source and binary forms, with or without |
|
7 * modification, are permitted provided that the following conditions are met: |
|
8 * |
|
9 * 1. Redistributions of source code must retain the above copyright |
|
10 * notice, this list of conditions and the following disclaimer. |
|
11 * |
|
12 * 2. Redistributions in binary form must reproduce the above copyright |
|
13 * notice, this list of conditions and the following disclaimer in the |
|
14 * documentation and/or other materials provided with the distribution. |
|
15 * |
|
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
|
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
|
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
|
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
|
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
|
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
|
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
|
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
|
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
|
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
|
26 * POSSIBILITY OF SUCH DAMAGE. |
|
27 */ |
|
28 /** |
|
29 * @file properties.h |
|
30 * |
|
31 * Load / store utilities for properties files. |
|
32 * |
|
33 * @author Mike Becker |
|
34 * @author Olaf Wintermann |
|
35 */ |
|
36 |
|
37 #ifndef UCX_PROPERTIES_H |
|
38 #define UCX_PROPERTIES_H |
|
39 |
|
40 #include "ucx.h" |
|
41 #include "map.h" |
|
42 |
|
43 #ifdef __cplusplus |
|
44 extern "C" { |
|
45 #endif |
|
46 |
|
47 /** |
|
48 * UcxProperties object for parsing properties data. |
|
49 * Most of the fields are for internal use only. You may configure the |
|
50 * properties parser, e.g. by changing the used delimiter or specifying |
|
51 * up to three different characters that shall introduce comments. |
|
52 */ |
|
53 typedef struct { |
|
54 /** |
|
55 * Input buffer (don't set manually). |
|
56 * Automatically set by calls to ucx_properties_fill(). |
|
57 */ |
|
58 char *buffer; |
|
59 /** |
|
60 * Length of the input buffer (don't set manually). |
|
61 * Automatically set by calls to ucx_properties_fill(). |
|
62 */ |
|
63 size_t buflen; |
|
64 /** |
|
65 * Current buffer position (don't set manually). |
|
66 * Used by ucx_properties_next(). |
|
67 */ |
|
68 size_t pos; |
|
69 /** |
|
70 * Internal temporary buffer (don't set manually). |
|
71 * Used by ucx_properties_next(). |
|
72 */ |
|
73 char *tmp; |
|
74 /** |
|
75 * Internal temporary buffer length (don't set manually). |
|
76 * Used by ucx_properties_next(). |
|
77 */ |
|
78 size_t tmplen; |
|
79 /** |
|
80 * Internal temporary buffer capacity (don't set manually). |
|
81 * Used by ucx_properties_next(). |
|
82 */ |
|
83 size_t tmpcap; |
|
84 /** |
|
85 * Parser error code. |
|
86 * This is always 0 on success and a nonzero value on syntax errors. |
|
87 * The value is set by ucx_properties_next(). |
|
88 */ |
|
89 int error; |
|
90 /** |
|
91 * The delimiter that shall be used. |
|
92 * This is '=' by default. |
|
93 */ |
|
94 char delimiter; |
|
95 /** |
|
96 * The first comment character. |
|
97 * This is '#' by default. |
|
98 */ |
|
99 char comment1; |
|
100 /** |
|
101 * The second comment character. |
|
102 * This is not set by default. |
|
103 */ |
|
104 char comment2; |
|
105 /** |
|
106 * The third comment character. |
|
107 * This is not set by default. |
|
108 */ |
|
109 char comment3; |
|
110 } UcxProperties; |
|
111 |
|
112 |
|
113 /** |
|
114 * Constructs a new UcxProperties object. |
|
115 * @return a pointer to the new UcxProperties object |
|
116 */ |
|
117 UcxProperties *ucx_properties_new(); |
|
118 /** |
|
119 * Destroys an UcxProperties object. |
|
120 * @param prop the UcxProperties object to destroy |
|
121 */ |
|
122 void ucx_properties_free(UcxProperties *prop); |
|
123 /** |
|
124 * Sets the input buffer for the properties parser. |
|
125 * |
|
126 * After calling this function, you may parse the data by calling |
|
127 * ucx_properties_next() until it returns 0. The function ucx_properties2map() |
|
128 * is a convenience function that performs these successive calls of |
|
129 * ucx_properties_next() within a while loop and puts the properties to a map. |
|
130 * |
|
131 * |
|
132 * @param prop the UcxProperties object |
|
133 * @param buf a pointer to the new buffer |
|
134 * @param len the payload length of the buffer |
|
135 * @see ucx_properties_next() |
|
136 * @see ucx_properties2map() |
|
137 */ |
|
138 void ucx_properties_fill(UcxProperties *prop, char *buf, size_t len); |
|
139 /** |
|
140 * Retrieves the next key/value-pair. |
|
141 * |
|
142 * This function returns a nonzero value as long as there are key/value-pairs |
|
143 * found. If no more key/value-pairs are found, you may refill the input buffer |
|
144 * with ucx_properties_fill(). |
|
145 * |
|
146 * <b>Attention:</b> the sstr_t.ptr pointers of the output parameters point to |
|
147 * memory within the input buffer of the parser and will get invalid some time. |
|
148 * If you want long term copies of the key/value-pairs, use sstrdup() after |
|
149 * calling this function. |
|
150 * |
|
151 * @param prop the UcxProperties object |
|
152 * @param name a pointer to the sstr_t that shall contain the property name |
|
153 * @param value a pointer to the sstr_t that shall contain the property value |
|
154 * @return Nonzero, if a key/value-pair was successfully retrieved |
|
155 * @see ucx_properties_fill() |
|
156 */ |
|
157 int ucx_properties_next(UcxProperties *prop, sstr_t *name, sstr_t *value); |
|
158 /** |
|
159 * Retrieves all available key/value-pairs and puts them into an UcxMap. |
|
160 * |
|
161 * This is done by successive calls to ucx_properties_next() until no more |
|
162 * key/value-pairs can be retrieved. |
|
163 * |
|
164 * @param prop the UcxProperties object |
|
165 * @param map the target map |
|
166 * @return The UcxProperties.error code (i.e. 0 on success). |
|
167 * @see ucx_properties_fill() |
|
168 */ |
|
169 int ucx_properties2map(UcxProperties *prop, UcxMap *map); |
|
170 |
|
171 /** |
|
172 * Loads a properties file to an UcxMap. |
|
173 * |
|
174 * This is a convenience function that reads chunks of 1 KB from an input |
|
175 * stream until the end of the stream is reached. |
|
176 * |
|
177 * An UcxProperties object is implicitly created and destroyed. |
|
178 * |
|
179 * @param map the map object to write the key/value-pairs to |
|
180 * @param file the <code>FILE*</code> stream to read from |
|
181 * @return 0 on success, or a non-zero value on error |
|
182 * |
|
183 * @see ucx_properties_fill() |
|
184 * @see ucx_properties2map() |
|
185 */ |
|
186 int ucx_properties_load(UcxMap *map, FILE *file); |
|
187 /** |
|
188 * Stores an UcxMap to a file. |
|
189 * |
|
190 * The key/value-pairs are written by using the following format: |
|
191 * |
|
192 * <code>[key] = [value]\\n</code> |
|
193 * |
|
194 * @param map the map to store |
|
195 * @param file the <code>FILE*</code> stream to write to |
|
196 * @return 0 on success, or a non-zero value on error |
|
197 */ |
|
198 int ucx_properties_store(UcxMap *map, FILE *file); |
|
199 |
|
200 #ifdef __cplusplus |
|
201 } |
|
202 #endif |
|
203 |
|
204 #endif /* UCX_PROPERTIES_H */ |
|
205 |