Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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)    __z_http_service_define(_name, _host, _port, _concurrent, _backlog, _detail, NULL, NULL)
 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)   STRUCT_SECTION_COUNT(http_service_desc, _dst)
 Count the number of HTTP services.
 
#define HTTP_SERVICE_RESOURCE_COUNT(_service)   ((_service)->res_end - (_service)->res_begin)
 Count HTTP service static resources.
 
#define HTTP_SERVICE_FOREACH(_it)   STRUCT_SECTION_FOREACH(http_service_desc, _it)
 Iterate over all HTTP services.
 
#define HTTP_RESOURCE_FOREACH(_service, _it)    STRUCT_SECTION_FOREACH_ALTERNATE(http_resource_desc_##_service, http_resource_desc, _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

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 STRUCT_SECTION_ITERABLE_ALTERNATE(secname, struct_type, varname)
Defines a new element of alternate data type for an iterable section.
Definition: iterable_sections.h:188
HTTP resource description.
Definition: service.h:32

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
_nameName of the resource.
_serviceName of the associated service.
_resourcePathname-like string identifying the resource.
_detailImplementation-specific detail associated with the resource.

◆ HTTP_RESOURCE_FOREACH

#define HTTP_RESOURCE_FOREACH (   _service,
  _it 
)     STRUCT_SECTION_FOREACH_ALTERNATE(http_resource_desc_##_service, http_resource_desc, _it)

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

Iterate over static HTTP resources associated with a given _service.

Note
This macro requires that _service is defined with HTTP_SERVICE_DEFINE.
Parameters
_serviceName of HTTP service
_itName of iterator (of type http_resource_desc)

◆ HTTP_SERVICE_COUNT

#define HTTP_SERVICE_COUNT (   _dst)    STRUCT_SECTION_COUNT(http_service_desc, _dst)

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

Count the number of HTTP services.

Parameters
[out]_dstPointer 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 must be non-NULL. It is used to specify an IP address either in IPv4 or IPv6 format a fully-qualified hostname or a virtual host.
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
_nameName of the service.
_hostIP address or hostname associated with the service.
[in,out]_portPointer to port associated with the service.
_concurrentMaximum number of concurrent clients.
_backlogMaximum number queued connections.
_detailImplementation-specific detail associated with the service.

◆ HTTP_SERVICE_DEFINE_EMPTY

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

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

Define an HTTP service without static resources.

Note
The _host parameter must be non-NULL. It is used to specify an IP address either in IPv4 or IPv6 format a fully-qualified hostname or a virtual host.
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
_nameName of the service.
_hostIP address or hostname associated with the service.
[in,out]_portPointer to port associated with the service.
_concurrentMaximum number of concurrent clients.
_backlogMaximum number queued connections.
_detailImplementation-specific detail associated with the service.

◆ HTTP_SERVICE_FOREACH

#define HTTP_SERVICE_FOREACH (   _it)    STRUCT_SECTION_FOREACH(http_service_desc, _it)

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

Iterate over all HTTP services.

Parameters
_itName 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
_servicePointer to HTTP service
_itName of iterator (of type http_resource_desc)

◆ HTTP_SERVICE_RESOURCE_COUNT

#define HTTP_SERVICE_RESOURCE_COUNT (   _service)    ((_service)->res_end - (_service)->res_begin)

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

Count HTTP service static resources.

Parameters
_servicePointer 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 IS_ENABLED(config_macro)
Check for macro definition in compiler-visible expressions.
Definition: util_macro.h:124

Define an HTTPS service with static resources.

Note
The _host parameter must be non-NULL. It is used to specify an IP address either in IPv4 or IPv6 format a fully-qualified hostname or a virtual host.
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
_nameName of the service.
_hostIP address or hostname associated with the service.
[in,out]_portPointer to port associated with the service.
_concurrentMaximum number of concurrent clients.
_backlogMaximum number queued connections.
_detailImplementation-specific detail associated with the service.
_sec_tag_listTLS security tag list used to setup a HTTPS socket.
_sec_tag_list_sizeTLS 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 must be non-NULL. It is used to specify an IP address either in IPv4 or IPv6 format a fully-qualified hostname or a virtual host.
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
_nameName of the service.
_hostIP address or hostname associated with the service.
[in,out]_portPointer to port associated with the service.
_concurrentMaximum number of concurrent clients.
_backlogMaximum number queued connections.
_detailImplementation-specific detail associated with the service.
_sec_tag_listTLS security tag list used to setup a HTTPS socket.
_sec_tag_list_sizeTLS security tag list size used to setup a HTTPS socket.