esp_websocket_client.h
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_WEBSOCKET_CLIENT_H_ 16 #define _ESP_WEBSOCKET_CLIENT_H_ 17 18 19 #include <stdint.h> 20 #include <stdbool.h> 21 #include <string.h> 22 #include "freertos/FreeRTOS.h" 23 #include "esp_err.h" 24 #include "esp_event.h" 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 typedef struct esp_websocket_client *esp_websocket_client_handle_t; 31 32 ESP_EVENT_DECLARE_BASE(WEBSOCKET_EVENTS); // declaration of the task events family 33 34 /** 35 * @brief Websocket Client events id 36 */ 37 typedef enum { 38 WEBSOCKET_EVENT_ANY = -1, 39 WEBSOCKET_EVENT_ERROR = 0, /*!< This event occurs when there are any errors during execution */ 40 WEBSOCKET_EVENT_CONNECTED, /*!< Once the Websocket has been connected to the server, no data exchange has been performed */ 41 WEBSOCKET_EVENT_DISCONNECTED, /*!< The connection has been disconnected */ 42 WEBSOCKET_EVENT_DATA, /*!< When receiving data from the server, possibly multiple portions of the packet */ 43 WEBSOCKET_EVENT_CLOSED, /*!< The connection has been closed cleanly */ 44 WEBSOCKET_EVENT_MAX 45 } esp_websocket_event_id_t; 46 47 /** 48 * @brief Websocket event data 49 */ 50 typedef struct { 51 const char *data_ptr; /*!< Data pointer */ 52 int data_len; /*!< Data length */ 53 uint8_t op_code; /*!< Received opcode */ 54 esp_websocket_client_handle_t client; /*!< esp_websocket_client_handle_t context */ 55 void *user_context; /*!< user_data context, from esp_websocket_client_config_t user_data */ 56 int payload_len; /*!< Total payload length, payloads exceeding buffer will be posted through multiple events */ 57 int payload_offset; /*!< Actual offset for the data associated with this event */ 58 } esp_websocket_event_data_t; 59 60 /** 61 * @brief Websocket Client transport 62 */ 63 typedef enum { 64 WEBSOCKET_TRANSPORT_UNKNOWN = 0x0, /*!< Transport unknown */ 65 WEBSOCKET_TRANSPORT_OVER_TCP, /*!< Transport over tcp */ 66 WEBSOCKET_TRANSPORT_OVER_SSL, /*!< Transport over ssl */ 67 } esp_websocket_transport_t; 68 69 /** 70 * @brief Websocket client setup configuration 71 */ 72 typedef struct { 73 const char *uri; /*!< Websocket URI, the information on the URI can be overrides the other fields below, if any */ 74 const char *host; /*!< Domain or IP as string */ 75 int port; /*!< Port to connect, default depend on esp_websocket_transport_t (80 or 443) */ 76 const char *username; /*!< Using for Http authentication - Not supported for now */ 77 const char *password; /*!< Using for Http authentication - Not supported for now */ 78 const char *path; /*!< HTTP Path, if not set, default is `/` */ 79 bool disable_auto_reconnect; /*!< Disable the automatic reconnect function when disconnected */ 80 void *user_context; /*!< HTTP user data context */ 81 int task_prio; /*!< Websocket task priority */ 82 int task_stack; /*!< Websocket task stack */ 83 int buffer_size; /*!< Websocket buffer size */ 84 const char *cert_pem; /*!< SSL Certification, PEM format as string, if the client requires to verify server */ 85 esp_websocket_transport_t transport; /*!< Websocket transport type, see `esp_websocket_transport_t */ 86 char *subprotocol; /*!< Websocket subprotocol */ 87 char *user_agent; /*!< Websocket user-agent */ 88 char *headers; /*!< Websocket additional headers */ 89 int pingpong_timeout_sec; /*!< Period before connection is aborted due to no PONGs received */ 90 bool disable_pingpong_discon; /*!< Disable auto-disconnect due to no PONG received within pingpong_timeout_sec */ 91 92 } esp_websocket_client_config_t; 93 94 /** 95 * @brief Start a Websocket session 96 * This function must be the first function to call, 97 * and it returns a esp_websocket_client_handle_t that you must use as input to other functions in the interface. 98 * This call MUST have a corresponding call to esp_websocket_client_destroy when the operation is complete. 99 * 100 * @param[in] config The configuration 101 * 102 * @return 103 * - `esp_websocket_client_handle_t` 104 * - NULL if any errors 105 */ 106 esp_websocket_client_handle_t esp_websocket_client_init(const esp_websocket_client_config_t *config); 107 108 /** 109 * @brief Set URL for client, when performing this behavior, the options in the URL will replace the old ones 110 * Must stop the WebSocket client before set URI if the client has been connected 111 * 112 * @param[in] client The client 113 * @param[in] uri The uri 114 * 115 * @return esp_err_t 116 */ 117 esp_err_t esp_websocket_client_set_uri(esp_websocket_client_handle_t client, const char *uri); 118 119 /** 120 * @brief Open the WebSocket connection 121 * 122 * @param[in] client The client 123 * 124 * @return esp_err_t 125 */ 126 esp_err_t esp_websocket_client_start(esp_websocket_client_handle_t client); 127 128 /** 129 * @brief Stops the WebSocket connection without websocket closing handshake 130 * 131 * This API stops ws client and closes TCP connection directly without sending 132 * close frames. It is a good practice to close the connection in a clean way 133 * using esp_websocket_client_close(). 134 * 135 * Notes: 136 * - Cannot be called from the websocket event handler 137 * 138 * @param[in] client The client 139 * 140 * @return esp_err_t 141 */ 142 esp_err_t esp_websocket_client_stop(esp_websocket_client_handle_t client); 143 144 /** 145 * @brief Destroy the WebSocket connection and free all resources. 146 * This function must be the last function to call for an session. 147 * It is the opposite of the esp_websocket_client_init function and must be called with the same handle as input that a esp_websocket_client_init call returned. 148 * This might close all connections this handle has used. 149 * 150 * Notes: 151 * - Cannot be called from the websocket event handler 152 * 153 * @param[in] client The client 154 * 155 * @return esp_err_t 156 */ 157 esp_err_t esp_websocket_client_destroy(esp_websocket_client_handle_t client); 158 159 /** 160 * @brief Generic write data to the WebSocket connection; defaults to binary send 161 * 162 * @param[in] client The client 163 * @param[in] data The data 164 * @param[in] len The length 165 * @param[in] timeout Write data timeout in RTOS ticks 166 * 167 * @return 168 * - Number of data was sent 169 * - (-1) if any errors 170 */ 171 int esp_websocket_client_send(esp_websocket_client_handle_t client, const char *data, int len, TickType_t timeout); 172 173 /** 174 * @brief Write binary data to the WebSocket connection (data send with WS OPCODE=02, i.e. binary) 175 * 176 * @param[in] client The client 177 * @param[in] data The data 178 * @param[in] len The length 179 * @param[in] timeout Write data timeout in RTOS ticks 180 * 181 * @return 182 * - Number of data was sent 183 * - (-1) if any errors 184 */ 185 int esp_websocket_client_send_bin(esp_websocket_client_handle_t client, const char *data, int len, TickType_t timeout); 186 187 /** 188 * @brief Write textual data to the WebSocket connection (data send with WS OPCODE=01, i.e. text) 189 * 190 * @param[in] client The client 191 * @param[in] data The data 192 * @param[in] len The length 193 * @param[in] timeout Write data timeout in RTOS ticks 194 * 195 * @return 196 * - Number of data was sent 197 * - (-1) if any errors 198 */ 199 int esp_websocket_client_send_text(esp_websocket_client_handle_t client, const char *data, int len, TickType_t timeout); 200 201 /** 202 * @brief Close the WebSocket connection in a clean way 203 * 204 * Sequence of clean close initiated by client: 205 * * Client sends CLOSE frame 206 * * Client waits until server echos the CLOSE frame 207 * * Client waits until server closes the connection 208 * * Client is stopped the same way as by the `esp_websocket_client_stop()` 209 * 210 * Notes: 211 * - Cannot be called from the websocket event handler 212 * 213 * @param[in] client The client 214 * @param[in] timeout Timeout in RTOS ticks for waiting 215 * 216 * @return esp_err_t 217 */ 218 esp_err_t esp_websocket_client_close(esp_websocket_client_handle_t client, TickType_t timeout); 219 220 /** 221 * @brief Close the WebSocket connection in a clean way with custom code/data 222 * Closing sequence is the same as for esp_websocket_client_close() 223 * 224 * Notes: 225 * - Cannot be called from the websocket event handler 226 * 227 * @param[in] client The client 228 * @param[in] code Close status code as defined in RFC6455 section-7.4 229 * @param[in] data Additional data to closing message 230 * @param[in] len The length of the additional data 231 * @param[in] timeout Timeout in RTOS ticks for waiting 232 * 233 * @return esp_err_t 234 */ 235 esp_err_t esp_websocket_client_close_with_code(esp_websocket_client_handle_t client, int code, const char *data, int len, TickType_t timeout); 236 237 /** 238 * @brief Check the WebSocket client connection state 239 * 240 * @param[in] client The client handle 241 * 242 * @return 243 * - true 244 * - false 245 */ 246 bool esp_websocket_client_is_connected(esp_websocket_client_handle_t client); 247 248 /** 249 * @brief Register the Websocket Events 250 * 251 * @param client The client handle 252 * @param event The event id 253 * @param event_handler The callback function 254 * @param event_handler_arg User context 255 * @return esp_err_t 256 */ 257 esp_err_t esp_websocket_register_events(esp_websocket_client_handle_t client, 258 esp_websocket_event_id_t event, 259 esp_event_handler_t event_handler, 260 void *event_handler_arg); 261 262 #ifdef __cplusplus 263 } 264 #endif 265 266 #endif