Annotation of libaitcfg/inc/aitcfg.h, revision 1.18.6.1

1.2       misho       1: /*************************************************************************
                      2: * (C) 2008 AITNET ltd - Sofia/Bulgaria - <misho@aitbg.com>
                      3: *  by Michael Pounov <misho@openbsd-bg.org>
                      4: *
                      5: * $Author: misho $
1.18.6.1! misho       6: * $Id: aitcfg.h,v 1.18 2021/11/26 01:15:03 misho Exp $
1.2       misho       7: *
1.6       misho       8: **************************************************************************
                      9: The ELWIX and AITNET software is distributed under the following
                     10: terms:
                     11: 
                     12: All of the documentation and software included in the ELWIX and AITNET
                     13: Releases is copyrighted by ELWIX - Sofia/Bulgaria <info@elwix.org>
                     14: 
1.18.6.1! misho      15: Copyright 2004 - 2023
1.6       misho      16:        by Michael Pounov <misho@elwix.org>.  All rights reserved.
                     17: 
                     18: Redistribution and use in source and binary forms, with or without
                     19: modification, are permitted provided that the following conditions
                     20: are met:
                     21: 1. Redistributions of source code must retain the above copyright
                     22:    notice, this list of conditions and the following disclaimer.
                     23: 2. Redistributions in binary form must reproduce the above copyright
                     24:    notice, this list of conditions and the following disclaimer in the
                     25:    documentation and/or other materials provided with the distribution.
                     26: 3. All advertising materials mentioning features or use of this software
                     27:    must display the following acknowledgement:
                     28: This product includes software developed by Michael Pounov <misho@elwix.org>
                     29: ELWIX - Embedded LightWeight unIX and its contributors.
                     30: 4. Neither the name of AITNET nor the names of its contributors
                     31:    may be used to endorse or promote products derived from this software
                     32:    without specific prior written permission.
                     33: 
                     34: THIS SOFTWARE IS PROVIDED BY AITNET AND CONTRIBUTORS ``AS IS'' AND
                     35: ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     36: IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     37: ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     38: FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     39: DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     40: OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     41: HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     42: LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     43: OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     44: SUCH DAMAGE.
                     45: */
1.1       misho      46: #ifndef __AITCFG_H
                     47: #define __AITCFG_H
                     48: 
                     49: 
1.7       misho      50: #include <pthread.h>
1.11      misho      51: #include <elwix.h>
1.1       misho      52: 
                     53: 
1.7       misho      54: struct tagCfg {
                     55:        ait_val_t               cfg_sec;
                     56:        ait_val_t               cfg_attr;
                     57:        ait_val_t               cfg_val;
1.18.6.1! misho      58:        int                     cfg_quoted;
1.1       misho      59: 
1.13      misho      60:        TAILQ_ENTRY(tagCfg)     cfg_next;
1.7       misho      61:        RB_ENTRY(tagCfg)        cfg_node;
                     62: };
                     63: typedef struct tagRC {
                     64:        pthread_mutex_t         rc_mtx;
1.4       misho      65: 
1.13      misho      66:        struct tagCfg           *tqh_first;
                     67:        struct tagCfg           **tqh_last;
1.7       misho      68:        struct tagCfg           *rbh_root;
                     69: } cfg_root_t;
                     70: #define CFG_RC_LOCK(x)         pthread_mutex_lock(&(x)->rc_mtx)
                     71: #define CFG_RC_UNLOCK(x)       pthread_mutex_unlock(&(x)->rc_mtx)
1.1       misho      72: 
1.15      misho      73: #define CFG_SECTION(x)         (assert((x)), AIT_GET_LIKE(&((struct tagCfg*) (x))->cfg_sec, const char*))
                     74: #define CFG_ATTRIBUTE(x)       (assert((x)), AIT_GET_LIKE(&((struct tagCfg*) (x))->cfg_attr, const char*))
                     75: #define CFG_VALUE(x)           (assert((x)), AIT_GET_LIKE(&((struct tagCfg*) (x))->cfg_val, const char*))
                     76: 
