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
28extern "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 excplitly 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 (espicially 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*/
121SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_setIniFileName( rtl_uString *pFileUri )
122 SAL_THROW_EXTERN_C();
123
124/**
125 @param ppValue
126 out parameter. Contains always a valid rtl_uString pointer.
127 @param pName
128 The name of the bootstrap setting to be retrieved.
129 @param pDefault
130 maybe NULL. If once the default is
131 returned, successive calls always return this
132 default value, even when called with different
133 defaults.
134
135 @return <code>sal_True</code>, when a value could be retrieved successfully,
136 <code>sal_False</code>, when none of the 4 methods gave a value. ppValue
137 then contains ane empty string.
138 When a pDefault value is given, the function returns always
139 <code>sal_True</code>.
140*/
141SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_bootstrap_get(
142 rtl_uString *pName, rtl_uString **ppValue, rtl_uString *pDefault )
143 SAL_THROW_EXTERN_C();
144
145/** Sets a bootstrap parameter.
146
147 @param pName
148 name of bootstrap parameter
149 @param pValue
150 value of bootstrap parameter
151*/
152SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_set(
153 rtl_uString * pName, rtl_uString * pValue )
154 SAL_THROW_EXTERN_C();
155
156
157typedef void * rtlBootstrapHandle;
158
159/**
160 Opens a bootstrap argument container.
161 @param pIniName [in] The name of the ini-file to use, if <code>NULL</code> defaults
162 to the excutables name
163 @return Handle for a boostrap argument container
164*/
165SAL_DLLPUBLIC rtlBootstrapHandle SAL_CALL rtl_bootstrap_args_open(rtl_uString * pIniName)
166 SAL_THROW_EXTERN_C();
167
168/**
169 Closes a boostrap agument container.
170 @param handle [in] The handle got by <code>rtl_bootstrap_args_open()</code>
171*/
172SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_args_close(rtlBootstrapHandle handle)
173 SAL_THROW_EXTERN_C();
174
175/**
176 @param handle [in] The handle got by <code>rtl_bootstrap_args_open()</code>
177 @param pName [in] The name of the variable to be retrieved
178 @param ppValue [out] The result of the retrieval. *ppValue may be null in case of failure.
179 @param pDefault [in] The default value for the retrieval, may be <code>NULL</code>
180
181 @return The status of the retrieval, <code>sal_True</code> on success.
182*/
183SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_bootstrap_get_from_handle(
184 rtlBootstrapHandle handle, rtl_uString *pName, rtl_uString **ppValue, rtl_uString *pDefault)
185 SAL_THROW_EXTERN_C();
186
187
188/** Returns the name of the inifile associated with this handle.
189
190 @param handle [in] The handle got by <code>rtl_bootstrap_args_open()</code>
191 @param ppIniName [out] contains after the call the name of the ini-filename.
192*/
193SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_get_iniName_from_handle(
194 rtlBootstrapHandle handle, rtl_uString ** ppIniName)
195 SAL_THROW_EXTERN_C();
196
197/** Expands a macro using bootstrap variables.
198
199 @param handle [in] The handle got by <code>rtl_bootstrap_args_open()</code>
200 @param macro [inout] The macro to be expanded
201*/
202SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_expandMacros_from_handle(
203 rtlBootstrapHandle handle, rtl_uString ** macro )
204 SAL_THROW_EXTERN_C();
205/** Expands a macro using default bootstrap variables.
206
207 @param macro [inout] The macro to be expanded
208*/
209SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_expandMacros(
210 rtl_uString ** macro )
211 SAL_THROW_EXTERN_C();
212
213/** Escapes special characters ("$" and "\").
214
215 @param value
216 an arbitrary, non-NULL value
217
218 @param encoded
219 non-NULL out parameter, receiving the given value with all occurrences of
220 special characters ("$" and "\") escaped
221
222 @since UDK 3.2.9
223*/
224SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_encode(
225 rtl_uString const * value, rtl_uString ** encoded )
226 SAL_THROW_EXTERN_C();
227
228#ifdef __cplusplus
229}
230#endif
231
232#endif
233
234/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
235