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_transaction_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_transaction_status { HTTP_SERVER_TRANSACTION_ABORTED = -1 , HTTP_SERVER_REQUEST_DATA_MORE = 0 , HTTP_SERVER_REQUEST_DATA_FINAL = 1 , HTTP_SERVER_TRANSACTION_COMPLETE = 2 }
	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_transaction_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 transaction status, HTTP_SERVER_REQUEST_DATA_MORE and HTTP_SERVER_REQUEST_DATA_FINAL describe the request-body delivery progress. HTTP_SERVER_TRANSACTION_ABORTED and HTTP_SERVER_TRANSACTION_COMPLETE are terminal notifications.
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_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.

http_transaction_status

enum http_transaction_status

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

Indicates the status of the currently processed piece of data.

Enumerator
HTTP_SERVER_TRANSACTION_ABORTED	Transaction aborted, data incomplete.
HTTP_SERVER_REQUEST_DATA_MORE	Transaction incomplete, more data expected.
HTTP_SERVER_REQUEST_DATA_FINAL	Final data fragment in current transaction.
HTTP_SERVER_TRANSACTION_COMPLETE	Transaction completed, response sent completely.

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.