← Back to branch summary

~zulcss/samba/server-dailies-3.4

« back to all changes in this revision

Viewing changes to source3/iniparser/src/iniparser.h

  • Committer: Chuck Short
  • Date: 2010-09-28 20:38:39 UTC
  • Revision ID: zulcss@ubuntu.com-20100928203839-pgjulytsi9ue63x1
Initial version

Show diffs side-by-side

added added

removed removed

Lines of Context:
source3/iniparser/src/iniparser.h
 
1
 
 
2
/*-------------------------------------------------------------------------*/
 
3
/**
 
4
   @file    iniparser.h
 
5
   @author  N. Devillard
 
6
   @date    Mar 2000
 
7
   @version $Revision: 1.23 $
 
8
   @brief   Parser for ini files.
 
9
*/
 
10
/*--------------------------------------------------------------------------*/
 
11
 
 
12
/*
 
13
        $Id: iniparser.h,v 1.23 2006-09-27 11:03:35 ndevilla Exp $
 
14
        $Author: ndevilla $
 
15
        $Date: 2006-09-27 11:03:35 $
 
16
        $Revision: 1.23 $
 
17
*/
 
18
 
 
19
#ifndef _INIPARSER_H_
 
20
#define _INIPARSER_H_
 
21
 
 
22
/*---------------------------------------------------------------------------
 
23
                                                                Includes
 
24
 ---------------------------------------------------------------------------*/
 
25
 
 
26
#include <stdio.h>
 
27
#include <stdlib.h>
 
28
#include <string.h>
 
29
 
 
30
/*
 
31
 * The following #include is necessary on many Unixes but not Linux.
 
32
 * It is not needed for Windows platforms.
 
33
 * Uncomment it if needed.
 
34
 */
 
35
/* #include <unistd.h> */
 
36
 
 
37
#include "dictionary.h"
 
38
 
 
39
/*-------------------------------------------------------------------------*/
 
40
/**
 
41
  @brief    Get number of sections in a dictionary
 
42
  @param    d   Dictionary to examine
 
43
  @return   int Number of sections found in dictionary
 
44
 
 
45
  This function returns the number of sections found in a dictionary.
 
46
  The test to recognize sections is done on the string stored in the
 
47
  dictionary: a section name is given as "section" whereas a key is
 
48
  stored as "section:key", thus the test looks for entries that do not
 
49
  contain a colon.
 
50
 
 
51
  This clearly fails in the case a section name contains a colon, but
 
52
  this should simply be avoided.
 
53
 
 
54
  This function returns -1 in case of error.
 
55
 */
 
56
/*--------------------------------------------------------------------------*/
 
57
 
 
58
int iniparser_getnsec(dictionary * d);
 
59
 
 
60
 
 
61
/*-------------------------------------------------------------------------*/
 
62
/**
 
63
  @brief    Get name for section n in a dictionary.
 
64
  @param    d   Dictionary to examine
 
65
  @param    n   Section number (from 0 to nsec-1).
 
66
  @return   Pointer to char string
 
67
 
 
68
  This function locates the n-th section in a dictionary and returns
 
69
  its name as a pointer to a string statically allocated inside the
 
70
  dictionary. Do not free or modify the returned string!
 
71
 
 
72
  This function returns NULL in case of error.
 
73
 */
 
74
/*--------------------------------------------------------------------------*/
 
75
 
 
76
char * iniparser_getsecname(dictionary * d, int n);
 
77
 
 
78
 
 
79
/*-------------------------------------------------------------------------*/
 
80
/**
 
81
  @brief    Save a dictionary to a loadable ini file
 
82
  @param    d   Dictionary to dump
 
83
  @param    f   Opened file pointer to dump to
 
84
  @return   void
 
85
 
 
86
  This function dumps a given dictionary into a loadable ini file.
 
87
  It is Ok to specify @c stderr or @c stdout as output files.
 
88
 */
 
89
/*--------------------------------------------------------------------------*/
 
90
 
 
91
void iniparser_dump_ini(dictionary * d, FILE * f);
 
92
 
 
93
/*-------------------------------------------------------------------------*/
 
