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

Return values:

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

Return values:

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

Return values:

MimeType –

String fromFileExtension(const char *extension)

Obtain content type string from file extension.

Parameters:

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

Return values:

String –

inline String fromFileExtension(const String &extension)

Obtain content type string from file extension.

Parameters:

extension –

Return values:

String –

MimeType fromString(const char *str)

Get enumerated value for a MIME type string.

Parameters:

str –

Return values:

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 –

Return values:

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 class HttpMethod

Strongly-typed enum which shadows http_method from http_parser library.

{

Values:

enumerator XX

enum class HttpStatus

HTTP status code.

Values:

enumerator XX

enum class 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 –

Return values:

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 –

Return values:

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 –

Return values:

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 –

Return values:

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

class HeaderConst : public BaseElement<true>

class Iterator : public HashMap<K, V>::Iterator<true>

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 also

HttpRequest(const HttpRequest& value)

Return values:

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)

Return values:

HttpRequest* –

inline const String &getHeader(const String &name)

Get header field value.

Parameters:

name – Name of field

Return values:

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

Return values:

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.

Return values:

String –

inline IDataSourceStream *getBodyStream()

Return the current body stream.

Note

may return null

Return values:

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 –

Return values:

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.

Return values:

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 –

Return values:

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

Return values:

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

Return values:

bool –

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

Send data from the given stream object.

Parameters:

• newDataStream –

• type –

Return values:

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 –

Return values:

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.

Return values:

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.

Return values:

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.