Support API

namespace ContentType

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

MimeType fromFullFileName(const char *fileName, MimeType unknown)

Parameters

fileName – As NUL-terminated string
unknown – Value to return if type cannot be determined

Returns

MimeType –

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

Parameters: fileName – As wiring String

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

String fromFullFileName(const char *fileName)

Parameters: fileName – as NUL-terminated string
Returns: String –

inline String fromFullFileName(const String &fileName)

Parameters: fileName – as wiring String

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

Defines

ENABLE_HTTP_REQUEST_AUTH

HTTP_MAX_HEADER_SIZE

HTTP_REQUEST_POOL_SIZE

XX(num, name, string)

XX(num, name, string)

XX(num, name, string)

XX(num, name, string)

XX(n, s)

XX(n, s)

HTTP_PARSER_ERRNO(p)

Typedefs

using HttpFiles = ObjectMap<String, ReadWriteStream>

Enums

enum HttpMethod

Strongly-typed enum which shadows http_method from http_parser library.

{

Values:

enumerator XX

enum HttpStatus

HTTP status code.

Values:

enumerator XX

enum HttpError

HTTP error codes.

Values:

enumerator XX

enum HttpConnectionState

Identifies current state for an HTTP connection.

Values:

enumerator eHCS_Ready

enumerator eHCS_StartSending

enumerator eHCS_SendingHeaders

enumerator eHCS_StartBody

enumerator eHCS_SendingBody

enumerator eHCS_Sent

enumerator eHCS_WaitResponse

Functions

String toString(HttpError err): Return a descriptive string for the given error.

String httpGetErrorDescription(HttpError err): Return a descriptive string for the given error.

String toString(HttpStatus code): Return a descriptive string for an HTTP status code.

inline String httpGetStatusText(unsigned code): Return a descriptive string for an HTTP status code.

inline String toString(HttpMethod method): Return text for an HTTP method.

class HttpHeaders : public HttpHeaderFields, private HashMap<HttpHeaderFieldName, String>

Encapsulates a set of HTTP header information.

Todo:: add name and/or value escaping

Note

fields are stored as a map of field names vs. values. Standard fields may be accessed using enumeration tags. Behaviour is as for HashMap, with the addition of methods to support enumerated field names.

Subclassed by SSDP::BaseMessage< HttpHeaders >

Public Functions

const String &operator[](const String &name) const

Fetch a reference to the header field value by name.

Note

if the field doesn’t exist a null String reference is returned

Parameters: name –
Returns: const – String& Reference to value

inline String &operator[](const String &name)

Fetch a reference to the header field value by name.

Note

if the field doesn’t exist it is created with the default null value

Parameters: name –
Returns: String& – Reference to value

inline String operator[](unsigned index) const

Return the HTTP header line for the value at the given index.

Note

if the index is invalid,

Parameters: index –
Returns: String –

inline bool contains(const String &name) const: Determine if given header field is present.

bool append(const HttpHeaderFieldName &name, const String &value)

Append value to multi-value field.

Parameters

name –
value –

Returns

bool – false if value exists and field does not permit multiple values

class HttpRequest

Encapsulates an incoming or outgoing request.

Set request body content

inline HttpRequest *setBody(const String &body): Set body from String object.

HttpRequest *setBody(String &&body) noexcept: Set body from String object using move semantics: body will be invalid on return.

HttpRequest *setBody(IDataSourceStream *stream): Set body using given stream object, and retain ownership.

HttpRequest *setBody(const uint8_t *rawData, size_t length)

Set body content by copying binary data.

Parameters

rawData – Data to copy
length – Number of bytes to copy

Public Types

using SslInitDelegate = Delegate<void(Ssl::Session &session, HttpRequest &request)>: Callback delegate type used to initialise an SSL session for a given request.

Public Functions

inline HttpRequest(const HttpRequest &value): Copy constructor.

Note

Internal streams are not copied so these must be dealt with afterwards

inline HttpRequest *clone() const

Clone this request into a new object using the copy constructor.

See: HttpRequest(const HttpRequest& value)

Returns: HttpRequest* – The new request object

inline HttpRequest *setFile(const String &formElementName, ReadWriteStream *stream)

Sets a file to be sent.

Parameters

formElementName – The name of the element in the form
stream – Pointer to the stream (doesn’t have to be a FileStream)

Returns

HttpRequest* –

inline const String &getHeader(const String &name)

Get header field value.

Parameters: name – Name of field
Returns: const – String& Value, will be invalid (i.e. if() == false) if field not present

inline const String &getPostParameter(const String &name)

Get POST parameter value.

Parameters: name – Name of parameter
Returns: const – String& Value, will be invalid (i.e. if() == false) if field not present

inline String getQueryParameter(const String &name, const String &defaultValue = nullptr) const

Get parameter from query fields.

Parameters

name – Name of parameter
defaultValue – Optional default value to use if requested parameter not present

inline String getBody()

Moves content from the body stream into a String.

Note

Move semantics are used to ensure that no/minimal additional memory is required. If your application has set a non-memory stream type then the method will fail and return an invalid String. The stream content will be left unchanged.

Returns: String –

inline IDataSourceStream *getBodyStream()

Return the current body stream.

Note

may return null

Returns: IDataSourceStream* –

HttpRequest *setResponseStream(ReadWriteStream *stream)

Instead of storing the response body we can set a stream that will take care to process it.

Note

The response to this request will be stored in the user-provided stream.

Parameters: stream –
Returns: HttpRequest* –

inline ReadWriteStream *getResponseStream(): Get the response stream (if any)

void reset(): Clear buffers and reset to default state in preparation for another request.

inline HttpRequest *onSslInit(SslInitDelegate delegate)

To customise SSL session options, provide a callback.

Parameters: delegate – Invoked before creating SSL connection

String toString() const

Tries to present a readable version of the current request values.

Returns: String –

Public Members

Url uri: Request URL.

HttpMethod method = HTTP_GET: Request method.

HttpHeaders headers: Request headers.

HttpParams postParams: POST parameters.

HttpFiles files: Attached files.

int retries = 0: how many times the request should be send again…

void *args = nullptr: Used to store data that should be valid during a single request.

Public Static Functions

static inline String toString(const HttpRequest &req)

Tries to present a readable version of the request.

Parameters: req –
Returns: String –

class HttpResponse

Represents either an incoming or outgoing response to a HTTP request.

Public Functions

bool sendFile(const String &fileName, bool allowGzipFileCheck = true)

Send file by name.

Parameters

fileName –
allowGzipFileCheck – If true, check file extension to see if content compressed

Returns

bool –

bool sendNamedStream(IDataSourceStream *newDataStream)

Parse and send stream, using the name to determine the content type.

Parameters: newDataStream – If not set already, the contentType will be obtained from the name of this stream
Returns: bool –

inline bool sendDataStream(IDataSourceStream *newDataStream, enum MimeType type)

Send data from the given stream object.

Parameters

newDataStream –
type –

Returns

false – on error

bool sendDataStream(IDataSourceStream *newDataStream, const String &reqContentType = nullptr)

Send data from the given stream object.

Note

all data is submitted via stream so called by internal routines

Parameters

newDataStream –
reqContentType –

Returns

on – error returns false and stream will have been destroyed so any external references to it must be invalidated.

inline String getBody()

Moves content from the body stream into a String.

Note

Move semantics are used to ensure that no/minimal additional memory is required. If your application has set a non-memory stream type then the method will fail and return an invalid String. The stream content will be left unchanged.

Returns: String –

void reset(): reset response so it can be re-used

void setBuffer(ReadWriteStream *buffer)

Called by connection to specify where incoming response data is written.

Parameters: buffer –

void freeStreams(): release allocated stream memory

inline bool isSuccess(): Determine if the response status indicates success.

String toString() const

Tries to present a readable version of the current response values.

Returns: String –

Public Members

HttpStatus code = HTTP_STATUS_OK: The HTTP status response code.

HttpHeaders headers: Response headers.

ReadWriteStream *buffer = nullptr: Internal stream for storing strings and receiving responses.

IDataSourceStream *stream = nullptr: The body stream.