HTTP server API

Data Structures
struct	http_resource_detail
	Representation of a server resource, common for all resource types. More...
struct	http_resource_detail_static
	Representation of a static server resource. More...
struct	http_resource_detail_static_fs
	Representation of a static filesystem server resource. More...
struct	http_content_type
struct	http_header
	HTTP header representation. More...
struct	http_request_ctx
	HTTP request context. More...
struct	http_response_ctx
	HTTP response context. More...
struct	http_resource_detail_dynamic
	Representation of a dynamic server resource. More...
struct	http_resource_detail_websocket
	Representation of a websocket server resource. More...
struct	http2_stream_ctx
	HTTP/2 stream representation. More...
struct	http2_frame
	HTTP/2 frame representation. More...
struct	http_header_name
	HTTP header name representation. More...
struct	http_client_ctx
	Representation of an HTTP client connected to the server. More...

Macros
#define	HTTP_SERVER_CONTENT_TYPE(_extension, _content_type)
#define	HTTP_SERVER_CONTENT_TYPE_FOREACH(_it)
#define	HTTP_SERVER_REGISTER_HEADER_CAPTURE(_id, _header)
	Register an HTTP request header to be captured by the server.

Typedefs
typedef int(*	http_resource_dynamic_cb_t) (struct http_client_ctx *client, enum http_data_status status, const struct http_request_ctx *request_ctx, struct http_response_ctx *response_ctx, void *user_data)
	Callback used when data is received.
typedef int(*	http_resource_websocket_cb_t) (int ws_socket, struct http_request_ctx *request_ctx, void *user_data)
	Callback used when a Websocket connection is setup.

Enumerations
enum	http_resource_type { HTTP_RESOURCE_TYPE_STATIC , HTTP_RESOURCE_TYPE_STATIC_FS , HTTP_RESOURCE_TYPE_DYNAMIC , HTTP_RESOURCE_TYPE_WEBSOCKET }
	HTTP server resource type. More...
enum	http_compression {   HTTP_NONE = 0 , HTTP_GZIP = 1 , HTTP_COMPRESS = 2 , HTTP_DEFLATE = 3 ,   HTTP_BR = 4 , HTTP_ZSTD = 5 }
	HTTP compressions. More...
enum	http_data_status { HTTP_SERVER_DATA_ABORTED = -1 , HTTP_SERVER_DATA_MORE = 0 , HTTP_SERVER_DATA_FINAL = 1 }
	Indicates the status of the currently processed piece of data. More...
enum	http_header_status { HTTP_HEADER_STATUS_OK , HTTP_HEADER_STATUS_DROPPED , HTTP_HEADER_STATUS_NONE }
	Status of captured request headers. More...

Functions
int	http_server_start (void)
	Start the HTTP2 server.
int	http_server_stop (void)
	Stop the HTTP2 server.

Detailed Description

Since

3.7

Version

0.1.0

Macro Definition Documentation

HTTP_SERVER_CONTENT_TYPE

#define HTTP_SERVER_CONTENT_TYPE	(		_extension,
			_content_type )

#include <zephyr/net/http/server.h>

Value:

        const STRUCT_SECTION_ITERABLE(http_content_type, _extension) = {                           \
                .extension = STRINGIFY(_extension),                                                \
                .extension_len = sizeof(STRINGIFY(_extension)) - 1,                                \
                .content_type = _content_type,                                                     \
        };

HTTP_SERVER_CONTENT_TYPE_FOREACH

#define HTTP_SERVER_CONTENT_TYPE_FOREACH

(

_it

)

#include <zephyr/net/http/server.h>

Value:

STRUCT_SECTION_FOREACH(http_content_type, _it)

HTTP_SERVER_REGISTER_HEADER_CAPTURE

#define HTTP_SERVER_REGISTER_HEADER_CAPTURE	(		_id,
			_header )

#include <zephyr/net/http/server.h>

Value:

        BUILD_ASSERT(sizeof(_header) <= CONFIG_HTTP_SERVER_MAX_HEADER_LEN,                         \
                     "Header is too long to be captured, try increasing "                          \
                     "CONFIG_HTTP_SERVER_MAX_HEADER_LEN");                                         \
        static const char *const _id##_str = _header;                                              \
        static const STRUCT_SECTION_ITERABLE(http_header_name, _id) = {                            \
                .name = _id##_str,                                                                 \
        }

Register an HTTP request header to be captured by the server.

Parameters

_id	variable name for the header capture instance
_header	header to be captured, as literal string

Typedef Documentation

http_resource_dynamic_cb_t

typedef int(* http_resource_dynamic_cb_t) (struct http_client_ctx *client, enum http_data_status status, const struct http_request_ctx *request_ctx, struct http_response_ctx *response_ctx, void *user_data)

#include <zephyr/net/http/server.h>

Callback used when data is received.

Data to be sent to client can be specified.

Parameters

client	HTTP context information for this client connection.
status	HTTP data status, indicate whether more data is expected or not.
request_ctx	Request context structure containing HTTP request data that was received.
response_ctx	Response context structure for application to populate with response data.
user_data	User specified data.

Returns

0 success, server can send any response data provided in the response_ctx. <0 error, close the connection.

http_resource_websocket_cb_t

typedef int(* http_resource_websocket_cb_t) (int ws_socket, struct http_request_ctx *request_ctx, void *user_data)

#include <zephyr/net/http/server.h>

Callback used when a Websocket connection is setup.

The application will need to handle all functionality related to the connection like reading and writing websocket data, and closing the connection.

Parameters

ws_socket	A socket for the Websocket data.
request_ctx	Request context structure associated with HTTP upgrade request
user_data	User specified data.

Returns

0 Accepting the connection, HTTP server library will no longer handle data to/from the socket and it is application responsibility to send and receive data to/from the supplied socket. <0 error, close the connection.

Enumeration Type Documentation

http_compression

enum http_compression

#include <zephyr/net/http/server.h>

HTTP compressions.

Enumerator
HTTP_NONE	NONE.
HTTP_GZIP	GZIP.
HTTP_COMPRESS	COMPRESS.
HTTP_DEFLATE	DEFLATE.
HTTP_BR	BR.
HTTP_ZSTD	ZSTD.

http_data_status

enum http_data_status

#include <zephyr/net/http/server.h>

Indicates the status of the currently processed piece of data.

Enumerator
HTTP_SERVER_DATA_ABORTED	Transaction aborted, data incomplete.
HTTP_SERVER_DATA_MORE	Transaction incomplete, more data expected.
HTTP_SERVER_DATA_FINAL	Final data fragment in current transaction.

http_header_status

enum http_header_status

#include <zephyr/net/http/server.h>

Status of captured request headers.

Enumerator
HTTP_HEADER_STATUS_OK	All available headers were successfully captured.
HTTP_HEADER_STATUS_DROPPED	One or more headers were dropped due to lack of space.
HTTP_HEADER_STATUS_NONE	No header status is available.

http_resource_type

enum http_resource_type

#include <zephyr/net/http/server.h>

HTTP server resource type.

Enumerator
HTTP_RESOURCE_TYPE_STATIC	Static resource, cannot be modified on runtime.
HTTP_RESOURCE_TYPE_STATIC_FS	serves static gzipped files from a filesystem
HTTP_RESOURCE_TYPE_DYNAMIC	Dynamic resource, server interacts with the application via registered http_resource_dynamic_cb_t.
HTTP_RESOURCE_TYPE_WEBSOCKET	Websocket resource, application takes control over Websocket connection after and upgrade.

Function Documentation

http_server_start()

int http_server_start

(

void

)

#include <zephyr/net/http/server.h>

Start the HTTP2 server.

The server runs in a background thread. Once started, the server will create a server socket for all HTTP services registered in the system and accept connections from clients (see HTTP_SERVICE_DEFINE).

http_server_stop()

int http_server_stop

(

void

)

#include <zephyr/net/http/server.h>

Stop the HTTP2 server.

All server sockets are closed and the server thread is suspended.