blob: 48804b1ff9bcdb9811e2cd6c141b4319ade5b1f0 [file] [log] [blame]
/*
* Copyright (c) 2017 Intel Corporation.
*
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @file
*
* @brief HTTP server and client implementation for Zephyr.
*/
#ifndef __HTTP_H__
#define __HTTP_H__
#include <net/net_app.h>
#include <net/http_parser.h>
#ifdef __cplusplus
extern "C" {
#endif
#if !defined(ZEPHYR_USER_AGENT)
#define ZEPHYR_USER_AGENT "Zephyr"
#endif
#if !defined(CONFIG_HTTP_SERVER_NUM_URLS)
#define CONFIG_HTTP_SERVER_NUM_URLS 1
#endif
#if !defined(CONFIG_HTTP_HEADERS)
#define CONFIG_HTTP_HEADERS 1
#endif
#if !defined(HTTP_PROTOCOL)
#define HTTP_PROTOCOL "HTTP/1.1"
#endif
/**
* @brief HTTP client and server library
* @defgroup http HTTP Library
* @ingroup networking
* @{
*/
#define HTTP_CRLF "\r\n"
struct http_ctx;
enum http_state {
HTTP_STATE_CLOSED,
HTTP_STATE_WAITING_HEADER,
HTTP_STATE_RECEIVING_HEADER,
HTTP_STATE_HEADER_RECEIVED,
HTTP_STATE_OPEN,
} __packed;
enum http_url_flags {
HTTP_URL_STANDARD = 0,
HTTP_URL_WEBSOCKET,
} __packed;
enum http_connection_type {
HTTP_CONNECTION = 1,
WS_CONNECTION,
};
/* HTTP header fields struct */
struct http_field_value {
/** Field name, this variable will point to the beginning of the string
* containing the HTTP field name
*/
const char *key;
/** Value, this variable will point to the beginning of the string
* containing the field value
*/
const char *value;
/** Length of the field name */
u16_t key_len;
/** Length of the field value */
u16_t value_len;
};
/* HTTP root URL struct, used for pattern matching */
struct http_root_url {
/** URL */
const char *root;
/** URL specific user data */
u8_t *user_data;
/** Length of the URL */
u16_t root_len;
/** Flags for this URL (values are from enum http_url_flags) */
u8_t flags;
/** Is this URL resource used or not */
u8_t is_used;
};
enum http_verdict {
HTTP_VERDICT_DROP,
HTTP_VERDICT_ACCEPT,
};
/**
* @typedef http_url_cb_t
* @brief Default URL callback.
*
* @details This callback is called if there is a connection to unknown URL.
*
* @param ctx The context to use.
* @param type Connection type (websocket or HTTP)
* @param dst Remote socket address
*
* @return HTTP_VERDICT_DROP if connection is to be dropped,
* HTTP_VERDICT_ACCEPT if the application wants to accept the unknown URL.
*/
typedef enum http_verdict (*http_url_cb_t)(struct http_ctx *ctx,
enum http_connection_type type,
const struct sockaddr *dst);
/* Collection of URLs that this server will handle */
struct http_server_urls {
/* First item is the default handler and it is always there.
*/
struct http_root_url default_url;
/** Callback that is called when unknown (default) URL is received */
http_url_cb_t default_cb;
struct http_root_url urls[CONFIG_HTTP_SERVER_NUM_URLS];
};
/**
* @typedef http_recv_cb_t
* @brief Network data receive callback.
*
* @details The recv callback is called after a network data is
* received.
*
* @param ctx The context to use.
* @param pkt Network buffer that is received. If the pkt is not NULL,
* then the callback will own the buffer and it needs to to unref the pkt
* as soon as it has finished working with it. On EOF, pkt will be NULL.
* @param status Value is set to 0 if some data or the connection is
* at EOF, <0 if there was an error receiving data, in this case the
* pkt parameter is set to NULL.
* @param flags Flags related to http. For example contains information
* if the data is text or binary etc.
* @param dst Remote socket address from where HTTP packet is received.
* @param user_data The user data given in init call.
*/
typedef void (*http_recv_cb_t)(struct http_ctx *ctx,
struct net_pkt *pkt,
int status,
u32_t flags,
const struct sockaddr *dst,
void *user_data);
/**
* @typedef http_connect_cb_t
* @brief Connection callback.
*
* @details The connect callback is called after there was a connection to
* non-default URL.
*
* @param ctx The context to use.
* @param type Connection type (websocket or HTTP)
* @param dst Remote socket address where the connection is established.
* @param user_data The user data given in init call.
*/
typedef void (*http_connect_cb_t)(struct http_ctx *ctx,
enum http_connection_type type,
const struct sockaddr *dst,
void *user_data);
/**
* @typedef http_send_cb_t
* @brief Network data send callback.
*
* @details The send callback is called after a network data is
* sent.
*
* @param ctx The context to use.
* @param status Value is set to 0 if all data was sent ok, <0 if
* there was an error sending data. >0 amount of data that was
* sent when not all data was sent ok.
* @param user_data_send The user data given in http_send() call.
* @param user_data The user data given in init call.
*/
typedef void (*http_send_cb_t)(struct http_ctx *ctx,
int status,
void *user_data_send,
void *user_data);
/**
* @typedef http_close_cb_t
* @brief Close callback.
*
* @details The close callback is called after a connection was shutdown.
*
* @param ctx The context to use.
* @param status Error code for the closing.
* @param user_data The user data given in init call.
*/
typedef void (*http_close_cb_t)(struct http_ctx *ctx,
int status,
void *user_data);
/** Websocket and HTTP callbacks */
struct http_cb {
/** Function that is called when a connection is established.
*/
http_connect_cb_t connect;
/** Function that is called when data is received from network.
*/
http_recv_cb_t recv;
/** Function that is called when net_pkt is sent.
*/
http_send_cb_t send;
/** Function that is called when connection is shutdown.
*/
http_close_cb_t close;
};
#if defined(CONFIG_HTTP_CLIENT)
/* Is there more data to come */
enum http_final_call {
HTTP_DATA_MORE = 0,
HTTP_DATA_FINAL = 1,
};
/* Some generic configuration options, these can be overridden if needed. */
#if !defined(HTTP_STATUS_STR_SIZE)
#define HTTP_STATUS_STR_SIZE 32
#endif
/**
* @typedef http_response_cb_t
* @brief Callback used when a response has been received from peer.
*
* @param ctx HTTP context.
* @param data Received data buffer
* @param buflen Data buffer len (as specified by user)
* @param datalen Received data len, if this is larger than buflen,
* then some data was skipped.
* @param final_data Does this data buffer contain all the data or
* is there still more data to come.
* @param user_data A valid pointer on some user data or NULL
*/
typedef void (*http_response_cb_t)(struct http_ctx *ctx,
u8_t *data,
size_t buflen,
size_t datalen,
enum http_final_call final_data,
void *user_data);
/**
* HTTP client request. This contains all the data that is needed when doing
* a HTTP request.
*/
struct http_request {
/** The HTTP method: GET, HEAD, OPTIONS, POST, ... */
enum http_method method;
/** The URL for this request, for example: /index.html */
const char *url;
/** The HTTP protocol: HTTP/1.1 */
const char *protocol;
/** The HTTP header fields (application specific)
* The Content-Type may be specified here or in the next field.
* Depending on your application, the Content-Type may vary, however
* some header fields may remain constant through the application's
* life cycle.
*/
const char *header_fields;
/** The value of the Content-Type header field, may be NULL */
const char *content_type_value;
/** Hostname to be used in the request */
const char *host;
/** Payload, may be NULL */
const char *payload;
/** Payload size, may be 0 */
u16_t payload_size;
};
#endif /* CONFIG_HTTP_CLIENT */
/**
* Http context information. This contains all the data that is
* needed when working with http API.
*/
struct http_ctx {
/** Net app context. The http connection is handled via
* the net app API.
*/
struct net_app_ctx app_ctx;
/** Local endpoint IP address */
struct sockaddr local;
/** Original server address */
struct sockaddr *server_addr;
/** Pending data to be sent */
struct net_pkt *pending;
#if defined(CONFIG_HTTP_CLIENT)
/** Server name */
const char *server;
#endif /* CONFIG_HTTP_CLIENT */
struct {
#if defined(CONFIG_HTTP_CLIENT)
/** Semaphore to signal HTTP connection creation. */
struct k_sem connect_wait;
/** HTTP request information */
struct {
/**
* Semaphore to signal HTTP request completion
*/
struct k_sem wait;
/** Hostname to be used in the request */
const char *host;
/** User provided data */
void *user_data;
/** What method we used here (GET, POST, HEAD etc.)
*/
enum http_method method;
} req;
/** HTTP response information */
struct {
/** User provided HTTP response callback which is
* called when a response is received to a sent HTTP
* request.
*/
http_response_cb_t cb;
/** Where the body starts.
*/
u8_t *body_start;
/** Where the response is stored, this is to be
* provided by the user.
*/
u8_t *response_buf;
/** Response buffer maximum length */
size_t response_buf_len;
/** Length of the data in the result buf. If the value
* is larger than response_buf_len, then it means that
* the data is truncated and could not be fully copied
* into response_buf. This can only happen if the user
* did not set the response callback. If the callback
* is set, then the HTTP client API will call response
* callback many times so that all the data is
* delivered to the user.
*/
size_t data_len;
/** HTTP Content-Length field value */
size_t content_length;
/** Content length parsed. This should be the same as
* the content_length field if parsing was ok.
*/
size_t processed;
/* https://tools.ietf.org/html/rfc7230#section-3.1.2
* The status-code element is a 3-digit integer code
*
* The reason-phrase element exists for the sole
* purpose of providing a textual description
* associated with the numeric status code. A client
* SHOULD ignore the reason-phrase content.
*/
char http_status[HTTP_STATUS_STR_SIZE];
u8_t cl_present:1;
u8_t body_found:1;
u8_t message_complete:1;
} rsp;
#endif /* CONFIG_HTTP_CLIENT */
/** HTTP parser for parsing the initial request */
struct http_parser parser;
/** HTTP parser settings */
struct http_parser_settings parser_settings;
#if defined(CONFIG_HTTP_SERVER)
/** Collection of HTTP header fields */
struct http_field_value field_values[CONFIG_HTTP_HEADERS];
/** Collection of HTTP URLs that this context will handle. */
struct http_server_urls *urls;
/** Where the request is stored, this needs to be provided by
* the user.
*/
u8_t *request_buf;
/** Request buffer maximum length */
size_t request_buf_len;
/** Length of the data in the request buf. */
size_t data_len;
/** Number of header field elements */
u16_t field_values_ctr;
#endif /* CONFIG_HTTP_SERVER */
/** HTTP Request URL */
const char *url;
/** URL's length */
u16_t url_len;
} http;
#if defined(CONFIG_WEBSOCKET)
struct {
/** Pending data that is not yet ready for processing */
struct net_pkt *pending;
/** Amount of data that needs to be read still */
u32_t data_waiting;
/** Websocket connection masking value */
u32_t masking_value;
/** How many bytes we have read */
u32_t data_read;
/** Message type flag. Value is one of WS_FLAG_XXX flag values
* defined in weboscket.h
*/
u32_t msg_type_flag;
} websocket;
#endif /* CONFIG_WEBSOCKET */
#if defined(CONFIG_NET_DEBUG_HTTP_CONN)
sys_snode_t node;
#endif /* CONFIG_HTTP_DEBUG_HTTP_CONN */
/** HTTP callbacks */
struct http_cb cb;
/** User specified data that is passed in callbacks. */
u8_t *user_data;
/** State of the websocket */
enum http_state state;
/** Network buffer allocation timeout */
s32_t timeout;
/** Is this context setup or not */
u8_t is_init : 1;
/** Is this context setup for client or server */
u8_t is_client : 1;
/** Is this instance supporting TLS or not. */
u8_t is_tls : 1;
/** Are we connected or not (only used in client) */
u8_t is_connected : 1;
};
#if defined(CONFIG_HTTP_SERVER)
/**
* @brief Create a HTTP listener.
*
* @details Note that the context must be valid for the whole duration of the
* http life cycle. This usually means that it cannot be allocated from
* stack.
*
* @param ctx Http context. This init function will initialize it.
* @param urls Array of URLs that the server instance will serve. If the
* server receives a HTTP request into one of the URLs, it will call user
* supplied callback. If no such URL is registered, a default handler will
* be called (if set by the user). If no data handler is found, the request
* is dropped.
* @param server_addr Socket address of the local network interface and TCP
* port where the data is being waited. If the socket family is set to
* AF_UNSPEC, then both IPv4 and IPv6 is started to be listened. If the
* address is set to be INADDR_ANY (for IPv4) or unspecified address (all bits
* zeros for IPv6), then the HTTP server will select proper IP address to bind
* to. If caller has not specified HTTP listening port, then port 80 is being
* listened. The parameter can be left NULL in which case a listener to port 80
* using IPv4 and IPv6 is created. Note that if IPv4 or IPv6 is disabled, then
* the corresponding disabled service listener is not created.
* @param request_buf Caller-supplied buffer where the HTTP request will be
* stored
* @param request_buf_len Length of the caller-supplied buffer.
* @param server_banner Print information about started service. This is only
* printed if HTTP debugging is activated. The parameter can be set to NULL if
* no extra prints are needed.
* @param user_data User specific data that is passed as is to the connection
* callbacks.
*
* @return 0 if ok, <0 if error.
*/
int http_server_init(struct http_ctx *ctx,
struct http_server_urls *urls,
struct sockaddr *server_addr,
u8_t *request_buf,
size_t request_buf_len,
const char *server_banner,
void *user_data);
#if defined(CONFIG_HTTPS)
/**
* @brief Initialize TLS support for this http context
*
* @param ctx Http context
* @param server_banner Print information about started service. This is only
* printed if net_app debugging is activated. The parameter can be set to NULL
* if no extra prints are needed.
* @param personalization_data Personalization data (Device specific
* identifiers) for random number generator. (Can be NULL).
* @param personalization_data_len Length of the personalization data.
* @param cert_cb User supplied callback that setups the certificates.
* @param entropy_src_cb User supplied callback that setup the entropy. This
* can be set to NULL, in which case default entropy source is used.
* @param pool Memory pool for RX data reads.
* @param stack TLS thread stack.
* @param stack_len TLS thread stack size.
*
* @return Return 0 if ok, <0 if error.
*/
int http_server_set_tls(struct http_ctx *ctx,
const char *server_banner,
u8_t *personalization_data,
size_t personalization_data_len,
net_app_cert_cb_t cert_cb,
net_app_entropy_src_cb_t entropy_src_cb,
struct k_mem_pool *pool,
k_thread_stack_t *stack,
size_t stack_len);
#endif /* CONFIG_HTTPS */
/**
* @brief Enable HTTP server that is related to this context.
*
* @detail The HTTP server will start to serve request after this.
*
* @param ctx Http context.
*
* @return 0 if server is enabled, <0 otherwise
*/
int http_server_enable(struct http_ctx *ctx);
/**
* @brief Disable HTTP server that is related to this context.
*
* @detail The HTTP server will stop to serve request after this.
*
* @param ctx Http context.
*
* @return 0 if server is disabled, <0 if there was an error
*/
int http_server_disable(struct http_ctx *ctx);
/**
* @brief Add an URL to a list of URLs that are tied to certain webcontext.
*
* @param urls URL struct that will contain all the URLs the user wants to
* register.
* @param url URL string.
* @param flags Flags for the URL.
*
* @return NULL if the URL is already registered, pointer to URL if
* registering was ok.
*/
struct http_root_url *http_server_add_url(struct http_server_urls *urls,
const char *url, u8_t flags);
/**
* @brief Delete the URL from list of URLs that are tied to certain
* webcontext.
*
* @param urls URL struct that will contain all the URLs the user has
* registered.
* @param url URL string.
*
* @return 0 if ok, <0 if error.
*/
int http_server_del_url(struct http_server_urls *urls, const char *url);
/**
* @brief Add default URL handler.
*
* @detail If no URL handler is found, then call this handler. There can
* be only one default handler in the URL struct. The callback can decide
* if the connection request is dropped or passed.
*
* @param urls URL struct that will contain all the URLs the user has
* registered.
* @param cb Callback that is called when non-registered URL is requested.
*
* @return NULL if default URL is already registered, pointer to default
* URL if registering was ok.
*/
struct http_root_url *http_server_add_default(struct http_server_urls *urls,
http_url_cb_t cb);
/**
* @brief Delete the default URL handler.
*
* @detail Unregister the previously registered default URL handler.
*
* @param urls URL struct that will contain all the URLs the user has
* registered.
*
* @return 0 if ok, <0 if error.
*/
int http_server_del_default(struct http_server_urls *urls);
#else /* CONFIG_HTTP_SERVER */
static inline int http_server_init(struct http_ctx *ctx,
struct http_server_urls *urls,
struct sockaddr *server_addr,
u8_t *request_buf,
size_t request_buf_len,
const char *server_banner)
{
ARG_UNUSED(ctx);
ARG_UNUSED(urls);
ARG_UNUSED(server_addr);
ARG_UNUSED(request_buf);
ARG_UNUSED(request_buf_len);
ARG_UNUSED(server_banner);
return -ENOTSUP;
}
#if defined(CONFIG_HTTPS) && defined(CONFIG_NET_APP_SERVER)
static inline int http_server_set_tls(struct http_ctx *ctx,
const char *server_banner,
u8_t *personalization_data,
size_t personalization_data_len,
net_app_cert_cb_t cert_cb,
net_app_entropy_src_cb_t entropy_src_cb,
struct k_mem_pool *pool,
k_thread_stack_t *stack,
size_t stack_len)
{
ARG_UNUSED(ctx);
ARG_UNUSED(server_banner);
ARG_UNUSED(personalization_data);
ARG_UNUSED(personalization_data_len);
ARG_UNUSED(cert_cb);
ARG_UNUSED(entropy_src_cb);
ARG_UNUSED(pool);
ARG_UNUSED(stack);
ARG_UNUSED(stack_len);
return -ENOTSUP;
}
#endif /* CONFIG_HTTPS && CONFIG_NET_APP_SERVER */
static inline int http_server_enable(struct http_ctx *ctx)
{
ARG_UNUSED(ctx);
return -ENOTSUP;
}
static inline int http_server_disable(struct http_ctx *ctx)
{
ARG_UNUSED(ctx);
return -ENOTSUP;
}
static inline
struct http_root_url *http_server_add_url(struct http_server_urls *urls,
const char *url, u8_t flags)
{
ARG_UNUSED(urls);
ARG_UNUSED(url);
ARG_UNUSED(flags);
return NULL;
}
#endif /* CONFIG_HTTP_SERVER */
#if defined(CONFIG_HTTP_CLIENT)
/**
* @brief Generic function to send a HTTP request to the network. Normally
* applications would not need to use this function.
*
* @param ctx HTTP context.
* @param req HTTP request to perform.
* @param timeout Timeout when doing net_buf allocations.
* @param user_data User data related to this request. This is passed
* to send callback if user has specified that.
*
* @return Return 0 if ok, and <0 if error.
*/
int http_request(struct http_ctx *ctx,
struct http_request *req,
s32_t timeout,
void *user_data);
/**
* @brief Cancel a pending request.
*
* @param ctx HTTP context.
*
* @return Return 0 if ok, and <0 if error.
*/
int http_request_cancel(struct http_ctx *ctx);
/**
* @brief Send a HTTP request to peer.
*
* @param http_ctx HTTP context.
* @param req HTTP request to perform.
* @param cb Callback to call when the response has been received from peer.
* @param response_buf Caller-supplied buffer where the HTTP response will be
* stored
* @param response_buf_len Length of the caller-supplied buffer.
* @param user_data A valid pointer on some user data or NULL
* @param timeout Amount of time to wait for a reply. If the timeout is 0,
* then we return immediately and the callback (if set) will be called later.
*
* @return Return 0 if ok, and <0 if error.
*/
int http_client_send_req(struct http_ctx *http_ctx,
struct http_request *req,
http_response_cb_t cb,
u8_t *response_buf,
size_t response_buf_len,
void *user_data,
s32_t timeout);
/**
* @brief Send a HTTP GET request to peer.
*
* @param http_ctx HTTP context.
* @param url URL to use.
* @param host Host field in HTTP header. If set to NULL, then server
* name is used.
* @param extra_header_fields Any extra header fields that caller wants
* to add. This can be set to NULL. The format is "name: value\\r\\n"
* Example: "Accept: text/plain\\r\\nConnection: Close\\r\\n"
* @param cb Callback to call when the response has been received from peer.
* @param response_buf Caller-supplied buffer where the HTTP request will be
* stored
* @param response_buf_len Length of the caller-supplied buffer.
* @param user_data A valid pointer on some user data or NULL
* @param timeout Amount of time to wait for a reply. If the timeout is 0,
* then we return immediately and the callback (if set) will be called later.
*
* @return Return 0 if ok, and <0 if error.
*/
static inline int http_client_send_get_req(struct http_ctx *http_ctx,
const char *url,
const char *host,
const char *extra_header_fields,
http_response_cb_t cb,
u8_t *response_buf,
size_t response_buf_len,
void *user_data,
s32_t timeout)
{
struct http_request req = {
.method = HTTP_GET,
.url = url,
.host = host,
.protocol = " " HTTP_PROTOCOL,
.header_fields = extra_header_fields,
};
return http_client_send_req(http_ctx, &req, cb, response_buf,
response_buf_len, user_data, timeout);
}
/**
* @brief Initialize user-supplied HTTP context.
*
* @detail Caller can set the various fields in http_ctx after this call
* if needed.
*
* @param http_ctx HTTP context.
* @param server HTTP server address or host name. If host name is given,
* then DNS resolver support (CONFIG_DNS_RESOLVER) must be enabled. If caller
* sets the server parameter as NULL, then the server_addr parameter must be
* set by the user and it is used when connecting to the server.
* @param server_port HTTP server TCP port. If server parameter is NULL, then
* this value is ignored.
* @param server_addr HTTP server IP address and port. This is only used if
* server parameter is not set.
* @param timeout If server address needs to be resolved, then this value is
* used as a timeout.
*
* @return Return 0 if ok, <0 if error.
*/
int http_client_init(struct http_ctx *http_ctx,
const char *server,
u16_t server_port,
struct sockaddr *server_addr,
s32_t timeout);
#if defined(CONFIG_HTTPS)
/**
* @brief Initialize user-supplied HTTP context when using HTTPS.
*
* @detail Caller can set the various fields in http_ctx after this call
* if needed.
*
* @param ctx HTTPS context.
* @param request_buf Caller-supplied buffer where the TLS request will be
* stored
* @param request_buf_len Length of the caller-supplied buffer.
* @param personalization_data Personalization data (Device specific
* identifiers) for random number generator. (Can be NULL).
* @param personalization_data_len Length of the personalization data.
* @param cert_cb User-supplied callback that setups the certificates.
* @param cert_host Hostname that is used to verify the server certificate.
* This value is used when HTTP client API calls mbedtls_ssl_set_hostname()
* which sets the hostname to check against the received server certificate.
* See https://tls.mbed.org/kb/how-to/use-sni for more details.
* This can be left NULL in which case mbedtls will silently skip certificate
* verification entirely. This option is only used if MBEDTLS_X509_CRT_PARSE_C
* is enabled in mbedtls config file.
* @param entropy_src_cb User-supplied callback that setup the entropy. This
* can be set to NULL, in which case default entropy source is used.
* @param pool Memory pool for RX data reads.
* @param https_stack HTTPS thread stack.
* @param https_stack_len HTTP thread stack size.
*
* @return Return 0 if ok, <0 if error.
*/
int http_client_set_tls(struct http_ctx *ctx,
u8_t *request_buf,
size_t request_buf_len,
u8_t *personalization_data,
size_t personalization_data_len,
net_app_ca_cert_cb_t cert_cb,
const char *cert_host,
net_app_entropy_src_cb_t entropy_src_cb,
struct k_mem_pool *pool,
k_thread_stack_t *https_stack,
size_t https_stack_size);
#endif /* CONFIG_HTTPS */
#endif /* CONFIG_HTTP_CLIENT */
/**
* @brief Close a network connection to peer.
*
* @param ctx Http context.
*
* @return 0 if ok, <0 if error.
*/
int http_close(struct http_ctx *ctx);
/**
* @brief Release this http context.
*
* @details No network data will be received via this context after this
* call.
*
* @param ctx Http context.
*
* @return 0 if ok, <0 if error.
*/
int http_release(struct http_ctx *ctx);
/**
* @brief Set various callbacks that are called at various stage of ws session.
*
* @param ctx Http context.
* @param connect_cb Connect callback.
* @param recv_cb Data receive callback.
* @param send_cb Data sent callback.
* @param close_cb Close callback.
*
* @return 0 if ok, <0 if error.
*/
int http_set_cb(struct http_ctx *ctx,
http_connect_cb_t connect_cb,
http_recv_cb_t recv_cb,
http_send_cb_t send_cb,
http_close_cb_t close_cb);
/**
* @brief Send a message to peer. The data can be either HTTP or websocket
* data.
*
* @details This does not modify the network packet but sends it as is.
*
* @param ctx Http context.
* @param pkt Network packet to send
* @param user_send_data User specific data to this connection. This is passed
* as a parameter to sent cb after the packet has been sent.
*
* @return 0 if ok, <0 if error.
*/
int http_send_msg_raw(struct http_ctx *ctx, struct net_pkt *pkt,
void *user_send_data);
/**
* @brief Prepare HTTP data to be sent to peer. If there is enough data, the
* function will then send it too.
*
* @param ctx Http context.
* @param payload Application data to send
* @param payload_len Length of application data
* @param dst Remote socket address
* @param user_send_data User specific data to this connection. This is passed
* as a parameter to sent cb after the packet has been sent.
*
* @return 0 if ok, <0 if error.
*/
int http_prepare_and_send(struct http_ctx *ctx, const char *payload,
size_t payload_len,
const struct sockaddr *dst,
void *user_send_data);
/**
* @brief Send HTTP data chunk to peer.
*
* @param ctx Http context.
* @param payload Application data to send
* @param payload_len Length of application data
* @param dst Remote socket address
* @param user_send_data User specific data to this connection. This is passed
* as a parameter to sent cb after the packet has been sent.
*
* @return 0 if ok, <0 if error.
*/
int http_send_chunk(struct http_ctx *ctx, const char *payload,
size_t payload_len,
const struct sockaddr *dst,
void *user_send_data);
/**
* @brief Send any pending data immediately.
*
* @param ctx Http context.
* @param user_send_data Optional user_data for that is used as a parameter in
* send callback if that is specified.
*
* @return 0 if ok, <0 if error.
*/
int http_send_flush(struct http_ctx *ctx, void *user_send_data);
/**
* @brief Send HTTP error message to peer.
*
* @param ctx Http context.
* @param code HTTP error code
* @param html_payload Extra payload, can be null
* @param html_len Payload length
* @param dst Remote socket address
*
* @return 0 if ok, <0 if error.
*/
int http_send_error(struct http_ctx *ctx, int code,
u8_t *html_payload, size_t html_len,
const struct sockaddr *dst);
/**
* @brief Add HTTP header field to the message.
*
* @details This can be called multiple times to add pieces of HTTP header
* fields into the message. Caller must put the "\\r\\n" characters to the
* input http_header_field variable.
*
* @param ctx Http context.
* @param http_header_field All or part of HTTP header to be added.
* @param dst Remote socket address.
* @param user_send_data User data value that is used in send callback.
* Note that this value is only used if this function call causes a HTTP
* message to be sent.
*
* @return <0 if error, other value tells how many bytes were added
*/
int http_add_header(struct http_ctx *ctx, const char *http_header_field,
const struct sockaddr *dst,
void *user_send_data);
/**
* @brief Add HTTP header field to the message.
*
* @details This can be called multiple times to add pieces of HTTP header
* fields into the message. If name is "Foo" and value is "bar", then this
* function will add "Foo: bar\\r\\n" to message.
*
* @param ctx Http context.
* @param name Name of the header field
* @param value Value of the header field
* @param dst Remote socket address
* @param user_send_data User data value that is used in send callback.
* Note that this value is only used if this function call causes a HTTP
* message to be sent.
*
* @return <0 if error, other value tells how many bytes were added
*/
int http_add_header_field(struct http_ctx *ctx, const char *name,
const char *value,
const struct sockaddr *dst,
void *user_send_data);
/**
* @brief Find a handler function for a given URL.
*
* @details This is internal function, do not call this from application.
*
* @param ctx Http context.
* @param flags Tells if the URL is either HTTP or websocket URL
*
* @return URL handler or NULL if no such handler was found.
*/
struct http_root_url *http_url_find(struct http_ctx *ctx,
enum http_url_flags flags);
#define http_change_state(ctx, new_state) \
_http_change_state(ctx, new_state, __func__, __LINE__)
/**
* @brief Change the state of the HTTP engine
*
* @details This is internal function, do not call this from application.
*
* @param ctx HTTP context.
* @param new_state New state of the context.
* @param func Function that changed the state (for debugging)
* @param line Line number of the function (for debugging)
*/
void _http_change_state(struct http_ctx *ctx,
enum http_state new_state,
const char *func, int line);
#if defined(CONFIG_HTTP_SERVER) && defined(CONFIG_NET_DEBUG_HTTP_CONN)
/**
* @typedef http_server_cb_t
* @brief HTTP connection monitoring callback.
*
* @details This callback is called by server if new HTTP connection is
* established or disconnected. Requires that HTTP connection monitoring
* is enabled.
*
* @param ctx The HTTP context to use.
* @param user_data User specified data.
*/
typedef void (*http_server_cb_t)(struct http_ctx *entry,
void *user_data);
/**
* @brief Go through all the HTTP connections in the server and call
* user provided callback for each connection.
*
* @param cb Callback to call for each HTTP connection.
* @param user_data User provided data that is passed to callback.
*/
void http_server_conn_foreach(http_server_cb_t cb, void *user_data);
/**
* @brief Register a callback that is called if HTTP connection is
* established or disconnected.
*
* @details This is normally called only by "net http monitor" shell command.
*
* @param cb Callback to call for each HTTP connection created or
* deleted.
* @param user_data User provided data that is passed to callback.
*/
void http_server_conn_monitor(http_server_cb_t cb, void *user_data);
/**
* @brief HTTP connection was established.
*
* @details This is internal function, do not call this from application.
*
* @param ctx HTTP context.
*/
void http_server_conn_add(struct http_ctx *ctx);
/**
* @brief HTTP connection was disconnected.
*
* @details This is internal function, do not call this from application.
*
* @param ctx HTTP context.
*/
void http_server_conn_del(struct http_ctx *ctx);
#else
#define http_server_conn_foreach(...)
#define http_server_conn_monitor(...)
#define http_server_conn_add(...)
#define http_server_conn_del(...)
#endif /* CONFIG_HTTP_SERVER && CONFIG_NET_DEBUG_HTTP_CONN */
/**
* @}
*/
#ifdef __cplusplus
}
#endif
#endif /* __HTTP_H__ */