1.1       misho      77: 
                     78: // cfg_GetErrno() Get error code of last operation
1.11      misho      79: int cfg_GetErrno();
1.1       misho      80: // cfg_GetError() Get error text of last operation
1.11      misho      81: const char *cfg_GetError();
1.1       misho      82: 
                     83: 
                     84: /*
1.7       misho      85:  * Macros for config library.
                     86:  */
                     87: #define CFG_ISEMPTY(x)         RB_EMPTY((x))
1.1       misho      88: 
1.3       misho      89: 
                     90: /*
1.7       misho      91:  * cfgInitConfig() - Init config root
                     92:  *
1.14      misho      93:  * return: NULL error or !=NULL allocated config root
                     94:  */
                     95: cfg_root_t *cfgInitConfig();
                     96: /*
                     97:  * cfgEndConfig() - Free resources & config root
                     98:  *
                     99:  * @pcfg = Config root
                    100:  * return: none
1.7       misho     101:  */
1.14      misho     102: void cfgEndConfig(cfg_root_t **pcfg);
1.7       misho     103: /*
                    104:  * cfgLoadConfig() - Load config from file
                    105:  *
                    106:  * @cfgName = Config filename
                    107:  * @cfg = Config root
                    108:  * return: -1 error or 0 ok
                    109:  */
                    110: int cfgLoadConfig(const char *cfgName, cfg_root_t * __restrict cfg);
                    111: /*
1.8       misho     112:  * cfgUnloadConfig() - Unload config from memory and destroy resources
1.7       misho     113:  *
                    114:  * @cfg = Config root
                    115:  * return: none
                    116:  */
                    117: void cfgUnloadConfig(cfg_root_t * __restrict cfg);
1.3       misho     118: /*
1.8       misho     119:  * cfgClearConfig() - Clear config and free resources
                    120:  *
                    121:  * @cfg = Config root
                    122:  * return: none
                    123:  */
                    124: void cfgClearConfig(cfg_root_t * __restrict cfg);
                    125: /*
1.7       misho     126:  * cfgCreateConfig() - Create config file from memory
                    127:  *
                    128:  * @csConfigName = New config filename
                    129:  * @cfg = Config root
                    130:  * @whitespace = Additional whitespace characters to file
                    131:  * return: -1 error or 0 ok
                    132:  */
                    133: int cfgCreateConfig(const char *csConfigName, cfg_root_t * __restrict cfg, 
                    134:                int whitespace);
                    135: 
                    136: /*
1.9       misho     137:  * cfgReadLines() - Read custom lines and add new item at config root
                    138:  *
                    139:  * @f = File resource
                    140:  * @delim = Custom delimiter, if =NULL default is '='
                    141:  * @end = Custom user end of file, if =NULL default is EOF
                    142:  * @cfg = Config root
                    143:  * return: -1 error or 0 ok
                    144:  */
                    145: int cfgReadLines(FILE *f, const char *delim, const char *end, 
                    146:                cfg_root_t * __restrict cfg);
                    147: /*
1.10      misho     148:  * cfgWriteLines() - Write custom lines and export data to variable
                    149:  *
                    150:  * @f = File resource
                    151:  * @delim = Custom delimiter, if =NULL default is '='
                    152:  * @eol = End of line string, if =NULL default is "\n"
                    153:  * @section = Export only section, if =NULL default is all
                    154:  * @cfg = Config root
1.11      misho     155:  * return: =NULL error or !=NULL exported data, must be free after use with ait_freeVar()
1.10      misho     156:  */
                    157: ait_val_t *cfgWriteLines(FILE *f, const char *delim, const char *eol, 
                    158:                const char *section, cfg_root_t * __restrict cfg);
                    159: /*
1.7       misho     160:  * cfgReadConfig() - Read file and add new item at config root
                    161:  *
                    162:  * @f = File resource
                    163:  * @cfg = Config root
                    164:  * return: -1 error or 0 ok
                    165:  */
                    166: int cfgReadConfig(FILE *f, cfg_root_t * __restrict cfg);
                    167: /*
                    168:  * cfgWriteConfig() - Write config from memory
                    169:  *
                    170:  * @f = File handle
                    171:  * @cfg = Config root
                    172:  * @whitespace = Additional whitespace characters to file
                    173:  * return: -1 error or 0 ok
                    174:  */
                    175: int cfgWriteConfig(FILE *f, cfg_root_t * __restrict cfg, int whitespace);
                    176: /*
1.18      misho     177:  * cfgWriteConfigRaw() - Write config from memory by list
                    178:  *
                    179:  * @f = File handle
                    180:  * @cfg = Config root
                    181:  * @whitespace = Additional whitespace characters to file
                    182:  * return: -1 error or 0 ok
                    183:  */
                    184: int cfgWriteConfigRaw(FILE *f, cfg_root_t * __restrict cfg, int whitespace);
                    185: /*
1.7       misho     186:  * cfgConcatConfig() - Concat two configs into one
                    187:  *
                    188:  * @cfg = Config root
                    189:  * @add_cfg = Concated config will be destroy after merge
                    190:  * return: -1 error or 0 ok
                    191:  */
                    192: int cfgConcatConfig(cfg_root_t * __restrict cfg, cfg_root_t * __restrict add_cfg);
                    193: /*
                    194:  * cfgMergeConfig() - Marge two list in one cfg and destroy add_cfg
                    195:  *
                    196:  * @cfg = Config root of main list
                    197:  * @add_cfg = Merged config will be destroy after merge
                    198:  * return: -1 error or 0 ok
                    199:  */
                    200: int cfgMergeConfig(cfg_root_t * __restrict cfg, cfg_root_t * __restrict add_cfg);
                    201: 
