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 }
	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. More...

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. More...

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. More...

enum ltrx_httpc_return_code	ltrx_httpc_request_clear (struct ltrx_http_client_request *handle)
	Clear an HTTP client request. More...

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. More...

struct ltrx_http_client_request *	ltrx_httpc_request_create (enum ltrx_httpc_method method)
	Create an HTTP client handle. More...

void	ltrx_httpc_request_destroy (struct ltrx_http_client_request *handle)
	Destroy an HTTP client request. More...

enum ltrx_httpc_return_code	ltrx_httpc_request_disconnect (struct ltrx_http_client_request *handle)
	HTTP client request execute disconnect. More...

enum ltrx_httpc_return_code	ltrx_httpc_request_execute (struct ltrx_http_client_request *handle)
	HTTP client request execute connect, send, receive, and disconnect. More...

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. More...

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. More...

enum ltrx_httpc_return_code	ltrx_httpc_request_receive (struct ltrx_http_client_request *handle)
	HTTP client request execute receive. More...

enum ltrx_httpc_return_code	ltrx_httpc_request_send_content (struct ltrx_http_client_request *handle)
	HTTP client request execute send content. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

const char *	ltrx_httpc_strerror (enum ltrx_httpc_return_code error)
	Convert error code to text. More...

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. More...

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. More...

Detailed Description

HTTP Client.

Enumeration Type Documentation

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.

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

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

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

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

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

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

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

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

[in,out] handle HTTP client request handle.

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

[in,out] handle HTTP client request handle.

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.

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

[in,out] handle HTTP client request handle.

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

[in,out] handle HTTP client request handle.

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

[in,out] handle HTTP client request handle.

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

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

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

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

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

[in,out] handle HTTP client request handle.

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

[in,out] handle HTTP client request handle.

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

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

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

[in,out]	handle	HTTP client request handle.
[in]	info	HTTP client 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.

Returns: enum ltrx_httpc_return_code

Parameters

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

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

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

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

[in,out]	handle	HTTP client request handle.
[in]	method	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.

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

[in,out]	handle	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.

enum ltrx_httpc_return_code ltrx_httpc_request_set_response_callback	(	struct ltrx_http_client_request *	handle,
		bool()(struct ltrx_http_client_request handle, void opaque, const void data, size_t size)	callback,
		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

[in,out]	handle	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.

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

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

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

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

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

[in,out]	handle	HTTP client request handle.
[in]	credentialName	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.

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

[in,out]	handle	HTTP client request handle.
[in]	userAgent	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.

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

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

enum ltrx_httpc_return_code ltrx_httpc_request_set_write_function	(	struct ltrx_http_client_request *	handle,
		void()(const uint8_t datap, size_t sizep, void *opaque)	write_callback,
		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

[in,out]	handle	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.

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

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

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.

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.
[in,out]	handle	HTTP client request handle.

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.
[in,out]	handle	HTTP client request handle.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation