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