Annotation of libaitcfg/inc/aitcfg.h, revision 1.15.2.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.15.2.1! misho       6: * $Id: aitcfg.h,v 1.15 2014/03/19 18:38:43 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.12      misho      15: Copyright 2004 - 2014
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.1       misho      58: 
1.13      misho      59:        TAILQ_ENTRY(tagCfg)     cfg_next;
1.7       misho      60:        RB_ENTRY(tagCfg)        cfg_node;
                     61: };
                     62: typedef struct tagRC {
                     63:        pthread_mutex_t         rc_mtx;
1.4       misho      64: 
1.13      misho      65:        struct tagCfg           *tqh_first;
                     66:        struct tagCfg           **tqh_last;
1.7       misho      67:        struct tagCfg           *rbh_root;
                     68: } cfg_root_t;
                     69: #define CFG_RC_LOCK(x)         pthread_mutex_lock(&(x)->rc_mtx)
                     70: #define CFG_RC_UNLOCK(x)       pthread_mutex_unlock(&(x)->rc_mtx)
1.1       misho      71: 
1.15      misho      72: #define CFG_SECTION(x)         (assert((x)), AIT_GET_LIKE(&((struct tagCfg*) (x))->cfg_sec, const char*))
                     73: #define CFG_ATTRIBUTE(x)       (assert((x)), AIT_GET_LIKE(&((struct tagCfg*) (x))->cfg_attr, const char*))
                     74: #define CFG_VALUE(x)           (assert((x)), AIT_GET_LIKE(&((struct tagCfg*) (x))->cfg_val, const char*))
                     75: 
1.1       misho      76: 
                     77: // cfg_GetErrno() Get error code of last operation
1.11      misho      78: int cfg_GetErrno();
1.1       misho      79: // cfg_GetError() Get error text of last operation
1.11      misho      80: const char *cfg_GetError();
1.1       misho      81: 
                     82: 
                     83: /*
1.7       misho      84:  * Macros for config library.
                     85:  */
                     86: #define CFG_ISEMPTY(x)         RB_EMPTY((x))
1.1       misho      87: 
1.3       misho      88: 
                     89: /*
1.7       misho      90:  * cfgInitConfig() - Init config root
                     91:  *
1.14      misho      92:  * return: NULL error or !=NULL allocated config root
                     93:  */
                     94: cfg_root_t *cfgInitConfig();
                     95: /*
                     96:  * cfgEndConfig() - Free resources & config root
                     97:  *
                     98:  * @pcfg = Config root
                     99:  * return: none
1.7       misho     100:  */
1.14      misho     101: void cfgEndConfig(cfg_root_t **pcfg);
1.7       misho     102: /*
                    103:  * cfgLoadConfig() - Load config from file
                    104:  *
                    105:  * @cfgName = Config filename
                    106:  * @cfg = Config root
                    107:  * return: -1 error or 0 ok
                    108:  */
                    109: int cfgLoadConfig(const char *cfgName, cfg_root_t * __restrict cfg);
                    110: /*
1.8       misho     111:  * cfgUnloadConfig() - Unload config from memory and destroy resources
1.7       misho     112:  *
                    113:  * @cfg = Config root
                    114:  * return: none
                    115:  */
                    116: void cfgUnloadConfig(cfg_root_t * __restrict cfg);
