Reference/Networking

Networking

CHTTP

Make HTTP requests with text, JSON-value, or binary responses.

C++23 mc/CHTTP.h
#include <mc/CHTTP.h>

Choose the response representation in the constructor. Configure the request before run() or start(); do not reconfigure an active request.

Transport failures throw CError. HTTP error status codes remain observable through status().

Jump to a declaration · 18
CHTTP CHTTP::addHeader CHTTP::addPost CHTTP::await CHTTP::CHTTP CHTTP::escape CHTTP::operator= CHTTP::postFile CHTTP::run CHTTP::setPost CHTTP::setTimeout CHTTP::setType CHTTP::setURL CHTTP::start CHTTP::status CHTTP::Type CHTTP::unsafeSSL CHTTP::~CHTTP

CHTTP

class CHTTP

Types, constants & data

enum Type { Text, JSON, Buffer };

Methods

CHTTP

CHTTP(Type type);
CHTTP(const CHTTP&) = delete;

Selects how response bodies are returned: Text as cstr, JSON as parsed values, or Buffer as owned binary data. This choice is separate from the request method and headers.

setURL

void setURL(const cstr& url);

Sets the request URL while the request is idle. Redirect following is enabled by default.

setType

void setType(const cstr& type);

Sets the HTTP request method, such as GET, POST, or DELETE. Set a Content-Type header with addHeader(); the constructor’s Type controls response decoding.

addHeader

void addHeader(const cstr& header);

Appends one complete request header line, such as Content-Type: application/json. Set headers before starting the request.

setTimeout

void setTimeout(double dt);

Sets the total transfer timeout in seconds. Zero disables the timeout; negative or non-finite values are rejected.

setPost

void setPost(const cstr& data);
void setPost(const std::string& data);
void setPost(const cvar& data);

Sets a copied request body and selects posting behavior. A cvar body is serialized as JSON, but callers must add the appropriate Content-Type header themselves.

addPost

void addPost(const cstr& key, const cstr& value);
void addPost(const cstr& key, const char* buf, size_t bytes);

Adds a multipart form field from text or counted bytes. Data is copied during the call; this is distinct from setting one raw body with setPost().

postFile

void postFile(const cstr& key, const cstr& path);

Adds a file as a named multipart field. The path must identify a file and remain readable until the transfer finishes.

unsafeSSL

void unsafeSSL();

Disables peer certificate and host verification for this request object.

run

cvar run();

Performs the configured request synchronously and returns the decoded body. Transport and decoding failures raise CError; HTTP error status codes remain available through status().

start

void start();

Starts the request on a background thread. A second start or configuration mutation is rejected until await() completes.

await

cvar await();

Joins a request started with start() and returns its decoded body. Asynchronous failures are rethrown here; calling without an active request is an error.

status

int status();

Returns the last completed HTTP response status, or zero before one is available. It is separate from transport success or failure.

escape

cstr escape(const cstr& s);

Percent-encodes a string for use as an individual URL component. It does not assemble a URL or encode an entire query structure.