NAME
Routes —
Matrix API endpoint
abstractions.
SYNOPSIS
#include
<Routes.h>
char *
MATRIX_PATH_POP(MATRIX_PATH);
size_t
MATRIX_PATH_PARTS(MATRIX_PATH);
int
MATRIX_PATH_EQUALS(char
*, char *);
DESCRIPTION
Routes 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.
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 Routes.h file for a list of the registered route functions.
MATRIX_PATH_POP()
and
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.
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.)
MATRIX_PATH_POP()
returns the next available part of the path, and removes it from the path
such that the next call to MATRIX_PATH_POP() returns
the part after. MATRIX_PATH_PARTS() returns the
number of path parts remaining.
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.
Routes also defines
ROUTE() and
ROUTE_IMPL().
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". 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.
Every route function takes a RouteArgs structure, which is defined as follows:
typedef struct RouteArgs
{
MatrixHttpHandlerArgs *matrixArgs;
HttpServerContext *context;
MATRIX_PATH *path;
} RouteArgs;
RETURN VALUES
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.