Helpers

Description

Direct access to basic environment properties and helpers.

Collaboration diagram for Helpers:

Environment ...
const char *	EnvBuildOS ()
	Operating software ("Debian", "Android", ...).
const char *	EnvBuildArch ()
	Operating architecture (e.g. "amd64", "armhf", ...).
const char *	EnvMachineName ()
	Machine name (network host name).
const char *	EnvExecPathName ()
	Full path name of the executable (== argv[0]).
const char *	EnvExecName ()
	File name of the executable without path.
const char *	EnvInstanceName ()
	Instance name - the identifier for the running process.
const char *	EnvDroidId ()
	Droid ID.
int	EnvPid ()
	Operating system's process identifier (PID).
bool	EnvHaveTerminal ()
	'true', if the application has been started from an interactive terminal.
void	EnvReadIniFile (const char *fileName, CDictCompact< CString > *map)
	Read a .ini file. 'fileName' must be an absolute path name.

Directories ...
const char *	EnvHome2lRoot ()
	Root installation path: all static data (blob + etc).
const char *	EnvHome2lEtc ()
	'etc' root path: configuration data.
const char *	EnvHome2lVar ()
	'var' root path: dynamic data (saved over reboots).
const char *	EnvHome2lTmp ()
	'tmp' root path: dynamic data (not need to save over reboots).
const char *	EnvGetHome2lRootPath (CString *ret, const char *relOrAbsPath)
	Return an absolute path name in the root domain. A path starting with '/' is considered already absolute and is returned unchanged, but normalized.
const char *	EnvGetHome2lEtcPath (CString *ret, const char *relOrAbsPath)
	Return an absolute path name in the 'etc' domain.
const char *	EnvGetHome2lVarPath (CString *ret, const char *relOrAbsPath)
	Return an absolute path name in the 'var' domain.
const char *	EnvGetHome2lTmpPath (CString *ret, const char *relOrAbsPath)
	Return an absolute path name in the 'tmp' domain.
bool	EnvMkVarDir (const char *relOrAbsPath)
	Prepare (create) a directory in the 'var' domain.
bool	EnvMkTmpDir (const char *relOrAbsPath)
	Prepare (create) a directory in the 'tmp' domain.

Network ...
bool	EnvNetResolve (const char *hostAndPort, CString *retHost, int *retPort=NULL, int defaultPort=0, bool warn=true)
	Get a resolved host + port combination.

Location ...
float	EnvLocationLatitudeN ()
	Get the WGS84 latitude north coordinate of the home (the 'location.latitudeN' setting).
float	EnvLocationLongitudeE ()
	Get the WGS84 longitude east coordinate of the home (the 'location.longitudeE' setting).

Function Documentation

EnvExecPathName()

const char * EnvExecPathName

(

)

Full path name of the executable (== argv[0]).

Note: The return values of EnvExecPathName() and EnvExecName() may be undefined (== NULL), e.g. if the main program is a Python script or an Android app.

EnvInstanceName()

const char * EnvInstanceName

(

)

Instance name - the identifier for the running process.

The instance name weakly identifies the running process as follows:

• By default ('EnvInit' called with 'argv[0][0] != '/'), it is set to the executable name (without leading "home2l-"). By calling 'EnvInit' with 'argv[0][0] != '/', it can be set to any given name, in which case EnvExecPathName() will return NULL. In this case 'argv[0]' must refer to the instance full name.
• In a correct installation and during normal operation, no two processes with the same instance name shall be executed simultaneously. This must be considered in the per-host setup and when writing tools for which multiple running instances regularly may make sense.
• The required uniqueness (previous note) is weak in the sense that no technical mechanisms exist to enforce it and no software may rely on it. An example is the case where an administrator starts two Home2l shells simultaneously, which may well act as a single instance.
• Code requiring strict uniqueness should use the PID as an additional criterion (presently done so in the Resources library to identify non-server hosts).

EnvMkVarDir()

bool EnvMkVarDir

(

const char *

relOrAbsPath

)

Prepare (create) a directory in the 'var' domain.

Parameters

relOrAbsPath

is either an absolute path or a path relative to the domain.

On error, a warning is emitted and 'false' is returned.

EnvNetResolve()

bool EnvNetResolve	(	const char *	hostAndPort,
		CString *	retHost,
		int *	retPort = NULL,
		int	defaultPort = 0,
		bool	warn = true
	)

Get a resolved host + port combination.

Parameters

hostAndPort	is a given network host name, optionally followed by ':' and a port number. The host part is translated using the 'net.resolve.<name>' settings.
retHost	is set to the resolved networt host name or IP address.
retPort	may contain a pointer to the resolved port number. This is the first of the following numbers: a) port appended to hostAndPort, b) port given in the 'net.resolve.<name>' setting, c) port passed as defaultPort.
defaultPort	is the default port.
warn	decides whether a warning is logged on error.

Returns

success status.