HTTP service API

Data Structures
struct	http_resource_desc
	HTTP resource description. More...
struct	http_service_config
	HTTP service configuration. More...

Macros
#define	HTTP_RESOURCE_DEFINE(_name, _service, _resource, _detail)
	Define a static HTTP resource.
#define	HTTP_SERVICE_DEFINE_EMPTY(_name, _host, _port, _concurrent, _backlog, _detail, _res_fallback, _config)
	Define an HTTP service without static resources.
#define	HTTPS_SERVICE_DEFINE_EMPTY(_name, _host, _port, _concurrent, _backlog, _detail, _res_fallback, _config, _sec_tag_list, _sec_tag_list_size)
	Define an HTTPS service without static resources.
#define	HTTP_SERVICE_DEFINE(_name, _host, _port, _concurrent, _backlog, _detail, _res_fallback, _config)
	Define an HTTP service with static resources.
#define	HTTPS_SERVICE_DEFINE(_name, _host, _port, _concurrent, _backlog, _detail, _res_fallback, _config, _sec_tag_list, _sec_tag_list_size)
	Define an HTTPS service with static resources.
#define	HTTP_SERVICE_COUNT(_dst)
	Count the number of HTTP services.
#define	HTTP_SERVICE_RESOURCE_COUNT(_service)
	Count HTTP service static resources.
#define	HTTP_SERVICE_FOREACH(_it)
	Iterate over all HTTP services.
#define	HTTP_RESOURCE_FOREACH(_service, _it)
	Iterate over static HTTP resources associated with a given _service.
#define	HTTP_SERVICE_FOREACH_RESOURCE(_service, _it)
	Iterate over all static resources associated with _service .

Typedefs
typedef int(*	http_socket_create_fn) (const struct http_service_desc *svc, int af, int proto)
	Custom socket creation function type.

Enumerations
enum	http_version { HTTP_VERSION_ANY = 0 , HTTP_VERSION_1 = 0x01 , HTTP_VERSION_2 = 0x02 , HTTP_VERSION_3 = 0x04 }
	Supported HTTP version for this service. More...
enum	http_h3_alt_svc_policy { HTTP_H3_ALT_SVC_DEFAULT = 0 , HTTP_H3_ALT_SVC_DISABLE , HTTP_H3_ALT_SVC_ENABLE }
	HTTP/3 Alt-Svc advertisement policy for this service. More...

Detailed Description

Since

3.4

Version

0.1.0

Macro Definition Documentation

HTTP_RESOURCE_DEFINE

#define HTTP_RESOURCE_DEFINE	(		_name,
			_service,
			_resource,
			_detail )

#include <service.h>

Value:

const STRUCT_SECTION_ITERABLE_ALTERNATE(http_resource_desc_##_service, http_resource_desc, \
                                        _name) = {                                         \
        .resource = _resource,                                                             \
        .detail = (void *)(_detail),                                                       \
}

Define a static HTTP resource.

A static HTTP resource is one that is known prior to system initialization. In contrast, dynamic resources may be discovered upon system initialization. Dynamic resources may also be inserted, or removed by events originating internally or externally to the system at runtime.

Note

The _resource is the URL without the associated protocol, host, or URL parameters. E.g. the resource for http://www.foo.com/bar/baz.html#param1=value1 would be /bar/baz.html. It is often referred to as the "path" of the URL. Every (service, resource) pair should be unique. The _resource must be non-NULL.

Parameters

_name	Name of the resource.
_service	Name of the associated service.
_resource	Pathname-like string identifying the resource.
_detail	Implementation-specific detail associated with the resource.

HTTP_RESOURCE_FOREACH

#define HTTP_RESOURCE_FOREACH	(		_service,
			_it )

#include <service.h>

Value:

STRUCT_SECTION_FOREACH_ALTERNATE(http_resource_desc_##_service, http_resource_desc, _it)

Iterate over static HTTP resources associated with a given _service.

Note

This macro requires that _service is defined with HTTP_SERVICE_DEFINE.

Parameters

_service	Name of HTTP service
_it	Name of iterator (of type http_resource_desc)

HTTP_SERVICE_COUNT

#define HTTP_SERVICE_COUNT

(

_dst

)

#include <service.h>

Value:

STRUCT_SECTION_COUNT(http_service_desc, _dst)

Count the number of HTTP services.

Parameters

[out]

_dst

Pointer to location where result is written.

HTTP_SERVICE_DEFINE

#define HTTP_SERVICE_DEFINE	(		_name,
			_host,
			_port,
			_concurrent,
			_backlog,
			_detail,
			_res_fallback,
			_config )

#include <service.h>

Value:

extern struct http_resource_desc _CONCAT(_http_resource_desc_##_name, _list_start)[];      \
extern struct http_resource_desc _CONCAT(_http_resource_desc_##_name, _list_end)[];        \
__z_http_service_define(_name, _host, _port, _concurrent, _backlog, _detail,               \
                        _res_fallback,                                                     \
                        &_CONCAT(_http_resource_desc_##_name, _list_start)[0],             \
                        &_CONCAT(_http_resource_desc_##_name, _list_end)[0], _config);

Define an HTTP service with static resources.

Note

The _host parameter is used to specify an IP address either in IPv4 or IPv6 format a fully-qualified hostname or a virtual host. If left NULL, the listening port will listen on all addresses.

The _port parameter must be non-NULL. It points to a location that specifies the port number to use for the service. If the specified port number is zero, then an ephemeral port number will be used and the actual port number assigned will be written back to memory. For ephemeral port numbers, the memory pointed to by _port must be writeable.

Parameters

	_name	Name of the service.
	_host	IP address or hostname associated with the service.
[in,out]	_port	Pointer to port associated with the service.
	_concurrent	Maximum number of concurrent clients. (max. CONFIG_HTTP_SERVER_MAX_CLIENTS)
	_backlog	Maximum number of queued connections. (min. 1)
	_detail	User-defined detail associated with the service.
	_res_fallback	Fallback resource to be served if no other resource matches path
	_config	Pointer to http_service_config structure (can be NULL for default behavior)

HTTP_SERVICE_DEFINE_EMPTY

#define HTTP_SERVICE_DEFINE_EMPTY	(		_name,
			_host,
			_port,
			_concurrent,
			_backlog,
			_detail,
			_res_fallback,
			_config )

#include <service.h>

Value:

__z_http_service_define(_name, _host, _port, _concurrent, _backlog, _detail,               \
                        _res_fallback, NULL, NULL, _config)

Define an HTTP service without static resources.

Note

The _host parameter is used to specify an IP address either in IPv4 or IPv6 format a fully-qualified hostname or a virtual host. If left NULL, the listening port will listen on all addresses.

The _port parameter must be non-NULL. It points to a location that specifies the port number to use for the service. If the specified port number is zero, then an ephemeral port number will be used and the actual port number assigned will be written back to memory. For ephemeral port numbers, the memory pointed to by _port must be writeable.

Parameters

	_name	Name of the service.
	_host	IP address or hostname associated with the service.
[in,out]	_port	Pointer to port associated with the service.
	_concurrent	Maximum number of concurrent clients. (max. CONFIG_HTTP_SERVER_MAX_CLIENTS)
	_backlog	Maximum number of queued connections. (min. 1)
	_detail	User-defined detail associated with the service.
	_res_fallback	Fallback resource to be served if no other resource matches path
	_config	Pointer to http_service_config structure (can be NULL for default behavior)

HTTP_SERVICE_FOREACH

#define HTTP_SERVICE_FOREACH

(

_it

)

#include <service.h>

Value:

STRUCT_SECTION_FOREACH(http_service_desc, _it)

Iterate over all HTTP services.

Parameters

_it	Name of http_service_desc iterator

HTTP_SERVICE_FOREACH_RESOURCE

#define HTTP_SERVICE_FOREACH_RESOURCE	(		_service,
			_it )

#include <service.h>

Value:

for (struct http_resource_desc *_it = (_service)->res_begin; ({                            \
             __ASSERT(_it <= (_service)->res_end, "unexpected list end location");         \
             _it < (_service)->res_end;                                                    \
     });                                                                                   \
     _it++)

Iterate over all static resources associated with _service .

Note

This macro is suitable for a _service defined with either HTTP_SERVICE_DEFINE or HTTP_SERVICE_DEFINE_EMPTY.

Parameters

_service	Pointer to HTTP service
_it	Name of iterator (of type http_resource_desc)

HTTP_SERVICE_RESOURCE_COUNT

#define HTTP_SERVICE_RESOURCE_COUNT

(

_service

)

#include <service.h>

Value:

((_service)->res_end - (_service)->res_begin)

Count HTTP service static resources.

Parameters

_service

Pointer to a service.

HTTPS_SERVICE_DEFINE

#define HTTPS_SERVICE_DEFINE	(		_name,
			_host,
			_port,
			_concurrent,
			_backlog,
			_detail,
			_res_fallback,
			_config,
			_sec_tag_list,
			_sec_tag_list_size )

#include <service.h>

Value:

extern struct http_resource_desc _CONCAT(_http_resource_desc_##_name, _list_start)[];  \
extern struct http_resource_desc _CONCAT(_http_resource_desc_##_name, _list_end)[];    \
__z_http_service_define(_name, _host, _port, _concurrent, _backlog, _detail,           \
                        _res_fallback,                                                 \
                        &_CONCAT(_http_resource_desc_##_name, _list_start)[0],         \
                        &_CONCAT(_http_resource_desc_##_name, _list_end)[0], _config,  \
                        _sec_tag_list, _sec_tag_list_size);                            \
BUILD_ASSERT(IS_ENABLED(CONFIG_NET_SOCKETS_SOCKOPT_TLS),                               \
             "TLS is required for HTTP secure (CONFIG_NET_SOCKETS_SOCKOPT_TLS)")

Define an HTTPS service with static resources.

Note

The _host parameter is used to specify an IP address either in IPv4 or IPv6 format a fully-qualified hostname or a virtual host. If left NULL, the listening port will listen on all addresses.

The _port parameter must be non-NULL. It points to a location that specifies the port number to use for the service. If the specified port number is zero, then an ephemeral port number will be used and the actual port number assigned will be written back to memory. For ephemeral port numbers, the memory pointed to by _port must be writeable.

Parameters

	_name	Name of the service.
	_host	IP address or hostname associated with the service.
[in,out]	_port	Pointer to port associated with the service.
	_concurrent	Maximum number of concurrent clients. (max. CONFIG_HTTP_SERVER_MAX_CLIENTS)
	_backlog	Maximum number of queued connections. (min. 1)
	_detail	User-defined detail associated with the service.
	_res_fallback	Fallback resource to be served if no other resource matches path
	_config	Pointer to http_service_config structure (can be NULL for default behavior)
	_sec_tag_list	TLS security tag list used to setup a HTTPS socket.
	_sec_tag_list_size	TLS security tag list size used to setup a HTTPS socket.

HTTPS_SERVICE_DEFINE_EMPTY

#define HTTPS_SERVICE_DEFINE_EMPTY	(		_name,
			_host,
			_port,
			_concurrent,
			_backlog,
			_detail,
			_res_fallback,
			_config,
			_sec_tag_list,
			_sec_tag_list_size )

#include <service.h>

Value:

__z_http_service_define(_name, _host, _port, _concurrent, _backlog, _detail,             \
                        _res_fallback, NULL, NULL, _config,                              \
                        _sec_tag_list, _sec_tag_list_size);                              \
BUILD_ASSERT(IS_ENABLED(CONFIG_NET_SOCKETS_SOCKOPT_TLS),                                 \
             "TLS is required for HTTP secure (CONFIG_NET_SOCKETS_SOCKOPT_TLS)")

Define an HTTPS service without static resources.

Note

The _host parameter is used to specify an IP address either in IPv4 or IPv6 format a fully-qualified hostname or a virtual host. If left NULL, the listening port will listen on all addresses.

The _port parameter must be non-NULL. It points to a location that specifies the port number to use for the service. If the specified port number is zero, then an ephemeral port number will be used and the actual port number assigned will be written back to memory. For ephemeral port numbers, the memory pointed to by _port must be writeable.

Parameters

	_name	Name of the service.
	_host	IP address or hostname associated with the service.
[in,out]	_port	Pointer to port associated with the service.
	_concurrent	Maximum number of concurrent clients. (max. CONFIG_HTTP_SERVER_MAX_CLIENTS)
	_backlog	Maximum number of queued connections. (min. 1)
	_detail	User-defined detail associated with the service.
	_res_fallback	Fallback resource to be served if no other resource matches path
	_config	Pointer to http_service_config structure (can be NULL for default behavior)
	_sec_tag_list	TLS security tag list used to setup a HTTPS socket.
	_sec_tag_list_size	TLS security tag list size used to setup a HTTPS socket.

Typedef Documentation

http_socket_create_fn

typedef int(* http_socket_create_fn) (const struct http_service_desc *svc, int af, int proto)

#include <service.h>

Custom socket creation function type.

Allow HTTP service to be customized according to user needs. For example, this can be used to create a socket with custom options or to create a socket of a different type for a specific service.

Parameters

svc	HTTP service description for which the socket is being created.
af	Address family (e.g., AF_INET or AF_INET6) for the socket to be created.
proto	Protocol (e.g., IPPROTO_TCP) for the socket to be created.

Returns

Valid socket file descriptor on success, or a negative error code on failure.

Enumeration Type Documentation

http_h3_alt_svc_policy

enum http_h3_alt_svc_policy

#include <service.h>

HTTP/3 Alt-Svc advertisement policy for this service.

Enumerator
HTTP_H3_ALT_SVC_DEFAULT	Use the global default policy configured in Kconfig.
HTTP_H3_ALT_SVC_DISABLE	Never advertise HTTP/3 via Alt-Svc for this service.
HTTP_H3_ALT_SVC_ENABLE	Always advertise HTTP/3 via Alt-Svc for this service when available.

http_version

enum http_version

#include <service.h>

Supported HTTP version for this service.

If not set, then any configured version is supported. User can also specify a specific version to only support that version for the service. The values can be ORed together to support multiple specific versions.

Enumerator
HTTP_VERSION_ANY	Support any HTTP version configured in the system.
HTTP_VERSION_1	Support HTTP/1.0 and HTTP/1.1.
HTTP_VERSION_2	Support HTTP/2.
HTTP_VERSION_3	Support HTTP/3.