1.17      misho     202: /*
                    203:  * cfg_dumpCfg() - dump config data
                    204:  *
                    205:  * @cfg = Config root
                    206:  * return: none
                    207:  */
                    208: void cfg_dumpCfg(cfg_root_t * __restrict cfg);
1.7       misho     209: /*
1.15      misho     210:  * cfg_getSection() - Get entire section attributes into array
                    211:  *
                    212:  * @cfg = Config root
                    213:  * @csSec = Config section //[{csSec}]
                    214:  * return: NULL not found or !=NULL allocated array, must free with array_Destroy() after use!
                    215:  */
                    216: array_t *cfg_getSection(cfg_root_t * __restrict cfg, const char *csSec);
                    217: /*
1.7       misho     218:  * cfg_findAttribute() - Find attribute position in config file
                    219:  *
                    220:  * @cfg = Config root
1.1       misho     221:  * @csSec = Config section //[{csSec}]
1.18      misho     222:  * @csAttr = Config attribute //{csAttr} = ...
1.7       misho     223:  * return: 0 not found item, -1 error or >0 position in list
                    224:  */
1.11      misho     225: int cfg_findAttribute(cfg_root_t * __restrict cfg, 
1.7       misho     226:                const char *csSec, const char *csAttr);
                    227: /*
                    228:  * cfg_getAttribute() - Get item from config and return value from it
                    229:  *
                    230:  * @cfg = Config root
                    231:  * @csSec = Config section //[{csSec}], if NULL unset in *default* section
1.18      misho     232:  * @csAttr = Config attribute //{csAttr} = ...
1.7       misho     233:  * return: NULL item not found or null parameters, !=NULL value const string
                    234:  */
