include/rtl/bootstrap.h

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