HTTP: HyperText Transfer Protocol

https://en.m.wikipedia.org/wiki/Hypertext_Transfer_Protocol

Build Variables

HTTP_SERVER_EXPOSE_NAME

Default: 1 (enabled)

Adds “HttpServer/Sming” to the SERVER field in response headers. If disabled, the SERVER field is omitted from all responses.

HTTP_SERVER_EXPOSE_VERSION

Default: 0 (disabled)

Adds the current Sming build version to the SERVER field in response headers. For example, “Sming/4.0.0-rc2”.

Requires HTTP_SERVER_EXPOSE_NAME to be enabled.

HTTP_SERVER_EXPOSE_DATE

Default: 0 (disabled)

Sets the DATE field in response headers.

Support API

namespace ContentType

Functions

String fromFileExtension(const char *extension)

Obtain content type string from file extension.

Parameters
  • extension: excluding ‘.’ separator (e.g. “htm”, “json”)
Return Value

static String fromFileExtension(const String &extension)

Obtain content type string from file extension.

Parameters
  • extension:
Return Value

String toString(enum MimeType m)

Get textual representation for a MIME type.

Parameters
  • m: the MIME type
Return Value

MimeType fromString(const char *str)

Get enumerated value for a MIME type string.

Parameters
  • str:
Return Value
  • MimeType: If empty, null or unrecognised returns MIME_UNKNOWN

MimeType fromString(const String &str)

Get enumerated value for a MIME type string.

Parameters
  • str:
Return Value
  • MimeType: If empty, null or unrecognised returns MIME_UNKNOWN

String fromFullFileName(const char *fileName)

Obtain content type string from file name or path, with extension.

Parameters
  • fileName:
Return Value

static String fromFullFileName(const String &fileName)

Obtain content type string from file name or path, with extension.

Parameters
  • fileName:
Return Value

Client API

class HttpClient
#include <HttpClient.h>

Subclassed by RbootHttpUpdater

Public Functions

virtual ~HttpClient()

HttpClient destructor.

Note
DON’T call cleanup. If you want to free all resources from HttpClients the correct sequence will be to
  1. Delete all instances of HttpClient
  2. Call the static method HttpClient::cleanup();

bool sendRequest(const Url &url, RequestCompletedDelegate requestComplete)
bool sendRequest(const HttpMethod method, const Url &url, const HttpHeaders &headers, RequestCompletedDelegate requestComplete)
bool sendRequest(const HttpMethod method, const Url &url, const HttpHeaders &headers, const String &body, RequestCompletedDelegate requestComplete)
bool downloadString(const Url &url, RequestCompletedDelegate requestComplete)
bool downloadFile(const Url &url, RequestCompletedDelegate requestComplete = nullptr)
bool downloadFile(const Url &url, const String &saveFileName, RequestCompletedDelegate requestComplete = nullptr)

Queue request to download a file.

Parameters
  • url: Source of file data
  • saveFileName: Path to save file to. Optional: specify nullptr to use name from url
  • requestComplete: Completion callback

bool send(HttpRequest *request)
HttpRequest *request(const String &url)

HttpRequest *createRequest(const Url &url)

Helper function to create a new request on a URL.

Parameters
  • url:
Return Value
  • HttpRequest*:

Public Static Functions

static void cleanup()

Use this method to clean all request queues and object pools

Server API

struct HttpServerSettings
#include <HttpServer.h>

Public Members

uint16_t maxActiveConnections = 10

maximum number of concurrent requests..

uint16_t keepAliveSeconds = 0

default seconds to keep the connection alive before closing it

int minHeapSize = -1

min heap size that is required to accept connection, -1 means use server default

bool useDefaultBodyParsers = 1

if the default body parsers, as form-url-encoded, should be used

bool closeOnContentError

=

true


close the connection if a body parser or resource fails to parse the body content.

class HttpServer : public TcpServer
#include <HttpServer.h>

Public Functions

HttpServer()
HttpServer(const HttpServerSettings &settings)
void configure(const HttpServerSettings &settings)

Allows changing the server configuration.

void setBodyParser(const String &contentType, HttpBodyParserDelegate parser)

Allows content-type specific parsing of the body based on content-type.

Parameters
  • contentType: Can be full content-type like ‘application/json’, or ‘application/*’ or ‘*’. If there is exact match for the content-type wildcard content-types will not be used. There can be only one catch-all ‘*’ body parser and that will be the last registered
  • parser:

void setBodyParser(MimeType mimeType, HttpBodyParserDelegate parser)

Allows content-type specific parsing of the body based on content-type.

Parameters
  • mimeType:
  • parser:

void addPath(String path, const HttpPathDelegate &callback)

void addPath(const String &path, const HttpResourceDelegate &onRequestComplete)

void addPath(const String &path, HttpResource *resource)

void setDefaultHandler(const HttpPathDelegate &callback)

void setDefaultResource(HttpResource *resource)

virtual bool listen(int port, bool useSsl = false)
void setKeepAlive(uint16_t seconds)
void shutdown()
const Vector<TcpConnection *> &getConnections() const
virtual bool connect(const String &server, int port, bool useSsl = false)
virtual bool connect(IpAddress addr, uint16_t port, bool useSsl = false)
virtual void close()
int writeString(const char *data, uint8_t apiflags = TCP_WRITE_FLAG_COPY)
int writeString(const String &data, uint8_t apiflags = TCP_WRITE_FLAG_COPY)
virtual int write(const char *data, int len, uint8_t apiflags = TCP_WRITE_FLAG_COPY)

Base write operation.

Parameters
  • data:
  • len:
  • apiflags: TCP_WRITE_FLAG_COPY, TCP_WRITE_FLAG_MORE
Return Value
  • int: -1 on error

int write(IDataSourceStream *stream)
uint16_t getAvailableWriteSize()
void flush()
void setTimeOut(uint16_t waitTimeOut)
IpAddress getRemoteIp() const
uint16_t getRemotePort() const
void setDestroyedDelegate(TcpConnectionDestroyedDelegate destroyedDelegate)

Sets a callback to be called when the object instance is destroyed.

Parameters
  • destroyedDelegate:

void setSslInitHandler(Ssl::Session::InitDelegate handler)

Set the SSL session initialisation callback.

Parameters
  • handler:

bool setSslConnection(Ssl::Connection *connection)
Ssl::Session *getSsl()

Get a pointer to the current SSL session object.

Note that this is typically used so we can query properties of an established session. If you need to change session parameters this must be done via setSslInitHandler.

Public Members

HttpResourceTree paths

Maps paths to resources which deal with incoming requests.

uint16_t activeClients = 0