sal/inc/rtl/bootstrap.h

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