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