API to make it possible to run an HTTP server to deliver and set values from other components. More...

Data Structures
struct	sol_http_server_config
	It's created with sol_http_server_new() and should be later deleted with sol_http_server_del() More...

struct	sol_http_server_progressive_config
	Progressive server response configuration. More...

Typedefs
typedef struct sol_http_progressive_response	sol_http_progressive_response
	Opaque handler used for send data progressively. More...

typedef struct sol_http_request	sol_http_request
	Opaque handler for a request made to an HTTP server. More...

typedef struct sol_http_server	sol_http_server
	Opaque handler for an HTTP server instance. More...

typedef struct sol_http_server_config	sol_http_server_config
	It's created with sol_http_server_new() and should be later deleted with sol_http_server_del() More...

typedef struct sol_http_server_progressive_config	sol_http_server_progressive_config
	Progressive server response configuration. More...

Functions
void	sol_http_progressive_response_del (struct sol_http_progressive_response *progressive, bool graceful_del)
	Delete the progressive response. More...

int	sol_http_progressive_response_feed (struct sol_http_progressive_response progressive, struct sol_blob blob)
	Send data for the progressive response. More...

int	sol_http_progressive_response_sse_feed (struct sol_http_progressive_response progressive, struct sol_blob blob)
	Send sse data for the progressive response. More...

int	sol_http_request_get_client_address (const struct sol_http_request request, struct sol_network_link_addr address)
	Gets the client address that made the request. More...

int	sol_http_request_get_interface_address (const struct sol_http_request request, struct sol_network_link_addr address)
	Gets the address of the interface that request comes. More...

enum sol_http_method	sol_http_request_get_method (const struct sol_http_request *request)
	Gets the method (GET, POST, ...) from a given request. More...

const struct sol_http_params *	sol_http_request_get_params (const struct sol_http_request *request)
	Gets the parameters from a given request. More...

const char *	sol_http_request_get_url (const struct sol_http_request *request)
	Gets the URL from a given request. More...

static int	sol_http_response_set_sse_headers (struct sol_http_response *response)
	Set the necessary headers to allow server sent events. More...

int	sol_http_server_add_dir (struct sol_http_server server, const char basename, const char *rootdir)
	Add a root dir where the server will look for static files to serve. More...

void	sol_http_server_del (struct sol_http_server *server)
	Destroy the server instance. More...

int	sol_http_server_get_buffer_size (struct sol_http_server server, size_t buf_size)
	Get the request buffer's size. More...

struct sol_http_server *	sol_http_server_new (const struct sol_http_server_config *config)
	Creates an HTTP server, binding on all interfaces in the specified port. More...

int	sol_http_server_register_handler (struct sol_http_server server, const char path, int(request_cb)(void data, struct sol_http_request request), const void data)
	Register a handler for a specific path. More...

int	sol_http_server_remove_dir (struct sol_http_server server, const char basename, const char *rootdir)
	Removes a dir registered with `sol_http_server_add_dir()` More...

struct sol_http_progressive_response *	sol_http_server_send_progressive_response (struct sol_http_request request, const struct sol_http_response response, const struct sol_http_server_progressive_config *config)
	Send the response and keep connection alive to request given in the callback registered on sol_http_server_register_handler(). More...

int	sol_http_server_send_response (struct sol_http_request request, struct sol_http_response response)
	Send the response to request given in the callback registered on `sol_http_server_register_handler()`. More...

int	sol_http_server_set_buffer_size (struct sol_http_server *server, size_t buf_size)
	Set the buffer size for a request. More...

int	sol_http_server_set_last_modified (struct sol_http_server server, const char path, time_t modified)
	Set the last time the specified path had its value modified. More...

int	sol_http_server_unregister_handler (struct sol_http_server server, const char path)
	Removes a handler registered with `sol_http_server_register_handler()` More...

Detailed Description

API to make it possible to run an HTTP server to deliver and set values from other components.

Typedef Documentation

sol_http_progressive_response

Opaque handler used for send data progressively.

Progressive responses can be used to create server sent events.

This response is created with sol_http_server_send_progressive_response() and data can be given using sol_http_progressive_response_feed(). To delete it use sol_http_progressive_response_del().

sol_http_request

Opaque handler for a request made to an HTTP server.

Request properties can be queried with:

A response to a request can be send with sol_http_server_send_response()

sol_http_server

Opaque handler for an HTTP server instance.

It's created with sol_http_server_new() and should be later deleted with sol_http_server_del()

typedef struct sol_http_server_config sol_http_server_config

It's created with sol_http_server_new() and should be later deleted with sol_http_server_del()

typedef struct sol_http_server_progressive_config sol_http_server_progressive_config

Progressive server response configuration.

See Also: sol_http_server_send_progressive_response()

Note: HTTP server follows the Soletta stream design pattern, which can be found here: IO Streams

Function Documentation

void sol_http_progressive_response_del	(	struct sol_http_progressive_response *	progressive,
		bool	graceful_del
	)

Delete the progressive response.

This function deletes the progressive response and its resources and closes the connection. When the connection be closed the callback given on sol_http_server_send_progressive_response() will be called.

Parameters

progressive	The progressive response created with sol_http_server_send_progressive_response()
graceful_del	If `true` all pending data will be sent before the connection be closed.

See Also: sol_http_server_send_progressive_response(); sol_http_progressive_response_feed()

Examples:: /src/samples/http/server-sse.c.

Referenced by on_stdin(), request_events_cb(), and shutdown_server().

int sol_http_progressive_response_feed	(	struct sol_http_progressive_response *	progressive,
		struct sol_blob *	blob
	)

Send data for the progressive response.

If the sum of all blobs plus the new >= sol_http_server_progressive_config::feed_size this function will return -ENOSPC and the blob will not be sent.

Parameters

progressive	The progressive response created with sol_http_server_send_progressive_response()
blob	The blob to be sent.

Returns: 0 on success, -ENOSPC if sol_message_digest_config::feed_size is not zero and there's no more space left or -errno on error. If error or -ENOPSC, If error, then the input reference is not taken.

See Also: sol_http_progressive_response_del(); sol_http_server_send_progressive_response()

Note: HTTP server follows the Soletta stream design pattern, which can be found here: IO Streams

int sol_http_progressive_response_sse_feed	(	struct sol_http_progressive_response *	progressive,
		struct sol_blob *	blob
	)

Send sse data for the progressive response.

If the sum of all blobs plus the new >= sol_http_server_progressive_config::feed_size this function will return -ENOSPC and the blob will not be sent.

This function will automatically add the SSE prefix and suffix.

Parameters

progressive	The progressive response created with sol_http_server_send_progressive_response()
blob	The blob to be sent.

Returns: 0 on success, -ENOSPC if sol_message_digest_config::feed_size is not zero and there's no more space left or -errno on error. If error or -ENOPSC, If error, then the input reference is not taken.

Note: HTTP server follows the Soletta stream design pattern, which can be found here: IO Streams

See Also: sol_http_progressive_response_feed()

Examples:: /src/samples/http/server-sse.c.

Referenced by on_stdin().

int sol_http_request_get_client_address	(	const struct sol_http_request *	request,
		struct sol_network_link_addr *	address
	)

Gets the client address that made the request.

Parameters

request	The request.
address	Will be filled with the origin address.

See Also: sol_http_request_get_interface_address()

int sol_http_request_get_interface_address	(	const struct sol_http_request *	request,
		struct sol_network_link_addr *	address
	)

Gets the address of the interface that request comes.

Parameters

request	The request.
address	Will be filled with the interface address

Returns: 0 on success, error code (always negative) otherwise.

See Also: sol_http_request_get_client_address()

Examples:: /src/samples/http/server-sse.c.

Referenced by request_cb().

enum sol_http_method sol_http_request_get_method ( const struct sol_http_request * request )

Gets the method (GET, POST, ...) from a given request.

Parameters

request The request which the URL is wanted.

Returns: the method on success, SOL_HTTP_METHOD_INVALID otherwise.

const struct sol_http_params* sol_http_request_get_params ( const struct sol_http_request * request )

Gets the parameters from a given request.

Parameters

request The request which the URL is wanted.

Returns: the parameters on success, NULL otherwise.

const char* sol_http_request_get_url ( const struct sol_http_request * request )

Gets the URL from a given request.

Parameters

request The request which the URL is wanted.

Returns: the URL on success, NULL otherwise.

static int sol_http_response_set_sse_headers ( struct sol_http_response * response )

inlinestatic

Set the necessary headers to allow server sent events.

Parameters

response The response to set the headers

Returns: 0 on success, error code (always negative) otherwise.

Examples:: /src/samples/http/server-sse.c.

References sol_http_response::param, sol_http_params_add(), and SOL_HTTP_REQUEST_PARAM_HEADER.

Referenced by request_events_cb().

int sol_http_server_add_dir	(	struct sol_http_server *	server,
		const char *	basename,
		const char *	rootdir
	)

Add a root dir where the server will look for static files to serve.

Note: : The http server will look first for a handler when a request comes, if no valid handler is found it will try to find the file in the root dirs set. The response will be sent as soon as a file matches with the request.

Parameters

server	The value got with `sol_http_server_new()`
basename	The base path of the requests where the server will look for files on `rootdir`
rootdir	The dir where the server will look for static files

Returns: 0 on success, error code (always negative) otherwise.

Examples:: /src/samples/http/static-files.c.

Referenced by startup_server().

void sol_http_server_del ( struct sol_http_server * server )

Destroy the server instance.

Parameters

server The value got with sol_http_server_new()

Examples:: /src/samples/http/server-https.c, /src/samples/http/server-sse.c, /src/samples/http/server.c, and /src/samples/http/static-files.c.

