HTTP Client

Data Structures
struct	ltrx_http_client_connect_info
	HTTP client connect information. More...
struct	ltrx_http_client_header
	HTTP client header. More...

Enumerations
enum	ltrx_httpc_method { LTRX_HTTPC_METHOD__UNSPECIFIED , LTRX_HTTPC_METHOD__POST , LTRX_HTTPC_METHOD__GET , LTRX_HTTPC_METHOD__PUT }
	HTTP client methods. More...
enum	ltrx_httpc_return_code {   LTRX_HTTPC_RC__SUCCESS = 0 , LTRX_HTTPC_RC__INVALID_PARAMETER = -1 , LTRX_HTTPC_RC__NOT_ENOUGH_MEMORY = -2 , LTRX_HTTPC_RC__INVALID_STATE = -3 ,   LTRX_HTTPC_RC__CONNECT_FAILED = -4 , LTRX_HTTPC_RC__PROTOCOL_ERROR = -5 , LTRX_HTTPC_RC__HTTP_ERROR_RESPONSE = -6 , LTRX_HTTPC_RC__OTHER_FAILURE = -7 }
	HTTP client Return codes. More...

Functions
enum ltrx_httpc_return_code	ltrx_httpc_request_add_header (struct ltrx_http_client_request *handle, struct ltrx_http_client_header *httpHeader)
	Add an HTTP client request header.
enum ltrx_httpc_return_code	ltrx_httpc_request_add_mime_type (struct ltrx_http_client_request *handle, const char *mimeType)
	Add an HTTP client request mime type.
enum ltrx_httpc_return_code	ltrx_httpc_request_add_tls_authority (struct ltrx_http_client_request *handle, const char *authorityPemCertificate)
	Add an HTTP client request TLS authority certificate.
enum ltrx_httpc_return_code	ltrx_httpc_request_clear (struct ltrx_http_client_request *handle)
	Clear an HTTP client request.
enum ltrx_httpc_return_code	ltrx_httpc_request_connect_and_send_headers (struct ltrx_http_client_request *handle)
	HTTP client request execute connect and send headers.
struct ltrx_http_client_request *	ltrx_httpc_request_create (enum ltrx_httpc_method method)
	Create an HTTP client handle.
void	ltrx_httpc_request_destroy (struct ltrx_http_client_request *handle)
	Destroy an HTTP client request.
enum ltrx_httpc_return_code	ltrx_httpc_request_disconnect (struct ltrx_http_client_request *handle)
	HTTP client request execute disconnect.
enum ltrx_httpc_return_code	ltrx_httpc_request_execute (struct ltrx_http_client_request *handle)
	HTTP client request execute connect, send, receive, and disconnect.
enum ltrx_httpc_return_code	ltrx_httpc_request_get_log_verbosity (struct ltrx_http_client_request *handle, uint8_t *verbosityp)
	Get the HTTP client request log verbosity.
enum ltrx_httpc_return_code	ltrx_httpc_request_get_status_code (struct ltrx_http_client_request *handle, uint32_t *codep, char *buffer, size_t *buffer_lengthp)
	Get then HTTP client request status code and/or string.
enum ltrx_httpc_return_code	ltrx_httpc_request_receive (struct ltrx_http_client_request *handle)
	HTTP client request execute receive.
enum ltrx_httpc_return_code	ltrx_httpc_request_send_content (struct ltrx_http_client_request *handle)
	HTTP client request execute send content.
enum ltrx_httpc_return_code	ltrx_httpc_request_set_100continue_timeout (struct ltrx_http_client_request *handle, uint32_t timeoutMsec)
	Set an HTTP client request 100 continue timeout.
enum ltrx_httpc_return_code	ltrx_httpc_request_set_connect_info (struct ltrx_http_client_request *handle, const struct ltrx_http_client_connect_info *info)
	Set the HTTP client request connect information.
enum ltrx_httpc_return_code	ltrx_httpc_request_set_debug (struct ltrx_http_client_request *handle, bool dump_send, bool dump_receive)
	Set the HTTP client request debug flags.
enum ltrx_httpc_return_code	ltrx_httpc_request_set_log_verbosity (struct ltrx_http_client_request *handle, uint8_t verbosity)
	Set the HTTP client request log verbosity.
enum ltrx_httpc_return_code	ltrx_httpc_request_set_method (struct ltrx_http_client_request *handle, enum ltrx_httpc_method method)
	Set the HTTP client request method.
enum ltrx_httpc_return_code	ltrx_httpc_request_set_response_buffer_malloc (struct ltrx_http_client_request *handle, uint8_t **bufferp, size_t size_guess)
	Initialize an HTTP client request input method of allocated buffer.
enum ltrx_httpc_return_code	ltrx_httpc_request_set_response_callback (struct ltrx_http_client_request *handle, bool(*callback)(struct ltrx_http_client_request *handle, void *opaque, const void *data, size_t size), void *opaque)
	Initialize an HTTP client request input method of callback function.
enum ltrx_httpc_return_code	ltrx_httpc_request_set_response_inactivity_timeout (struct ltrx_http_client_request *handle, uint32_t timeoutMsec)
	Set an HTTP client request timeout.
enum ltrx_httpc_return_code	ltrx_httpc_request_set_response_stream (struct ltrx_http_client_request *handle, struct output_stream *ostream)
	Initialize an HTTP client request input method of output stream.
enum ltrx_httpc_return_code	ltrx_httpc_request_set_tls_credential (struct ltrx_http_client_request *handle, const char *credentialName)
	Set the HTTP client request TLS credential name.
enum ltrx_httpc_return_code	ltrx_httpc_request_set_user_agent (struct ltrx_http_client_request *handle, const char *userAgent)
	Set the HTTP client request user agent.
enum ltrx_httpc_return_code	ltrx_httpc_request_set_write_buffer (struct ltrx_http_client_request *handle, const void *data, size_t size)
	Initialize an HTTP client request output method of buffer.
enum ltrx_httpc_return_code	ltrx_httpc_request_set_write_function (struct ltrx_http_client_request *handle, void(*write_callback)(const uint8_t **datap, size_t *sizep, void *opaque), void *opaque)
	Initialize an HTTP client request output method of callback function.
enum ltrx_httpc_return_code	ltrx_httpc_request_set_write_stream (struct ltrx_http_client_request *handle, struct input_stream *istream)
	Initialize an HTTP client request output method of input stream.
const char *	ltrx_httpc_strerror (enum ltrx_httpc_return_code error)
	Convert error code to text.
bool	ltrx_input_stream_init_from_httpc_request (struct input_stream_from_httpc_request *istream, struct ltrx_http_client_request *handle)
	Initialize an HTTP client request input stream struct.
bool	ltrx_output_stream_init_to_httpc_request (struct output_stream_to_httpc_request *ostream, struct ltrx_http_client_request *handle)
	Initialize an HTTP client request output stream struct.

Detailed Description

HTTP Client.

HTTP Client.

HTTP Client.

HTTP Client.

Enumeration Type Documentation

ltrx_httpc_method

enum ltrx_httpc_method

HTTP client methods.

Enumerator
LTRX_HTTPC_METHOD__UNSPECIFIED	Unspecified method (can be specified later).
LTRX_HTTPC_METHOD__POST	POST method.
LTRX_HTTPC_METHOD__GET	GET method.
LTRX_HTTPC_METHOD__PUT	PUT method.

ltrx_httpc_return_code

enum ltrx_httpc_return_code

HTTP client Return codes.

Enumerator
LTRX_HTTPC_RC__SUCCESS	Success.
LTRX_HTTPC_RC__INVALID_PARAMETER	Invalid parameter.
LTRX_HTTPC_RC__NOT_ENOUGH_MEMORY	Insufficient memory.
LTRX_HTTPC_RC__INVALID_STATE	Invalid state.
LTRX_HTTPC_RC__CONNECT_FAILED	Connect failed.
LTRX_HTTPC_RC__PROTOCOL_ERROR	Protocol error.
LTRX_HTTPC_RC__HTTP_ERROR_RESPONSE	HTTP error response.
LTRX_HTTPC_RC__OTHER_FAILURE	Unknown error.

Function Documentation

ltrx_httpc_request_add_header()

enum ltrx_httpc_return_code ltrx_httpc_request_add_header	(	struct ltrx_http_client_request *	handle,
		struct ltrx_http_client_header *	httpHeader )

Add an HTTP client request header.

Must be set after each ltrx_httpc_request_clear() and before sending. The header name and value must persist till ltrx_httpc_request_clear() or ltrx_httpc_request_destroy(), as they are referenced, not copied.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[in]	httpHeader	Header to be added.

ltrx_httpc_request_add_mime_type()

enum ltrx_httpc_return_code ltrx_httpc_request_add_mime_type	(	struct ltrx_http_client_request *	handle,
		const char *	mimeType )

Add an HTTP client request mime type.

Must be set after each ltrx_httpc_request_clear() and before sending. The mime type must persist till ltrx_httpc_request_clear() or ltrx_httpc_request_destroy(), as it is referenced, not copied.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[in]	mimeType	Mime type to be added.

ltrx_httpc_request_add_tls_authority()

enum ltrx_httpc_return_code ltrx_httpc_request_add_tls_authority	(	struct ltrx_http_client_request *	handle,
		const char *	authorityPemCertificate )

Add an HTTP client request TLS authority certificate.

Must be set after each ltrx_httpc_request_clear() and before sending. The TLS authority certificate must persist till ltrx_httpc_request_clear() or ltrx_httpc_request_destroy(), as it is referenced, not copied.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[in]	authorityPemCertificate	TLS authority certificate in PEM format.

ltrx_httpc_request_clear()

enum ltrx_httpc_return_code ltrx_httpc_request_clear

(

struct ltrx_http_client_request *

handle

)

Clear an HTTP client request.

Frees data and resets handle in preparation for another request, but keeps receive buffer, if used, so reply is retained.

Returns

enum ltrx_httpc_return_code

Parameters

handle

[in,out] HTTP client request handle.

ltrx_httpc_request_connect_and_send_headers()

enum ltrx_httpc_return_code ltrx_httpc_request_connect_and_send_headers

(

struct ltrx_http_client_request *

handle

)

HTTP client request execute connect and send headers.

Use other functions to set various options before this call.

Returns

enum ltrx_httpc_return_code

Parameters

handle

[in,out] HTTP client request handle.

ltrx_httpc_request_create()

struct ltrx_http_client_request * ltrx_httpc_request_create

(

enum ltrx_httpc_method

method

)

Create an HTTP client handle.

Return values

non-NULL	Pointer to the new HTTP client handle.
NULL	Failed.

Parameters

[in]

method

Method for convenience; can be set after create.

ltrx_httpc_request_destroy()

void ltrx_httpc_request_destroy

(

struct ltrx_http_client_request *

handle

)

Destroy an HTTP client request.

Clears and destroys a handle. Do not attempt to use the handle after this call.

Parameters

handle

[in,out] HTTP client request handle.

ltrx_httpc_request_disconnect()

enum ltrx_httpc_return_code ltrx_httpc_request_disconnect

(

struct ltrx_http_client_request *

handle

)

HTTP client request execute disconnect.

Call subsequent to ltrx_httpc_request_create().

Returns

enum ltrx_httpc_return_code

Parameters

handle

[in,out] HTTP client request handle.

ltrx_httpc_request_execute()

enum ltrx_httpc_return_code ltrx_httpc_request_execute

(

struct ltrx_http_client_request *

handle

)

HTTP client request execute connect, send, receive, and disconnect.

Use other functions to set various options before this call.

Returns

enum ltrx_httpc_return_code

Parameters

handle

[in,out] HTTP client request handle.

ltrx_httpc_request_get_log_verbosity()

enum ltrx_httpc_return_code ltrx_httpc_request_get_log_verbosity	(	struct ltrx_http_client_request *	handle,
		uint8_t *	verbosityp )

Get the HTTP client request log verbosity.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[out]	verbosityp	The current verbosity level.

ltrx_httpc_request_get_status_code()

enum ltrx_httpc_return_code ltrx_httpc_request_get_status_code	(	struct ltrx_http_client_request *	handle,
		uint32_t *	codep,
		char *	buffer,
		size_t *	buffer_lengthp )

Get then HTTP client request status code and/or string.

Upon call, *buffer_lengthp is the size of the buffer. Upon return, *buffer_lengthp is the length of the status string.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[out]	codep	HTTP client request status code.
[out]	buffer	HTTP client request status buffer pointer.
	buffer_lengthp	[in,out] HTTP client request status buffer size/length.

ltrx_httpc_request_receive()

enum ltrx_httpc_return_code ltrx_httpc_request_receive

(

struct ltrx_http_client_request *

handle

)

HTTP client request execute receive.

Call ltrx_httpc_request_connect_and_send_headers() and send any content before this call.

Returns

enum ltrx_httpc_return_code

Parameters

handle

[in,out] HTTP client request handle.

ltrx_httpc_request_send_content()

enum ltrx_httpc_return_code ltrx_httpc_request_send_content

(

struct ltrx_http_client_request *

handle

)

