xref: /aoo41x/main/sal/inc/rtl/bootstrap.h (revision 514f4c20)
1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 #ifndef _RTL_BOOTSTRAP_H_
24 #define _RTL_BOOTSTRAP_H_
25 
26 #include <rtl/ustring.h>
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 /**
33    @HTML
34    @file
35 
36    The described concept provides a platform independent way to access
37    minimum bootstrap settings for every application by excplitly or
38    implicitly passing the values to the application.<p>
39 
40    MULTI-LEVEL STRATEGY FOR RETRIEVAL OF BOOTSTRAP VALUES :<p>
41 
42    The 1st level is tried first. On failure,
43    the next level is tried. Every query starts at the first level again, so
44    that one setting may be taken from the 3rd and one from the 1st level.<p>
45 
46    1st level: explicitly set variables via rtl_bootstrap_set()
47 
48    2nd level: command line arguments. A "-env:SETTINGNAME=value" is given on
49    command line. This allows to give an application a certain setting, even
50    if an ini-file exists (espicially useful for e.g. daemons that want to
51    start an executable with dynamical changing settings).<p>
52 
53    3rd level: environment variables. The application tries to get the
54    setting from the environment.<p>
55 
56    4th level: executable ini-file. Every application looks for an ini-file.
57    The filename defaults to /absoulte/path/to/executable[rc|.ini]
58    (without .bin or .exe suffix). The ini-filename can be
59    set by the special command line parameter
60    '-env:INIFILENAME=/absolute/path/to/inifile' at runtime or it may
61    be set at compiletime by an API-call.<p>
62 
63    5th level: URE_BOOTSTRAP ini-file. If the bootstrap variable URE_BOOTSTRAP
64    expands to the URL of an ini-file, that ini-file is searched.<p>
65 
66    6th level: default. An application can have some default settings decided
67    at compile time, which allow the application to run even with no
68    deployment settings. <p>
69 
70    If neither of the above levels leads to an successful retrieval of the value
71    (no default possible), the application may  fail to start.<p>
72 
73    NAMING CONVENTIONS <p>
74 
75    Naming conventions for names of bootstrap values :
76    Names may only include characters, that are allowed charcters for
77    environment variables. This excludes '.', ' ', ';', ':' and any non-ascii
78    character. Names are case insensitive.<p>
79 
80    An ini-file is only allowed to have one section, which must be named '[Bootstrap]'.
81    The section may be omitted.
82    The section name does not appear in the name of the corresponding
83    environment variable or commandline arg.
84    Values maybe arbitrary unicode strings, they must be encoded in UTF8.<p>
85 
86    Example:<p>
87 
88    in an ini-file:
89    <code>
90    [Sectionname]
91    Name=value
92    </code><p>
93 
94    as commandline arg:
95    <code>-env:Name=value</code><p>
96 
97    as environment
98    <code>
99    setenv Name value
100    set Name=value
101    </code><p>
102 
103    SPECIAL VARIABLES:
104 
105    <ul>
106    <li> INIFILENAME<br>
107      This variable allows to set the inifilename. This makes only sense, if the filename
108 	 is different than the executable file name. It must be given on command line. If it is
109 	 given the executable ini-file is ignored.
110    </li>
111 */
112 
113 /** may be called by an application to set an ini-filename.
114 
115 	<p>
116     Must be called before rtl_bootstrap_get(). May not be called twice.
117     If it is never called, a the filename executable.ini (win)
118 	or execuablerc (unx) is assumed.
119 
120     @param pName Name of the inifile with path but WITHOUT
121 	suffix (.ini or rc)
122 */
123 void SAL_CALL rtl_bootstrap_setIniFileName( rtl_uString *pName )
124     SAL_THROW_EXTERN_C();
125 
126 /**
127    @param ppValue
128 		out parameter. Contains always a valid rtl_uString pointer.
129    @param pName
130             The name of the bootstrap setting to be 	retrieved.
131    @param pDefault
132 		maybe NULL. If once the default is
133    		returned, successive calls always return this
134        	default value, even when called with different
135        	defaults.
136 
137    @return <code>sal_True</code>, when a value could be retrieved successfully,
138            <code>sal_False</code>, when none of the 4 methods gave a value. ppValue
139 		   then contains ane empty string.
140 		   When a pDefault value is given, the function returns always
141 		   <code>sal_True</code>.
142 */
143 sal_Bool SAL_CALL rtl_bootstrap_get( rtl_uString *pName, rtl_uString **ppValue, rtl_uString *pDefault )
144     SAL_THROW_EXTERN_C();
145 
146 /** Sets a bootstrap parameter.
147 
148    @param pName
149           name of bootstrap parameter
150    @param pValue
151           value of bootstrap parameter
152 */
153 void SAL_CALL rtl_bootstrap_set( rtl_uString * pName, rtl_uString * pValue )
154     SAL_THROW_EXTERN_C();
155 
156 
157 typedef	void * rtlBootstrapHandle;
158 
159 /**
160    Opens a bootstrap argument container.
161    @param pIniName [in]   The name of the ini-file to use, if <code>NULL</code> defaults
162                           to the excutables name
163    @return                Handle for a boostrap argument container
164 */
165 rtlBootstrapHandle SAL_CALL rtl_bootstrap_args_open(rtl_uString * pIniName)
166     SAL_THROW_EXTERN_C();
167 
168 /**
169    Closes a boostrap agument container.
170    @param handle [in]     The handle got by <code>rtl_bootstrap_args_open()</code>
171 */
172 void SAL_CALL rtl_bootstrap_args_close(rtlBootstrapHandle handle)
173     SAL_THROW_EXTERN_C();
174 
175 /**
176    @param handle   [in]     The handle got by <code>rtl_bootstrap_args_open()</code>
177    @param pName    [in]     The name of the variable to be retrieved
178    @param ppValue  [out]    The result of the retrieval. *ppValue may be null in case of failure.
179    @param pDefault [in]     The default value for the retrieval, may be <code>NULL</code>
180 
181    @return                  The status of the retrieval, <code>sal_True</code> on success.
182 */
183 sal_Bool SAL_CALL rtl_bootstrap_get_from_handle(rtlBootstrapHandle handle, rtl_uString *pName, rtl_uString **ppValue, rtl_uString *pDefault)
184     SAL_THROW_EXTERN_C();
185 
186 
187 /** Returns the name of the inifile associated with this handle.
188 
189    @param ppIniName contains after the call the name of the ini-filename.
190 */
191 void SAL_CALL rtl_bootstrap_get_iniName_from_handle(rtlBootstrapHandle handle, rtl_uString ** ppIniName)
192     SAL_THROW_EXTERN_C();
193 
194 /** Expands a macro using bootstrap variables.
195 
196     @param handle   [in]     The handle got by <code>rtl_bootstrap_args_open()</code>
197     @param macro    [inout]  The macro to be expanded
198 */
199 void SAL_CALL rtl_bootstrap_expandMacros_from_handle(
200     rtlBootstrapHandle handle, rtl_uString ** macro )
201     SAL_THROW_EXTERN_C();
202 /** Expands a macro using default bootstrap variables.
203 
204     @param macro    [inout]  The macro to be expanded
205 */
206 void SAL_CALL rtl_bootstrap_expandMacros(
207     rtl_uString ** macro )
208     SAL_THROW_EXTERN_C();
209 
210 /** Escapes special characters ("$" and "\").
211 
212     @param value
213     an arbitrary, non-NULL value
214 
215     @param encoded
216     non-NULL out parameter, receiving the given value with all occurences of
217     special characters ("$" and "\") escaped
218 
219     @since UDK 3.2.9
220 */
221 void SAL_CALL rtl_bootstrap_encode(
222     rtl_uString const * value, rtl_uString ** encoded )
223     SAL_THROW_EXTERN_C();
224 
225 #ifdef __cplusplus
226 }
227 #endif
228 
229 #endif
230