http_server.h File Reference

HTTP server (HyperText Transfer Protocol) More...

#include "os_port.h"
#include "core/socket.h"
#include "web_socket/web_socket.h"
#include "http/http_common.h"
#include "fs_port.h"
#include "core/crypto.h"
#include "tls.h"
#include "tls_ticket.h"
#include "encoding/base64.h"
#include "hash/md5.h"

Go to the source code of this file.

Data Structures

struct  HttpStatusCodeDesc
 HTTP status code. More...
 
struct  HttpAuthorizationHeader
 Authorization header. More...
 
struct  HttpAuthenticateHeader
 Authenticate header. More...
 
struct  HttpRequest
 HTTP request. More...
 
struct  HttpResponse
 HTTP response. More...
 
struct  HttpServerSettings
 HTTP server settings. More...
 
struct  HttpNonceCacheEntry
 Nonce cache entry. More...
 
struct  _HttpServerContext
 HTTP server context. More...
 
struct  _HttpConnection
 HTTP connection. More...
 

Macros

#define HTTP_SERVER_SUPPORT   ENABLED
 
#define HTTP_SERVER_PERSISTENT_CONN_SUPPORT   DISABLED
 
#define HTTP_SERVER_FS_SUPPORT   DISABLED
 
#define HTTP_SERVER_SSI_SUPPORT   DISABLED
 
#define HTTP_SERVER_TLS_SUPPORT   DISABLED
 
#define HTTP_SERVER_HSTS_SUPPORT   DISABLED
 
#define HTTP_SERVER_BASIC_AUTH_SUPPORT   DISABLED
 
#define HTTP_SERVER_DIGEST_AUTH_SUPPORT   DISABLED
 
#define HTTP_SERVER_WEB_SOCKET_SUPPORT   DISABLED
 
#define HTTP_SERVER_GZIP_TYPE_SUPPORT   DISABLED
 
#define HTTP_SERVER_MULTIPART_TYPE_SUPPORT   DISABLED
 
#define HTTP_SERVER_COOKIE_SUPPORT   DISABLED
 
#define HTTP_SERVER_STACK_SIZE   650
 
#define HTTP_SERVER_PRIORITY   OS_TASK_PRIORITY_NORMAL
 
#define HTTP_SERVER_MAX_CONNECTIONS   10
 
#define HTTP_SERVER_TIMEOUT   10000
 
#define HTTP_SERVER_IDLE_TIMEOUT   5000
 
#define HTTP_SERVER_BACKLOG   4
 
#define HTTP_SERVER_MAX_REQUESTS   1000
 
#define HTTP_SERVER_BUFFER_SIZE   1024
 
#define HTTP_SERVER_ROOT_DIR_MAX_LEN   31
 
#define HTTP_SERVER_DEFAULT_DOC_MAX_LEN   31
 
#define HTTP_SERVER_METHOD_MAX_LEN   7
 
#define HTTP_SERVER_URI_MAX_LEN   255
 
#define HTTP_SERVER_QUERY_STRING_MAX_LEN   255
 
#define HTTP_SERVER_HOST_MAX_LEN   31
 
#define HTTP_SERVER_USERNAME_MAX_LEN   31
 
#define HTTP_SERVER_CGI_PARAM_MAX_LEN   31
 
#define HTTP_SERVER_SSI_MAX_RECURSION   3
 
#define HTTP_SERVER_MAX_AGE   0
 
#define HTTP_SERVER_NONCE_CACHE_SIZE   8
 
#define HTTP_SERVER_NONCE_LIFETIME   60000
 
#define HTTP_SERVER_NONCE_SIZE   16
 
#define HTTP_SERVER_BOUNDARY_MAX_LEN   70
 
#define HTTP_SERVER_COOKIE_MAX_LEN   256
 
#define HTTP_SERVER_PRIVATE_CONTEXT
 
#define HTTP_PORT   80
 
#define HTTPS_PORT   443
 
#define HttpServerContext   struct _HttpServerContext
 
#define HttpConnection   struct _HttpConnection
 
#define HTTP_FLAG_BREAK(c)   (HTTP_FLAG_BREAK_CHAR | LSB(c))
 

Typedefs

typedef error_t(* TlsInitCallback) (HttpConnection *connection, TlsContext *tlsContext)
 TLS initialization callback function. More...
 
typedef error_t(* HttpRandCallback) (uint8_t *data, size_t length)
 Random data generation callback function. More...
 
typedef HttpAccessStatus(* HttpAuthCallback) (HttpConnection *connection, const char_t *user, const char_t *uri)
 HTTP authentication callback function. More...
 
