Handlers

User processing of data is made through request handers. There are many builtin handlers but the real power is to be able to create your own.

A custom handler implementation

A proper handler has the following signature:

onion_connection_status handler(void *private_data, onion_request *request, onion_response *response);

But usually you will find it in this more friendly one (and fully compatible):

int handler(hander_data *data, onion_request *request, onion_response *response);

A handler can decide based on data of the request to process the data or pass to the next. To pass to the next just return 0 or OCS_NOT_PROCESSED. If its not processed its passed to the next on this layer. alternatively it may decide to pass the request just to an internal layer, calling another handler.

If it decides to process it, it uses the onion_response object as provided. This response may set the headers (onion_response_set_header), and then write normal data (onion_response_write, onion_response_write0 or onion_response_printf). When processing ends OCS_PROCESSED should be returned.

There exist also some helpers for normal response manipulation: onion_response_set_code, onion_response_set_length. It is important to set the headers at the begining, as if they are set after any user write, they will be lost.

int handler(void *nodata, onion_request *req, onion_response *res){
 if (strcmp(onion_request_path(req),"index.html")!=0)
   return OCS_NOT_PROCESSED;
 onion_response_printf(res, "You are calling host %s", onion_request_get_header("Host"));
 return OCS_PROCESSED;
}

To use this handler, you need the handler object: onion_handler_new((void*)handler, NULL, NULL).

Please check the examples for real world examples on how to use it.