Outline ![]()
Files ![]()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
/*
* This file is subject to the terms and conditions defined in
* file 'LICENSE', which is part of this source code package.
* Tuan PM <tuanpm at live dot com>
*/
#ifndef _ESP_TRANSPORT_WS_H_
#define _ESP_TRANSPORT_WS_H_
#include "esp_transport.h"
#include <stdbool.h>
#ifdef __cplusplus
extern "C" {
#endif
typedef enum ws_transport_opcodes {
WS_TRANSPORT_OPCODES_CONT = 0x00,
WS_TRANSPORT_OPCODES_TEXT = 0x01,
WS_TRANSPORT_OPCODES_BINARY = 0x02,
WS_TRANSPORT_OPCODES_CLOSE = 0x08,
WS_TRANSPORT_OPCODES_PING = 0x09,
WS_TRANSPORT_OPCODES_PONG = 0x0a,
WS_TRANSPORT_OPCODES_FIN = 0x80,
WS_TRANSPORT_OPCODES_NONE = 0x100, /*!< not a valid opcode to indicate no message previously received
* from the API esp_transport_ws_get_read_opcode() */
} ws_transport_opcodes_t;
/**
* WS transport configuration structure
*/
typedef struct {
const char *ws_path; /*!< HTTP path to update protocol to websocket */
const char *sub_protocol; /*!< WS subprotocol */
const char *user_agent; /*!< WS user agent */
const char *headers; /*!< WS additional headers */
const char *auth; /*!< HTTP authorization header */
bool propagate_control_frames; /*!< If true, control frames are passed to the reader
* If false, only user frames are propagated, control frames are handled
* automatically during read operations
*/
} esp_transport_ws_config_t;
/**
* @brief Create web socket transport
*
* @return
* - transport
* - NULL
*/
esp_transport_handle_t esp_transport_ws_init(esp_transport_handle_t parent_handle);
/**
* @brief Set HTTP path to update protocol to websocket
*
* @param t websocket transport handle
* @param path The HTTP Path
*/
void esp_transport_ws_set_path(esp_transport_handle_t t, const char *path);
/**
* @brief Set websocket sub protocol header
*
* @param t websocket transport handle
* @param sub_protocol Sub protocol string
*
* @return
* - ESP_OK on success
* - One of the error codes
*/
esp_err_t esp_transport_ws_set_subprotocol(esp_transport_handle_t t, const char *sub_protocol);
/**
* @brief Set websocket user-agent header
*
* @param t websocket transport handle
* @param sub_protocol user-agent string
*
* @return
* - ESP_OK on success
* - One of the error codes
*/
esp_err_t esp_transport_ws_set_user_agent(esp_transport_handle_t t, const char *user_agent);
/**
* @brief Set websocket additional headers
*
* @param t websocket transport handle
* @param sub_protocol additional header strings each terminated with \r\n
*
* @return
* - ESP_OK on success
* - One of the error codes
*/
esp_err_t esp_transport_ws_set_headers(esp_transport_handle_t t, const char *headers);
/**
* @brief Set websocket authorization headers
*
* @param t websocket transport handle
* @param sub_protocol The HTTP authorization header string, set NULL to clear the old value
*
* @return
* - ESP_OK on success
* - One of the error codes
*/
esp_err_t esp_transport_ws_set_auth(esp_transport_handle_t t, const char *auth);
/**
* @brief Set websocket transport parameters
*
* @param t websocket transport handle
* @param config pointer to websocket config structure
*
* @return
* - ESP_OK on success
* - One of the error codes
*/
esp_err_t esp_transport_ws_set_config(esp_transport_handle_t t, const esp_transport_ws_config_t *config);
/**
* @brief Sends websocket raw message with custom opcode and payload
*
* Note that generic esp_transport_write for ws handle sends
* binary massages by default if size is > 0 and
* ping message if message size is set to 0.
* This API is provided to support explicit messages with arbitrary opcode,
* should it be PING, PONG or TEXT message with arbitrary data.
*
* @param[in] t Websocket transport handle
* @param[in] opcode ws operation code
* @param[in] buffer The buffer
* @param[in] len The length
* @param[in] timeout_ms The timeout milliseconds (-1 indicates block forever)
*
* @return
* - Number of bytes was written
* - (-1) if there are any errors, should check errno
*/
int esp_transport_ws_send_raw(esp_transport_handle_t t, ws_transport_opcodes_t opcode, const char *b, int len, int timeout_ms);
/**
* @brief Returns websocket fin flag for last received data
*
* @param t websocket transport handle
*
* @return
* - Fin flag as a boolean
*/
bool esp_transport_ws_get_fin_flag(esp_transport_handle_t t);
/**
* @brief Returns the HTTP status code of the websocket handshake
*
* This API should be called after the connection atempt otherwise its result is meaningless
*
* @param t websocket transport handle
*
* @return
* -Response status code
* -1 on failure
*/
int esp_transport_ws_get_upgrade_request_status(esp_transport_handle_t t);
/**
* @brief Returns websocket op-code for last received data
*
* @param t websocket transport handle
*
* @return
* - Received op-code as enum
*/
ws_transport_opcodes_t esp_transport_ws_get_read_opcode(esp_transport_handle_t t);
/**
* @brief Returns payload length of the last received data
*
* @param t websocket transport handle
*
* @return
* - Number of bytes in the payload
*/
int esp_transport_ws_get_read_payload_len(esp_transport_handle_t t);
/**
* @brief Polls the active connection for termination
*
* This API is typically used by the client to wait for clean connection closure
* by websocket server
*
* @param t Websocket transport handle
* @param[in] timeout_ms The timeout milliseconds
*
* @return
* 0 - no activity on read and error socket descriptor within timeout
* 1 - Success: either connection terminated by FIN or the most common RST err codes
* -1 - Failure: Unexpected error code or socket is normally readable
*/
int esp_transport_ws_poll_connection_closed(esp_transport_handle_t t, int timeout_ms);
#ifdef __cplusplus
}
#endif
#endif /* _ESP_TRANSPORT_WS_H_ */
Details ![]()
Show: from Types: Columns: ![]( "Show Project Names")
![]( "Show Locations")
![]( "Show Referring Symbols")
![]( "Show Scope")
This file uses the notable symbols shown below. Click anywhere in the file to view more details.