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