1/*
2 * Author:      William Chia-Wei Cheng (bill.cheng@acm.org)
3 *
4 * Copyright (C) 2001-2009, William Chia-Wei Cheng.
5 *
6 * This file may be distributed under the terms of the Q Public License
7 * as defined by Trolltech AS of Norway and appearing in the file
8 * LICENSE.QPL included in the packaging of this file.
9 *
10 * THIS FILE IS PROVIDED AS IS WITH NO WARRANTY OF ANY KIND, INCLUDING
11 * THE WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
12 * PURPOSE.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL,
13 * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
14 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
15 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
16 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 *
18 * @(#)$Header: /mm2/home/cvs/bc-src/tgif/ini.e,v 1.6 2011/05/16 16:21:58 william Exp $
19 */
20
21#ifndef _INI_E_
22#define _INI_E_
23
24#ifdef _INCLUDE_FROM_INI_C_
25#undef extern
26#define extern
27#endif /*_INCLUDE_FROM_INI_C_*/
28
29   /*
30    * tgCleanUpProfile() frees all file information.
31    */
32extern void	tgCleanUpProfile ARGS_DECL((void));
33
34   /*
35    * tgFreeProfileString() must be called to free any string returned by
36    *      tgGetProfileString().
37    * NULL is always returned;
38    */
39extern char	* tgFreeProfileString ARGS_DECL((char *pszStr));
40
41   /*
42    * tgBeginFastProfile() turns off file time checking for pszFile.
43    * tgEndFastProfile() turns on file time checking for pszFile.
44    * Normally, any of the tgGet...() and tgWrite...() routines below checks
45    *      to see if the INI file is modified.  If the INI file is modified,
46    *      the cache is flushed before any action is take.
47    * Surrounding a set of tgGet...() and tgWrite...() routines by a
48    *      tgBeginFastProfile() and tgEndFastProfile() pair turns off file
49    *      time checking.  This approach should only be used if the tg...()
50    *      routines are called in a tight loop.
51    */
52extern void	tgBeginFastProfile ARGS_DECL((char *pszFile));
53extern void	tgEndFastProfile ARGS_DECL((char *pszFile));
54
55   /*
56    * tgSetProfileStripQuotes() turns on/off single and double quotes stripping
57    *      for pszFile.  By default, quotes-stripping is turned on (TRUE).  If
58    *      you are using an encrypted file, you should call this function with
59    *      bStripQuotes set to FALSE.
60    * It returns the current quotes-stripping setting for pszFile.
61    */
62extern int	tgSetProfileStripQuotes ARGS_DECL((char *pszFile,
63		                                   int bStripQuotes));
64
65   /*
66    * tgGetProfileString() works the same way as GetPrivateProfileString()
67    *      except that when pszSection is NULL, all sections are returned (in
68    *      the way similar to the case where pszEntry is NULL).
69    * If the returned string is non-NULL, it must be freed by calling
70    *      tgFreeProfileString();
71    */
72extern char	* tgGetProfileString ARGS_DECL((char *pszSection,
73		                                char *pszEntry,
74		                                char *pszFile));
75
76   /*
77    * tgGetProfileInt() works the same way as GetPrivateProfileInt() except
78    *      that when pszSection is NULL, the information cached for pszFile is
79    *      discarded.  If pszSection is NULL and the file can not be written,
80    *      the returned value will be !nDefault.
81    */
82extern int	tgGetProfileInt ARGS_DECL((char *pszSection, char *pszEntry,
83                                           int nDefault, char *pszFile));
84
85   /*
86    * tgWriteProfileString() works the same way as WritePrivateProfileString()
87    *      except that if pszSection is not NULL, the write is doesn't update
88    *      pszFile (it uses write-back instead of write-through).  Therefore,
89    *      one should always call this function again with a NULL pszSection to
90    *      force out the write.
91    * Returns FALSE if memory allocation fails.
92    */
93extern int	tgWriteProfileString ARGS_DECL((char *pszSection,
94		                                char *pszEntry,
95		                                char *pszString,
96		                                char *pszFile));
97
98   /*
99    * tgBeginDupKeySection() turns on duplicate key retrieval for the pszSection
100    *      of pszFile.  The pszSection can NOT be NULL.
101    * tgEndFastProfile() turns it off.
102    * Normally, any of the tgGet...() and tgWrite...() routines behaves like
103    *      their Windows API counter-parts where duplicate entries are removed.
104    * Surrounding a set of tgGet...() and tgWrite...() routines by a
105    *      tgBeginDupKeySection() and tgEndDupKeySection() enables retrieval of
106    *      entries with duplicate keys.  This approach should only be used if
107    *      the tg...() routines are called in a tight loop.  Also, the
108    *      pszSection in the tg...() calls must be the same as the pszSection
109    *      used in tgBeginDupKeySection() and tgEndDupKeySection().
110    */
111extern void	tgBeginDupKeySection ARGS_DECL((char *pszSection,
112		                                char *pszFile));
113extern void	tgEndDupKeySection ARGS_DECL((char *pszSection,
114		                              char *pszFile));
115
116   /*
117    * tgBeginValuelessKeySection() turns on valueless key writes for the
118    *      pszSection of pszFile.  The pszSection can NOT be NULL.  Examples of
119    *      valueless key section are sections in Ios.ini.
120    * tgBeginValuelessKeySection() returns TRUE if pszSection of pszFile is
121    *      valueless.
122    * tgEndFastProfile() sets the valueless key flag for pszSection of pszFile
123    *      to be bValuelessKey.
124    * These two functions has no effect on reads!
125    *
126    * Surrounding a set of tgWriteProfileString() calls by
127    *      tgBeginValuelessKeySection() and tgEndValuelessKeySection() enables
128    *      writes of lines with valueless keys.  The pszSection in the
129    *      tgWriteProfileString() calls must use the same pszSection as the
130    *      pszSection used in tgBeginValuelessKeySection() and
131    *      tgEndValuelessKeySection(). Furthermore, tgWriteProfileString() must
132    *      be called with NULL pszValue.  Also, please make sure that
133    *      tgWriteProfileString() is called with a NULL pszSection to force out
134    *      the write before tgEndValuelessKeySection() is called.
135    *
136    * The following is an example of how to use these functions.
137    *
138    *      BOOL bValuelessKey=faBeginValuelessKeySection(pszSection, pszFile);
139    *
140    *      tgWriteProfileString(pszSection, pszEntry1, NULL, pszFile);
141    *      tgWriteProfileString(pszSection, pszEntry2, NULL, pszFile);
142    *      ...
143    *      tgWriteProfileString(NULL, NULL, NULL, pszFile);
144    *
145    *      tgEndValuelessKeySection(pszSection, pszFile, bValuelessKey);
146    */
147extern int	tgBeginValuelessKeySection ARGS_DECL((char *pszSection,
148		                                      char *pszFile));
149extern void	tgEndValuelessKeySection ARGS_DECL((char *pszSection,
150		                                    char *pszFile,
151		                                    int bValuelessKey));
152
153   /*
154    * tgIsValuelessKeySection() returns TRUE if pszSection of pszFile is a
155    *      valueless key section.
156    */
157extern int	tgIsValuelessKeySection ARGS_DECL((char *pszSection,
158		                                   char *pszFile));
159
160   /*
161    * tgDeleteDupKeyValue() deletes the key/value pair specified by
162    *      pszEntry/pszValue in pszSection of pszFile.
163    * Returns FALSE if any of the parameters is NULL.
164    * Internally, this function calls tgBeginDupKeySection() and
165    *      tgEndDupKeySection() but it does NOT write out the file.
166    */
167extern int	tgDeleteDupKeyValue ARGS_DECL((char *pszSection,
168		                               char *pszEntry,
169		                               char *pszValue,
170		                               char *pszFile));
171
172#ifdef _INCLUDE_FROM_INI_C_
173#undef extern
174#ifndef _NO_RECURSIVE_EXTERN
175#define extern extern
176#endif /* ~_NO_RECURSIVE_EXTERN */
177#endif /*_INCLUDE_FROM_INI_C_*/
178
179#endif /*_INI_E_*/
180