typedef error_t(* HttpCgiCallback) (HttpConnection *connection, const char_t *param)
 CGI callback function. More...
 
typedef error_t(* HttpRequestCallback) (HttpConnection *connection, const char_t *uri)
 HTTP request callback function. More...
 
typedef error_t(* HttpUriNotFoundCallback) (HttpConnection *connection, const char_t *uri)
 URI not found callback function. More...
 

Enumerations

enum  HttpAccessStatus { HTTP_ACCESS_DENIED = 0 , HTTP_ACCESS_ALLOWED = 1 , HTTP_ACCESS_BASIC_AUTH_REQUIRED = 2 , HTTP_ACCESS_DIGEST_AUTH_REQUIRED = 3 }
 Access status. More...
 
enum  HttpConnState {
  HTTP_CONN_STATE_IDLE = 0 , HTTP_CONN_STATE_REQ_LINE = 1 , HTTP_CONN_STATE_REQ_HEADER = 2 , HTTP_CONN_STATE_REQ_BODY = 3 ,
  HTTP_CONN_STATE_RESP_HEADER = 4 , HTTP_CONN_STATE_RESP_BODY = 5 , HTTP_CONN_STATE_SHUTDOWN = 6 , HTTP_CONN_STATE_CLOSE = 7
}
 HTTP connection states. More...
 

Functions

void httpServerGetDefaultSettings (HttpServerSettings *settings)
 Initialize settings with default values. More...
 
error_t httpServerInit (HttpServerContext *context, const HttpServerSettings *settings)
 HTTP server initialization. More...
 
error_t httpServerStart (HttpServerContext *context)
 Start HTTP server. More...
 
void httpListenerTask (void *param)
 HTTP server listener task. More...
 
void httpConnectionTask (void *param)
 Task that services requests from an active connection. More...
 
error_t httpWriteHeader (HttpConnection *connection)
 Send HTTP response header. More...
 
error_t httpReadStream (HttpConnection *connection, void *data, size_t size, size_t *received, uint_t flags)
 Read data from client request. More...
 
error_t httpWriteStream (HttpConnection *connection, const void *data, size_t length)
 Write data to the client. More...
 
error_t httpCloseStream (HttpConnection *connection)
 Close output stream. More...
 
error_t httpSendResponse (HttpConnection *connection, const char_t *uri)
 Send HTTP response. More...
 
error_t httpSendErrorResponse (HttpConnection *connection, uint_t statusCode, const char_t *message)
 Send error response to the client. More...
 
error_t httpSendRedirectResponse (HttpConnection *connection, uint_t statusCode, const char_t *uri)
 Send redirect response to the client. More...
 
bool_t httpCheckPassword (HttpConnection *connection, const char_t *password, HttpAuthMode mode)
 Password verification. More...
 
bool_t httpCheckWebSocketHandshake (HttpConnection *connection)
 Check whether the client's handshake is valid. More...
 
WebSockethttpUpgradeToWebSocket (HttpConnection *connection)
 Upgrade an existing HTTP connection to a WebSocket. More...
 
error_t httpDecodePercentEncodedString (const char_t *input, char_t *output, size_t outputSize)
 Decode a percent-encoded string. More...
 

Detailed Description

HTTP server (HyperText Transfer Protocol)

License

SPDX-License-Identifier: GPL-2.0-or-later

Copyright (C) 2010-2024 Oryx Embedded SARL. All rights reserved.

This file is part of CycloneTCP Open.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Author
Oryx Embedded SARL (www.oryx-embedded.com)
Version
2.4.0

Definition in file http_server.h.

Macro Definition Documentation

◆ HTTP_FLAG_BREAK

#define HTTP_FLAG_BREAK (   c)    (HTTP_FLAG_BREAK_CHAR | LSB(c))

Definition at line 372 of file http_server.h.

◆ HTTP_PORT

#define HTTP_PORT   80

Definition at line 322 of file http_server.h.

◆ HTTP_SERVER_BACKLOG

#define HTTP_SERVER_BACKLOG   4

Definition at line 160 of file http_server.h.

◆ HTTP_SERVER_BASIC_AUTH_SUPPORT

#define HTTP_SERVER_BASIC_AUTH_SUPPORT   DISABLED

Definition at line 84 of file http_server.h.

◆ HTTP_SERVER_BOUNDARY_MAX_LEN

#define HTTP_SERVER_BOUNDARY_MAX_LEN   70

Definition at line 272 of file http_server.h.

◆ HTTP_SERVER_BUFFER_SIZE

