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.
  37
  38    <strong>MULTI-LEVEL STRATEGY FOR RETRIEVAL OF BOOTSTRAP VALUES:</strong>
  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.
  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 giving 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).
  50
  51    3rd level: environment variables. The application tries to get the
  52    setting from the environment.
  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 compile time by an API-call.
  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.
  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.
  67
  68    If neither of the above levels leads to a successful retrieval of the value
  69    (no default possible), the application may fail to start.
  70
  71    <strong>NAMING CONVENTIONS</strong>
  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.
  77
  78    An ini-file is only allowed to have one section, which must be named
  79    `[Bootstrap]` with the square brackets.
  80    The section may be omitted.
  81    The section name does not appear in the name of the corresponding
  82    environment variable or commandline arg.
  83    Values may be arbitrary unicode strings, they must be encoded in UTF8.
  84
  85    <em>Example:</em>
  86
  87    in an ini-file:
  88    <code>
  89    [Sectionname]
  90    Name=value
  91    </code>
  92
  93    as commandline arg:
  94    <code>-env:Name=value</code>
  95
  96    as environment:
  97    - <code>setenv Name value</code>
  98    - <code>set Name=value</code>
  99
 100    <strong>SPECIAL VARIABLES:</strong>
 101
 102    - INIFILENAME<br>
 103      This variable allows to set the inifilename. This makes only sense, if the filename
 104      is different than the executable file name. It must be given on command line. If it is
 105      given the executable ini-file is ignored.
 106 */
 107
 108 /** may be called by an application to set an ini-filename.
 109
 110     Must be called before rtl_bootstrap_get(). May not be called twice.
 111     If it is never called, the filename is based on the name of the executable,
 112     with the suffix ".ini" on Windows or "rc" on Unix.
 113
 114     @param pFileUri URL of the inifile with path but WITHOUT suffix (.ini or rc)
 115 */
 116 SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_setIniFileName( rtl_uString *pFileUri );
 117
 118 /**
 119    @param pName
 120            The name of the bootstrap setting to be retrieved.
 121    @param[out] ppValue
 122            Contains always a valid rtl_uString pointer.
 123    @param pDefault
 124            maybe <code>NULL</code>. If once the default is
 125            returned, successive calls always return this
 126            default value, even when called with different
 127            defaults.
 128
 129    @retval sal_True when a value could be retrieved successfully.
 130            When a <code>pDefault</code> value is given,
 131            the function always returns <code>sal_True</code>.
 132    @retval sal_False when none of the 4 methods gave a value.
 133            <code>ppValue</code> then contains an empty string.
 134 */
 135 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_bootstrap_get(
 136         rtl_uString *pName, rtl_uString **ppValue, rtl_uString *pDefault );
 137
 138 /** Sets a bootstrap parameter.
 139
 140    @param pName
 141           name of bootstrap parameter
 142    @param pValue
 143           value of bootstrap parameter
 144 */
 145 SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_set(
 146         rtl_uString * pName, rtl_uString * pValue );
 147
 148
 149 typedef void * rtlBootstrapHandle;
 150
 151 /**
 152    Opens a bootstrap argument container.
 153    @param[in] pIniName    The name of the ini-file to use, if <code>NULL</code> defaults
 154                           to the executables name
 155    @return                Handle for a bootstrap argument container
 156 */
 157 SAL_DLLPUBLIC rtlBootstrapHandle SAL_CALL rtl_bootstrap_args_open(rtl_uString * pIniName);
 158
 159 /**
 160    Closes a bootstrap argument container.
 161    @param[in] handle      The handle got by rtl_bootstrap_args_open()
 162 */
 163 SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_args_close(rtlBootstrapHandle handle)
 164     SAL_THROW_EXTERN_C();
 165
 166 /**
 167    @param[in]  handle       The handle got by rtl_bootstrap_args_open()
 168    @param[in]  pName        The name of the variable to be retrieved
 169    @param[out] ppValue      The result of the retrieval. *ppValue may be null in case of failure.
 170    @param[in]  pDefault     The default value for the retrieval, may be <code>NULL</code>
 171
 172    @return                  The status of the retrieval, <code>sal_True</code> on success.
 173 */
 174 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_bootstrap_get_from_handle(
 175         rtlBootstrapHandle handle, rtl_uString *pName, rtl_uString **ppValue, rtl_uString *pDefault);
 176
 177
 178 /** Returns the name of the inifile associated with this handle.
 179
 180    @param[in]  handle       The handle got by rtl_bootstrap_args_open()
 181    @param[out] ppIniName    contains after the call the name of the ini-filename.
 182 */
 183 SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_get_iniName_from_handle(
 184         rtlBootstrapHandle handle, rtl_uString ** ppIniName);
 185
 186 /** Expands a macro using bootstrap variables.
 187
 188     @param[in]     handle   The handle got by rtl_bootstrap_args_open()
 189     @param[in,out] macro    The macro to be expanded
 190 */
 191 SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_expandMacros_from_handle(
 192     rtlBootstrapHandle handle, rtl_uString ** macro );
 193
 194 /** Expands a macro using default bootstrap variables.
 195
 196     @param[in,out] macro    The macro to be expanded
 197 */
 198 SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_expandMacros(
 199     rtl_uString ** macro);
 200
 201 /** Escapes special characters ("$" and "\").
 202
 203     @param value
 204     an arbitrary, non-NULL value
 205
 206     @param[out] encoded
 207     the given value with all occurrences of special characters ("$" and "\") escaped
 208
 209     @since UDK 3.2.9
 210 */
 211 SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_encode(
 212     rtl_uString const * value, rtl_uString ** encoded );
 213
 214 #ifdef __cplusplus
 215 }
 216 #endif
 217
 218 #endif
 219
 220 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */