HTTP Client

HTTP Client library.

Example Usage

#include <proto/httpc.h>

struct httparg_t arg;
char buffer[256];
int ret;

memset(&arg, 0, sizeof(arg));
memset(response, 0, sizeof(buffer));
/* set URL to access */
arg.url = "http://example.com";
/* a custom header example, must end with \r\n */
arg.headers = "custom-header: some_value\r\n";
/* certificates when using SSL */
arg.certs = NULL;
/* receive headers not needed in response */
arg.recv_headers = 0;
/* set size of response buffer */
arg.buflen = sizeof(buffer);
/* set response buffer pointer */
arg.resp_buffer = bufer;

/* run request */
ret = httpc_submit(HTTP_CLIENT_DEFAULT, "GET", &arg);
printf("HTTP GET request failed: %d\n", ret);
if (!ret) {
    printf("HTTP response (%d bytes): %s\n\n", arg.buflen, buffer);
}

API Reference

Header File

Source: include/proto/httpc.h

#include <proto/httpc.h>

Functions

int httpc_client_open(void)

Open a new client

Returns:: On success, returns handle to http client, negative value on error

int httpc_client_close(int client)

Close a client

Parameters:: client – [in] Client handle
Returns:: 0 on success, negative value on error

int httpc_submit(int client, const char *method, struct httparg_t *arg)

Perform HTTP Request

Parameters:

client – [in] Client handle
method – [in] HTTP Method e.g. “GET”, “POST”, “PUT” etc.
arg – [in] HTTP client argument httparg_t

Returns:

0 on success, If server response is not 2xx then server error code is returned, if any operation issue negative error code will be returned

int httpc_upload(int client, struct httpupload_t *arg)

HTTP file upload. This function will perform a POST with “multipart/form-data” mime on the provided URL. Its a special case of httpc_submit()

Parameters:

client – [in] Client handle
arg – [in] HTTP Upload request information struction httpupload_t

Returns:

0 on success, If server response is not 2xx then server error code is returned, if any operation issue negative error code will be returned

int httpc_download(int client, struct httpdownload_t *arg)

HTTP file download to local storage

Parameters:

client – [in] Client handle
arg – [in] HTTP download request information struction httpdownload_t

Returns:

0 on success, If server response is not 2xx then server error code is returned, if any operation issue negative error code will be returned

int httpclient_set_keepalive(int client, int enable)

Enable or disable HTTP client keep-alive function. Keep-alive is enabled by default. If server returns a “connection: close” response then socket will be closed after execution

Parameters:

client – [in] Client handle
enable – [in] TRUE or FALSE to enable or disable respectively.

Returns:

0 on success, negative value on error

int httpclient_get_keepalive(int client)

Get current HTTP client keep-alive configuration

Parameters:: client – [in] Client handle
Returns:: On success, configuration value is returned, negative value on error

int urlencode(const unsigned char *in_buf, char *enc)

HTTP URL Encode data. Please make sure output buffer is enough to store encoded data

Parameters:

in_buf – [in] Data to encode
enc – [out] Buffer to store encoded Data

Returns:

0 on success

int urldecode(const char *in_buf, char *dec)

HTTP URL Decode data. Please make sure output buffer is enough to store decoded data

Parameters:

in_buf – [in] Input buffer containing encoded data
dec – [out] Buffere to store decoded data

Returns:

On success length of data stored in output buffer, negative value on error

Structures

struct http_filemeta_t

HTTP File Upload information structure

Public Members

const char *filename: File name (63 char max) to be uploaded with

const char *filepath: Complete file path on storage media (255 max)

time_t timestamp: UNIX timestamp to send to server

const char *info: Other supplementary Info e.g. location info etc, This information is sent to server with HTTP form key “info” (127 max)

uint8_t mime_type: MIME type to upload http_mimetype_e for more information

const char *mime: File mime type when mime_type is set to HTTP_MIME_TYPE_CUSTOM, e.g. “text/csv”, NULL otherwise

struct http_certs_t

SSL client certificates

Public Members

const char *rootca: buffer containing Root CA

int rootca_len: Length of Root CA buffer (with null)

const char *cert: buffer containing certificate

int cert_len: Length of certificate buffer (with null)

const char *privatekey: buffer containing private key

int privatekey_len: Length of private key buffer (with null)

struct httparg_t

HTTP Client request argument

Public Members

const char *url: Client URL

const char *headers: Custom headers, can be NULL. if used then header must end with CRLF (\r\n)

struct http_certs_t *certs: SSL Client certificate

const void *submit_data: Data to send as request body

uint16_t submit_len: Length of data to send

uint8_t mime: MIME type http_mimetype_e

uint8_t recv_headers: if TRUE, HTTP response headers are also stored in response buffer

char *resp_buffer: Pointer to response buffer

uint16_t buflen: Length of response buffer

uint16_t timeout: Timeout in seconds for Read/Write in HTTP and READ in HTTPS, 0 for default 45 sec

struct httpupload_t

HTTP Client upload argument

Public Members

const char *url: Client URL

const char *headers: Custom headers, can be NULL. if used then header must end with CRLF (\r\n)

const struct http_filemeta_t *meta: Upload file information http_filemeta_t

const struct http_certs_t *certs: SSL Client certificates

int recv_headers: if TRUE, HTTP response headers are also stored in response buffer

char *resp_buffer: Pointer to response buffer

uint16_t buflen: Length of response buffer

uint16_t timeout: Timeout in seconds for Read/Write in HTTP and READ in HTTPS, 0 for default 45 sec

struct httpdownload_t

HTTP Client download argument

Public Members

const char *url: Client URL

const char *headers: Custom headers, can be NULL. if used then header must end with CRLF (\r\n)

const char *filepath: Complete file path on storage media (255 max)

const struct http_certs_t *certs: SSL Client certificates

http_download_cb callback: Callback function called after download is finished see http_download_cb

uint16_t timeout: Timeout in seconds for Read/Write in HTTP and READ in HTTPS, 0 for default 45 sec

Macros

HTTP_CLIENT_DEFAULT: Default HTTP client

Type Definitions

typedef void (*http_download_cb)(unsigned int dl_size, unsigned int reserved, int error)

HTTP download finished callback

Param dl_size:: Download size
Param reserved:: reserved
Param error:: Error code if any

Enumerations

enum http_mimetype_e

HTTP supported MIME types

Values:

enumerator HTTP_MIME_TYPE_JPEG: For MIME type image/jpeg

enumerator HTTP_MIME_TYPE_PNG: For MIME type image/png

enumerator HTTP_MIME_TYPE_JSON: For MIME type application/json

enumerator HTTP_MIME_TYPE_CSV: For MIME type text/csv

enumerator HTTP_MIME_TYPE_TXT: For MIME type text/plain

enumerator HTTP_MIME_TYPE_BINARY: For MIME type application/octet-stream

enumerator HTTP_MIME_TYPE_AMR: For MIME type audio/amr

enumerator HTTP_MIME_TYPE_AAC: For MIME type audio/aac

enumerator HTTP_MIME_TYPE_WAV: For MIME type audio/wav

enumerator HTTP_MIME_TYPE_MPEG: For MIME type audio/mpeg

enumerator HTTP_MIME_TYPE_FORM: For MIME type application/x-www-form-urlencoded

enumerator HTTP_MIME_TYPE_CUSTOM: For user defined MIME type, must be supplied via custom header argument

enum httpup_status_e

HTTP Upload status

Values:

enumerator HTTPUP_STATUS_FAIL: Upload failed

enumerator HTTPUP_STATUS_SUCCESS: File uploaded success

enumerator HTTPUP_STATUS_RECVDATA: File upload response data

enumerator HTTPUP_SERVER_ERR: Upload server error