LibreOffice
LibreOffice 6.2 SDK C/C++ API Reference
Typedefs | Functions
bootstrap.h File Reference

The described concept provides a platform independent way to access minimum bootstrap settings for every application by explicitly or implicitly passing the values to the application. More...

#include "sal/config.h"
#include "rtl/ustring.h"
#include "sal/saldllapi.h"

Go to the source code of this file.

Typedefs

typedef void * rtlBootstrapHandle
 

Functions

SAL_DLLPUBLIC void rtl_bootstrap_setIniFileName (rtl_uString *pFileUri)
 may be called by an application to set an ini-filename. More...
 
SAL_DLLPUBLIC sal_Bool rtl_bootstrap_get (rtl_uString *pName, rtl_uString **ppValue, rtl_uString *pDefault)
 
SAL_DLLPUBLIC void rtl_bootstrap_set (rtl_uString *pName, rtl_uString *pValue)
 Sets a bootstrap parameter. More...
 
SAL_DLLPUBLIC rtlBootstrapHandle rtl_bootstrap_args_open (rtl_uString *pIniName)
 Opens a bootstrap argument container. More...
 
SAL_DLLPUBLIC void rtl_bootstrap_args_close (rtlBootstrapHandle handle) SAL_THROW_EXTERN_C()
 Closes a bootstrap argument container. More...
 
SAL_DLLPUBLIC sal_Bool rtl_bootstrap_get_from_handle (rtlBootstrapHandle handle, rtl_uString *pName, rtl_uString **ppValue, rtl_uString *pDefault)
 
SAL_DLLPUBLIC void rtl_bootstrap_get_iniName_from_handle (rtlBootstrapHandle handle, rtl_uString **ppIniName)
 Returns the name of the inifile associated with this handle. More...
 
SAL_DLLPUBLIC void rtl_bootstrap_expandMacros_from_handle (rtlBootstrapHandle handle, rtl_uString **macro)
 Expands a macro using bootstrap variables. More...
 
SAL_DLLPUBLIC void rtl_bootstrap_expandMacros (rtl_uString **macro)
 Expands a macro using default bootstrap variables. More...
 
