CMUTIL_HttpClient Struct Reference

An HTTP/HTTPS client built on the socket layer. More...

Data Fields
CMBool(*	SetVerify )(CMUTIL_HttpClient *client, CMBool verify_host, CMBool verify_peer)
	Set TLS verification for this client.
CMBool(*	SetSSLCert )(CMUTIL_HttpClient *client, const char *certfile, const char *keyfile, const char *cafile)
	Set the TLS certificates this client uses.
void(*	SetKeepAlive )(CMUTIL_HttpClient *client, CMBool keepalive)
	Whether to keep connections open between requests.
CMUTIL_ByteBuffer *(*	Request )(CMUTIL_HttpClient *client, const char *method, CMUTIL_Map *headers, const char *uri, CMUTIL_ByteBuffer *body, int *status, long timeout)
	Perform a request with any method.
CMUTIL_ByteBuffer *(*	Get )(CMUTIL_HttpClient *client, CMUTIL_Map *headers, const char *uri, int *status, long timeout)
	Perform a GET request.
CMUTIL_ByteBuffer *(*	Post )(CMUTIL_HttpClient *client, CMUTIL_Map *headers, const char *uri, CMUTIL_ByteBuffer *body, int *status, long timeout)
	Perform a POST request.
void(*	Destroy )(CMUTIL_HttpClient *client)
	Destroy this client.

Detailed Description

An HTTP/HTTPS client built on the socket layer.

The client is fixed to one origin: it takes a URL prefix at construction and every request names a URI relative to it. Request and response bodies are CMUTIL_ByteBuffer objects; see CMUTIL_RestClient for the same client speaking CMUTIL_Json.

Connections are kept alive and pooled per host and port, so a series of requests to one origin reuses one socket. A pooled connection is dropped once it has been idle for 30 seconds.

Field Documentation

SetVerify

CMBool(* CMUTIL_HttpClient::SetVerify) (CMUTIL_HttpClient *client, CMBool verify_host, CMBool verify_peer)

Set TLS verification for this client.

A fresh client verifies the host name and presents no client certificate. Turning verify_host off reaches a server whose certificate does not match its name - including a self-signed one.

Parameters

client	This HTTP client object.
verify_host	CMTrue to check the server's certificate against the host name, and to use the CA file set by SetSSLCert as the trust anchor rather than the system trust store.
verify_peer	CMTrue to present the client certificate set by SetSSLCert.

Returns

CMTrue on success.

SetSSLCert

CMBool(* CMUTIL_HttpClient::SetSSLCert) (CMUTIL_HttpClient *client, const char *certfile, const char *keyfile, const char *cafile)

Set the TLS certificates this client uses.

Which of them take effect depends on SetVerify: the client certificate and key are only sent when verify_peer is on, and the CA file only becomes the trust anchor when verify_host is on.

Parameters

client	This HTTP client object.
certfile	Client certificate in PEM form, or NULL.
keyfile	Private key for certfile in PEM form, or NULL.
cafile	CA certificate to trust in PEM form, or NULL to use the system trust store.

Returns

CMTrue on success, CMFalse if a path is too long to store.

SetKeepAlive

void(* CMUTIL_HttpClient::SetKeepAlive) (CMUTIL_HttpClient *client, CMBool keepalive)

Whether to keep connections open between requests.

On by default. A server that answers with HTTP/1.0, or with Connection: close, ends the connection regardless.

Parameters

client	This HTTP client object.
keepalive	CMFalse to close the connection after each request.

Request

CMUTIL_ByteBuffer *(* CMUTIL_HttpClient::Request) (CMUTIL_HttpClient *client, const char *method, CMUTIL_Map *headers, const char *uri, CMUTIL_ByteBuffer *body, int *status, long timeout)

Perform a request with any method.

Get and Post are this function with the method filled in; use it directly for PUT, DELETE, HEAD, PATCH and the rest.

Host, Connection and - for a method that carries a body - Content-Length are supplied automatically unless headers already names them.

Parameters

client	This HTTP client object.
method	Request method, such as "GET".
headers	Request headers as a map of C strings, or NULL. The map is only read.
uri	Request URI, relative to the prefix given at creation.
body	Request body, or NULL. It is only sent for POST and PUT.
status	Receives the response status code. It is left untouched when the request never reaches a response, so initialize it.
timeout	Timeout in milliseconds, applied to each socket operation the request performs.

Returns

The response body, which the caller must destroy, or NULL if the request failed. A response with no body yields an empty buffer rather than NULL.

Get

CMUTIL_ByteBuffer *(* CMUTIL_HttpClient::Get) (CMUTIL_HttpClient *client, CMUTIL_Map *headers, const char *uri, int *status, long timeout)

Perform a GET request.

Parameters

client	This HTTP client object.
headers	Request headers as a map of C strings, or NULL.
uri	Request URI, relative to the prefix given at creation.
status	Receives the response status code.
timeout	Timeout in milliseconds.

Returns

The response body, which the caller must destroy, or NULL.

Post

CMUTIL_ByteBuffer *(* CMUTIL_HttpClient::Post) (CMUTIL_HttpClient *client, CMUTIL_Map *headers, const char *uri, CMUTIL_ByteBuffer *body, int *status, long timeout)

Perform a POST request.

Parameters

client	This HTTP client object.
headers	Request headers as a map of C strings, or NULL.
uri	Request URI, relative to the prefix given at creation.
body	Request body. Ownership stays with the caller.
status	Receives the response status code.
timeout	Timeout in milliseconds.

Returns

The response body, which the caller must destroy, or NULL.

Destroy

void(* CMUTIL_HttpClient::Destroy) (CMUTIL_HttpClient *client)

Destroy this client.

Connections this client left in the pool are not closed here; they are closed when they expire, or at CMUTIL_Clear().

Parameters

client

This HTTP client object.

---

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

• /home/runner/work/libcmutils/libcmutils/src/libcmutils.h