Asynchronous HTTP/1.1 client using caller-provided fixed storage. More...

#include <HttpAsyncClient.h>

Public Member Functions
Result	init (HttpConnectionBase &storage)
	Initializes the client with caller-provided connection storage The storage must outlive the client and provides buffers, queues and socket state.

Result	close ()
	Closes any active connection and releases references to the initialized storage.

Result	start (AsyncEventLoop &loop, HttpParser::Method method, StringSpan url, bool keepAlive=false)
	Starts a request that must be configured inside `onPrepareRequest` `onPrepareRequest` must send the headers before returning, typically by calling `HttpAsyncClientRequest::sendHeaders()`.

Result	get (AsyncEventLoop &loop, StringSpan url, bool keepAlive=false)
	Convenience wrapper for a GET request without a request body.

Result	put (AsyncEventLoop &loop, StringSpan url, Span< const char > body, bool keepAlive=false)
	Convenience wrapper for a PUT request with a fixed in-memory body.

Result	put (AsyncEventLoop &loop, StringSpan url, StringSpan body, bool keepAlive=false)

Result	post (AsyncEventLoop &loop, StringSpan url, Span< const char > body, bool keepAlive=false)
	Convenience wrapper for a POST request with a fixed in-memory body.

Result	post (AsyncEventLoop &loop, StringSpan url, StringSpan body, bool keepAlive=false)

Result	postMultipart (AsyncEventLoop &loop, StringSpan url, HttpMultipartWriter &writer, bool keepAlive=false)
	Convenience wrapper for a multipart/form-data POST request.

HttpAsyncClientResponse &	getResponse ()

const HttpAsyncClientResponse &	getResponse () const

Public Attributes
Function< void(HttpAsyncClientRequest &)>	onPrepareRequest
	Called after the request has been created and can still be customized.

Function< void(HttpAsyncClientResponse &)>	onResponse
	Called after the response headers have been parsed.

Function< void(Result)>	onError
	Called on connection, protocol or streaming errors.

Detailed Description

Asynchronous HTTP/1.1 client using caller-provided fixed storage.

HttpAsyncClient processes a single request at a time and can sequentially reuse the same connection when keep-alive is enabled and the next request targets the same host and port.

Use the convenience wrappers (get, put, post, postMultipart) when the request body is already available in memory. Use start() when the request must be customized inside onPrepareRequest, for example to stream the request body with HttpAsyncClientRequest::setBody(AsyncReadableStream&, uint64_t) or to write it manually through HttpAsyncClientRequest::getWritableStream().

onResponse is called after response headers have been parsed. The response body is then read incrementally from HttpAsyncClientResponse::getReadableStream(), and the readable stream eventEnd signals the end of the response body.

Example without a streamed request body:

    client.onResponse = [this, &ctx](HttpAsyncClientResponse& response)
    {
        ctx.collector.attach(response,
                             [this, &ctx](HttpAsyncClientResponse& completedResponse)
                             {
                                 ctx.collector.detach();
                                 SC_TEST_EXPECT(completedResponse.getParser().statusCode == 200);
                                 SC_TEST_EXPECT(StringView(ctx.collector.view()) == "hello");
                                 SC_TEST_EXPECT(ctx.httpServer.stop());
                             });
    };
    client.onError = [this](Result result) { SC_TEST_EXPECT(result); };
 
    SC_TEST_EXPECT(client.get(loop, url.view()));

Example streaming the request body:

    client.onPrepareRequest = [this, &bodyStream](HttpAsyncClientRequest& request)
    {
        request.setBody(bodyStream, 11);
        SC_TEST_EXPECT(request.sendHeaders());
    };
 
    client.onResponse = [this, &ctx](HttpAsyncClientResponse& response)
    {
        ctx.collector.attach(response,
                             [this, &ctx](HttpAsyncClientResponse& completedResponse)
                             {
                                 ctx.collector.detach();
                                 SC_TEST_EXPECT(completedResponse.getParser().statusCode == 201);
                                 String content;
                                 SC_TEST_EXPECT(ctx.fs.read("client-put-stream.txt", content));
                                 SC_TEST_EXPECT(content == "ChunkedBody");
                                 SC_TEST_EXPECT(ctx.fs.removeFile("client-put-stream.txt"));
                                 SC_TEST_EXPECT(ctx.httpServer.stop());
                             });
    };
    client.onError = [this](Result result) { SC_TEST_EXPECT(result); };
 
    SC_TEST_EXPECT(client.start(loop, HttpParser::Method::HttpPUT, url.view()));

Member Function Documentation

◆ close()

Result SC::HttpAsyncClient::close ( )

Closes any active connection and releases references to the initialized storage.

◆ get()

Result SC::HttpAsyncClient::get	(	AsyncEventLoop &	loop,
		StringSpan	url,
		bool	keepAlive = false )

Convenience wrapper for a GET request without a request body.

◆ init()

Result SC::HttpAsyncClient::init ( HttpConnectionBase & storage )

Initializes the client with caller-provided connection storage The storage must outlive the client and provides buffers, queues and socket state.

◆ post()

Result SC::HttpAsyncClient::post	(	AsyncEventLoop &	loop,
		StringSpan	url,
		Span< const char >	body,
		bool	keepAlive = false )

Convenience wrapper for a POST request with a fixed in-memory body.

◆ postMultipart()

Result SC::HttpAsyncClient::postMultipart	(	AsyncEventLoop &	loop,
		StringSpan	url,
		HttpMultipartWriter &	writer,
		bool	keepAlive = false )

Convenience wrapper for a multipart/form-data POST request.

◆ put()

Result SC::HttpAsyncClient::put	(	AsyncEventLoop &	loop,
		StringSpan	url,
		Span< const char >	body,
		bool	keepAlive = false )

Convenience wrapper for a PUT request with a fixed in-memory body.

◆ start()

Result SC::HttpAsyncClient::start	(	AsyncEventLoop &	loop,
		HttpParser::Method	method,
		StringSpan	url,
		bool	keepAlive = false )

Starts a request that must be configured inside onPrepareRequest onPrepareRequest must send the headers before returning, typically by calling HttpAsyncClientRequest::sendHeaders().

Member Data Documentation

◆ onError

Function<void(Result)> SC::HttpAsyncClient::onError

Called on connection, protocol or streaming errors.

◆ onPrepareRequest

Function<void(HttpAsyncClientRequest&)> SC::HttpAsyncClient::onPrepareRequest

Called after the request has been created and can still be customized.

◆ onResponse

Function<void(HttpAsyncClientResponse&)> SC::HttpAsyncClient::onResponse

Called after the response headers have been parsed.

The documentation for this struct was generated from the following file:

HttpAsyncClient.h

Public Member Functions

Public Attributes