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

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

param fileName

returns String

String fromFullFileName(const char *fileName)
inline String fromFullFileName(const String &fileName)

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

Functions

MimeType fromFileExtension(const char *extension, MimeType unknown)

Obtain MIME type value from file extension.

Parameters

  • extension – excluding ‘.’ separator (e.g. “htm”, “json”)

  • unknown – Value to return if type cannot be determined

Returns

MimeType –

String fromFileExtension(const char *extension)

Obtain content type string from file extension.

Parameters

extension – excluding ‘.’ separator (e.g. “htm”, “json”)

Returns

String –

inline String fromFileExtension(const String &extension)

Obtain content type string from file extension.

Parameters

extension –

Returns

String –

MimeType fromString(const char *str)

Get enumerated value for a MIME type string.

Parameters

str –

Returns

MimeType – If empty, null or unrecognised returns MIME_UNKNOWN

inline MimeType fromString(const String &str)

Get enumerated value for a MIME type string.

Parameters

str –

Returns

MimeType – If empty, null or unrecognised returns MIME_UNKNOWN

MimeType fromFullFileName(const char *fileName, MimeType unknown)

Obtain MIME type value from file name or path, with extension.

Parameters

  • fileName –

  • unknown – Value to return if type cannot be determined

Returns

MimeType –

inline MimeType fromFullFileName(const String &fileName, MimeType unknown)

Client API

class HttpClient
#include <HttpClient.h>

Public Functions

inline 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();

inline bool downloadString(const Url &url, RequestCompletedDelegate requestComplete, size_t maxLength = NETWORK_SEND_BUFFER_SIZE)

Queue request to download content as string (in memory)

Parameters

  • url – URL from which the content will be fetched

  • requestComplete – Completion callback

  • maxLength – maximum bytes to store in memory. If the response is bigger than maxLength then the rest bytes will be discarded. Use this parameter wisely as setting the value too high may consume all available RAM resulting in device restart and Denial-Of-Service

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

inline HttpRequest *createRequest(const Url &url)

Helper function to create a new request on a URL.

Parameters

url –

Returns

HttpRequest* –

Public Static Functions

static inline void cleanup()

Use this method to clean all 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

void configure(const HttpServerSettings &settings)

Allows changing the server configuration.

inline 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 –

inline void setBodyParser(MimeType mimeType, HttpBodyParserDelegate parser)

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

Parameters

  • mimeType –

  • parser –

Public Members

HttpResourceTree paths

Maps paths to resources which deal with incoming requests.