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 "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_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_STACK_SIZE   650
 
#define HTTP_SERVER_PRIORITY   OS_TASK_PRIORITY_NORMAL
 
#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_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  HttpVersion { HTTP_VERSION_0_9 = 0x0009, HTTP_VERSION_1_0 = 0x0100, HTTP_VERSION_1_1 = 0x0101 }
 HTTP version numbers. More...
 
enum  HttpAuthMode { HTTP_AUTH_MODE_NONE = 0, HTTP_AUTH_MODE_BASIC = 1, HTTP_AUTH_MODE_DIGEST = 2 }
 HTTP authentication schemes. More...
 
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  HttpFlags {
  HTTP_FLAG_WAIT_ALL = 0x0800, HTTP_FLAG_BREAK_CHAR = 0x1000, HTTP_FLAG_BREAK_CRLF = 0x100A, HTTP_FLAG_WAIT_ACK = 0x2000,
  HTTP_FLAG_NO_DELAY = 0x4000, HTTP_FLAG_DELAY = 0x8000
}
 Flags used by I/O functions. 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

Copyright (C) 2010-2018 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
1.9.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 375 of file http_server.h.

◆ HTTP_PORT

#define HTTP_PORT   80

Definition at line 286 of file http_server.h.

◆ HTTP_SERVER_BACKLOG

#define HTTP_SERVER_BACKLOG   4

Definition at line 136 of file http_server.h.

◆ HTTP_SERVER_BASIC_AUTH_SUPPORT

#define HTTP_SERVER_BASIC_AUTH_SUPPORT   DISABLED

Definition at line 74 of file http_server.h.

◆ HTTP_SERVER_BOUNDARY_MAX_LEN

#define HTTP_SERVER_BOUNDARY_MAX_LEN   70

Definition at line 248 of file http_server.h.

◆ HTTP_SERVER_BUFFER_SIZE

#define HTTP_SERVER_BUFFER_SIZE   1024

Definition at line 150 of file http_server.h.

◆ HTTP_SERVER_CGI_PARAM_MAX_LEN

#define HTTP_SERVER_CGI_PARAM_MAX_LEN   31

Definition at line 206 of file http_server.h.

◆ HTTP_SERVER_DEFAULT_DOC_MAX_LEN

#define HTTP_SERVER_DEFAULT_DOC_MAX_LEN   31

Definition at line 164 of file http_server.h.

◆ HTTP_SERVER_DIGEST_AUTH_SUPPORT

#define HTTP_SERVER_DIGEST_AUTH_SUPPORT   DISABLED

Definition at line 81 of file http_server.h.

◆ HTTP_SERVER_FS_SUPPORT

#define HTTP_SERVER_FS_SUPPORT   DISABLED

Definition at line 53 of file http_server.h.

◆ HTTP_SERVER_GZIP_TYPE_SUPPORT

#define HTTP_SERVER_GZIP_TYPE_SUPPORT   DISABLED

Definition at line 95 of file http_server.h.

◆ HTTP_SERVER_HOST_MAX_LEN

#define HTTP_SERVER_HOST_MAX_LEN   31

Definition at line 192 of file http_server.h.

◆ HTTP_SERVER_IDLE_TIMEOUT

#define HTTP_SERVER_IDLE_TIMEOUT   5000

Definition at line 129 of file http_server.h.

◆ HTTP_SERVER_MAX_AGE

#define HTTP_SERVER_MAX_AGE   0

Definition at line 220 of file http_server.h.

◆ HTTP_SERVER_MAX_REQUESTS

#define HTTP_SERVER_MAX_REQUESTS   1000

Definition at line 143 of file http_server.h.

◆ HTTP_SERVER_METHOD_MAX_LEN

#define HTTP_SERVER_METHOD_MAX_LEN   7

Definition at line 171 of file http_server.h.

◆ HTTP_SERVER_MULTIPART_TYPE_SUPPORT

#define HTTP_SERVER_MULTIPART_TYPE_SUPPORT   DISABLED

Definition at line 102 of file http_server.h.

◆ HTTP_SERVER_NONCE_CACHE_SIZE

#define HTTP_SERVER_NONCE_CACHE_SIZE   8

Definition at line 227 of file http_server.h.

◆ HTTP_SERVER_NONCE_LIFETIME

#define HTTP_SERVER_NONCE_LIFETIME   60000

Definition at line 234 of file http_server.h.

◆ HTTP_SERVER_NONCE_SIZE