Referenced by shutdown_server().

int sol_http_server_get_buffer_size	(	struct sol_http_server *	server,
		size_t *	buf_size
	)

Get the request buffer's size.

Parameters

server	The handle got with `sol_http_server_new()`
buf_size	Variable to get the buffer's size.

Returns: 0 in success, a negative value otherwise.

See Also: sol_http_server_set_buffer_size()

struct sol_http_server* sol_http_server_new ( const struct sol_http_server_config * config )

Creates an HTTP server, binding on all interfaces in the specified port.

With the returned handle it's possible to register paths using sol_http_server_register_handler() and directories to be served with sol_http_server_add_dir().

Note: Only one instance of sol_http_server is possible per port. Trying to run a second instance in the same port will result in failure.

Parameters

config The parameters to setup the server.

Returns: a handle to the server on success, otherwise NULL is returned.

See Also: sol_http_server_config

Examples:: /src/samples/http/server-https.c, /src/samples/http/server-sse.c, /src/samples/http/server.c, and /src/samples/http/static-files.c.

Referenced by startup_server().

int sol_http_server_register_handler	(	struct sol_http_server *	server,
		const char *	path,
		int()(void data, struct sol_http_request *request)	request_cb,
		const void *	data
	)

Register a handler for a specific path.

Parameters

server	The value got with `sol_http_server_new()`
path	The path where the handler will serve, it means, when a request comes in this path the callback set will be called and a response should be sent back from it
request_cb	The callback for the request received on the specified path
data	The user data passed in the callback

Returns: 0 on success, error code (always negative) otherwise.

Examples:: /src/samples/http/server-https.c, /src/samples/http/server-sse.c, and /src/samples/http/server.c.

Referenced by startup_server().

int sol_http_server_remove_dir	(	struct sol_http_server *	server,
		const char *	basename,
		const char *	rootdir
	)

Removes a dir registered with sol_http_server_add_dir()

Parameters

server	The value got with `sol_http_server_new()`
basename	The same basename given on `sol_http_server_add_dir()`
rootdir	The same rootdir given on `sol_http_server_add_dir()`

Returns: 0 on success, error code (always negative) otherwise.

struct sol_http_progressive_response* sol_http_server_send_progressive_response	(	struct sol_http_request *	request,
		const struct sol_http_response *	response,
		const struct sol_http_server_progressive_config *	config
	)

Send the response and keep connection alive to request given in the callback registered on sol_http_server_register_handler().

After this call, the caller will be resposible to close the connection calling sol_http_progressive_response_del().

Note: all the necessary headers are set by this function.

Parameters

request	The request given on the callback of sol_http_server_register_handler().
response	The response for the request containing the data and parameters (e.g http headers)
config	The progressive connection configuration.

Returns: sol_http_progressive_response on success, NULL otherwise.

See Also: sol_http_server_send_response(); sol_http_progressive_response_del(); sol_http_progressive_response_feed(); sol_http_server_progressive_config

Examples:: /src/samples/http/server-sse.c.

Referenced by request_events_cb().

int sol_http_server_send_response	(	struct sol_http_request *	request,
		struct sol_http_response *	response
	)

Send the response to request given in the callback registered on sol_http_server_register_handler().

After this call, request should not be used anymore.

Parameters

request	The request given on the callback of `sol_http_server_register_handler()`
response	The response for the request containing the data and parameters (e.g http headers)

Returns: 0 on success, error code (always negative) otherwise.

See Also: sol_http_server_send_progressive_response()

Examples:: /src/samples/http/server-https.c, /src/samples/http/server-sse.c, and /src/samples/http/server.c.

Referenced by request_cb().

int sol_http_server_set_buffer_size	(	struct sol_http_server *	server,
		size_t	buf_size
	)

Set the buffer size for a request.

This function changes the default request's buffer size, it is used to store the post data. The default value is 4096 bytes.

Parameters

server	The handle got with `sol_http_server_new()`
buf_size	The size of the buffer.

Returns: 0 in success, a negative value otherwise.

See Also: sol_http_server_get_buffer_size

int sol_http_server_set_last_modified	(	struct sol_http_server *	server,
		const char *	path,
		time_t	modified
	)

Set the last time the specified path had its value modified.

It'll make the server return automatically a response with the code 304 (not modified) when the request contains the header If-Since-Modified greater than the value given in this function.

Note: : This is specific per server/path.

Parameters

server	The value got with `sol_http_server_new()`
path	The same path given on `sol_http_server_register_handler()`
modified	The time it was modified

Returns: 0 on success, error code (always negative) otherwise.

int sol_http_server_unregister_handler	(	struct sol_http_server *	server,
		const char *	path
	)

Removes a handler registered with sol_http_server_register_handler()

Parameters

server	The value got with `sol_http_server_new`
path	The same path given on `sol_http_server_register_handler()`

Returns: 0 on success, error code (always negative) otherwise.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation