1 // Copyright 2015-2018 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef _ESP_TRANSPORT_H_ 16 #define _ESP_TRANSPORT_H_ 17 18 #include <esp_err.h> 19 #include <stdbool.h> 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 /** 26 * @brief Keep alive parameters structure 27 */ 28 typedef struct esp_transport_keepalive { 29 bool keep_alive_enable; /*!< Enable keep-alive timeout */ 30 int keep_alive_idle; /*!< Keep-alive idle time (second) */ 31 int keep_alive_interval; /*!< Keep-alive interval time (second) */ 32 int keep_alive_count; /*!< Keep-alive packet retry send count */ 33 } esp_transport_keep_alive_t; 34 35 typedef struct esp_transport_internal* esp_transport_list_handle_t; 36 typedef struct esp_transport_item_t* esp_transport_handle_t; 37 38 typedef int (*connect_func)(esp_transport_handle_t t, const char *host, int port, int timeout_ms); 39 typedef int (*io_func)(esp_transport_handle_t t, const char *buffer, int len, int timeout_ms); 40 typedef int (*io_read_func)(esp_transport_handle_t t, char *buffer, int len, int timeout_ms); 41 typedef int (*trans_func)(esp_transport_handle_t t); 42 typedef int (*poll_func)(esp_transport_handle_t t, int timeout_ms); 43 typedef int (*connect_async_func)(esp_transport_handle_t t, const char *host, int port, int timeout_ms); 44 typedef esp_transport_handle_t (*payload_transfer_func)(esp_transport_handle_t); 45 46 typedef struct esp_tls_last_error* esp_tls_error_handle_t; 47 48 /** 49 * @brief Create transport list 50 * 51 * @return A handle can hold all transports 52 */ 53 esp_transport_list_handle_t esp_transport_list_init(void); 54 55 /** 56 * @brief Cleanup and free all transports, include itself, 57 * this function will invoke esp_transport_destroy of every transport have added this the list 58 * 59 * @param[in] list The list 60 * 61 * @return 62 * - ESP_OK 63 * - ESP_FAIL 64 */ 65 esp_err_t esp_transport_list_destroy(esp_transport_list_handle_t list); 66 67 /** 68 * @brief Add a transport to the list, and define a scheme to indentify this transport in the list 69 * 70 * @param[in] list The list 71 * @param[in] t The Transport 72 * @param[in] scheme The scheme 73 * 74 * @return 75 * - ESP_OK 76 */ 77 esp_err_t esp_transport_list_add(esp_transport_list_handle_t list, esp_transport_handle_t t, const char *scheme); 78 79 /** 80 * @brief This function will remove all transport from the list, 81 * invoke esp_transport_destroy of every transport have added this the list 82 * 83 * @param[in] list The list 84 * 85 * @return 86 * - ESP_OK 87 * - ESP_ERR_INVALID_ARG 88 */ 89 esp_err_t esp_transport_list_clean(esp_transport_list_handle_t list); 90 91 /** 92 * @brief Get the transport by scheme, which has been defined when calling function `esp_transport_list_add` 93 * 94 * @param[in] list The list 95 * @param[in] tag The tag 96 * 97 * @return The transport handle 98 */ 99 esp_transport_handle_t esp_transport_list_get_transport(esp_transport_list_handle_t list, const char *scheme); 100 101 /** 102 * @brief Initialize a transport handle object 103 * 104 * @return The transport handle 105 */ 106 esp_transport_handle_t esp_transport_init(void); 107 108 /** 109 * @brief Cleanup and free memory the transport 110 * 111 * @param[in] t The transport handle 112 * 113 * @return 114 * - ESP_OK 115 * - ESP_FAIL 116 */ 117 esp_err_t esp_transport_destroy(esp_transport_handle_t t); 118 119 /** 120 * @brief Get default port number used by this transport 121 * 122 * @param[in] t The transport handle 123 * 124 * @return the port number 125 */ 126 int esp_transport_get_default_port(esp_transport_handle_t t); 127 128 /** 129 * @brief Set default port number that can be used by this transport 130 * 131 * @param[in] t The transport handle 132 * @param[in] port The port number 133 * 134 * @return 135 * - ESP_OK 136 * - ESP_FAIL 137 */ 138 esp_err_t esp_transport_set_default_port(esp_transport_handle_t t, int port); 139 140 /** 141 * @brief Transport connection function, to make a connection to server 142 * 143 * @param t The transport handle 144 * @param[in] host Hostname 145 * @param[in] port Port 146 * @param[in] timeout_ms The timeout milliseconds (-1 indicates wait forever) 147 * 148 * @return 149 * - socket for will use by this transport 150 * - (-1) if there are any errors, should check errno 151 */ 152 int esp_transport_connect(esp_transport_handle_t t, const char *host, int port, int timeout_ms); 153 154 /** 155 * @brief Non-blocking transport connection function, to make a connection to server 156 * 157 * @param t The transport handle 158 * @param[in] host Hostname 159 * @param[in] port Port 160 * @param[in] timeout_ms The timeout milliseconds (-1 indicates wait forever) 161 * 162 * @return 163 * - socket for will use by this transport 164 * - (-1) if there are any errors, should check errno 165 */ 166 int esp_transport_connect_async(esp_transport_handle_t t, const char *host, int port, int timeout_ms); 167 168 /** 169 * @brief Transport read function 170 * 171 * @param t The transport handle 172 * @param buffer The buffer 173 * @param[in] len The length 174 * @param[in] timeout_ms The timeout milliseconds (-1 indicates wait forever) 175 * 176 * @return 177 * - Number of bytes was read 178 * - (-1) if there are any errors, should check errno 179 */ 180 int esp_transport_read(esp_transport_handle_t t, char *buffer, int len, int timeout_ms); 181 182 /** 183 * @brief Poll the transport until readable or timeout 184 * 185 * @param[in] t The transport handle 186 * @param[in] timeout_ms The timeout milliseconds (-1 indicates wait forever) 187 * 188 * @return 189 * - 0 Timeout 190 * - (-1) If there are any errors, should check errno 191 * - other The transport can read 192 */ 193 int esp_transport_poll_read(esp_transport_handle_t t, int timeout_ms); 194 195 /** 196 * @brief Transport write function 197 * 198 * @param t The transport handle 199 * @param buffer The buffer 200 * @param[in] len The length 201 * @param[in] timeout_ms The timeout milliseconds (-1 indicates wait forever) 202 * 203 * @return 204 * - Number of bytes was written 205 * - (-1) if there are any errors, should check errno 206 */ 207 int esp_transport_write(esp_transport_handle_t t, const char *buffer, int len, int timeout_ms); 208 209 /** 210 * @brief Poll the transport until writeable or timeout 211 * 212 * @param[in] t The transport handle 213 * @param[in] timeout_ms The timeout milliseconds (-1 indicates wait forever) 214 * 215 * @return 216 * - 0 Timeout 217 * - (-1) If there are any errors, should check errno 218 * - other The transport can write 219 */ 220 int esp_transport_poll_write(esp_transport_handle_t t, int timeout_ms); 221 222 /** 223 * @brief Transport close 224 * 225 * @param t The transport handle 226 * 227 * @return 228 * - 0 if ok 229 * - (-1) if there are any errors, should check errno 230 */ 231 int esp_transport_close(esp_transport_handle_t t); 232 233 /** 234 * @brief Get user data context of this transport 235 * 236 * @param[in] t The transport handle 237 * 238 * @return The user data context 239 */ 240 void *esp_transport_get_context_data(esp_transport_handle_t t); 241 242 /** 243 * @brief Get transport handle of underlying protocol 244 * which can access this protocol payload directly 245 * (used for receiving longer msg multiple times) 246 * 247 * @param[in] t The transport handle 248 * 249 * @return Payload transport handle 250 */ 251 esp_transport_handle_t esp_transport_get_payload_transport_handle(esp_transport_handle_t t); 252 253 /** 254 * @brief Set the user context data for this transport 255 * 256 * @param[in] t The transport handle 257 * @param data The user data context 258 * 259 * @return 260 * - ESP_OK 261 */ 262 esp_err_t esp_transport_set_context_data(esp_transport_handle_t t, void *data); 263 264 /** 265 * @brief Set transport functions for the transport handle 266 * 267 * @param[in] t The transport handle 268 * @param[in] _connect The connect function pointer 269 * @param[in] _read The read function pointer 270 * @param[in] _write The write function pointer 271 * @param[in] _close The close function pointer 272 * @param[in] _poll_read The poll read function pointer 273 * @param[in] _poll_write The poll write function pointer 274 * @param[in] _destroy The destroy function pointer 275 * 276 * @return 277 * - ESP_OK 278 */ 279 esp_err_t esp_transport_set_func(esp_transport_handle_t t, 280 connect_func _connect, 281 io_read_func _read, 282 io_func _write, 283 trans_func _close, 284 poll_func _poll_read, 285 poll_func _poll_write, 286 trans_func _destroy); 287 288 289 /** 290 * @brief Set transport functions for the transport handle 291 * 292 * @param[in] t The transport handle 293 * @param[in] _connect_async_func The connect_async function pointer 294 * 295 * @return 296 * - ESP_OK 297 * - ESP_FAIL 298 */ 299 esp_err_t esp_transport_set_async_connect_func(esp_transport_handle_t t, connect_async_func _connect_async_func); 300 301 /** 302 * @brief Set parent transport function to the handle 303 * 304 * @param[in] t The transport handle 305 * @param[in] _parent_transport The underlying transport getter pointer 306 * 307 * @return 308 * - ESP_OK 309 * - ESP_FAIL 310 */ 311 esp_err_t esp_transport_set_parent_transport_func(esp_transport_handle_t t, payload_transfer_func _parent_transport); 312 313 /** 314 * @brief Returns esp_tls error handle. 315 * Warning: The returned pointer is valid only as long as esp_transport_handle_t exists. Once transport 316 * handle gets destroyed, this value (esp_tls_error_handle_t) is freed automatically. 317 * 318 * @param[in] A transport handle 319 * 320 * @return 321 * - valid pointer of esp_error_handle_t 322 * - NULL if invalid transport handle 323 */ 324 esp_tls_error_handle_t esp_transport_get_error_handle(esp_transport_handle_t t); 325 326 /** 327 * @brief Get and clear last captured socket errno 328 * 329 * Socket errno is internally stored whenever any of public facing API 330 * for reading, writing, polling or connection fails returning negative return code. 331 * The error code corresponds to the `SO_ERROR` value retrieved from the underlying 332 * transport socket using `getsockopt()` API. After reading the captured errno, 333 * the internal value is cleared to 0. 334 * 335 * @param[in] t The transport handle 336 * 337 * @return 338 * - >=0 Last captured socket errno 339 * - -1 Invalid transport handle or invalid transport's internal error storage 340 */ 341 int esp_transport_get_errno(esp_transport_handle_t t); 342 343 #ifdef __cplusplus 344 } 345 #endif 346 #endif /* _ESP_TRANSPORT_ */ 347
