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

String:

static String fromFileExtension(const String &extension)¶

Obtain content type string from file extension.

Parameters

extension:

Return Value

String:

String toString(enum MimeType m)¶

Get textual representation for a MIME type.

Parameters

m: the MIME type

Return Value

String:

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

String:

static String fromFullFileName(const String &fileName)¶

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

Parameters

fileName:

Return Value

String:

Client API¶

class HttpClient¶

#include <HttpClient.h>

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

Delete all instances of HttpClient
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