SAL_DLLPUBLIC void rtl_bootstrap_encode (rtl_uString const *value, rtl_uString **encoded)
 Escapes special characters ("$" and "\"). More...
 

Detailed Description

The described concept provides a platform independent way to access minimum bootstrap settings for every application by explicitly or implicitly passing the values to the application.

MULTI-LEVEL STRATEGY FOR RETRIEVAL OF BOOTSTRAP VALUES:

The 1st level is tried first. On failure, the next level is tried. Every query starts at the first level again, so that one setting may be taken from the 3rd and one from the 1st level.

1st level: explicitly set variables via rtl_bootstrap_set()

2nd level: command line arguments. A -env:SETTINGNAME=value is given on command line. This allows giving an application a certain setting, even if an ini-file exists (especially useful for e.g. daemons that want to start an executable with dynamical changing settings).

3rd level: environment variables. The application tries to get the setting from the environment.

4th level: executable ini-file. Every application looks for an ini-file. The filename defaults to /absolute/path/to/executable[rc|.ini] without .bin or .exe suffix. The ini-filename can be set by the special command line parameter -env:INIFILENAME=/absolute/path/to/inifile at runtime or it may be set at compile time by an API-call.

5th level: URE_BOOTSTRAP ini-file. If the bootstrap variable URE_BOOTSTRAP expands to the URL of an ini-file, that ini-file is searched.

6th level: default. An application can have some default settings decided at compile time, which allow the application to run even with no deployment settings.

If neither of the above levels leads to a successful retrieval of the value (no default possible), the application may fail to start.

NAMING CONVENTIONS

Naming conventions for names of bootstrap values: Names may only include characters, that are allowed characters for environment variables. This excludes '.', ' ', ';', ':' and any non-ascii character. Names are case insensitive.

An ini-file is only allowed to have one section, which must be named [Bootstrap] with the square brackets. The section may be omitted. The section name does not appear in the name of the corresponding environment variable or commandline arg. Values may be arbitrary unicode strings, they must be encoded in UTF8.

Example:

in an ini-file: [Sectionname] Name=value

as commandline arg: -env:Name=value

as environment:

SPECIAL VARIABLES:

Typedef Documentation

typedef void* rtlBootstrapHandle

Function Documentation

SAL_DLLPUBLIC void rtl_bootstrap_args_close ( rtlBootstrapHandle  handle)

Closes a bootstrap argument container.

Parameters
[in]handleThe handle got by rtl_bootstrap_args_open()
SAL_DLLPUBLIC rtlBootstrapHandle rtl_bootstrap_args_open ( rtl_uString *  pIniName)

Opens a bootstrap argument container.

Parameters
[in]pIniNameThe name of the ini-file to use, if NULL defaults to the executables name
Returns
Handle for a bootstrap argument container
SAL_DLLPUBLIC void rtl_bootstrap_encode ( rtl_uString const *  value,
rtl_uString **  encoded 
)

Escapes special characters ("$" and "\").

Parameters
valuean arbitrary, non-NULL value
[out]encodedthe given value with all occurrences of special characters ("$" and "\") escaped
Since
UDK 3.2.9
SAL_DLLPUBLIC void rtl_bootstrap_expandMacros ( rtl_uString **  macro)

Expands a macro using default bootstrap variables.

Parameters
[in,out]macroThe macro to be expanded
SAL_DLLPUBLIC void rtl_bootstrap_expandMacros_from_handle ( rtlBootstrapHandle  handle,
rtl_uString **  macro 
)

Expands a macro using bootstrap variables.

Parameters
[in]handleThe handle got by rtl_bootstrap_args_open()
[in,out]macroThe macro to be expanded
SAL_DLLPUBLIC sal_Bool rtl_bootstrap_get ( rtl_uString *  pName,
rtl_uString **  ppValue,
rtl_uString *  pDefault 
)
Parameters
pNameThe name of the bootstrap setting to be retrieved.
[out]ppValueContains always a valid rtl_uString pointer.
pDefaultmaybe NULL. If once the default is returned, successive calls always return this default value, even when called with different defaults.
Return values
sal_Truewhen a value could be retrieved successfully. When a pDefault value is given, the function always returns sal_True.
sal_Falsewhen none of the 4 methods gave a value. ppValue then contains an empty string.
SAL_DLLPUBLIC sal_Bool rtl_bootstrap_get_from_handle ( rtlBootstrapHandle  handle,
rtl_uString *  pName,
rtl_uString **  ppValue,
rtl_uString *  pDefault 
)
Parameters
[in]handleThe handle got by rtl_bootstrap_args_open()
[in]pNameThe name of the variable to be retrieved
[out]ppValueThe result of the retrieval. *ppValue may be null in case of failure.
[in]pDefaultThe default value for the retrieval, may be NULL
Returns
The status of the retrieval, sal_True on success.
SAL_DLLPUBLIC void rtl_bootstrap_get_iniName_from_handle ( rtlBootstrapHandle  handle,
rtl_uString **  ppIniName 
)

Returns the name of the inifile associated with this handle.

Parameters
[in]handleThe handle got by rtl_bootstrap_args_open()
[out]ppIniNamecontains after the call the name of the ini-filename.
SAL_DLLPUBLIC void rtl_bootstrap_set ( rtl_uString *  pName,
rtl_uString *  pValue 
)

Sets a bootstrap parameter.

Parameters
pNamename of bootstrap parameter
pValuevalue of bootstrap parameter
SAL_DLLPUBLIC void rtl_bootstrap_setIniFileName ( rtl_uString *  pFileUri)

may be called by an application to set an ini-filename.

Must be called before rtl_bootstrap_get(). May not be called twice. If it is never called, the filename is based on the name of the executable, with the suffix ".ini" on Windows or "rc" on Unix.

Parameters
pFileUriURL of the inifile with path but WITHOUT suffix (.ini or rc)