HTTPC
Ameba SDK » Network

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