Description

The HTTP server module implements a lightweight HTTP server. The HTTP server itself is only a framework for handler classes. It will accept incoming connections and extract various parameters of the request, like URL, query parameters, headers etc. Then it will call all request handlers in sequence until one of the handlers signals that the request was completely handled by the handler.

The server is multithreaded and will start one thread for each connection.

Any number of request handler classes may be installed to the HTTP server. Each of those handler classes has to implement a handle() function. This function gets the requesting connection. From the connection the handle() function may get the various parameters of the request.

Each handler may alter the various request and response parameters. This is useful for preprocessing the request for subsequent handlers. In that case it can return false which will pass the request to subsequent handlers. Note that if a handler changes the URL of a request and then returns false then the iteration over the handlers will start again from the first handler.

If a request handler is responsible for handling a request it may first alter the response and then use the IConnection::print() or IConnection::enqueue() function to output data. Then it has to return true to indicate that no subsequent request handlers have to be called.

In addition to the request handlers, response handlers may be installed to the server. A response handler is called just before the response is sent out to the client. It may alter the response header fields and it may cause side effects (like installing data handlers). Each request or response handler may install a data handler to the connection. All payload data sent to the client will be passed through all data handlers installed to the connection. The data handlers may or may not alter the data passed through it. This may be used to do things like SSI (server-side include) expansion, server side script execution, implementing logging etc.

To create a server the mi::http::IFactory needs to be obtained from the neuray API using mi::neuraylib::INeuray::get_api_component(). The factory can then be used to create as many HTTP servers as needed and also to create built-in request and response handlers.