forked from Telodendria/Telodendria
88 lines
2.8 KiB
Groff
88 lines
2.8 KiB
Groff
|
.Dd $Mdocdate: December 12 2022 $
|
||
|
|
.Dt ROUTES 3
|
||
|
|
.Os Telodendria Project
|
||
|
|
.Sh NAME
|
||
|
|
.Nm Routes
|
||
|
|
.Nd Matrix API endpoint abstractions.
|
||
|
|
.Sh SYNOPSIS
|
||
|
|
.In Routes.h
|
||
|
|
.Ft char *
|
||
|
|
.Fn MATRIX_PATH_POP "MATRIX_PATH"
|
||
|
|
.Ft size_t
|
||
|
|
.Fn MATRIX_PATH_PARTS "MATRIX_PATH"
|
||
|
|
.Ft int
|
||
|
|
.Fn MATRIX_PATH_EQUALS "char *" "char *"
|
||
|
|
.Sh DESCRIPTION
|
||
|
|
.Pp
|
||
|
|
.Nm
|
||
|
|
provides all of the Matrix API route functions, as well as a few
|
||
|
|
helpful macros to be used to declare those route functions, and some
|
||
|
|
macros that are intended to be used inside them.
|
||
|
|
.Pp
|
||
|
|
The route macros are intended to increase the readability of the header,
|
||
|
|
so the individual routes are not documented here; only the helper
|
||
|
|
macros and structures are documented here. Consult the
|
||
|
|
.Pa Routes.h
|
||
|
|
file for a list of the registered route functions.
|
||
|
|
.Pp
|
||
|
|
.Fn MATRIX_PATH_POP
|
||
|
|
and
|
||
|
|
.Fn MATRIX_PATH_PARTS
|
||
|
|
are macros that abstract away the underlying data structure of the
|
||
|
|
path so that that routes don't have to care what it is. The reason
|
||
|
|
this design choice was made was so that the data structure can be
|
||
|
|
switched out without breaking all the routes. These macros should
|
||
|
|
be preferred to the actual underlying data structure functions,
|
||
|
|
because the data structure may change in the future.
|
||
|
|
.Pp
|
||
|
|
At the moment, the path data structure is just an array, but it would
|
||
|
|
be much more efficient to switch to a queue (which can be easily done
|
||
|
|
with the current Queue implementation if we just add a function that
|
||
|
|
computes how many elements are in the queue.)
|
||
|
|
.Pp
|
||
|
|
.Fn MATRIX_PATH_POP
|
||
|
|
returns the next available part of the path, and removes it from
|
||
|
|
the path such that the next call to
|
||
|
|
.Fn MATRIX_PATH_POP
|
||
|
|
returns the part after.
|
||
|
|
.Fn MATRIX_PATH_PARTS
|
||
|
|
returns the number of path parts remaining.
|
||
|
|
.Pp
|
||
|
|
.Fn MATRIX_PATH_EQUALS
|
||
|
|
is just a simple string comparison macro. It takes two strings and
|
||
|
|
returns a boolean value indicating whether or not they're equal.
|
||
|
|
.Pp
|
||
|
|
.Nm
|
||
|
|
also defines
|
||
|
|
.Fn ROUTE
|
||
|
|
and
|
||
|
|
.Fn ROUTE_IMPL .
|
||
|
|
.Fn ROUTE
|
||
|
|
is intended to be used only inside the route header, and should be
|
||
|
|
invoked to declare a new route function prototype. It takes the
|
||
|
|
route function name, which by convention starts with "Route".
|
||
|
|
.Fn ROUTE_IMPL
|
||
|
|
may be used to actually implement a route function. It takes the
|
||
|
|
route function name, and the name of the variable to put the
|
||
|
|
RouteArgs in.
|
||
|
|
.Pp
|
||
|
|
Every route function takes a RouteArgs structure, which is defined
|
||
|
|
as follows:
|
||
|
|
.Bd -literal -offset indent
|
||
|
|
typedef struct RouteArgs
|
||
|
|
{
|
||
|
|
MatrixHttpHandlerArgs *matrixArgs;
|
||
|
|
HttpServerContext *context;
|
||
|
|
MATRIX_PATH *path;
|
||
|
|
} RouteArgs;
|
||
|
|
.Ed
|
||
|
|
.Sh RETURN VALUES
|
||
|
|
.Pp
|
||
|
|
Each route returns a JSON hash map that contains the response it
|
||
|
|
intends to return to the client making the request. Routes
|
||
|
|
should NOT return NULL, because then no body will be returned to
|
||
|
|
the client, and that is almost always a bug. The Matrix specification
|
||
|
|
usually mandates that at least an empty JSON object is returned.
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr Matrix 3
|