94
/**
 
95
  @brief    Dump a dictionary to an opened file pointer.
 
96
  @param    d   Dictionary to dump.
 
97
  @param    f   Opened file pointer to dump to.
 
98
  @return   void
 
99
 
 
100
  This function prints out the contents of a dictionary, one element by
 
101
  line, onto the provided file pointer. It is OK to specify @c stderr
 
102
  or @c stdout as output files. This function is meant for debugging
 
103
  purposes mostly.
 
104
 */
 
105
/*--------------------------------------------------------------------------*/
 
106
void iniparser_dump(dictionary * d, FILE * f);
 
107
 
 
108
/*-------------------------------------------------------------------------*/
 
109
/**
 
110
  @brief    Get the string associated to a key, return NULL if not found
 
111
  @param    d   Dictionary to search
 
112
  @param    key Key string to look for
 
113
  @return   pointer to statically allocated character string, or NULL.
 
114
 
 
115
  This function queries a dictionary for a key. A key as read from an
 
116
  ini file is given as "section:key". If the key cannot be found,
 
117
  NULL is returned.
 
118
  The returned char pointer is pointing to a string allocated in
 
119
  the dictionary, do not free or modify it.
 
120
 
 
121
  This function is only provided for backwards compatibility with
 
122
  previous versions of iniparser. It is recommended to use
 
123
  iniparser_getstring() instead.
 
124
 */
 
125
/*--------------------------------------------------------------------------*/
 
126
char * iniparser_getstr(dictionary * d, const char * key);
 
127
 
 
128
 
 
129
/*-------------------------------------------------------------------------*/
 
130
/**
 
131
  @brief    Get the string associated to a key
 
132
  @param    d       Dictionary to search
 
133
  @param    key     Key string to look for
 
134
  @param    def     Default value to return if key not found.
 
135
  @return   pointer to statically allocated character string
 
136
 
 
137
  This function queries a dictionary for a key. A key as read from an
 
138
  ini file is given as "section:key". If the key cannot be found,
 
139
  the pointer passed as 'def' is returned.
 
140
  The returned char pointer is pointing to a string allocated in
 
141
  the dictionary, do not free or modify it.
 
142
 */
 
143
/*--------------------------------------------------------------------------*/
 
144
char * iniparser_getstring(dictionary * d, const char * key, char * def);
 
145
 
 
146
/*-------------------------------------------------------------------------*/
 
147
/**
 
148
  @brief    Get the string associated to a key, convert to an int
 
149
  @param    d Dictionary to search
 
150
  @param    key Key string to look for
 
151
  @param    notfound Value to return in case of error
 
152
  @return   integer
 
153
 
 
154
  This function queries a dictionary for a key. A key as read from an
 
155
  ini file is given as "section:key". If the key cannot be found,
 
156
  the notfound value is returned.
 
157
 
 
158
  Supported values for integers include the usual C notation
 
159
  so decimal, octal (starting with 0) and hexadecimal (starting with 0x)
 
160
  are supported. Examples:
 
161
 
 
162
  - "42"      ->  42
 
163
  - "042"     ->  34 (octal -> decimal)
 
164
  - "0x42"    ->  66 (hexa  -> decimal)
 
165
 
 
166
  Warning: the conversion may overflow in various ways. Conversion is
 
167
  totally outsourced to strtol(), see the associated man page for overflow
 
168
  handling.
 
169
 
 
170
  Credits: Thanks to A. Becker for suggesting strtol()
 
171
 */
 
172
/*--------------------------------------------------------------------------*/
 
173
int iniparser_getint(dictionary * d, const char * key, int notfound);
 
174
 
 
175
/*-------------------------------------------------------------------------*/
 
176
/**
 
177
  @brief    Get the string associated to a key, convert to a double
 
178
  @param    d Dictionary to search
 
179
  @param    key Key string to look for
 
180
  @param    notfound Value to return in case of error
 
181
  @return   double
 
182
 
 
183
  This function queries a dictionary for a key. A key as read from an
 
184
  ini file is given as "section:key". If the key cannot be found,
 
185
  the notfound value is returned.
 
186
 */
 
187
/*--------------------------------------------------------------------------*/
 
188
double iniparser_getdouble(dictionary * d, char * key, double notfound);
 
189
 
 
190
/*-------------------------------------------------------------------------*/
 