#define HTTP_SERVER_BUFFER_SIZE   1024

Definition at line 174 of file http_server.h.

◆ HTTP_SERVER_CGI_PARAM_MAX_LEN

#define HTTP_SERVER_CGI_PARAM_MAX_LEN   31

Definition at line 230 of file http_server.h.

◆ HTTP_SERVER_COOKIE_MAX_LEN

#define HTTP_SERVER_COOKIE_MAX_LEN   256

Definition at line 279 of file http_server.h.

◆ HTTP_SERVER_COOKIE_SUPPORT

#define HTTP_SERVER_COOKIE_SUPPORT   DISABLED

Definition at line 119 of file http_server.h.

◆ HTTP_SERVER_DEFAULT_DOC_MAX_LEN

#define HTTP_SERVER_DEFAULT_DOC_MAX_LEN   31

Definition at line 188 of file http_server.h.

◆ HTTP_SERVER_DIGEST_AUTH_SUPPORT

#define HTTP_SERVER_DIGEST_AUTH_SUPPORT   DISABLED

Definition at line 91 of file http_server.h.

◆ HTTP_SERVER_FS_SUPPORT

#define HTTP_SERVER_FS_SUPPORT   DISABLED

Definition at line 56 of file http_server.h.

◆ HTTP_SERVER_GZIP_TYPE_SUPPORT

#define HTTP_SERVER_GZIP_TYPE_SUPPORT   DISABLED

Definition at line 105 of file http_server.h.

◆ HTTP_SERVER_HOST_MAX_LEN

#define HTTP_SERVER_HOST_MAX_LEN   31

Definition at line 216 of file http_server.h.

◆ HTTP_SERVER_HSTS_SUPPORT

#define HTTP_SERVER_HSTS_SUPPORT   DISABLED

Definition at line 77 of file http_server.h.

◆ HTTP_SERVER_IDLE_TIMEOUT

#define HTTP_SERVER_IDLE_TIMEOUT   5000

Definition at line 153 of file http_server.h.

◆ HTTP_SERVER_MAX_AGE

#define HTTP_SERVER_MAX_AGE   0

Definition at line 244 of file http_server.h.

◆ HTTP_SERVER_MAX_CONNECTIONS

#define HTTP_SERVER_MAX_CONNECTIONS   10

Definition at line 138 of file http_server.h.

◆ HTTP_SERVER_MAX_REQUESTS

#define HTTP_SERVER_MAX_REQUESTS   1000

Definition at line 167 of file http_server.h.

◆ HTTP_SERVER_METHOD_MAX_LEN

#define HTTP_SERVER_METHOD_MAX_LEN   7

Definition at line 195 of file http_server.h.

◆ HTTP_SERVER_MULTIPART_TYPE_SUPPORT

#define HTTP_SERVER_MULTIPART_TYPE_SUPPORT   DISABLED

Definition at line 112 of file http_server.h.

◆ HTTP_SERVER_NONCE_CACHE_SIZE

#define HTTP_SERVER_NONCE_CACHE_SIZE   8

Definition at line 251 of file http_server.h.

◆ HTTP_SERVER_NONCE_LIFETIME

#define HTTP_SERVER_NONCE_LIFETIME   60000

Definition at line 258 of file http_server.h.

◆ HTTP_SERVER_NONCE_SIZE

#define HTTP_SERVER_NONCE_SIZE   16

Definition at line 265 of file http_server.h.

◆ HTTP_SERVER_PERSISTENT_CONN_SUPPORT

#define HTTP_SERVER_PERSISTENT_CONN_SUPPORT   DISABLED

Definition at line 49 of file http_server.h.

◆ HTTP_SERVER_PRIORITY

#define HTTP_SERVER_PRIORITY   OS_TASK_PRIORITY_NORMAL

Definition at line 133 of file http_server.h.

◆ HTTP_SERVER_PRIVATE_CONTEXT

#define HTTP_SERVER_PRIVATE_CONTEXT

Definition at line 286 of file http_server.h.

◆ HTTP_SERVER_QUERY_STRING_MAX_LEN

#define HTTP_SERVER_QUERY_STRING_MAX_LEN   255

Definition at line 209 of file http_server.h.

◆ HTTP_SERVER_ROOT_DIR_MAX_LEN

#define HTTP_SERVER_ROOT_DIR_MAX_LEN   31

Definition at line 181 of file http_server.h.

◆ HTTP_SERVER_SSI_MAX_RECURSION

#define HTTP_SERVER_SSI_MAX_RECURSION   3

Definition at line 237 of file http_server.h.

◆ HTTP_SERVER_SSI_SUPPORT

#define HTTP_SERVER_SSI_SUPPORT   DISABLED

Definition at line 63 of file http_server.h.

◆ HTTP_SERVER_STACK_SIZE

#define HTTP_SERVER_STACK_SIZE   650

Definition at line 126 of file http_server.h.

◆ HTTP_SERVER_SUPPORT

#define HTTP_SERVER_SUPPORT   ENABLED

Definition at line 42 of file http_server.h.

◆ HTTP_SERVER_TIMEOUT

#define HTTP_SERVER_TIMEOUT   10000

Definition at line 145 of file http_server.h.

◆ HTTP_SERVER_TLS_SUPPORT

#define HTTP_SERVER_TLS_SUPPORT   DISABLED

Definition at line 70 of file http_server.h.

◆ HTTP_SERVER_URI_MAX_LEN

#define HTTP_SERVER_URI_MAX_LEN   255

Definition at line 202 of file http_server.h.

◆ HTTP_SERVER_USERNAME_MAX_LEN

#define HTTP_SERVER_USERNAME_MAX_LEN   31

Definition at line 223 of file http_server.h.

◆ HTTP_SERVER_WEB_SOCKET_SUPPORT

#define HTTP_SERVER_WEB_SOCKET_SUPPORT   DISABLED

Definition at line 98 of file http_server.h.

◆ HttpConnection

#define HttpConnection   struct _HttpConnection

Definition at line 332 of file http_server.h.

◆ HTTPS_PORT

#define HTTPS_PORT   443

Definition at line 324 of file http_server.h.

◆ HttpServerContext

#define HttpServerContext   struct _HttpServerContext

Definition at line 328 of file http_server.h.

Typedef Documentation

◆ HttpAuthCallback

typedef HttpAccessStatus(* HttpAuthCallback) (HttpConnection *connection, const char_t *user, const char_t *uri)

HTTP authentication callback function.

Definition at line 399 of file http_server.h.

◆ HttpCgiCallback

typedef error_t(* HttpCgiCallback) (HttpConnection *connection, const char_t *param)

CGI callback function.

Definition at line 407 of file http_server.h.

◆ HttpRandCallback

typedef error_t(* HttpRandCallback) (uint8_t *data, size_t length)

Random data generation callback function.

Definition at line 392 of file http_server.h.

◆ HttpRequestCallback

typedef error_t(* HttpRequestCallback) (HttpConnection *connection, const char_t *uri)

HTTP request callback function.

Definition at line 415 of file http_server.h.

◆ HttpUriNotFoundCallback

typedef error_t(* HttpUriNotFoundCallback) (HttpConnection *connection, const char_t *uri)

URI not found callback function.

Definition at line 423 of file http_server.h.

◆ TlsInitCallback

typedef error_t(* TlsInitCallback) (HttpConnection *connection, TlsContext *tlsContext)

TLS initialization callback function.

Definition at line 382 of file http_server.h.

Enumeration Type Documentation

◆ HttpAccessStatus

Access status.

Enumerator
HTTP_ACCESS_DENIED 
HTTP_ACCESS_ALLOWED 
HTTP_ACCESS_BASIC_AUTH_REQUIRED 
HTTP_ACCESS_DIGEST_AUTH_REQUIRED 

Definition at line 344 of file http_server.h.

◆ HttpConnState

HTTP connection states.

Enumerator
HTTP_CONN_STATE_IDLE 
HTTP_CONN_STATE_REQ_LINE 
HTTP_CONN_STATE_REQ_HEADER 
HTTP_CONN_STATE_REQ_BODY 
HTTP_CONN_STATE_RESP_HEADER 
HTTP_CONN_STATE_RESP_BODY 
HTTP_CONN_STATE_SHUTDOWN 
HTTP_CONN_STATE_CLOSE 

Definition at line 357 of file http_server.h.

Function Documentation

◆ httpCheckPassword()

bool_t httpCheckPassword ( HttpConnection connection,
const char_t password,
HttpAuthMode  mode 
)

Password verification.

Parameters
[in]connectionStructure representing an HTTP connection
[in]passwordNULL-terminated string containing the password to be checked
[in]modeHTTP authentication scheme to be used. Acceptable values are HTTP_AUTH_MODE_BASIC or HTTP_AUTH_MODE_DIGEST
Returns
TRUE if the password is valid, else FALSE

Definition at line 56 of file http_server_auth.c.

◆ httpCheckWebSocketHandshake()

bool_t httpCheckWebSocketHandshake ( HttpConnection connection)

Check whether the client's handshake is valid.

