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 argument 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 occurrences 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