Rename the macro for compilation guard; prepare for #inclusion in C++
[OpenSRF.git] / include / opensrf / osrfConfig.h
1 /*
2 Copyright (C) 2005  Georgia Public Library Service 
3 Bill Erickson <highfalutin@gmail.com>
4
5 This program is free software; you can redistribute it and/or
6 modify it under the terms of the GNU General Public License
7 as published by the Free Software Foundation; either version 2
8 of the License, or (at your option) any later version.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 GNU General Public License for more details.
14 */
15
16 #ifndef OSRF_CONFIG_H
17 #define OSRF_CONFIG_H
18
19 #include <opensrf/xml_utils.h>
20 #include <opensrf/utils.h>
21 #include <opensrf/string_array.h>
22 #include <opensrf/osrf_json.h>
23
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27
28 typedef struct {
29         jsonObject* config;
30         char* configContext;
31 } osrfConfig;
32
33
34 /**
35         Parses a new config file.  Caller is responsible for freeing the returned
36                 config object when finished.  
37         @param configFile The XML config file to parse.
38         @param configContext Optional root of the subtree in the config file where 
39         we will look for values. If it's not provided,  searches will be 
40         performed from the root of the config file
41         @return The config object if the file parses successfully.  Otherwise
42                 it returns NULL;
43 */
44 osrfConfig* osrfConfigInit(const char* configFile, const char* configContext);
45
46 /**
47         @return True if we have a default config defined
48 */
49 int osrfConfigHasDefaultConfig();
50
51 /**
52         Replaces the config object's json object.  This is useful
53         if you have a json object already and not an XML config
54         file to parse.
55         @param cfg The config object to alter
56         @param obj The json object to use when searching values
57 */
58 void osrfConfigReplaceConfig(osrfConfig* cfg, const jsonObject* obj);
59
60 /** Deallocates a config object 
61         @param cfg The config object to free
62 */
63 void osrfConfigFree(osrfConfig* cfg);
64
65
66 /* Assigns the default config file.  This file will be used whenever
67         NULL is passed to config retrieval functions 
68         @param cfg The config object to use as the default config
69 */
70 void osrfConfigSetDefaultConfig(osrfConfig* cfg);
71
72 /* frees the default config if one exists */
73 void osrfConfigCleanup();
74
75
76 /** 
77         Returns the value in the config found at 'path'.
78         If the value found at 'path' is a long or a double,
79         the value is stringified and then returned.
80         The caller must free the returned char* 
81
82         if there is a configContext, then it will be appended to 
83         the front of the path like so: //<configContext>/<path>
84         if no configContext was provided to osfConfigSetFile, then 
85         the path is interpreted literally.
86         @param cfg The config file to search or NULL if the default
87                 config should be used
88         @param path The search path
89 */
90 char* osrfConfigGetValue(const osrfConfig* cfg, const char* path, ...);
91
92
93 /**
94  *  @see osrfConfigGetValue
95  *  @return jsonObject found at path
96  */
97 jsonObject* osrfConfigGetValueObject(osrfConfig* cfg, char* path, ...);
98
99
100 /** 
101         Puts the list of values found at 'path' into the pre-allocated 
102         string array.  
103         Note that the config node found at 'path' must be an array.
104         @param cfg The config file to search or NULL if the default
105                 config should be used
106         @param arr An allocated string_array where the values will
107                 be stored
108         @param path The search path
109         @return the number of values added to the string array;
110 */
111
112 int osrfConfigGetValueList(const osrfConfig* cfg, osrfStringArray* arr,
113                 const char* path, ...);
114
115 #ifdef __cplusplus
116 }
117 #endif
118
119 #endif