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