HTTP service API

Data Structures
struct	http_resource_desc
	HTTP resource description. 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)
	Define an HTTP service without static resources.
#define	HTTPS_SERVICE_DEFINE_EMPTY(_name, _host, _port, _concurrent, _backlog, _detail, _sec_tag_list, _sec_tag_list_size)
	Define an HTTPS service without static resources.
#define	HTTP_SERVICE_DEFINE(_name, _host, _port, _concurrent, _backlog, _detail)
	Define an HTTP service with static resources.
#define	HTTPS_SERVICE_DEFINE(_name, _host, _port, _concurrent, _backlog, _detail, _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 .

Detailed Description

Since

3.4

Version

0.1.0

Macro Definition Documentation

HTTP_RESOURCE_DEFINE

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

#include <zephyr/net/http/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 <zephyr/net/http/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 <zephyr/net/http/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 )

#include <zephyr/net/http/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,               \
                                &_CONCAT(_http_resource_desc_##_name, _list_start)[0],             \
                                &_CONCAT(_http_resource_desc_##_name, _list_end)[0])

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.
	_backlog	Maximum number queued connections.
	_detail	Implementation-specific detail associated with the service.

HTTP_SERVICE_DEFINE_EMPTY

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

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

Value:

        __z_http_service_define(_name, _host, _port, _concurrent, _backlog, _detail, NULL, NULL)

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.
	_backlog	Maximum number queued connections.
	_detail	Implementation-specific detail associated with the service.

HTTP_SERVICE_FOREACH

#define HTTP_SERVICE_FOREACH

(

_it

)

#include <zephyr/net/http/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 <zephyr/net/http/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 <zephyr/net/http/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,
			_sec_tag_list,
			_sec_tag_list_size )

#include <zephyr/net/http/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,           \
                                &_CONCAT(_http_resource_desc_##_name, _list_start)[0],         \
                                &_CONCAT(_http_resource_desc_##_name, _list_end)[0],           \
                                _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.
	_backlog	Maximum number queued connections.
	_detail	Implementation-specific detail associated with the service.
	_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,
			_sec_tag_list,
			_sec_tag_list_size )

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

Value:

        __z_http_service_define(_name, _host, _port, _concurrent, _backlog, _detail, NULL, NULL, \
                                _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.
	_backlog	Maximum number queued connections.
	_detail	Implementation-specific detail associated with the service.
	_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.