#define HTTP_SERVER_NONCE_SIZE   16

Definition at line 241 of file http_server.h.

◆ HTTP_SERVER_PERSISTENT_CONN_SUPPORT

#define HTTP_SERVER_PERSISTENT_CONN_SUPPORT   DISABLED

Definition at line 46 of file http_server.h.

◆ HTTP_SERVER_PRIORITY

#define HTTP_SERVER_PRIORITY   OS_TASK_PRIORITY_NORMAL

Definition at line 116 of file http_server.h.

◆ HTTP_SERVER_QUERY_STRING_MAX_LEN

#define HTTP_SERVER_QUERY_STRING_MAX_LEN   255

Definition at line 185 of file http_server.h.

◆ HTTP_SERVER_ROOT_DIR_MAX_LEN

#define HTTP_SERVER_ROOT_DIR_MAX_LEN   31

Definition at line 157 of file http_server.h.

◆ HTTP_SERVER_SSI_MAX_RECURSION

#define HTTP_SERVER_SSI_MAX_RECURSION   3

Definition at line 213 of file http_server.h.

◆ HTTP_SERVER_SSI_SUPPORT

#define HTTP_SERVER_SSI_SUPPORT   DISABLED

Definition at line 60 of file http_server.h.

◆ HTTP_SERVER_STACK_SIZE

#define HTTP_SERVER_STACK_SIZE   650

Definition at line 109 of file http_server.h.

◆ HTTP_SERVER_SUPPORT

#define HTTP_SERVER_SUPPORT   ENABLED

Definition at line 39 of file http_server.h.

◆ HTTP_SERVER_TIMEOUT

#define HTTP_SERVER_TIMEOUT   10000

Definition at line 121 of file http_server.h.

◆ HTTP_SERVER_TLS_SUPPORT

#define HTTP_SERVER_TLS_SUPPORT   DISABLED

Definition at line 67 of file http_server.h.

◆ HTTP_SERVER_URI_MAX_LEN

#define HTTP_SERVER_URI_MAX_LEN   255

Definition at line 178 of file http_server.h.

◆ HTTP_SERVER_USERNAME_MAX_LEN

#define HTTP_SERVER_USERNAME_MAX_LEN   31

Definition at line 199 of file http_server.h.

◆ HTTP_SERVER_WEB_SOCKET_SUPPORT

#define HTTP_SERVER_WEB_SOCKET_SUPPORT   DISABLED

Definition at line 88 of file http_server.h.

◆ HttpConnection

#define HttpConnection   struct _HttpConnection

Definition at line 296 of file http_server.h.

◆ HTTPS_PORT

#define HTTPS_PORT   443

Definition at line 288 of file http_server.h.

◆ HttpServerContext

#define HttpServerContext   struct _HttpServerContext

Definition at line 292 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 402 of file http_server.h.

◆ HttpCgiCallback

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

CGI callback function.

Definition at line 410 of file http_server.h.

◆ HttpRandCallback

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

Random data generation callback function.

Definition at line 395 of file http_server.h.

◆ HttpRequestCallback

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

HTTP request callback function.

Definition at line 418 of file http_server.h.

◆ HttpUriNotFoundCallback

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

URI not found callback function.

Definition at line 426 of file http_server.h.

◆ TlsInitCallback

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

TLS initialization callback function.

Definition at line 385 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 332 of file http_server.h.

◆ HttpAuthMode

HTTP authentication schemes.

Enumerator
HTTP_AUTH_MODE_NONE 
HTTP_AUTH_MODE_BASIC 
HTTP_AUTH_MODE_DIGEST 

Definition at line 320 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 360 of file http_server.h.

◆ HttpFlags

enum HttpFlags

Flags used by I/O functions.

Enumerator
HTTP_FLAG_WAIT_ALL 
HTTP_FLAG_BREAK_CHAR 
HTTP_FLAG_BREAK_CRLF 
HTTP_FLAG_WAIT_ACK 
HTTP_FLAG_NO_DELAY 
HTTP_FLAG_DELAY 

Definition at line 345 of file http_server.h.

◆ HttpVersion

HTTP version numbers.

Enumerator
HTTP_VERSION_0_9 
HTTP_VERSION_1_0 
HTTP_VERSION_1_1 

Definition at line 308 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 54 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 1165 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 821 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 316 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 1087 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 246 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 650 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 1054 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 1110 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 849 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 61 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 106 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 204 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 1214 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 617 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 756 of file http_server.c.