HTTP/HTTPS client functions. More...

Data Structures
struct	http_response
	The structure is the context used for HTTP response header parsing. More...

struct	httpc_conn
	The structure is the context used for connection. More...

Macros
#define	HTTPC_SECURE_NONE 0

#define	HTTPC_SECURE_TLS 1

#define	HTTPC_DEBUG_OFF 0

#define	HTTPC_DEBUG_ON 1

#define	HTTPC_DEBUG_VERBOSE 2

#define	HTTPC_TLS_POLARSSL 0

#define	HTTPC_TLS_MBEDTLS 1

Functions
struct httpc_conn *	httpc_conn_new (uint8_t secure, char client_cert, char client_key, char *ca_certs)
	This function is used to generate connection context for an HTTP/HTTPS client. More...

void	httpc_conn_free (struct httpc_conn *conn)
	This function is used to deallocate a connection context. More...

int	httpc_conn_connect (struct httpc_conn conn, char host, uint16_t port, uint32_t timeout)
	This function is used to connect to a server. More...

void	httpc_conn_close (struct httpc_conn *conn)
	This function is used to close connection from a server. More...

int	httpc_conn_setup_user_password (struct httpc_conn conn, char user, char *password)
	This function is used to setup authorization for connection. More...

void	httpc_setup_debug (uint8_t debug)
	This function is used to setup httpc debug. More...

void	httpc_free (void *ptr)
	This function is used to free memory allocated by httpc API, such as httpc_response_get_header_field(). More...

void	httpc_conn_dump_header (struct httpc_conn *conn)
	This function is used to dump the parsed HTTP header of response in connection context. More...

int	httpc_request_write_header_start (struct httpc_conn conn, char method, char resource, char content_type, size_t content_len)
	This function is used to start a HTTP request in connection. More...

int	httpc_request_write_header (struct httpc_conn conn, char name, char *value)
	This function is used to add an HTTP header field to HTTP request. More...

int	httpc_request_write_header_finish (struct httpc_conn *conn)
	This function is used to write HTTP request header data to connection. More...

int	httpc_request_write_data (struct httpc_conn conn, uint8_t data, size_t data_len)
	This function is used to write HTTP request body data to connection. More...

int	httpc_response_is_status (struct httpc_conn conn, char status)
	This function is used to check HTTP status of response in connection context. More...

int	httpc_response_read_header (struct httpc_conn *conn)
	This function is used to read HTTP header from client socket descriptor and parse content to connection context. More...

int	httpc_response_read_data (struct httpc_conn conn, uint8_t data, size_t data_len)
	This function is used to read data from HTTP/HTTPS connection. More...

int	httpc_response_get_header_field (struct httpc_conn conn, char field, char **value)
	This function is used to get a header field from HTTP header of connection context. More...

Variables
uint8_t *	header

size_t	header_len

uint8_t *	version

size_t	version_len

uint8_t *	status

size_t	status_len

uint8_t *	content_type

size_t	content_type_len

size_t	content_len

int	sock

struct http_response	response

void *	tls

uint8_t *	request_header

char *	host

uint16_t	port

char *	user_password

Detailed Description

HTTP/HTTPS client functions.

Macro Definition Documentation

#define HTTPC_DEBUG_OFF 0

Disable httpc debug log

#define HTTPC_DEBUG_ON 1

Enable httpc debug log

#define HTTPC_DEBUG_VERBOSE 2

Enable httpc verbose debug log

#define HTTPC_SECURE_NONE 0

Running with HTTP client

#define HTTPC_SECURE_TLS 1

Running with HTTPS client

#define HTTPC_TLS_MBEDTLS 1

Use mbedTLS for TLS when HTTPS

#define HTTPC_TLS_POLARSSL 0

Use PolarSSL for TLS when HTTPS

Function Documentation

void httpc_conn_close ( struct httpc_conn * conn )

This function is used to close connection from a server.

Parameters

[in] conn pointer to connection context

Returns: None

int httpc_conn_connect	(	struct httpc_conn *	conn,
		char *	host,
		uint16_t	port,
		uint32_t	timeout
	)

This function is used to connect to a server.

Parameters

[in]	conn	pointer to connection context
[in]	host	string of server host name or IP
[in]	port	service port
[in]	timeout	connection timeout in seconds

Returns: 0 : if successful; -1 : if error occurred

void httpc_conn_dump_header ( struct httpc_conn * conn )

This function is used to dump the parsed HTTP header of response in connection context.

Parameters

[in] conn pointer to connection context

Returns: None

void httpc_conn_free ( struct httpc_conn * conn )

This function is used to deallocate a connection context.

Parameters

[in] conn pointer to connection context

Returns: None

struct httpc_conn* httpc_conn_new	(	uint8_t	secure,
		char *	client_cert,
		char *	client_key,
		char *	ca_certs
	)

This function is used to generate connection context for an HTTP/HTTPS client.

Parameters

[in]	secure	security mode for HTTP or HTTPS. Must be HTTPD_SECURE_NONE, HTTPD_SECURE_TLS.
[in]	client_cert	string of client certificate if required to be verified by server.
[in]	client_key	string of client private key if required to be verified by server.
[in]	ca_certs	string including certificates in CA trusted chain if want to verify server certificate.

Returns: pointer to the generated connection context

int httpc_conn_setup_user_password	(	struct httpc_conn *	conn,
		char *	user,
		char *	password
	)

This function is used to setup authorization for connection.

Parameters

[in]	conn	pointer to connection context
[in]	user	string of user name for authorization
[in]	password	string of password for authorization

Returns: 0 : if successful; -1 : if error occurred

Note: Must be used before httpc_conn_connect() if basic authorization is used

void httpc_free ( void * ptr )

This function is used to free memory allocated by httpc API, such as httpc_response_get_header_field().

Parameters

[in] ptr pointer to memory to be deallocated

Returns: None

int httpc_request_write_data	(	struct httpc_conn *	conn,
		uint8_t *	data,
		size_t	data_len
	)

This function is used to write HTTP request body data to connection.

Parameters

[in]	conn	pointer to connection context
[in]	data	data to be written
[in]	data_len	data length

Returns: return value of lwip socket write() for HTTP and PolarSSL ssl_write() for HTTPS

int httpc_request_write_header	(	struct httpc_conn *	conn,
		char *	name,
		char *	value
	)

This function is used to add an HTTP header field to HTTP request.

Parameters

[in]	conn	pointer to connection context
[in]	name	HTTP header field name string
[in]	value	HTTP header field value

Returns: 0 : if successful; -1 : if error occurred

int httpc_request_write_header_finish ( struct httpc_conn * conn )

This function is used to write HTTP request header data to connection.

Parameters

[in] conn pointer to connection context

Returns: return value of lwip socket write() for HTTP and PolarSSL ssl_write() for HTTPS

int httpc_request_write_header_start	(	struct httpc_conn *	conn,
		char *	method,
		char *	resource,
		char *	content_type,
		size_t	content_len
	)

This function is used to start a HTTP request in connection.

Parameters

[in]	conn	pointer to connection context
[in]	method	string of HTTP method in HTTP request
[in]	resource	string including path and query string to identify a resource
[in]	content_type	string of Content-Type header field written to HTTP request. No Content-Type in HTTP request if NULL.
[in]	content_len	value of Content-Length header field written to HTTP request. No Content-Length in HTTP request if NULL.

Returns: 0 : if successful; -1 : if error occurred

int httpc_response_get_header_field	(	struct httpc_conn *	conn,
		char *	field,
		char **	value
	)

This function is used to get a header field from HTTP header of connection context.

Parameters

[in]	conn	pointer to connection context
[in]	field	header field string to search
[out]	value	search result stored in memory allocated

Returns: 0 : if found; -1 : if not found

Note: The search result memory should be free by httpc_free().

int httpc_response_is_status	(	struct httpc_conn *	conn,
		char *	status
	)

This function is used to check HTTP status of response in connection context.

Parameters

[in]	conn	pointer to connection context
[in]	status	HTTP status string to compare with

Returns: 0 : if different; 1 : if matched

int httpc_response_read_data	(	struct httpc_conn *	conn,
		uint8_t *	data,
		size_t	data_len
	)

This function is used to read data from HTTP/HTTPS connection.

Parameters

[in]	conn	pointer to connection context
[out]	data	buffer for data read
[in]	data_len	buffer length

Returns: return value of lwip socket read() for HTTP and PolarSSL ssl_read() for HTTPS

int httpc_response_read_header ( struct httpc_conn * conn )

This function is used to read HTTP header from client socket descriptor and parse content to connection context.

Parameters

[in] conn pointer to connection context

Returns: 0 : if successful; -1 : if error occurred

void httpc_setup_debug ( uint8_t debug )

This function is used to setup httpc debug.

Parameters

[in] debug flag to enable/disable httpc debug. Must be HTTPC_DEBUG_OFF, HTTPC_DEBUG_ON, HTTPC_DEBUG_VERBOSE.

Returns: None

Variable Documentation

size_t content_len

Value of Content-Length header field parsed in HTTP header string

uint8_t* content_type

Pointer to Content-Type header field in the parsed HTTP header string

size_t content_type_len

Content-Type header field data length

uint8_t* header

HTTP header string parsed in HTTP response

size_t header_len

HTTP header string length

char* host

String of server host name or IP

uint16_t port

Service port

uint8_t* request_header

Pointer to transmission buffer of HTTP request header

struct http_response response

Context for HTTP response

int sock

Client socket descriptor for connection

uint8_t* status

Pointer to HTTP status code in the parsed HTTP header string

size_t status_len

HTTP status code data length

void* tls

Context for TLS connection

char* user_password

Base64 string for HTTP basic authorization

uint8_t* version

Pointer to HTTP version in the parsed HTTP header string

size_t version_len

HTTP version data length

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

Function Documentation

Variable Documentation