HTTP client (HyperText Transfer Protocol) More...

#include <limits.h>
#include <stdarg.h>
#include "core/net.h"
#include "http/http_client.h"
#include "http/http_client_auth.h"
#include "http/http_client_transport.h"
#include "http/http_client_misc.h"
#include "str.h"
#include "debug.h"

Macros
#define	TRACE_LEVEL HTTP_TRACE_LEVEL

Functions
error_t	httpClientInit (HttpClientContext *context)
	Initialize HTTP client context. More...

error_t	httpClientRegisterTlsInitCallback (HttpClientContext context, HttpClientTlsInitCallback callback, void param)
	Register TLS initialization callback function. More...

error_t	httpClientRegisterRandCallback (HttpClientContext *context, HttpClientRandCallback callback)
	Register random data generation callback function. More...

error_t	httpClientSetVersion (HttpClientContext *context, HttpVersion version)
	Set the HTTP protocol version to be used. More...

error_t	httpClientSetTimeout (HttpClientContext *context, systime_t timeout)
	Set communication timeout. More...

error_t	httpClientSetAllowedAuthModes (HttpClientContext *context, uint_t allowedAuthModes)
	Set allowed HTTP authentication modes. More...

error_t	httpClientSetAuthInfo (HttpClientContext context, const char_t username, const char_t *password)
	Set authentication information. More...

error_t	httpClientBindToInterface (HttpClientContext context, NetInterface interface)
	Bind the HTTP client to a particular network interface. More...

error_t	httpClientConnect (HttpClientContext context, const IpAddr serverIpAddr, uint16_t serverPort)
	Establish a connection with the specified HTTP server. More...

error_t	httpClientCreateRequest (HttpClientContext *context)
	Create a new HTTP request. More...

error_t	httpClientSetMethod (HttpClientContext context, const char_t method)
	Set HTTP request method. More...

error_t	httpClientSetUri (HttpClientContext context, const char_t uri)
	Set request URI. More...

error_t	httpClientSetHost (HttpClientContext context, const char_t host, uint16_t port)
	Set the hostname and port number of the resource being requested. More...

error_t	httpClientSetQueryString (HttpClientContext context, const char_t queryString)
	Set query string. More...

error_t	httpClientAddQueryParam (HttpClientContext context, const char_t name, const char_t *value)
	Add a key/value pair to the query string. More...

error_t	httpClientAddHeaderField (HttpClientContext context, const char_t name, const char_t *value)
	Add a header field to the HTTP request. More...

error_t	httpClientFormatHeaderField (HttpClientContext context, const char_t name, const char_t *format,...)
	Format an HTTP header field. More...

error_t	httpClientSetContentLength (HttpClientContext *context, size_t length)
	Set the length of the HTTP request body. More...

error_t	httpClientWriteHeader (HttpClientContext *context)
	Write HTTP request header. More...

error_t	httpClientWriteBody (HttpClientContext context, const void data, size_t length, size_t *written, uint_t flags)
	Write HTTP request body. More...

error_t	httpClientWriteTrailer (HttpClientContext *context)
	Write HTTP trailer. More...

error_t	httpClientReadHeader (HttpClientContext *context)
	Read HTTP response header. More...

uint_t	httpClientGetStatus (HttpClientContext *context)
	Retrieve the HTTP status code of the response. More...

const char_t *	httpClientGetHeaderField (HttpClientContext context, const char_t name)
	Retrieve the value of the specified header field name. More...

error_t	httpClientGetNextHeaderField (HttpClientContext context, const char_t name, const char_t *value)
	Iterate through the HTTP response header. More...

error_t	httpClientReadBody (HttpClientContext context, void data, size_t size, size_t *received, uint_t flags)
	Read HTTP response body. More...

error_t	httpClientReadTrailer (HttpClientContext *context)
	Read HTTP trailer. More...

error_t	httpClientCloseBody (HttpClientContext *context)
	Close HTTP request or response body. More...

error_t	httpClientDisconnect (HttpClientContext *context)
	Gracefully disconnect from the HTTP server. More...

