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