HTTP client request execute send content.

Call ltrx_httpc_request_connect_and_send_headers() before this call.

Returns

enum ltrx_httpc_return_code

Parameters

handle

[in,out] HTTP client request handle.

ltrx_httpc_request_set_100continue_timeout()

enum ltrx_httpc_return_code ltrx_httpc_request_set_100continue_timeout	(	struct ltrx_http_client_request *	handle,
		uint32_t	timeoutMsec )

Set an HTTP client request 100 continue timeout.

Must be set after each ltrx_httpc_request_clear() and before sending.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[in]	timeoutMsec	Timeout to be set, in milliseconds.

ltrx_httpc_request_set_connect_info()

enum ltrx_httpc_return_code ltrx_httpc_request_set_connect_info	(	struct ltrx_http_client_request *	handle,
		const struct ltrx_http_client_connect_info *	info )

Set the HTTP client request connect information.

Must be set after each ltrx_httpc_request_clear() and before sending. Information must persist till ltrx_httpc_request_clear() or ltrx_httpc_request_destroy(), as it is referenced, not copied.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[in]	info	HTTP client connect information.

ltrx_httpc_request_set_debug()

enum ltrx_httpc_return_code ltrx_httpc_request_set_debug	(	struct ltrx_http_client_request *	handle,
		bool	dump_send,
		bool	dump_receive )

Set the HTTP client request debug flags.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[in]	dump_send	Dump send if true.
[in]	dump_receive	Dump receive if true.

ltrx_httpc_request_set_log_verbosity()

enum ltrx_httpc_return_code ltrx_httpc_request_set_log_verbosity	(	struct ltrx_http_client_request *	handle,
		uint8_t	verbosity )

Set the HTTP client request log verbosity.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[in]	verbosity	The verbosity level to set.

ltrx_httpc_request_set_method()

enum ltrx_httpc_return_code ltrx_httpc_request_set_method	(	struct ltrx_http_client_request *	handle,
		enum ltrx_httpc_method	method )

Set the HTTP client request method.

Must be set after each ltrx_httpc_request_clear() and before sending.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[in]	method	Method.

ltrx_httpc_request_set_response_buffer_malloc()

enum ltrx_httpc_return_code ltrx_httpc_request_set_response_buffer_malloc	(	struct ltrx_http_client_request *	handle,
		uint8_t **	bufferp,
		size_t	size_guess )

Initialize an HTTP client request input method of allocated buffer.

The buffer will contain the HTTP Client (GET, PUT or POST) response.

The method may be ltrx_httpc_request_set_response_buffer_malloc(), ltrx_httpc_request_set_response_callback(), or ltrx_httpc_request_set_response_stream(), but only one of them.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[out]	bufferp	The allocated buffer that will hold the response.
[in]	size_guess	The size for the initial malloc of the buffer.

ltrx_httpc_request_set_response_callback()

enum ltrx_httpc_return_code ltrx_httpc_request_set_response_callback	(	struct ltrx_http_client_request *	handle,
		bool(*	callback )(struct ltrx_http_client_request *handle, void *opaque, const void *data, size_t size),
		void *	opaque )

Initialize an HTTP client request input method of callback function.

The callback function will be passed the HTTP Client (GET, PUT or POST) response.

The method may be ltrx_httpc_request_set_response_buffer_malloc(), ltrx_httpc_request_set_response_callback(), or ltrx_httpc_request_set_response_stream(), but only one of them.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[in]	callback	The callback function that will be fed the response.
[in]	opaque	An opaque pointer to pass to the callback function when called.

ltrx_httpc_request_set_response_inactivity_timeout()

enum ltrx_httpc_return_code ltrx_httpc_request_set_response_inactivity_timeout	(	struct ltrx_http_client_request *	handle,
		uint32_t	timeoutMsec )

Set an HTTP client request timeout.

Must be set after each ltrx_httpc_request_clear() and before sending.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[in]	timeoutMsec	Timeout to be set, in milliseconds.

ltrx_httpc_request_set_response_stream()

enum ltrx_httpc_return_code ltrx_httpc_request_set_response_stream	(	struct ltrx_http_client_request *	handle,
		struct output_stream *	ostream )

Initialize an HTTP client request input method of output stream.

The output stream will be fed the HTTP Client (GET, PUT or POST) response.

The method may be ltrx_httpc_request_set_response_buffer_malloc(), ltrx_httpc_request_set_response_callback(), or ltrx_httpc_request_set_response_stream(), but only one of them.

