1 /** 2 * @file httpclient.h 3 * http API header file. 4 * 5 * @version V1.0 6 * @date 2019-12-24 7 * Copyright (C) 2015-2020 Alibaba Group Holding Limited 8 */ 9 10 #ifndef HTTPCLIENT_H 11 #define HTTPCLIENT_H 12 13 #ifdef __cplusplus 14 extern "C" { 15 #endif 16 17 #include <stdbool.h> 18 #include <stdint.h> 19 20 /** @defgroup aos_httpclient_api http 21 * @{ 22 */ 23 24 /** @brief http requst type */ 25 typedef enum { 26 HTTP_DELETE, 27 HTTP_GET, 28 HTTP_HEAD, 29 HTTP_POST, 30 HTTP_PUT 31 } HTTP_REQUEST_TYPE; 32 33 /** @brief http error code */ 34 typedef enum { 35 HTTP_EAGAIN = 1, /**< more data to retrieved */ 36 HTTP_SUCCESS = 0, /**< operation success */ 37 HTTP_ENOBUFS = -1, /**< buffer error */ 38 HTTP_EARG = -2, /**< illegal argument */ 39 HTTP_ENOTSUPP = -3, /**< not support */ 40 HTTP_EDNS = -4, /**< DNS fail */ 41 HTTP_ECONN = -5, /**< connect fail */ 42 HTTP_ESEND = -6, /**< send packet fail */ 43 HTTP_ECLSD = -7, /**< connect closed */ 44 HTTP_ERECV = -8, /**< recv packet fail */ 45 HTTP_EPARSE = -9, /**< url parse error */ 46 HTTP_EPROTO = -10, /**< protocol error */ 47 HTTP_EUNKOWN = -11, /**< unknown error */ 48 HTTP_ETIMEOUT = -12, /**< timeout */ 49 } HTTPC_RESULT; 50 51 /** @brief This structure defines the httpclient_t structure */ 52 typedef struct { 53 int socket; /**< socket ID */ 54 int remote_port; /**< hTTP or HTTPS port */ 55 int response_code; /**< response code */ 56 char *header; /**< request custom header */ 57 char *auth_user; /**< username for basic authentication */ 58 char *auth_password; /**< password for basic authentication */ 59 bool is_http; /**< http connection? if 1, http; if 0, https */ 60 #if CONFIG_HTTP_SECURE 61 const char *server_cert; /**< server certification */ 62 const char *client_cert; /**< client certification */ 63 const char *client_pk; /**< client private key */ 64 int server_cert_len; /**< server certification lenght, server_cert buffer size */ 65 int client_cert_len; /**< client certification lenght, client_cert buffer size */ 66 int client_pk_len; /**< client private key lenght, client_pk buffer size */ 67 void *ssl; /**< ssl content */ 68 #endif 69 } httpclient_t; 70 71 /** @brief This structure defines the HTTP data structure. */ 72 typedef struct { 73 bool is_more; /**< indicates if more data needs to be retrieved. */ 74 bool is_chunked; /**< response data is encoded in portions/chunks.*/ 75 int retrieve_len; /**< content length to be retrieved. */ 76 int response_content_len; /**< response content length. */ 77 int content_block_len; /**< the content length of one block. */ 78 int post_buf_len; /**< post data length. */ 79 int response_buf_len; /**< response body buffer length. */ 80 int header_buf_len; /**< response head buffer lehgth. */ 81 char *post_content_type; /**< content type of the post data. */ 82 char *post_buf; /**< user data to be posted. */ 83 char *response_buf; /**< buffer to store the response body data. */ 84 char *header_buf; /**< buffer to store the response head data. */ 85 bool is_redirected; /**< redirected URL? if 1, has redirect url; if 0, no redirect url */ 86 char* redirect_url; /**< redirect url when got http 3** response code. */ 87 } httpclient_data_t; 88 89 /** 90 * This function executes a GET request on a given URL. It blocks until completion. 91 * @param[in] client client is a pointer to the #httpclient_t. 92 * @param[in] url url is the URL to run the request. 93 * @param[in, out] client_data client_data is a pointer to the #httpclient_data_t instance to collect the data returned by the request. 94 * @return Please refer to #HTTPC_RESULT. 95 */ 96 HTTPC_RESULT httpclient_get(httpclient_t *client, const char *url, httpclient_data_t *client_data); 97 98 /** 99 * This function executes a HEAD request on a given URL. It blocks until completion. 100 * @param[in] client client is a pointer to the #httpclient_t. 101 * @param[in] url url is the URL to run the request. 102 * @param[in, out] client_data client_data is a pointer to the #httpclient_data_t instance to collect the data returned by the request. 103 * @return Please refer to #HTTPC_RESULT. 104 */ 105 HTTPC_RESULT httpclient_head(httpclient_t *client, const char *url, httpclient_data_t *client_data); 106 107 /** 108 * This function executes a POST request on a given URL. It blocks until completion. 109 * @param[in] client client is a pointer to the #httpclient_t. 110 * @param[in] url url is the URL to run the request. 111 * @param[in, out] client_data client_data is a pointer to the #httpclient_data_t instance to collect the data returned by the request. It also contains the data to be posted. 112 * @return Please refer to #HTTPC_RESULT. 113 */ 114 HTTPC_RESULT httpclient_post(httpclient_t *client, const char *url, httpclient_data_t *client_data); 115 116 /** 117 * This function executes a PUT request on a given URL. It blocks until completion. 118 * @param[in] client client is a pointer to the #httpclient_t. 119 * @param[in] url url is the URL to run the request. 120 * @param[in, out] client_data client_data is a pointer to the #httpclient_data_t instance to collect the data returned by the request. It also contains the data to be put. 121 * @return Please refer to #HTTPC_RESULT. 122 */ 123 HTTPC_RESULT httpclient_put(httpclient_t *client, const char *url, httpclient_data_t *client_data); 124 125 /** 126 * This function executes a DELETE request on a given URL. It blocks until completion. 127 * @param[in] client client is a pointer to the #httpclient_t. 128 * @param[in] url url is the URL to run the request. 129 * @param[in, out] client_data client_data is a pointer to the #httpclient_data_t instance to collect the data returned by the request. 130 * @return Please refer to #HTTPC_RESULT. 131 */ 132 HTTPC_RESULT httpclient_delete(httpclient_t *client, const char *url, httpclient_data_t *client_data); 133 134 /** 135 * This function allocates buffer for http header/response 136 * @param[in] client_data pointer to the #httpclient_data_t. 137 * @param[in] header_size header buffer size 138 * @param[in] resp_size response buffer size 139 * @return HTTP_SUCCESS success 140 * @return HTTP_EUNKOWN fail 141 */ 142 HTTPC_RESULT httpclient_prepare(httpclient_data_t *client_data, int header_size, int resp_size); 143 144 /** 145 * This function deallocates buffer for http header/response. 146 * @param[in] client_data pointer to the #httpclient_data_t. 147 * @return HTTP_SUCCESS success 148 * @return HTTP_EUNKOWN fail 149 */ 150 HTTPC_RESULT httpclient_unprepare(httpclient_data_t *client_data); 151 152 /** 153 * This function reset buffer for http header/response. 154 * @param[in] client_data pointer to the #httpclient_data_t. 155 * @return None. 156 */ 157 void httpclient_reset(httpclient_data_t *client_data); 158 159 /** 160 * This function establish http/https connection. 161 * @param[in] client pointer to the #httpclient_t. 162 * @param[in] url remote URL 163 * @return Please refer to #HTTPC_RESULT. 164 */ 165 HTTPC_RESULT httpclient_conn(httpclient_t *client, const char *url); 166 167 /** 168 * This function sends HTTP request. 169 * @param[in] client a pointer to the #httpclient_t. 170 * @param[in] url remote URL 171 * @param[in] method http request method 172 * @param[in] client_data a pointer to #httpclient_data_t. 173 * @return Please refer to #HTTPC_RESULT. 174 */ 175 HTTPC_RESULT httpclient_send(httpclient_t *client, const char *url, int method, httpclient_data_t *client_data); 176 177 /** 178 * This function receives response from remote 179 * @param[in] client a pointer to #httpclient_t. 180 * @param[out] client_data a pointer to #httpclient_data_t. 181 * @return Please refer to #HTTPC_RESULT. 182 */ 183 HTTPC_RESULT httpclient_recv(httpclient_t *client, httpclient_data_t *client_data); 184 185 /** 186 * This function close http connection. 187 * @param[in] client client is a pointer to the #httpclient_t. 188 * @return None. 189 */ 190 void httpclient_clse(httpclient_t *client); 191 192 /** 193 * This function sets a custom header. 194 * @param[in] client client is a pointer to the #httpclient_t. 195 * @param[in] header header is a custom header string. 196 * @return None. 197 */ 198 void httpclient_set_custom_header(httpclient_t *client, char *header); 199 200 /** 201 * This function gets the HTTP response code assigned to the last request. 202 * @param[in] client client is a pointer to the #httpclient_t. 203 * @return The HTTP response code of the last request. 204 */ 205 int httpclient_get_response_code(httpclient_t *client); 206 207 /** 208 * This function get specified response header value. 209 * @param[in] header_buf header_buf is the response header buffer. 210 * @param[in] name name is the specified http response header name. 211 * @param[in, out] val_pos val_pos is the position of header value in header_buf. 212 * @param[in, out] val_len val_len is header value length. 213 * @return 0, if value is got. Others, if errors occurred. 214 */ 215 int httpclient_get_response_header_value(char *header_buf, char *name, int *val_pos, int *val_len); 216 217 /** 218 * This function add text formdata information. 219 * @param[in] client_data client_data is a pointer to the #httpclient_data_t. 220 * @param[in] content_disposition content_disposition is a pointer to the content disposition string. 221 * @param[in] content_type content_type is a pointer to the content type string. 222 * @param[in] name name is a pointer to the name string. 223 * @param[in] data data is a pointer to the data. 224 * @param[in] data_len data_len is the data length. 225 * @return The HTTP response code of the last request. 226 */ 227 int httpclient_formdata_addtext(httpclient_data_t* client_data, char* content_disposition, char* content_type, char* name, char* data, int data_len); 228 229 /** 230 * This function add file formdata information. 231 * @param[in] client_data client_data is a pointer to the #httpclient_data_t. 232 * @param[in] content_disposition content_disposition is a pointer to the content disposition string. 233 * @param[in] content_type content_type is a pointer to the content type string. 234 * @param[in] file_path file_path is a pointer to the file path. 235 * @return The HTTP response code of the last request. 236 */ 237 int httpclient_formdata_addfile(httpclient_data_t* client_data, char* content_disposition, char* name, char* content_type, char* file_path); 238 239 #ifdef __cplusplus 240 } 241 #endif 242 243 #endif /* HTTPCLIENT_H */ 244