1.11      misho     235: const char *cfg_getAttribute(cfg_root_t * __restrict cfg, 
1.7       misho     236:                const char *csSec, const char *csAttr);
                    237: /*
1.16      misho     238:  * cfg_getAttributeLong() - Get item as long from config and return value from it
                    239:  *
                    240:  * @cfg = Config root
                    241:  * @csSec = Config section //[{csSec}], if NULL unset in *default* section
1.18      misho     242:  * @csAttr = Config attribute //{csAttr} = ...
1.16      misho     243:  * return: value
                    244:  */
                    245: long cfg_getAttributeLong(cfg_root_t * __restrict cfg, 
                    246:                const char *csSec, const char *csAttr);
                    247: /*
                    248:  * cfg_getAttributeLLong() - Get item as long long from config and return value from it
                    249:  *
                    250:  * @cfg = Config root
                    251:  * @csSec = Config section //[{csSec}], if NULL unset in *default* section
1.18      misho     252:  * @csAttr = Config attribute //{csAttr} = ...
1.16      misho     253:  * return: value
                    254:  */
                    255: long long
                    256: cfg_getAttributeLLong(cfg_root_t * __restrict cfg, 
                    257:                const char *csSec, const char *csAttr);
                    258: /*
                    259:  * cfg_getAttributeDouble() - Get item as double from config and return value from it
                    260:  *
                    261:  * @cfg = Config root
                    262:  * @csSec = Config section //[{csSec}], if NULL unset in *default* section
1.18      misho     263:  * @csAttr = Config attribute //{csAttr} = ...
1.16      misho     264:  * return: value
                    265:  */
                    266: double cfg_getAttributeDouble(cfg_root_t * __restrict cfg, 
                    267:                const char *csSec, const char *csAttr);
                    268: /*
                    269:  * cfg_getAttributeLDouble() - Get item as long double from config and return value from it
                    270:  *
                    271:  * @cfg = Config root
                    272:  * @csSec = Config section //[{csSec}], if NULL unset in *default* section
1.18      misho     273:  * @csAttr = Config attribute //{csAttr} = ...
1.16      misho     274:  * return: value
                    275:  */
                    276: long double cfg_getAttributeLDouble(cfg_root_t * __restrict cfg, 
                    277:                const char *csSec, const char *csAttr);
                    278: /*
1.7       misho     279:  * cfg_setAttribute() - Set item in config or adding new item if not exists
                    280:  *
                    281:  * @cfg = Config root
1.1       misho     282:  * @csSec = Config section //[{csSec}], if NULL set in *default* section
1.7       misho     283:  * @csAttr = Config attribute //{csAttr} = ...
1.1       misho     284:  * @csVal = Config value //... = {csVal} to setup
1.7       misho     285:  * return: 0 nothing changed, -1 error, 1 found and updated item or 2 added new item
                    286:  */
                    287: int cfg_setAttribute(cfg_root_t * __restrict cfg, const char *csSec, 
                    288:                const char *csAttr, const char *csVal);
                    289: /*
                    290:  * cfg_unsetAttribute() - Unset item from config and free resources
                    291:  *
                    292:  * @cfg = Config root
1.1       misho     293:  * @csSec = Config section //[{csSec}], if NULL unset in *default* section
1.18      misho     294:  * @csAttr = Config attribute //{csAttr} = ...
1.7       misho     295:  * return: 0 item not found, -1 error or 1 removed item
                    296:  */
                    297: int cfg_unsetAttribute(cfg_root_t * __restrict cfg, const char *csSec, 
                    298:                const char *csAttr);
1.1       misho     299: 
                    300: /*
1.7       misho     301:  * cfg_loadAttribute() - Get guarded attribute, if not found item return *default value*
                    302:  *
                    303:  * @cfg = Config root
1.1       misho     304:  * @csSec = Config section //[{csSec}], if NULL unset in *default* section
1.18      misho     305:  * @csAttr = Config attribute //{csAttr} = ...
1.7       misho     306:  * @val = Return buffer for item Value //... = {val}
                    307:  * @csDefValue = *Default Value* for return in //{val}, if not found item in config
                    308:  * return: 0 item not found, -1 error or >0 number of copied bytes in //{val}
                    309:  */
                    310: int cfg_loadAttribute(cfg_root_t * __restrict cfg, const char *csSec, 
                    311:                const char *csAttr, ait_val_t * __restrict val, const char *csDefValue);
1.1       misho     312: 
                    313: 
                    314: #endif

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>