forked from Telodendria/Telodendria
96 lines
3 KiB
Groff
96 lines
3 KiB
Groff
|
.Dd $Mdocdate: December 10 2022 $
|
||
|
|
.Dt TELODENDRIACONFIG 3
|
||
|
|
.Os Telodendria Project
|
||
|
|
.Sh NAME
|
||
|
|
.Nm TelodendriaConfig
|
||
|
|
.Nd Parse the configuration file into a structure.
|
||
|
|
.Sh SYNOPSIS
|
||
|
|
.In TelodendriaConfig.h
|
||
|
|
.Ft TelodendriaConfig *
|
||
|
|
.Fn TelodendriaConfigParse "HashMap *" "LogConfig *"
|
||
|
|
.Ft void
|
||
|
|
.Fn TelodendriaConfigFree "TelodendriaConfig *"
|
||
|
|
.Sh DESCRIPTION
|
||
|
|
.Pp
|
||
|
|
Validate and maintain the Telodendria server's configuration data. This API
|
||
|
|
builds on the JSON API to add Telodendria-specific parsing. It takes a
|
||
|
|
fully-parsed JSON object and converts it into a TelodendriaConfig, which is
|
||
|
|
much more structured and easier to work with than the JSON. The config
|
||
|
|
structure is not opaque like many other structures in Telodendria. This is
|
||
|
|
intentional; defining functions for all of the fields would just add a lot
|
||
|
|
of unecessary overhead. The structure is defined as follows:
|
||
|
|
.Bd -literal -offset indent
|
||
|
|
typedef struct TelodendriaConfig
|
||
|
|
{
|
||
|
|
char *serverName;
|
||
|
|
char *baseUrl;
|
||
|
|
char *identityServer;
|
||
|
|
|
||
|
|
char *uid;
|
||
|
|
char *gid;
|
||
|
|
char *dataDir;
|
||
|
|
|
||
|
|
unsigned short listenPort;
|
||
|
|
unsigned int flags;
|
||
|
|
unsigned int threads;
|
||
|
|
unsigned int maxConnections;
|
||
|
|
|
||
|
|
size_t maxCache;
|
||
|
|
|
||
|
|
char *logTimestamp;
|
||
|
|
int logLevel;
|
||
|
|
} TelodendriaConfig;
|
||
|
|
.Ed
|
||
|
|
.Pp
|
||
|
|
Since the configuration will live in memory for a long time, it is important
|
||
|
|
that unused values are freed as soon as possible. Therefore, the Telodendria
|
||
|
|
structure is not opaque; values are accessed directly, and they can be
|
||
|
|
freed as the program wishes. Do note that if you're going to free a value, you
|
||
|
|
should set it to NULL, because
|
||
|
|
.Fn TelodendriaConfigFree
|
||
|
|
will unconditionally call
|
||
|
|
.Fn Free
|
||
|
|
on all values.
|
||
|
|
.Pp
|
||
|
|
The flags variable in this structure is a bit field that contains the OR-ed values
|
||
|
|
of any of the given flags:
|
||
|
|
.Bd -literal -offset indent
|
||
|
|
typedef enum TelodendriaConfigFlag
|
||
|
|
{
|
||
|
|
TELODENDRIA_FEDERATION,
|
||
|
|
TELODENDRIA_REGISTRATION,
|
||
|
|
|
||
|
|
TELODENDRIA_LOG_COLOR,
|
||
|
|
|
||
|
|
TELODENDRIA_LOG_FILE,
|
||
|
|
TELODENDRIA_LOG_STDOUT,
|
||
|
|
TELODENDRIA_LOG_SYSLOG
|
||
|
|
} TelodendriaConfigFlag;
|
||
|
|
.Ed
|
||
|
|
.Pp
|
||
|
|
Do note that the actual values of these enums are omitted, but they can be
|
||
|
|
OR-ed together and added to flags.
|
||
|
|
.Pp
|
||
|
|
.Fn TelodendriaConfigParse
|
||
|
|
parses a JSON map, extracting the necessary values, validating them, and then
|
||
|
|
adding them to a new TelodendriaConfig for future use by the program. All values
|
||
|
|
are copied, so the JSON hash map can be safely freed if this function
|
||
|
|
succeeds. It takes a working log configuration so that messages can be written
|
||
|
|
to the log as the parsing progresses, to warn users about default values and
|
||
|
|
report errors, for example.
|
||
|
|
.Pp
|
||
|
|
.Fn TelodendriaConfigFree
|
||
|
|
frees all of the memory allocated for the given configuration. This function
|
||
|
|
unconditionally calls
|
||
|
|
.Fn Free
|
||
|
|
on all items in the structure, so make sure that items that were already freed
|
||
|
|
are NULL.
|
||
|
|
.Sh RETURN VALUES
|
||
|
|
.Pp
|
||
|
|
.Fn TelodendriaConfigParse
|
||
|
|
returns a TelodendriaConfig that is completely independent of the passed
|
||
|
|
configuration hash map, or NULL if one or more required values is missing, or
|
||
|
|
there was some other error while parsing the configuration.
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr Json 3
|