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 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 | */ |
121 | SAL_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 | */ |
141 | SAL_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 | */ |
152 | SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_set( |
153 | rtl_uString * pName, rtl_uString * pValue ) |
154 | SAL_THROW_EXTERN_C(); |
155 | |
156 | |
157 | typedef 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 | */ |
165 | SAL_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 | */ |
172 | SAL_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 | */ |
183 | SAL_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 | */ |
193 | SAL_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 | */ |
202 | SAL_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 | */ |
209 | SAL_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 | */ |
224 | SAL_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 | |