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

Parameters

  • fileName:

Return Value

String fromFullFileName(const char *fileName)
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

Return Value

  • MimeType:

String fromFileExtension(const char *extension)

Obtain content type string from file extension.

Parameters

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

Return Value

String fromFileExtension(const String &extension)

Obtain content type string from file extension.

Parameters

  • extension:

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

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

Return Value

  • MimeType:

MimeType fromFullFileName(const String &fileName, MimeType unknown)

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

  1. Delete all instances of HttpClient

  2. Call the static method HttpClient::cleanup();

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

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 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.

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)

Public Members

HttpResourceTree paths

Maps paths to resources which deal with incoming requests.