Returns

enum ltrx_httpc_return_code

Parameters

handle	[in,out] HTTP client request handle.
ostream	[in,out] The output stream that will be fed the response.

ltrx_httpc_request_set_tls_credential()

enum ltrx_httpc_return_code ltrx_httpc_request_set_tls_credential	(	struct ltrx_http_client_request *	handle,
		const char *	credentialName )

Set the HTTP client request TLS credential name.

Must be set after each ltrx_httpc_request_clear() and before sending. The TLS credential name text must persist till ltrx_httpc_request_clear() or ltrx_httpc_request_destroy(), as it is referenced, not copied.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[in]	credentialName	TLS credential name.

ltrx_httpc_request_set_user_agent()

enum ltrx_httpc_return_code ltrx_httpc_request_set_user_agent	(	struct ltrx_http_client_request *	handle,
		const char *	userAgent )

Set the HTTP client request user agent.

If overriding default, must be set after each ltrx_httpc_request_clear() and before sending. The userAgent text must persist till ltrx_httpc_request_clear() or ltrx_httpc_request_destroy(), as it is referenced, not copied.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[in]	userAgent	User agent.

ltrx_httpc_request_set_write_buffer()

enum ltrx_httpc_return_code ltrx_httpc_request_set_write_buffer	(	struct ltrx_http_client_request *	handle,
		const void *	data,
		size_t	size )

Initialize an HTTP client request output method of buffer.

The buffer will feed the HTTP Client (PUT or POST) request.

The method may be ltrx_httpc_request_set_write_buffer(), ltrx_httpc_request_set_write_function(), or ltrx_httpc_request_set_write_stream(), but only one of them.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[in]	data	Location of data to feed request.
[in]	size	Size of data to feed request.

ltrx_httpc_request_set_write_function()

enum ltrx_httpc_return_code ltrx_httpc_request_set_write_function	(	struct ltrx_http_client_request *	handle,
		void(*	write_callback )(const uint8_t **datap, size_t *sizep, void *opaque),
		void *	opaque )

Initialize an HTTP client request output method of callback function.

The callback function will feed the HTTP Client (PUT or POST) request.

The method may be ltrx_httpc_request_set_write_buffer(), ltrx_httpc_request_set_write_function(), or ltrx_httpc_request_set_write_stream(), but only one of them.

Returns

enum ltrx_httpc_return_code

Parameters

	handle	[in,out] HTTP client request handle.
[in]	write_callback	The callback function that will feed request.
[in]	opaque	An opaque pointer to pass to the callback function when called.

ltrx_httpc_request_set_write_stream()

enum ltrx_httpc_return_code ltrx_httpc_request_set_write_stream	(	struct ltrx_http_client_request *	handle,
		struct input_stream *	istream )

Initialize an HTTP client request output method of input stream.

The input stream will feed the HTTP Client (PUT or POST) request.

The method may be ltrx_httpc_request_set_write_buffer(), ltrx_httpc_request_set_write_function(), or ltrx_httpc_request_set_write_stream(), but only one of them.

Returns

enum ltrx_httpc_return_code

Parameters

handle	[in,out] HTTP client request handle.
istream	[in,out] The input stream that will feed request.

ltrx_httpc_strerror()

const char * ltrx_httpc_strerror

(

enum ltrx_httpc_return_code

error

)

Convert error code to text.

Returns

Error message as text.

Parameters

[in]

error

Error code to be converted to text.

ltrx_input_stream_init_from_httpc_request()

bool ltrx_input_stream_init_from_httpc_request	(	struct input_stream_from_httpc_request *	istream,
		struct ltrx_http_client_request *	handle )

Initialize an HTTP client request input stream struct.

The input stream will be fed the response to the HTTP Client request.

Return values

true	Success.
false	Failure.

Parameters

[out]	istream	Stream struct to be initialized.
	handle	[in,out] HTTP client request handle.

ltrx_output_stream_init_to_httpc_request()

bool ltrx_output_stream_init_to_httpc_request	(	struct output_stream_to_httpc_request *	ostream,
		struct ltrx_http_client_request *	handle )

Initialize an HTTP client request output stream struct.

The output stream will feed the HTTP Client (PUT or POST) request, but must be set up via ltrx_httpc_request_set_write_stream.

Return values

true	Success.
false	Failure.

Parameters

[out]	ostream	Stream struct to be initialized.
	handle	[in,out] HTTP client request handle.