ROUTES(3) Library Functions Manual ROUTES(3)

RoutesMatrix API endpoint abstractions.

#include <Routes.h>

char *


MATRIX_PATH_EQUALS(char *, char *);

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.

() and () 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.)

() 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.

() 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 () and (). 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;
} RouteArgs;

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.


December 12, 2022 Telodendria Project