Skip to content

Latest commit

 

History

History
119 lines (107 loc) · 3.57 KB

app.md

File metadata and controls

119 lines (107 loc) · 3.57 KB

App functions

Configuration

Before creating an application, you can create a custom configuration:

ctorm_config_t config;

But before using it you should initialize it:

ctorm_config_new(&config);

This will set all the default values, you can modify these by directly accessing them through the ctorm_config_t structure, for example:

// disable request/response logging
config.disable_logging = false;

Managing the application

To create an application:

ctorm_app_t *app = ctorm_app_new(&config);

If you don't have a custom configuration and you want to use the default configuration:

ctorm_app_t *app = ctorm_app_new(NULL);

And to start the application:

ctorm_app_run(app, "0.0.0.0:8080")

This will start the application on port 8080, all interfaces, after the app stops, you should clean up the ctorm_app_t pointer to free all the resources, to do this:

ctorm_app_free(app);

Simple routing

Handlers used for routing should follow this structure:

void route(ctorm_req_t*, ctorm_res_t*);

The ctorm_req_t pointer points to the request object, and the ctorm_res_t pointer points to the response object. To learn what you can do with them, check out the request and response documentation.

To setup routes, you can use these simple macros:

// get_index will handle any GET request for /
GET(app, "/", get_index);

// set_route will handle any PUT request for any routes
// under the `/set` route
PUT(app, "/set/*", set_route);

// top_secret will handle any request which is under the `/top`
// route which contains the `/secret` sub-route
ALL(app, "/top/*/secret", top_secret);

// similar examples
HEAD(app, "/", head_index);
POST(app, "/", post_index);
DELETE(app, "/", delete_index);
OPTIONS(app, "/", options_index);

URL parameters

You can use the : character to specify URL parameters in the routes:

GET(app, "/blog/:lang/desc", get_blog_desc);

For example this route will act the same as /blog/*/desc route. However whatever fills the asterisk (wildcard) will be used as the value of the lang URL parameter.

Later during the handler call, URL parameters can be accessed using the request pointer. See the request documentation for more information.

Middleware

Middleware handlers have the exact same structure with the routes, however they have different macros:

MIDDLEWARE_ALL(app, "/auth/*", auth_check);
MIDDLEWARE_GET(app, "/", get_index_mid);
MIDDLEWARE_PUT(app, "/", put_index_mid);
MIDDLEWARE_HEAD(app, "/", head_index_mid);
MIDDLEWARE_POST(app, "/", post_index_mid);
MIDDLEWARE_DELETE(app, "/", delete_index_mid);
MIDDLEWARE_OPTIONS(app, "/", options_index_mid);

Set static directory

To setup a static route you can use the ctorm_app_static function, please note that ctorm only supports a single static route.

// static files be served at '/static' path,
// from the './files' directory
ctorm_app_static(app, "/static", "./files");

Setup 404 (all) route

By default, requests that does not match with any route will receive a 404 page. You can change this behavior by creating a custom handler for these requests:

ctorm_app_all(app, all_route);

This handler needs to follow the same route handler structure.

Global locals

If you want to pass a variable to all the routes and middlewares, you can use global locals:

ctorm_app_local(app, "config", &config);

To access the local from a route or the middleware handler, you can use REQ_LOCAL or ctorm_req_local. See the request documentation for more information.