1/*
2 * libwebsockets - small server side websockets and web server implementation
3 *
4 * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22 * IN THE SOFTWARE.
23 */
24
25/** \defgroup sock-adopt Socket adoption helpers
26 * ##Socket adoption helpers
27 *
28 * When integrating with an external app with its own event loop, these can
29 * be used to accept connections from someone else's listening socket.
30 *
31 * When using lws own event loop, these are not needed.
32 */
33///@{
34
35/**
36 * lws_adopt_socket() - adopt foreign socket as if listen socket accepted it
37 * for the default vhost of context.
38 *
39 * \param context: lws context
40 * \param accept_fd: fd of already-accepted socket to adopt
41 *
42 * Either returns new wsi bound to accept_fd, or closes accept_fd and
43 * returns NULL, having cleaned up any new wsi pieces.
44 *
45 * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
46 * to ws or just serve http.
47 */
48LWS_VISIBLE LWS_EXTERN struct lws *
49lws_adopt_socket(struct lws_context *context, lws_sockfd_type accept_fd);
50
51/**
52 * lws_adopt_socket_vhost() - adopt foreign socket as if listen socket accepted
53 * it for vhost
54 *
55 * \param vh: lws vhost
56 * \param accept_fd: fd of already-accepted socket to adopt
57 *
58 * Either returns new wsi bound to accept_fd, or closes accept_fd and
59 * returns NULL, having cleaned up any new wsi pieces.
60 *
61 * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
62 * to ws or just serve http.
63 */
64LWS_VISIBLE LWS_EXTERN struct lws *
65lws_adopt_socket_vhost(struct lws_vhost *vh, lws_sockfd_type accept_fd);
66
67typedef enum {
68 LWS_ADOPT_RAW_FILE_DESC = 0, /* convenience constant */
69 LWS_ADOPT_HTTP = 1, /* flag: absent implies RAW */
70 LWS_ADOPT_SOCKET = 2, /* flag: absent implies file */
71 LWS_ADOPT_ALLOW_SSL = 4, /* flag: use tls */
72 LWS_ADOPT_FLAG_UDP = 16, /* flag: socket is UDP */
73 LWS_ADOPT_FLAG_RAW_PROXY = 32, /* flag: raw proxy */
74
75 LWS_ADOPT_RAW_SOCKET_UDP = LWS_ADOPT_SOCKET | LWS_ADOPT_FLAG_UDP,
76} lws_adoption_type;
77
78typedef union {
79 lws_sockfd_type sockfd;
80 lws_filefd_type filefd;
81} lws_sock_file_fd_type;
82
83#if defined(LWS_ESP_PLATFORM)
84#include <lwip/sockets.h>
85#endif
86
87typedef union {
88#if defined(LWS_WITH_IPV6)
89 struct sockaddr_in6 sa6;
90#else
91#if defined(LWS_ESP_PLATFORM)
92 uint8_t _pad_sa6[28];
93#endif
94#endif
95 struct sockaddr_in sa4;
96} lws_sockaddr46;
97
98#define sa46_sockaddr(_sa46) ((struct sockaddr *)(_sa46))
99
100#if defined(LWS_WITH_IPV6)
101#define sa46_socklen(_sa46) (socklen_t)((_sa46)->sa4.sin_family == AF_INET ? \
102 sizeof(struct sockaddr_in) : \
103 sizeof(struct sockaddr_in6))
104#define sa46_sockport(_sa46, _sp) { if ((_sa46)->sa4.sin_family == AF_INET) \
105 (_sa46)->sa4.sin_port = (_sp); else \
106 (_sa46)->sa6.sin6_port = (_sp); }
107#define sa46_address(_sa46) ((uint8_t *)((_sa46)->sa4.sin_family == AF_INET ? \
108 &_sa46->sa4.sin_addr : &_sa46->sa6.sin6_addr ))
109#else
110#define sa46_socklen(_sa46) (socklen_t)sizeof(struct sockaddr_in)
111#define sa46_sockport(_sa46, _sp) (_sa46)->sa4.sin_port = (_sp)
112#define sa46_address(_sa46) (uint8_t *)&_sa46->sa4.sin_addr
113#endif
114
115#define sa46_address_len(_sa46) ((_sa46)->sa4.sin_family == AF_INET ? 4 : 16)
116
117#if defined(LWS_WITH_UDP)
118struct lws_udp {
119 lws_sockaddr46 sa46;
120 lws_sockaddr46 sa46_pending;
121 uint8_t connected:1;
122};
123#endif
124
125/**
126* lws_adopt_descriptor_vhost() - adopt foreign socket or file descriptor
127* if socket descriptor, should already have been accepted from listen socket
128*
129* \param vh: lws vhost
130* \param type: OR-ed combinations of lws_adoption_type flags
131* \param fd: union with either .sockfd or .filefd set
132* \param vh_prot_name: NULL or vh protocol name to bind raw connection to
133* \param parent: NULL or struct lws to attach new_wsi to as a child
134*
135* Either returns new wsi bound to accept_fd, or closes accept_fd and
136* returns NULL, having cleaned up any new wsi pieces.
137*
138* If LWS_ADOPT_SOCKET is set, LWS adopts the socket in http serving mode, it's
139* ready to accept an upgrade to ws or just serve http.
140*
141* parent may be NULL, if given it should be an existing wsi that will become the
142* parent of the new wsi created by this call.
143*/
144LWS_VISIBLE LWS_EXTERN struct lws *
145lws_adopt_descriptor_vhost(struct lws_vhost *vh, lws_adoption_type type,
146 lws_sock_file_fd_type fd, const char *vh_prot_name,
147 struct lws *parent);
148
149typedef struct lws_adopt_desc {
150 struct lws_vhost *vh; /**< vhost the wsi should belong to */
151 lws_adoption_type type; /**< OR-ed combinations of
152 * lws_adoption_type flags */
153 lws_sock_file_fd_type fd; /**< union with either .sockfd
154 * or .filefd set */
155 const char *vh_prot_name; /**< NULL or vh protocol name to
156 * bind raw connection to */
157 struct lws *parent; /**< NULL or struct lws to
158 * attach new_wsi to as a child */
159 void *opaque; /**< opaque pointer to set on
160 *created wsi */
161 const char *fi_wsi_name; /**< NULL, or Fault Injection
162 * inheritence filter for
163 * wsi=string/ context faults */
164} lws_adopt_desc_t;
165
166/**
167* lws_adopt_descriptor_vhost_via_info() - adopt foreign socket or file descriptor
168* if socket descriptor, should already have been accepted from listen socket
169*
170* \param info: the struct containing the parameters
171*
172* - vh: lws vhost
173* - type: OR-ed combinations of lws_adoption_type flags
174* - fd: union with either .sockfd or .filefd set
175* - vh_prot_name: NULL or vh protocol name to bind raw connection to
176* - parent: NULL or struct lws to attach new_wsi to as a child
177* - opaque: opaque pointer to set on created wsi
178*
179* Either returns new wsi bound to accept_fd, or closes accept_fd and
180* returns NULL, having cleaned up any new wsi pieces.
181*
182* If LWS_ADOPT_SOCKET is set, LWS adopts the socket in http serving mode, it's
183* ready to accept an upgrade to ws or just serve http.
184*
185* parent may be NULL, if given it should be an existing wsi that will become the
186* parent of the new wsi created by this call.
187*/
188LWS_VISIBLE LWS_EXTERN struct lws *
189lws_adopt_descriptor_vhost_via_info(const lws_adopt_desc_t *info);
190
191/**
192 * lws_adopt_socket_readbuf() - adopt foreign socket and first rx as if listen socket accepted it
193 * for the default vhost of context.
194 * \param context: lws context
195 * \param accept_fd: fd of already-accepted socket to adopt
196 * \param readbuf: NULL or pointer to data that must be drained before reading from
197 * accept_fd
198 * \param len: The length of the data held at \p readbuf
199 *
200 * Either returns new wsi bound to accept_fd, or closes accept_fd and
201 * returns NULL, having cleaned up any new wsi pieces.
202 *
203 * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
204 * to ws or just serve http.
205 *
206 * If your external code did not already read from the socket, you can use
207 * lws_adopt_socket() instead.
208 *
209 * This api is guaranteed to use the data at \p readbuf first, before reading from
210 * the socket.
211 *
212 * \p readbuf is limited to the size of the ah rx buf, currently 2048 bytes.
213 */
214LWS_VISIBLE LWS_EXTERN struct lws *
215lws_adopt_socket_readbuf(struct lws_context *context, lws_sockfd_type accept_fd,
216 const char *readbuf, size_t len);
217/**
218 * lws_adopt_socket_vhost_readbuf() - adopt foreign socket and first rx as if listen socket
219 * accepted it for vhost.
220 * \param vhost: lws vhost
221 * \param accept_fd: fd of already-accepted socket to adopt
222 * \param readbuf: NULL or pointer to data that must be drained before reading from accept_fd
223 * \param len: The length of the data held at \p readbuf
224 *
225 * Either returns new wsi bound to accept_fd, or closes accept_fd and
226 * returns NULL, having cleaned up any new wsi pieces.
227 *
228 * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
229 * to ws or just serve http.
230 *
231 * If your external code did not already read from the socket, you can use
232 * lws_adopt_socket() instead.
233 *
234 * This api is guaranteed to use the data at \p readbuf first, before reading from
235 * the socket.
236 *
237 * \p readbuf is limited to the size of the ah rx buf, currently 2048 bytes.
238 */
239LWS_VISIBLE LWS_EXTERN struct lws *
240lws_adopt_socket_vhost_readbuf(struct lws_vhost *vhost,
241 lws_sockfd_type accept_fd, const char *readbuf,
242 size_t len);
243
244#define LWS_CAUDP_BIND (1 << 0)
245#define LWS_CAUDP_BROADCAST (1 << 1)
246#define LWS_CAUDP_PF_PACKET (1 << 2)
247
248#if defined(LWS_WITH_UDP)
249/**
250 * lws_create_adopt_udp() - create, bind and adopt a UDP socket
251 *
252 * \param vhost: lws vhost
253 * \param ads: NULL or address to do dns lookup on
254 * \param port: UDP port to bind to, -1 means unbound
255 * \param flags: 0 or LWS_CAUDP_NO_BIND
256 * \param protocol_name: Name of protocol on vhost to bind wsi to
257 * \param ifname: NULL, for network interface name to bind socket to
258 * \param parent_wsi: NULL or parent wsi new wsi will be a child of
259 * \param opaque: set created wsi opaque ptr to this
260 * \param retry_policy: NULL for vhost default policy else wsi specific policy
261 * \param fi_wsi_name: NULL, or string to inherit Fault Injection rules in
262 * form "wsi=string/rule". "wsi/rule" faults will be
263 * automatically applied as well. It's done at creation
264 * time so the rules can, eg, inject faults related to
265 * creation.
266 *
267 * Either returns new wsi bound to accept_fd, or closes accept_fd and
268 * returns NULL, having cleaned up any new wsi pieces.
269 * */
270LWS_VISIBLE LWS_EXTERN struct lws *
271lws_create_adopt_udp(struct lws_vhost *vhost, const char *ads, int port,
272 int flags, const char *protocol_name, const char *ifname,
273 struct lws *parent_wsi, void *opaque,
274 const lws_retry_bo_t *retry_policy, const char *fi_wsi_name);
275#endif
276
277
278
279///@}
280