forked from lda/telodendria
Document TelodendriaConfig
This commit is contained in:
parent
152d444e32
commit
323dad1f8b
4 changed files with 102 additions and 42 deletions
2
TODO.txt
2
TODO.txt
|
|
@ -36,7 +36,7 @@ Due: January 1, 2023
|
|||
[ ] Matrix
|
||||
[x] Queue
|
||||
[ ] Routes
|
||||
[ ] TelodendriaConfig
|
||||
[x] TelodendriaConfig
|
||||
[x] Util
|
||||
[x] Memory
|
||||
[x] Db
|
||||
|
|
|
|||
95
man/man3/TelodendriaConfig.3
Normal file
95
man/man3/TelodendriaConfig.3
Normal file
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="man/man3/TelodendriaConfig.3.html">TelodendriaConfig(3)</a></td>
|
||||
<td>
|
||||
Parse the configuration file into a structure.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
<h2 id="resources">Resources</h2>
|
||||
<ul>
|
||||
|
|
|
|||
|
|
@ -22,12 +22,6 @@
|
|||
* SOFTWARE.
|
||||
*/
|
||||
|
||||
/*
|
||||
* TelodendriaConfig.h: Validate and maintain the Telodendria server's
|
||||
* configuration data. This API builds on the Config API to add
|
||||
* Telodendria-specific parsing. It takes a fully parsed Config, and
|
||||
* converts it into a TelodendriaConfig, which is more structured.
|
||||
*/
|
||||
#ifndef TELODENDRIA_TELODENDRIACONFIG_H
|
||||
#define TELODENDRIA_TELODENDRIACONFIG_H
|
||||
|
||||
|
|
@ -44,15 +38,6 @@ typedef enum TelodendriaConfigFlag
|
|||
TELODENDRIA_LOG_SYSLOG = (1 << 5)
|
||||
} TelodendriaConfigFlag;
|
||||
|
||||
/*
|
||||
* Since this configuration will live in memory for a long time, it is
|
||||
* important that unused values are freed as soon as possible. Therefore,
|
||||
* the TelodendriaConfig structure is not opaque; values are accessed
|
||||
* directly, and they can be freed as the program wishes.
|
||||
*
|
||||
* NOTE: If you're going to free a value, make sure you set the pointer
|
||||
* to NULL. TelodendriaConfigFree() will call free() on all values.
|
||||
*/
|
||||
typedef struct TelodendriaConfig
|
||||
{
|
||||
char *serverName;
|
||||
|
|
@ -74,35 +59,9 @@ typedef struct TelodendriaConfig
|
|||
int logLevel;
|
||||
} TelodendriaConfig;
|
||||
|
||||
/*
|
||||
* Parse a Config 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 Config hash map can be safely
|
||||
* freed if this function succeeds.
|
||||
*
|
||||
* Params:
|
||||
* (HashMap *) A hash map from ConfigParse(). This should be a map of
|
||||
* ConfigDirectives.
|
||||
* (LogConfig *) A working log configuration. Messages are written to
|
||||
* this log as the parsing progresses, and this log is
|
||||
* copied into the resulting TelodendriaConfig. It is
|
||||
* also potentially modified by the configuration file's
|
||||
* "log" block.
|
||||
*
|
||||
* Return: A TelodendriaConfig that is completely independent of the passed
|
||||
* configuration hash map, or NULL if one or more required values is missing.
|
||||
*/
|
||||
extern TelodendriaConfig *
|
||||
TelodendriaConfigParse(HashMap *, LogConfig *);
|
||||
|
||||
/*
|
||||
* Free all of the memory allocated to the given configuration. This
|
||||
* function unconditionally calls free() on all items in the structure,
|
||||
* so make sure items that were already freed are NULL.
|
||||
*
|
||||
* Params:
|
||||
* (TelodendriaConfig *) The configuration to free all the values for.
|
||||
*/
|
||||
extern void
|
||||
TelodendriaConfigFree(TelodendriaConfig *);
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue