NAME

REST Client

SYNOPSIS

#include <rest.h>

int rest_request (struct rest_param *param, int connect_timeout_ms, int total_timeout_ms);

DESCRIPTION

The REST client component allows user to sent requests to REST server and receive responses from it. Structure param is used for control requests and responses. Value connect_timeout_ms set maximum connect time to remote server (in milliseconds). Value total_timeout_ms set total time limit for connect to remote server, send request and receive answer from it (in milliseconds).

struct rest_param {

	/*
	 * remote host information
	 */
	const char      *host_name;
	const char      *host_ipaddr;
	int             host_port;

	/*
	 * request header
	 */
	const char      *http_method;
	const char      *request_uri;

	/*
	 * request body
	 */
	const char      *content_type;
	const char      *charset;
	const char      *body;
	int             body_len;

	/*
	 * SSL/TLS setup user function
	 */
	int (*set_ssl_ctx) (SSL_CTX *ssl_ctx);

	/*
	 * answer
	 */
	char        *answer_status;
	char        *answer_type;
	char        *answer_body;
	int         answer_len;
};

Structure fields description

Remote host information:

  host_name

Remote REST server name.

  host_ipaddr

Remote REST server IPv4 or IPv6 address.

  host_port

Remote REST server port.

Request header

:

  http_method

REST request to remote server: “GET”, “POST”, “PUT”, “DELETE” or “HEAD”.

  request_uri

Requested URI at remote server.

Request body

:

  content_type

Type of request content. See IANA Media Types.

  charset

Character set of request content. See IANA Character Sets.

  body

Pointer to body content for request.

  body_len

Body content length.

These fields uses only for requests “POST”, “PUT”, and “DELETE”. If these requests do not require body transfer then field

body_len

must be zero. For others requests these fields are ignored.

SSL/TLS setup user function

:

  set_ssl_ctx

User callback function that will be called from REST client when it need to setup SSL/TLS parameters: key, certificates and etc.

If this pointer equal to NULL, REST client will do non-secure request.

Answer

:

  answer_status

REST server answer status. See IANA HTTP Status Codes. Should be freed by user.

  answer_type

Type of answer content. See IANA Media Types and IANA Character Sets. Should be freed by user.

  answer_body

Pointer to body content for answer. Should be freed by user.

  answer_len

Body content length.

Note: for some errors

answer_status

can be filled.

ERRORS

REST_OK

No errors.

REST_ENOMEM

Not enough memory – can’t make malloc().

REST_ADDR_ERROR

Remote host error address.

REST_GENERAL_TCP_ERROR

Errors with TCP socket.

REST_HOST_NOT_ANSWER

Can’t connect to remote host (network down, connection rejected and etc).

REST_SSL_ERROR

SSL/TLS errors.

REST_ERROR_DATA_SEND

Error during data sending to remote server.

REST_ERROR_ANSWER

Error during data receiving from remote server.

REST_TIMEOUT_CONNECT

Connect timeout expired.

REST_TIMEOUT_TOTAL

Total timeout expired.

EXAMPLE

This example shows how to send request to REST server and process answer from it.

. . .
	int ret;
	struct rest_param param;
	memset(&param, 0, sizeof(param));

	param.host_name = "Unison HTTP server";
	param.host_ipaddr = "192.168.16.200";
	param.host_port = 80;
	param.set_ssl_ctx = NULL;

	param.http_method = "GET";
	param.request_uri = "/rest/users/1";


	ret = rest_request(&param, 1000, 3000);
	if (ret != REST_OK)
	{
		xprintf("GET error %d\n", ret);
		if (param.answer_status)
		{
			xprintf("Answer status: %s\n", param.answer_status);
			free(param.answer_status);
		}
	}
	else
	{
		int i;
		xprintf("Answer:\n");
		xprintf("status: %s\n", param.answer_status);
		xprintf("type: %s\n", param.answer_type);
		xprintf("len: %d\n", param.answer_len);
		xprintf("------------------------------\n");
		for (i=0; i < param.answer_len; i++)
			xputchar(param.answer_body[i]);
		xprintf("\n------------------------------\n");
		free(param.answer_status);
		free(param.answer_type);
		free(param.answer_body);
	}
. . .

NOTES

There is demo available for the Unison and DSPnano REST Client which can be found in installdir/demos.

SEE ALSO

tcpd, tcpd_dual