Parameters
[in]connectionStructure representing an HTTP connection
Returns
TRUE if the WebSocket handshake is valid, else FALSE

Definition at line 1247 of file http_server.c.

◆ httpCloseStream()

error_t httpCloseStream ( HttpConnection connection)

Close output stream.

Parameters
[in]connectionStructure representing an HTTP connection
Returns
Error code

Definition at line 883 of file http_server.c.

◆ httpConnectionTask()

void httpConnectionTask ( void *  param)

Task that services requests from an active connection.

Parameters
[in]paramStructure representing an HTTP connection with a client

Definition at line 363 of file http_server.c.

◆ httpDecodePercentEncodedString()

error_t httpDecodePercentEncodedString ( const char_t input,
char_t output,
size_t  outputSize 
)

Decode a percent-encoded string.

Parameters
[in]inputNULL-terminated string to be decoded
[out]outputNULL-terminated string resulting from the decoding process
[in]outputSizeSize of the output buffer in bytes
Returns
Error code

Definition at line 1135 of file http_server_misc.c.

◆ httpListenerTask()

void httpListenerTask ( void *  param)

HTTP server listener task.

Parameters
[in]paramPointer to the HTTP server context

Definition at line 282 of file http_server.c.

◆ httpReadStream()

error_t httpReadStream ( HttpConnection connection,
void *  data,
size_t  size,
size_t *  received,
uint_t  flags 
)

Read data from client request.

Parameters
[in]connectionStructure representing an HTTP connection
[out]dataBuffer where to store the incoming data
[in]sizeMaximum number of bytes that can be received
[out]receivedNumber of bytes that have been received
[in]flagsSet of flags that influences the behavior of this function
Returns
Error code

Definition at line 712 of file http_server.c.

◆ httpSendErrorResponse()

error_t httpSendErrorResponse ( HttpConnection connection,
uint_t  statusCode,
const char_t message 
)

Send error response to the client.

Parameters
[in]connectionStructure representing an HTTP connection
[in]statusCodeHTTP status code
[in]messageUser message
Returns
Error code

Definition at line 1116 of file http_server.c.

◆ httpSendRedirectResponse()

error_t httpSendRedirectResponse ( HttpConnection connection,
uint_t  statusCode,
const char_t uri 
)

Send redirect response to the client.

Parameters
[in]connectionStructure representing an HTTP connection
[in]statusCodeHTTP status code (301 for permanent redirects)
[in]uriNULL-terminated string containing the redirect URI
Returns
Error code

Definition at line 1182 of file http_server.c.

◆ httpSendResponse()

error_t httpSendResponse ( HttpConnection connection,
const char_t uri 
)

Send HTTP response.

Parameters
[in]connectionStructure representing an HTTP connection
[in]uriNULL-terminated string containing the file to be sent in response
Returns
Error code

Definition at line 911 of file http_server.c.

◆ httpServerGetDefaultSettings()

void httpServerGetDefaultSettings ( HttpServerSettings settings)

Initialize settings with default values.

Parameters
[out]settingsStructure that contains HTTP server settings

Definition at line 63 of file http_server.c.

◆ httpServerInit()

error_t httpServerInit ( HttpServerContext context,
const HttpServerSettings settings 
)

HTTP server initialization.

Parameters
[in]contextPointer to the HTTP server context
[in]settingsHTTP server specific settings
Returns
Error code

Definition at line 128 of file http_server.c.

◆ httpServerStart()

error_t httpServerStart ( HttpServerContext context)

Start HTTP server.

Parameters
[in]contextPointer to the HTTP server context
Returns
Error code

Definition at line 237 of file http_server.c.

◆ httpUpgradeToWebSocket()

WebSocket* httpUpgradeToWebSocket ( HttpConnection connection)

Upgrade an existing HTTP connection to a WebSocket.

Parameters
[in]connectionStructure representing an HTTP connection
Returns
Handle referencing the new WebSocket

Definition at line 1296 of file http_server.c.

◆ httpWriteHeader()

error_t httpWriteHeader ( HttpConnection connection)

Send HTTP response header.

Parameters
[in]connectionStructure representing an HTTP connection
Returns
Error code

Definition at line 673 of file http_server.c.

◆ httpWriteStream()

error_t httpWriteStream ( HttpConnection connection,
const void *  data,
size_t  length 
)

Write data to the client.

Parameters
[in]connectionStructure representing an HTTP connection
[in]dataBuffer containing the data to be transmitted
[in]lengthNumber of bytes to be transmitted
Returns
Error code

Definition at line 818 of file http_server.c.