error_t	httpClientClose (HttpClientContext *context)
	Close the connection with the HTTP server. More...

void	httpClientDeinit (HttpClientContext *context)
	Release HTTP client context. More...

Detailed Description

HTTP client (HyperText Transfer Protocol)

License

SPDX-License-Identifier: GPL-2.0-or-later

This file is part of CycloneTCP Open.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Description

The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypermedia information systems. Refer to the following RFCs for complete details:

RFC 1945: Hypertext Transfer Protocol - HTTP/1.0
RFC 2616: Hypertext Transfer Protocol - HTTP/1.1
RFC 2818: HTTP Over TLS
RFC 7230: Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing
RFC 7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content

Author: Oryx Embedded SARL (www.oryx-embedded.com)

Version: 2.5.4

Definition in file http_client.c.

Macro Definition Documentation

◆ TRACE_LEVEL

#define TRACE_LEVEL HTTP_TRACE_LEVEL

Definition at line 43 of file http_client.c.

Function Documentation

◆ httpClientAddHeaderField()

error_t httpClientAddHeaderField	(	HttpClientContext *	context,
		const char_t *	name,
		const char_t *	value
	)

Add a header field to the HTTP request.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	name	NULL-terminated string that holds the header field name
[in]	value	NULL-terminated string that holds the header field value

Returns: Error code

Definition at line 859 of file http_client.c.

◆ httpClientAddQueryParam()

error_t httpClientAddQueryParam	(	HttpClientContext *	context,
		const char_t *	name,
		const char_t *	value
	)

Add a key/value pair to the query string.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	name	NULL-terminated string that holds the parameter name
[in]	value	NULL-terminated string that holds the parameter value

Returns: Error code

Definition at line 742 of file http_client.c.

◆ httpClientBindToInterface()

error_t httpClientBindToInterface	(	HttpClientContext *	context,
		NetInterface *	interface
	)

Bind the HTTP client to a particular network interface.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	interface	Network interface to be used

Returns: Error code

Definition at line 297 of file http_client.c.

◆ httpClientClose()

error_t httpClientClose ( HttpClientContext * context )

Close the connection with the HTTP server.

Parameters

[in] context Pointer to the HTTP client context

Returns: Error code

Definition at line 2277 of file http_client.c.

◆ httpClientCloseBody()

error_t httpClientCloseBody ( HttpClientContext * context )

Close HTTP request or response body.

Parameters

[in] context Pointer to the HTTP client context

Returns: Error code

Definition at line 2065 of file http_client.c.

◆ httpClientConnect()

error_t httpClientConnect	(	HttpClientContext *	context,
		const IpAddr *	serverIpAddr,
		uint16_t	serverPort
	)

Establish a connection with the specified HTTP server.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	serverIpAddr	IP address of the HTTP server to connect to
[in]	serverPort	Port number

Returns: Error code

Definition at line 320 of file http_client.c.

◆ httpClientCreateRequest()

error_t httpClientCreateRequest ( HttpClientContext * context )

Create a new HTTP request.

Parameters

[in] context Pointer to the HTTP client context

Returns: Error code

Definition at line 416 of file http_client.c.

◆ httpClientDeinit()

void httpClientDeinit ( HttpClientContext * context )

Release HTTP client context.

Parameters

[in] context Pointer to the HTTP client context

Definition at line 2298 of file http_client.c.

◆ httpClientDisconnect()

error_t httpClientDisconnect ( HttpClientContext * context )

Gracefully disconnect from the HTTP server.

Parameters

[in] context Pointer to the HTTP client context

Returns: Error code

Definition at line 2202 of file http_client.c.

◆ httpClientFormatHeaderField()

error_t httpClientFormatHeaderField	(	HttpClientContext *	context,
		const char_t *	name,
		const char_t *	format,
			...
	)

Format an HTTP header field.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	name	NULL-terminated string that holds the header field name
[in]	format	NULL-terminated string that that contains a format string
[in]	...	Optional arguments

Returns: Error code

Definition at line 941 of file http_client.c.

◆ httpClientGetHeaderField()

const char_t* httpClientGetHeaderField	(	HttpClientContext *	context,
		const char_t *	name
	)

Retrieve the value of the specified header field name.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	name	NULL-terminated string that specifies the header field name

Returns: Value of the header field

Definition at line 1592 of file http_client.c.

◆ httpClientGetNextHeaderField()

error_t httpClientGetNextHeaderField	(	HttpClientContext *	context,
		const char_t **	name,
		const char_t **	value
	)

Iterate through the HTTP response header.

Parameters

[in]	context	Pointer to the HTTP client context
[out]	name	NULL-terminated string that contains the name of the next header field
[out]	value	NULL-terminated string that contains the value of the next header field

Returns: Error code

Definition at line 1651 of file http_client.c.

◆ httpClientGetStatus()

uint_t httpClientGetStatus ( HttpClientContext * context )

Retrieve the HTTP status code of the response.

Parameters

[in] context Pointer to the HTTP client context

Returns: HTTP status code

Definition at line 1565 of file http_client.c.

◆ httpClientInit()

error_t httpClientInit ( HttpClientContext * context )

Initialize HTTP client context.

Parameters

[in] context Pointer to the HTTP client context

Returns: Error code

Definition at line 66 of file http_client.c.

◆ httpClientReadBody()

error_t httpClientReadBody	(	HttpClientContext *	context,
		void *	data,
		size_t	size,
		size_t *	received,
		uint_t	flags
	)

Read HTTP response body.

Parameters

[in]	context	Pointer to the HTTP client context
[out]	data	Buffer where to store the incoming data
[in]	size	Maximum number of bytes that can be received
[out]	received	Number of bytes that have been received
[in]	flags	Set of flags that influences the behavior of this function

Returns: Error code

Definition at line 1699 of file http_client.c.

◆ httpClientReadHeader()

error_t httpClientReadHeader ( HttpClientContext * context )

Read HTTP response header.

Parameters

[in] context Pointer to the HTTP client context

Returns: Error code

Definition at line 1425 of file http_client.c.

◆ httpClientReadTrailer()

error_t httpClientReadTrailer ( HttpClientContext * context )

Read HTTP trailer.

Parameters

[in] context Pointer to the HTTP client context

Returns: Error code

Definition at line 1937 of file http_client.c.

◆ httpClientRegisterRandCallback()

error_t httpClientRegisterRandCallback	(	HttpClientContext *	context,
		HttpClientRandCallback	callback
	)

Register random data generation callback function.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	callback	Random data generation callback function

Returns: Error code

Definition at line 144 of file http_client.c.

◆ httpClientRegisterTlsInitCallback()

error_t httpClientRegisterTlsInitCallback	(	HttpClientContext *	context,
		HttpClientTlsInitCallback	callback,
		void *	param
	)

Register TLS initialization callback function.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	callback	TLS initialization callback function
[in]	param	An opaque pointer passed to the callback function

Returns: Error code

Definition at line 118 of file http_client.c.

◆ httpClientSetAllowedAuthModes()

error_t httpClientSetAllowedAuthModes	(	HttpClientContext *	context,
		uint_t	allowedAuthModes
	)

Set allowed HTTP authentication modes.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	allowedAuthModes	Logic OR of allowed HTTP authentication schemes

Returns: Error code

Definition at line 218 of file http_client.c.

◆ httpClientSetAuthInfo()

error_t httpClientSetAuthInfo	(	HttpClientContext *	context,
		const char_t *	username,
		const char_t *	password
	)

Set authentication information.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	username	NULL-terminated string containing the user name to be used
[in]	password	NULL-terminated string containing the password to be used

Returns: Error code

Definition at line 253 of file http_client.c.

◆ httpClientSetContentLength()

error_t httpClientSetContentLength	(	HttpClientContext *	context,
		size_t	length
	)

Set the length of the HTTP request body.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	length	Length of the HTTP request body, in bytes

Returns: Error code

Definition at line 1038 of file http_client.c.

◆ httpClientSetHost()

error_t httpClientSetHost	(	HttpClientContext *	context,
		const char_t *	host,
		uint16_t	port
	)

Set the hostname and port number of the resource being requested.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	host	NULL-terminated string containing the hostname
[in]	port	TCP port number

Returns: Error code

Definition at line 584 of file http_client.c.

◆ httpClientSetMethod()

error_t httpClientSetMethod	(	HttpClientContext *	context,
		const char_t *	method
	)

Set HTTP request method.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	method	NULL-terminating string containing the HTTP method

Returns: Error code

Definition at line 453 of file http_client.c.

◆ httpClientSetQueryString()

error_t httpClientSetQueryString	(	HttpClientContext *	context,
		const char_t *	queryString
	)

Set query string.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	queryString	NULL-terminated string that contains the query string

Returns: Error code

Definition at line 645 of file http_client.c.

◆ httpClientSetTimeout()

error_t httpClientSetTimeout	(	HttpClientContext *	context,
		systime_t	timeout
	)

Set communication timeout.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	timeout	Timeout value, in milliseconds

Returns: Error code

Definition at line 196 of file http_client.c.

◆ httpClientSetUri()

error_t httpClientSetUri	(	HttpClientContext *	context,
		const char_t *	uri
	)

Set request URI.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	uri	NULL-terminated string that contains the resource name

Returns: Error code

Definition at line 513 of file http_client.c.

◆ httpClientSetVersion()

error_t httpClientSetVersion	(	HttpClientContext *	context,
		HttpVersion	version
	)

Set the HTTP protocol version to be used.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	version	HTTP protocol version (1.0 or 1.1)

Returns: Error code

Definition at line 171 of file http_client.c.

◆ httpClientWriteBody()

error_t httpClientWriteBody	(	HttpClientContext *	context,
		const void *	data,
		size_t	length,
		size_t *	written,
		uint_t	flags
	)

Write HTTP request body.

Parameters

[in]	context	Pointer to the HTTP client context
[in]	data	Pointer to the buffer containing the data to be transmitted
[in]	length	Number of data bytes to send
[out]	written	Actual number of bytes written (optional parameter)
[in]	flags	Set of flags that influences the behavior of this function

Returns: Error code

Definition at line 1188 of file http_client.c.

◆ httpClientWriteHeader()

error_t httpClientWriteHeader ( HttpClientContext * context )

Write HTTP request header.

Parameters

[in] context Pointer to the HTTP client context

Returns: Error code

Definition at line 1065 of file http_client.c.

◆ httpClientWriteTrailer()

error_t httpClientWriteTrailer ( HttpClientContext * context )

Write HTTP trailer.

Parameters

[in] context Pointer to the HTTP client context

Returns: Error code

Definition at line 1346 of file http_client.c.

Macros

Functions

Detailed Description

License

Description

Macro Definition Documentation

◆ TRACE_LEVEL

Function Documentation

◆ httpClientAddHeaderField()

◆ httpClientAddQueryParam()

◆ httpClientBindToInterface()

◆ httpClientClose()

◆ httpClientCloseBody()

◆ httpClientConnect()

◆ httpClientCreateRequest()

◆ httpClientDeinit()

◆ httpClientDisconnect()

◆ httpClientFormatHeaderField()

◆ httpClientGetHeaderField()

◆ httpClientGetNextHeaderField()

◆ httpClientGetStatus()

◆ httpClientInit()

◆ httpClientReadBody()

◆ httpClientReadHeader()

◆ httpClientReadTrailer()

◆ httpClientRegisterRandCallback()

◆ httpClientRegisterTlsInitCallback()

◆ httpClientSetAllowedAuthModes()

◆ httpClientSetAuthInfo()

◆ httpClientSetContentLength()

◆ httpClientSetHost()

◆ httpClientSetMethod()

◆ httpClientSetQueryString()

◆ httpClientSetTimeout()

◆ httpClientSetUri()

◆ httpClientSetVersion()

◆ httpClientWriteBody()

◆ httpClientWriteHeader()

◆ httpClientWriteTrailer()