Line data Source code
1 1 : /** @file
2 : * @brief Websocket API
3 : *
4 : * An API for applications to setup websocket connections
5 : */
6 :
7 : /*
8 : * Copyright (c) 2019 Intel Corporation
9 : *
10 : * SPDX-License-Identifier: Apache-2.0
11 : */
12 :
13 : #ifndef ZEPHYR_INCLUDE_NET_WEBSOCKET_H_
14 : #define ZEPHYR_INCLUDE_NET_WEBSOCKET_H_
15 :
16 : #include <zephyr/kernel.h>
17 :
18 : #include <zephyr/net/net_ip.h>
19 : #include <zephyr/net/http/parser.h>
20 : #include <zephyr/net/http/client.h>
21 :
22 : #ifdef __cplusplus
23 : extern "C" {
24 : #endif
25 :
26 : /**
27 : * @brief Websocket API
28 : * @defgroup websocket Websocket API
29 : * @since 1.12
30 : * @version 0.1.0
31 : * @ingroup networking
32 : * @{
33 : */
34 :
35 : /** Message type values. Returned in websocket_recv_msg() */
36 1 : #define WEBSOCKET_FLAG_FINAL 0x00000001 /**< Final frame */
37 1 : #define WEBSOCKET_FLAG_TEXT 0x00000002 /**< Textual data */
38 1 : #define WEBSOCKET_FLAG_BINARY 0x00000004 /**< Binary data */
39 1 : #define WEBSOCKET_FLAG_CLOSE 0x00000008 /**< Closing connection */
40 1 : #define WEBSOCKET_FLAG_PING 0x00000010 /**< Ping message */
41 1 : #define WEBSOCKET_FLAG_PONG 0x00000020 /**< Pong message */
42 :
43 : /** @brief Websocket option codes */
44 1 : enum websocket_opcode {
45 : WEBSOCKET_OPCODE_CONTINUE = 0x00, /**< Message continues */
46 : WEBSOCKET_OPCODE_DATA_TEXT = 0x01, /**< Textual data */
47 : WEBSOCKET_OPCODE_DATA_BINARY = 0x02, /**< Binary data */
48 : WEBSOCKET_OPCODE_CLOSE = 0x08, /**< Closing connection */
49 : WEBSOCKET_OPCODE_PING = 0x09, /**< Ping message */
50 : WEBSOCKET_OPCODE_PONG = 0x0A, /**< Pong message */
51 : };
52 :
53 : /**
54 : * @typedef websocket_connect_cb_t
55 : * @brief Callback called after Websocket connection is established.
56 : *
57 : * @param ws_sock Websocket id
58 : * @param req HTTP handshake request
59 : * @param user_data A valid pointer on some user data or NULL
60 : *
61 : * @return 0 if ok, <0 if there is an error and connection should be aborted
62 : */
63 1 : typedef int (*websocket_connect_cb_t)(int ws_sock, struct http_request *req,
64 : void *user_data);
65 :
66 : /**
67 : * Websocket client connection request. This contains all the data that is
68 : * needed when doing a Websocket connection request.
69 : */
70 1 : struct websocket_request {
71 : /** Host of the Websocket server when doing HTTP handshakes. */
72 1 : const char *host;
73 :
74 : /** URL of the Websocket. */
75 1 : const char *url;
76 :
77 : /** User supplied callback function to call when optional headers need
78 : * to be sent. This can be NULL, in which case the optional_headers
79 : * field in http_request is used. The idea of this optional_headers
80 : * callback is to allow user to send more HTTP header data that is
81 : * practical to store in allocated memory.
82 : */
83 1 : http_header_cb_t optional_headers_cb;
84 :
85 : /** A NULL terminated list of any optional headers that
86 : * should be added to the HTTP request. May be NULL.
87 : * If the optional_headers_cb is specified, then this field is ignored.
88 : */
89 1 : const char **optional_headers;
90 :
91 : /** User supplied callback function to call when a connection is
92 : * established.
93 : */
94 1 : websocket_connect_cb_t cb;
95 :
96 : /** User supplied list of callback functions if the calling application
97 : * wants to know the parsing status or the HTTP fields during the
98 : * handshake. This is optional parameter and normally not needed but
99 : * is useful if the caller wants to know something about
100 : * the fields that the server is sending.
101 : */
102 1 : const struct http_parser_settings *http_cb;
103 :
104 : /** User supplied buffer where HTTP connection data is stored */
105 1 : uint8_t *tmp_buf;
106 :
107 : /** Length of the user supplied temp buffer */
108 1 : size_t tmp_buf_len;
109 : };
110 :
111 : /**
112 : * @brief Connect to a server that provides Websocket service. The callback is
113 : * called after connection is established. The returned value is a new socket
114 : * descriptor that can be used to send / receive data using the BSD socket API.
115 : *
116 : * @param http_sock Socket id to the server. Note that this socket is used to do
117 : * HTTP handshakes etc. The actual Websocket connectivity is done via the
118 : * returned websocket id. Note that the http_sock must not be closed
119 : * after this function returns as it is used to deliver the Websocket
120 : * packets to the Websocket server.
121 : * @param req Websocket request. User should allocate and fill the request
122 : * data.
123 : * @param timeout Max timeout to wait for the connection. The timeout value is
124 : * in milliseconds. Value SYS_FOREVER_MS means to wait forever.
125 : * @param user_data User specified data that is passed to the callback.
126 : *
127 : * @return Websocket id to be used when sending/receiving Websocket data.
128 : */
129 1 : int websocket_connect(int http_sock, struct websocket_request *req,
130 : int32_t timeout, void *user_data);
131 :
132 : /**
133 : * @brief Send websocket msg to peer.
134 : *
135 : * @details The function will automatically add websocket header to the
136 : * message.
137 : *
138 : * @param ws_sock Websocket id returned by websocket_connect().
139 : * @param payload Websocket data to send.
140 : * @param payload_len Length of the data to be sent.
141 : * @param opcode Operation code (text, binary, ping, pong, close)
142 : * @param mask Mask the data, see RFC 6455 for details
143 : * @param final Is this final message for this message send. If final == false,
144 : * then the first message must have valid opcode and subsequent messages
145 : * must have opcode WEBSOCKET_OPCODE_CONTINUE. If final == true and this
146 : * is the only message, then opcode should have proper opcode (text or
147 : * binary) set.
148 : * @param timeout How long to try to send the message. The value is in
149 : * milliseconds. Value SYS_FOREVER_MS means to wait forever.
150 : *
151 : * @return <0 if error, >=0 amount of bytes sent
152 : */
153 1 : int websocket_send_msg(int ws_sock, const uint8_t *payload, size_t payload_len,
154 : enum websocket_opcode opcode, bool mask, bool final,
155 : int32_t timeout);
156 :
157 : /**
158 : * @brief Receive websocket msg from peer.
159 : *
160 : * @details The function will automatically remove websocket header from the
161 : * message.
162 : *
163 : * @param ws_sock Websocket id returned by websocket_connect().
164 : * @param buf Buffer where websocket data is read.
165 : * @param buf_len Length of the data buffer.
166 : * @param message_type Type of the message.
167 : * @param remaining How much there is data left in the message after this read.
168 : * @param timeout How long to try to receive the message.
169 : * The value is in milliseconds. Value SYS_FOREVER_MS means to wait
170 : * forever.
171 : *
172 : * @retval >=0 amount of bytes received.
173 : * @retval -EAGAIN on timeout.
174 : * @retval -ENOTCONN on socket close.
175 : * @retval -errno other negative errno value in case of failure.
176 : */
177 1 : int websocket_recv_msg(int ws_sock, uint8_t *buf, size_t buf_len,
178 : uint32_t *message_type, uint64_t *remaining,
179 : int32_t timeout);
180 :
181 : /**
182 : * @brief Close websocket.
183 : *
184 : * @details One must call websocket_connect() after this call to re-establish
185 : * the connection.
186 : *
187 : * @param ws_sock Websocket id returned by websocket_connect().
188 : *
189 : * @return <0 if error, 0 the connection was closed successfully
190 : */
191 1 : int websocket_disconnect(int ws_sock);
192 :
193 : /**
194 : * @brief Register a socket as websocket. This is called by HTTP server
195 : * when a connection is upgraded to a websocket connection.
196 : *
197 : * @param http_sock Underlying socket connection socket.
198 : * @param recv_buf Temporary receive buffer for websocket parsing. This must
199 : * point to a memory area that is valid for the duration of the whole
200 : * websocket session.
201 : * @param recv_buf_len Length of the temporary receive buffer.
202 : *
203 : * @return <0 if error, >=0 the actual websocket to be used by application
204 : */
205 1 : int websocket_register(int http_sock, uint8_t *recv_buf, size_t recv_buf_len);
206 :
207 : /**
208 : * @brief Unregister a websocket. This is called when we no longer need
209 : * the underlying "real" socket. This will close first the websocket
210 : * and then the original socket.
211 : *
212 : * @param ws_sock Websocket connection socket.
213 : *
214 : * @return <0 if error, 0 the websocket connection is now fully closed
215 : */
216 1 : int websocket_unregister(int ws_sock);
217 :
218 : /** @cond INTERNAL_HIDDEN */
219 :
220 : #if defined(CONFIG_WEBSOCKET_CLIENT)
221 : void websocket_init(void);
222 : #else
223 : static inline void websocket_init(void)
224 : {
225 : }
226 : #endif
227 :
228 : /** @endcond */
229 :
230 : #ifdef __cplusplus
231 : }
232 : #endif
233 :
234 : /**
235 : * @}
236 : */
237 :
238 : #endif /* ZEPHYR_INCLUDE_NET_WEBSOCKET_H_ */
|
