NAME

HTTP/HTTPS Client

SYNOPSIS

#include <thttpc.h>

int http_client_get (http_get_param *http_param, char *result);

int http_client_post (http_post_param *http_param, int connect_timeout_ms, int total_timeout_ms, int *httpreturncode, char *response_data, int response_max_length);

int https_client_get (http_get_param *http_param, char *result);

DESCRIPTION

HTTP/HTTPS client component allows user to use general commands for downloading and uploading files (HTTS only downloading). This is a HTTP GET and HTTP POST commands. The functions which realize that commands are represented below.

Functions description:

• • http_client_get – this fuction “gets” the separate file from HTTP server.
  • https_client_get – this fuction “gets” the separate file from HTTPS server using SSL/TLS protocols.

Parameters:

• • • http_param – setup structure containing necessary settings for remote HTTP server.
    • result – pointer to space where function places resulting error code.

Possible error codes in result parameter:

HTTPC_ENOMEM

Returned if there is no free memory for the operation.

HTTPC_GENERAL_TCP_ERROR

Returned if TCP server error occurred.

HTTPC_HOST_NOT_ANSWER

Returned if host did not answered during the timeout period.

HTTPC_FILE_NOT_FOUND

Returned if file not found on the HTTP server.

HTTPC_DOWNLOAD_SIZE_ERROR

Returned if size of downloaded file differs from what we was waiting.

HTTPC_ERROR_FILE_WRITE

Returned if an error in write to file occurred.

HTTPC_TIMEOUT_DOWNLOAD

Returned if select() results in timeout.

“GET” setup structure:

typedef struct {
	const char	*host_name;
	const char	*host_ipaddr;
	const char	*host_path_file;
	int		host_port;			
	int		fd;
	int		max_file_size;
} http_get_param;

typedef struct {
	const char 	*host_name;
	const char 	*host_ipaddr;
	const char 	*host_path_file;
	SSL_params  SSL_param;
	int 	host_port;			
	int		fd;
	int		max_file_size;
} https_get_param;

typedef struct {
#ifndef SSL_CERT_FMT_NONE
	#define	SSL_CERT_FMT_NONE	0
	#define	SSL_CERT_FMT_PKCS8	1
	#define	SSL_CERT_FMT_PKCS12	2
#endif
	char	SSL_cert_format;
	union {
		struct{
			char	*SSL_sert;
			char	*SSL_key;
			char	*SSL_passwd;
		} file;
		struct {
			char	*SSL_key;
			int 	SSL_key_len;
			char	*SSL_passwd;

			char	*SSL_target_ss_cert;
			int 	SSL_target_ss_cert_len;
			char	*SSL_host_ss_cert;
			int 	SSL_host_ss_cert_len;
		} mem;
	} storage;
	enum {
		file_storage,
		memory_storage
	} storage_format;
} SSL_params;

• • http_client_post – this function “puts” the separate file onto remote HTTP server.

Parameters:

• • • http_param – setup structure containing necessary settings for remote HTTP server.
    • connect_timeout_ms – connection timeout in milliseconds.
    • total_timeout_ms – general timeout in milliseconds for POST operation.
    • httpreturncode – pointer to specific return code from HTTP server.
    • response_data – pointer to space containing responce data from server.
    • response_max_length – value of response data size.
    • SSL_param – paraeters for HTTPS client
      • SSL_cert_format – SSL certificate format
      • storage_format – way of presenting the certificate (file_storage – sertificate stored in a files on diks; memory_storage – sertificate store as array in memory)
      • SSL_sert – path to SSL sertificate file
      • SSL_key -path to SSL key file
      • SSL_passwd – path to SSL key file
      • SSL_key – pointer to SSL key array
      • SSL_key_len – size of SSL key
      • SSL_passwd – pointer to SSL password array
      • SSL_target_ss_cert – pointer to array of target SelfSigned sertificate
      • SSL_target_ss_cert_len – size of array of target SelfSigned sertificate
      • SSL_host_ss_cert – pointer to array of host SelfSigned sertificate
      • SSL_host_ss_cert_len – of array of target SelfSigned sertificate

Error codes returning by http_client_post function:

HTTPC_OK

Returned if function work finished successfully.

HTTPC_ENOMEM

Returned if there is no free memory for the operation.

HTTPC_GENERAL_TCP_ERROR

Returned if TCP server error occurred.

HTTPC_HOST_NOT_ANSWER

Returned if host did not answered during the timeout period.

HTTPC_ERROR_FILE_READ

Returned if an error in read from file occurred.

HTTPC_TIMEOUT_UPLOAD

Returned if file uploading results in timeout.

HTTPC_TIMEOUT_CONNECT

Returned if connection to server (repeatable calls of connect()) results in timeout.

HTTPC_ERROR_DATA_SEND

Returned if data send to server was unsuccessfull.

HTTPC_ERROR_ANSWER

Returned if server answered with an error.

“POST” setup structure:

typedef struct {
	const char 	*host_name;
	const char 	*host_ipaddr;
	const char 	*host_path_file;
	const char 	*file_name;
	int 		host_port;			
	int		fd;
	int		file_size;
} http_post_param;

HTTP/HTTPS Client component works together with file system components. It may be FSYS or FATFS.

SPECIFIC OPTIONS (Compile time)

EXAMPLE

Example for HTTP GET function:

	int ret;
	char result;
	http_get_param http_param;

	memset(&http_param, 0, sizeof(http_get_param));

	// Example  Download file U41-51compare.pdf from site www.rowebots.com	
	//Download Link: "http://rowebots.com/articles/U41-51compare.pdf"

	if(( http_param.fd = open(FATFS_MOUNT"/U41-51compare.pdf", O_CREAT | O_RDWR, 0)) == -1)
	{
		xprintf("files opened  errno = %d\n", errno);
	}
	lseek( http_param.fd, 0 , SEEK_SET );

	http_param.host_name		= "www.rowebots.com";			//web site URL address
	http_param.host_ipaddr		= "184.107.235.10";			//web site ip address 
	http_param.host_path_file	= "/articles/U41-51compare.pdf";	//path to file at web site 
	http_param.host_port		= 80;
	http_param.max_file_size	= -1;					//max file size in bytes, which could be written.
										//value = -1, mean do not control size.

	xprintf("Start download file U41-51compare.pdf\n");
	/*************************************/
	/* HTTP Client GET */
	/*************************************/
	if((ret = http_client_get(&http_param, &result))< 0)
	{
		xprintf("Error http_client_get\n");
		switch(result)
		{
			case HTTPC_ENOMEM:
				xprintf("Not free memory\n");
			break;
			case HTTPC_GENERAL_TCP_ERROR:
				xprintf("TCP server error\n");
			break;
			case HTTPC_HOST_NOT_ANSWER:
				xprintf("Host not answer\n");
			break;
			case HTTPC_FILE_NOT_FOUND:
				xprintf("File not found on server\n");
			break;
			case HTTPC_ERROR_FILE_WRITE:
				xprintf("Error write to file\n");
			break;
		}
	}
	else
	{
		xprintf("File download! Size download file = %d\n",ret);
	}

	xprintf("File Closed\n");
	close(http_param.fd);

...

Example for HTTPS GET function:

	int ret;
	char result;
	http_get_param http_param;

	memset(&http_param, 0, sizeof(http_get_param));

	// Example  Download root HTML file from site wiki.com
	//Download Link: "http://wiki.com/"

	if(( http_param.fd = open("/dev/sd/index.html", O_CREAT | O_RDWR, 0)) == -1)
	{
		xprintf("files opened  errno = %d\n", errno);
	}
	lseek( http_param.fd, 0 , SEEK_SET );

	http_param.host_name		= "wiki.com";				//web site URL address
	http_param.host_ipaddr		= "66.96.160.149";					//web site ip address 
	http_param.host_path_file	= "/";	//path to file at web site 

	http_param.host_port		= 443;
	http_param.max_file_size	= -1;								//max file size in bytes, which could be written.
																	//value = -1, mean do not control size.
	http_param.SSL_param.SSL_cert_format = SSL_CERT_FMT_NONE;
	http_param.SSL_param.storage_format = memory_storage;
		
	http_param.SSL_param.storage.mem.SSL_key = (char *)target_key;
	http_param.SSL_param.storage.mem.SSL_key_len = sizeof(target_key);
	http_param.SSL_param.storage.mem.SSL_passwd = NULL;

	http_param.SSL_param.storage.mem.SSL_target_ss_cert = (char *)target_ss_cert;
	http_param.SSL_param.storage.mem.SSL_target_ss_cert_len = sizeof(target_ss_cert);
	http_param.SSL_param.storage.mem.SSL_host_ss_cert = (char *)host_ss_cert;
	http_param.SSL_param.storage.mem.SSL_host_ss_cert_len = sizeof(host_ss_cert);	
    
	xprintf("Start download file from https:/wiki.com/ \n");
	/*************************************/
	/* HTTPS Client GET */
	/*************************************/
	if((ret = https_client_get(&http_param, &result))< 0)
	{
		xprintf("Error http_client_get\n");
		switch(result)
		{
			case HTTPC_ENOMEM:
				xprintf("Not free memory\n");
			break;
			case HTTPC_GENERAL_TCP_ERROR:
				xprintf("TCP server error\n");
			break;
			case HTTPC_HOST_NOT_ANSWER:
				xprintf("Host not answer\n");
			break;
			case HTTPC_FILE_NOT_FOUND:
				xprintf("File not found on server\n");
			break;
			case HTTPC_ERROR_FILE_WRITE:
				xprintf("Error write to file\n");
			break;
		}
	}
	else
	{
		xprintf("File download! Size download file = %d\n",ret);
	}

	xprintf("File Closed\n");
	close(http_param.fd);

...

Example for HTTP POST function:

	int ret;
	http_post_param http_param;

	memset(&http_param, 0, sizeof(http_post_param));

	if(( http_param.fd = open(FATFS_MOUNT"/test.zip",O_RDONLY, 0)) == -1)
	{
		xprintf("Error: Files not found on SD(CF) or Error FAT-FS \n", errno);
		return;
	}

	http_param.file_size		= lseek(http_param.fd, 0, SEEK_END);
	// The offset is set 0
	lseek(http_param.fd, 0 , SEEK_SET );

	http_param.file_name		= "test.zip";			//file name to write to web server
	http_param.host_name		= "rowebots.com";		//web site URL address
	http_param.host_ipaddr		= "184.107.235.10";		//web site ip address
	http_param.host_path_file	= "/testing/uploadtest.php";	//path to file at web
	http_param.host_port		= 80;

	xprintf("Post to server =%s, file =%s\n",http_param.host_name,http_param.file_name);
	xprintf("file size =%d\n",http_param.file_size);

	/*************************************/
	/* HTTP Client Post */
	/*************************************/
	if((ret = http_client_post(&http_param,
			150000, // Timeout connect 4000 ms
			200000, // Total timeout 6000 ms
			NULL, NULL, 0 ))!= 0)
	{
		xprintf("Error http_client_post ret=%d\n",ret);
		switch(ret)
		{
			case HTTPC_ENOMEM:
				xprintf("Not free memory\n");
			break;
			case HTTPC_GENERAL_TCP_ERROR:
				xprintf("TCP server error\n");
			break;
			case HTTPC_HOST_NOT_ANSWER:
				xprintf("Host not answer\n");
			break;
			case HTTPC_ERROR_FILE_READ:
				xprintf("error read data from file\n");
			break;
			case HTTPC_TIMEOUT_UPLOAD:
				xprintf("TIMEOUT UPLOAD\n");
			break;
			case HTTPC_TIMEOUT_CONNECT:
				xprintf("TIMEOUT HTTPC_TIMEOUT_CONNECT\n");
			break;
		}
	}
	else
	{
		xprintf("File send Ok!\n");
	}

	close(http_param.fd);

...

NOTES

There are two demos available for the Unison and DSPnano HTTP Client which can be found in installdir/demos.

SEE ALSO

tcpd, tcpd_dual, fsys, fatfs, autoip