1.3       misho     117: /*
1.8       misho     118:  * cfgClearConfig() - Clear config and free resources
                    119:  *
                    120:  * @cfg = Config root
                    121:  * return: none
                    122:  */
                    123: void cfgClearConfig(cfg_root_t * __restrict cfg);
                    124: /*
1.7       misho     125:  * cfgCreateConfig() - Create config file from memory
                    126:  *
                    127:  * @csConfigName = New config filename
                    128:  * @cfg = Config root
                    129:  * @whitespace = Additional whitespace characters to file
                    130:  * return: -1 error or 0 ok
                    131:  */
                    132: int cfgCreateConfig(const char *csConfigName, cfg_root_t * __restrict cfg, 
                    133:                int whitespace);
                    134: 
                    135: /*
1.9       misho     136:  * cfgReadLines() - Read custom lines and add new item at config root
                    137:  *
                    138:  * @f = File resource
                    139:  * @delim = Custom delimiter, if =NULL default is '='
                    140:  * @end = Custom user end of file, if =NULL default is EOF
                    141:  * @cfg = Config root
                    142:  * return: -1 error or 0 ok
                    143:  */
                    144: int cfgReadLines(FILE *f, const char *delim, const char *end, 
                    145:                cfg_root_t * __restrict cfg);
                    146: /*
1.10      misho     147:  * cfgWriteLines() - Write custom lines and export data to variable
                    148:  *
                    149:  * @f = File resource
                    150:  * @delim = Custom delimiter, if =NULL default is '='
                    151:  * @eol = End of line string, if =NULL default is "\n"
                    152:  * @section = Export only section, if =NULL default is all
                    153:  * @cfg = Config root
1.11      misho     154:  * return: =NULL error or !=NULL exported data, must be free after use with ait_freeVar()
1.10      misho     155:  */
                    156: ait_val_t *cfgWriteLines(FILE *f, const char *delim, const char *eol, 
                    157:                const char *section, cfg_root_t * __restrict cfg);
                    158: /*
1.7       misho     159:  * cfgReadConfig() - Read file and add new item at config root
                    160:  *
                    161:  * @f = File resource
                    162:  * @cfg = Config root
                    163:  * return: -1 error or 0 ok
                    164:  */
                    165: int cfgReadConfig(FILE *f, cfg_root_t * __restrict cfg);
                    166: /*
                    167:  * cfgWriteConfig() - Write config from memory
                    168:  *
                    169:  * @f = File handle
                    170:  * @cfg = Config root
                    171:  * @whitespace = Additional whitespace characters to file
                    172:  * return: -1 error or 0 ok
                    173:  */
                    174: int cfgWriteConfig(FILE *f, cfg_root_t * __restrict cfg, int whitespace);
                    175: /*
                    176:  * cfgConcatConfig() - Concat two configs into one
                    177:  *
                    178:  * @cfg = Config root
                    179:  * @add_cfg = Concated config will be destroy after merge
                    180:  * return: -1 error or 0 ok
                    181:  */
                    182: int cfgConcatConfig(cfg_root_t * __restrict cfg, cfg_root_t * __restrict add_cfg);
                    183: /*
                    184:  * cfgMergeConfig() - Marge two list in one cfg and destroy add_cfg
                    185:  *
                    186:  * @cfg = Config root of main list
                    187:  * @add_cfg = Merged config will be destroy after merge
                    188:  * return: -1 error or 0 ok
                    189:  */
                    190: int cfgMergeConfig(cfg_root_t * __restrict cfg, cfg_root_t * __restrict add_cfg);
                    191: 
                    192: /*
1.15      misho     193:  * cfg_getSection() - Get entire section attributes into array
                    194:  *
                    195:  * @cfg = Config root
                    196:  * @csSec = Config section //[{csSec}]
                    197:  * return: NULL not found or !=NULL allocated array, must free with array_Destroy() after use!
                    198:  */
                    199: array_t *cfg_getSection(cfg_root_t * __restrict cfg, const char *csSec);
                    200: /*
1.7       misho     201:  * cfg_findAttribute() - Find attribute position in config file
                    202:  *
                    203:  * @cfg = Config root
1.1       misho     204:  * @csSec = Config section //[{csSec}]
1.15      misho     205:  * @csAttr = Config attribute //{csAttr} = ..., if NULL as *any* attribute
1.7       misho     206:  * return: 0 not found item, -1 error or >0 position in list
                    207:  */
1.11      misho     208: int cfg_findAttribute(cfg_root_t * __restrict cfg, 
1.7       misho     209:                const char *csSec, const char *csAttr);
                    210: /*
                    211:  * cfg_getAttribute() - Get item from config and return value from it
                    212:  *
                    213:  * @cfg = Config root
                    214:  * @csSec = Config section //[{csSec}], if NULL unset in *default* section
1.15      misho     215:  * @csAttr = Config attribute //{csAttr} = ..., if NULL as *any* attribute
1.7       misho     216:  * return: NULL item not found or null parameters, !=NULL value const string
                    217:  */