191
/**
 
192
  @brief    Get the string associated to a key, convert to a boolean
 
193
  @param    d Dictionary to search
 
194
  @param    key Key string to look for
 
195
  @param    notfound Value to return in case of error
 
196
  @return   integer
 
197
 
 
198
  This function queries a dictionary for a key. A key as read from an
 
199
  ini file is given as "section:key". If the key cannot be found,
 
200
  the notfound value is returned.
 
201
 
 
202
  A true boolean is found if one of the following is matched:
 
203
 
 
204
  - A string starting with 'y'
 
205
  - A string starting with 'Y'
 
206
  - A string starting with 't'
 
207
  - A string starting with 'T'
 
208
  - A string starting with '1'
 
209
 
 
210
  A false boolean is found if one of the following is matched:
 
211
 
 
212
  - A string starting with 'n'
 
213
  - A string starting with 'N'
 
214
  - A string starting with 'f'
 
215
  - A string starting with 'F'
 
216
  - A string starting with '0'
 
217
 
 
218
  The notfound value returned if no boolean is identified, does not
 
219
  necessarily have to be 0 or 1.
 
220
 */
 
221
/*--------------------------------------------------------------------------*/
 
222
int iniparser_getboolean(dictionary * d, const char * key, int notfound);
 
223
 
 
224
 
 
225
/*-------------------------------------------------------------------------*/
 
226
/**
 
227
  @brief    Set an entry in a dictionary.
 
228
  @param    ini     Dictionary to modify.
 
229
  @param    entry   Entry to modify (entry name)
 
230
  @param    val     New value to associate to the entry.
 
231
  @return   int 0 if Ok, -1 otherwise.
 
232
 
 
233
  If the given entry can be found in the dictionary, it is modified to
 
234
  contain the provided value. If it cannot be found, -1 is returned.
 
235
  It is Ok to set val to NULL.
 
236
 */
 
237
/*--------------------------------------------------------------------------*/
 
238
 
 
239
int iniparser_setstr(dictionary * ini, char * entry, char * val);
 
240
 
 
241
/*-------------------------------------------------------------------------*/
 
242
/**
 
243
  @brief    Delete an entry in a dictionary
 
244
  @param    ini     Dictionary to modify
 
245
  @param    entry   Entry to delete (entry name)
 
246
  @return   void
 
247
 
 
248
  If the given entry can be found, it is deleted from the dictionary.
 
249
 */
 
250
/*--------------------------------------------------------------------------*/
 
251
void iniparser_unset(dictionary * ini, char * entry);
 
252
 
 
253
/*-------------------------------------------------------------------------*/
 
254
/**
 
255
  @brief    Finds out if a given entry exists in a dictionary
 
256
  @param    ini     Dictionary to search
 
257
  @param    entry   Name of the entry to look for
 
258
  @return   integer 1 if entry exists, 0 otherwise
 
259
 
 
260
  Finds out if a given entry exists in the dictionary. Since sections
 
261
  are stored as keys with NULL associated values, this is the only way
 
262
  of querying for the presence of sections in a dictionary.
 
263
 */
 
264
/*--------------------------------------------------------------------------*/
 
265
int iniparser_find_entry(dictionary * ini, char * entry) ;
 
266
 
 
267
/*-------------------------------------------------------------------------*/
 
268
/**
 
269
  @brief    Parse an ini file and return an allocated dictionary object
 
270
  @param    ininame Name of the ini file to read.
 
271
  @return   Pointer to newly allocated dictionary
 
272
 
 
273
  This is the parser for ini files. This function is called, providing
 
274
  the name of the file to be read. It returns a dictionary object that
 
275
  should not be accessed directly, but through accessor functions
 
276
  instead.
 
277
 
 
278
  The returned dictionary must be freed using iniparser_freedict().
 
279
 */
 
280
/*--------------------------------------------------------------------------*/
 
281
dictionary * iniparser_load(const char * ininame);
 
282
 
 
283
/*-------------------------------------------------------------------------*/
 
284
/**
 
285
  @brief    Free all memory associated to an ini dictionary
 
286
  @param    d Dictionary to free
 
287
  @return   void
 
288
 
 
289
  Free all memory associated to an ini dictionary.
 
290
  It is mandatory to call this function before the dictionary object
 
291
  gets out of the current context.
 
292
 */
 
293
/*--------------------------------------------------------------------------*/
 
294
void iniparser_freedict(dictionary * d);
 
295
 
 
296
#endif