diff --git a/TODO.txt b/TODO.txt index ccae22e..5bf4dbb 100644 --- a/TODO.txt +++ b/TODO.txt @@ -36,7 +36,7 @@ Due: January 1, 2023 [ ] Matrix [x] Queue [ ] Routes - [ ] TelodendriaConfig + [x] TelodendriaConfig [x] Util [x] Memory [x] Db diff --git a/man/man3/TelodendriaConfig.3 b/man/man3/TelodendriaConfig.3 new file mode 100644 index 0000000..02d46cf --- /dev/null +++ b/man/man3/TelodendriaConfig.3 @@ -0,0 +1,95 @@ +.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 diff --git a/site/index.html b/site/index.html index a80ca98..86bf9c4 100644 --- a/site/index.html +++ b/site/index.html @@ -241,6 +241,12 @@ A feature-complete API for reading and writing JSON. An extension to the Json API that implements Matrix's canonical JSON. + +TelodendriaConfig(3) + +Parse the configuration file into a structure. + +

Resources