1.11      misho     218: const char *cfg_getAttribute(cfg_root_t * __restrict cfg, 
1.7       misho     219:                const char *csSec, const char *csAttr);
                    220: /*
1.15.2.1! misho     221:  * cfg_getAttributeLong() - Get item as long from config and return value from it
        !           222:  *
        !           223:  * @cfg = Config root
        !           224:  * @csSec = Config section //[{csSec}], if NULL unset in *default* section
        !           225:  * @csAttr = Config attribute //{csAttr} = ..., if NULL as *any* attribute
        !           226:  * return: value
        !           227:  */
        !           228: long cfg_getAttributeLong(cfg_root_t * __restrict cfg, 
        !           229:                const char *csSec, const char *csAttr);
        !           230: /*
        !           231:  * cfg_getAttributeLLong() - Get item as long long from config and return value from it
        !           232:  *
        !           233:  * @cfg = Config root
        !           234:  * @csSec = Config section //[{csSec}], if NULL unset in *default* section
        !           235:  * @csAttr = Config attribute //{csAttr} = ..., if NULL as *any* attribute
        !           236:  * return: value
        !           237:  */
        !           238: long long
        !           239: cfg_getAttributeLLong(cfg_root_t * __restrict cfg, 
        !           240:                const char *csSec, const char *csAttr);
        !           241: /*
        !           242:  * cfg_getAttributeDouble() - Get item as double from config and return value from it
        !           243:  *
        !           244:  * @cfg = Config root
        !           245:  * @csSec = Config section //[{csSec}], if NULL unset in *default* section
        !           246:  * @csAttr = Config attribute //{csAttr} = ..., if NULL as *any* attribute
        !           247:  * return: value
        !           248:  */
        !           249: double cfg_getAttributeDouble(cfg_root_t * __restrict cfg, 
        !           250:                const char *csSec, const char *csAttr);
        !           251: /*
        !           252:  * cfg_getAttributeLDouble() - Get item as long double from config and return value from it
        !           253:  *
        !           254:  * @cfg = Config root
        !           255:  * @csSec = Config section //[{csSec}], if NULL unset in *default* section
        !           256:  * @csAttr = Config attribute //{csAttr} = ..., if NULL as *any* attribute
        !           257:  * return: value
        !           258:  */
        !           259: long double cfg_getAttributeLDouble(cfg_root_t * __restrict cfg, 
        !           260:                const char *csSec, const char *csAttr);
        !           261: /*
1.7       misho     262:  * cfg_setAttribute() - Set item in config or adding new item if not exists
                    263:  *
                    264:  * @cfg = Config root
1.1       misho     265:  * @csSec = Config section //[{csSec}], if NULL set in *default* section
1.7       misho     266:  * @csAttr = Config attribute //{csAttr} = ...
1.1       misho     267:  * @csVal = Config value //... = {csVal} to setup
1.7       misho     268:  * return: 0 nothing changed, -1 error, 1 found and updated item or 2 added new item
                    269:  */
                    270: int cfg_setAttribute(cfg_root_t * __restrict cfg, const char *csSec, 
                    271:                const char *csAttr, const char *csVal);
                    272: /*
                    273:  * cfg_unsetAttribute() - Unset item from config and free resources
                    274:  *
                    275:  * @cfg = Config root
1.1       misho     276:  * @csSec = Config section //[{csSec}], if NULL unset in *default* section
1.15      misho     277:  * @csAttr = Config attribute //{csAttr} = ..., if NULL as *any* attribute
1.7       misho     278:  * return: 0 item not found, -1 error or 1 removed item
                    279:  */
                    280: int cfg_unsetAttribute(cfg_root_t * __restrict cfg, const char *csSec, 
                    281:                const char *csAttr);
1.1       misho     282: 
                    283: /*
1.7       misho     284:  * cfg_loadAttribute() - Get guarded attribute, if not found item return *default value*
                    285:  *
                    286:  * @cfg = Config root
1.1       misho     287:  * @csSec = Config section //[{csSec}], if NULL unset in *default* section
1.15      misho     288:  * @csAttr = Config attribute //{csAttr} = ..., if NULL as *any* attribute
1.7       misho     289:  * @val = Return buffer for item Value //... = {val}
                    290:  * @csDefValue = *Default Value* for return in //{val}, if not found item in config
                    291:  * return: 0 item not found, -1 error or >0 number of copied bytes in //{val}
                    292:  */
                    293: int cfg_loadAttribute(cfg_root_t * __restrict cfg, const char *csSec, 
                    294:                const char *csAttr, ait_val_t * __restrict val, const char *csDefValue);
1.1       misho     295: 
                    296: 
                    297: #endif

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