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 * lws_adopt_socket_vhost() - adopt foreign socket as if listen socket accepted
52 * it for vhost
53 *
54 * \param vh: lws vhost
55 * \param accept_fd: fd of already-accepted socket to adopt
56 *
57 * Either returns new wsi bound to accept_fd, or closes accept_fd and
58 * returns NULL, having cleaned up any new wsi pieces.
59 *
60 * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
61 * to ws or just serve http.
62 */
63LWS_VISIBLE LWS_EXTERN struct lws *
64lws_adopt_socket_vhost(struct lws_vhost *vh, lws_sockfd_type accept_fd);
65
66typedef enum {
67 LWS_ADOPT_RAW_FILE_DESC = 0, /* convenience constant */
68 LWS_ADOPT_HTTP = 1, /* flag: absent implies RAW */
69 LWS_ADOPT_SOCKET = 2, /* flag: absent implies file */
70 LWS_ADOPT_ALLOW_SSL = 4, /* flag: use tls */
71 LWS_ADOPT_FLAG_UDP = 16, /* flag: socket is UDP */
72 LWS_ADOPT_FLAG_RAW_PROXY = 32, /* flag: raw proxy */
73
74 LWS_ADOPT_RAW_SOCKET_UDP = LWS_ADOPT_SOCKET | LWS_ADOPT_FLAG_UDP,
75} lws_adoption_type;
76
77typedef union {
78 lws_sockfd_type sockfd;
79 lws_filefd_type filefd;
80} lws_sock_file_fd_type;
81
82#if defined(LWS_ESP_PLATFORM)
83#include <lwip/sockets.h>
84#endif
85
86typedef union {
87#if defined(LWS_WITH_IPV6)
88 struct sockaddr_in6 sa6;
89#else
90#if defined(LWS_ESP_PLATFORM)
91 uint8_t _pad_sa6[28];
92#endif
93#endif
94 struct sockaddr_in sa4;
95} lws_sockaddr46;
96
97#define sa46_sockaddr(_sa46) ((struct sockaddr *)(_sa46))
98
99#if defined(LWS_WITH_IPV6)
100#define sa46_socklen(_sa46) (socklen_t)((_sa46)->sa4.sin_family == AF_INET ? \
101 sizeof(struct sockaddr_in) : \
102 sizeof(struct sockaddr_in6))
103#define sa46_sockport(_sa46, _sp) { if ((_sa46)->sa4.sin_family == AF_INET) \
104 (_sa46)->sa4.sin_port = (_sp); else \
105 (_sa46)->sa6.sin6_port = (_sp); }
106#define sa46_address(_sa46) ((uint8_t *)((_sa46)->sa4.sin_family == AF_INET ? \
107 &_sa46->sa4.sin_addr : &_sa46->sa6.sin6_addr ))
108#else
109#define sa46_socklen(_sa46) (socklen_t)sizeof(struct sockaddr_in)
110#define sa46_sockport(_sa46, _sp) (_sa46)->sa4.sin_port = (_sp)
111#define sa46_address(_sa46) (uint8_t *)&_sa46->sa4.sin_addr
112#endif
113
114#define sa46_address_len(_sa46) ((_sa46)->sa4.sin_family == AF_INET ? 4 : 16)
115
116#if defined(LWS_WITH_UDP)
117struct lws_udp {
118 lws_sockaddr46 sa46;
119 lws_sockaddr46 sa46_pending;
120 uint8_t connected:1;
121};
122#endif
123
124/**
125* lws_adopt_descriptor_vhost() - adopt foreign socket or file descriptor
126* if socket descriptor, should already have been accepted from listen socket
127*
128* \param vh: lws vhost
129* \param type: OR-ed combinations of lws_adoption_type flags
130* \param fd: union with either .sockfd or .filefd set
131* \param vh_prot_name: NULL or vh protocol name to bind raw connection to
132* \param parent: NULL or struct lws to attach new_wsi to as a child
133*
134* Either returns new wsi bound to accept_fd, or closes accept_fd and
135* returns NULL, having cleaned up any new wsi pieces.
136*
137* If LWS_ADOPT_SOCKET is set, LWS adopts the socket in http serving mode, it's
138* ready to accept an upgrade to ws or just serve http.
139*
140* parent may be NULL, if given it should be an existing wsi that will become the
141* parent of the new wsi created by this call.
142*/
143LWS_VISIBLE LWS_EXTERN struct lws *
144lws_adopt_descriptor_vhost(struct lws_vhost *vh, lws_adoption_type type,
145 lws_sock_file_fd_type fd, const char *vh_prot_name,
146 struct lws *parent);
147
148typedef struct lws_adopt_desc {
149 struct lws_vhost *vh; /**< vhost the wsi should belong to */
150 lws_adoption_type type; /**< OR-ed combinations of lws_adoption_type flags */
151 lws_sock_file_fd_type fd; /**< union with either .sockfd or .filefd set */
152 const char *vh_prot_name; /**< NULL or vh protocol name to bind raw connection to */
153 struct lws *parent; /**< NULL or struct lws to attach new_wsi to as a child */
154 void *opaque; /**< opaque pointer to set on created wsi */
155 const char *fi_wsi_name; /**< NULL, or Fault Injection inheritence filter for wsi=string/ context faults */
156} lws_adopt_desc_t;
157
158/**
159* lws_adopt_descriptor_vhost_via_info() - adopt foreign socket or file descriptor
160* if socket descriptor, should already have been accepted from listen socket
161*
162* \param info: the struct containing the parameters
163*
164* - vh: lws vhost
165* - type: OR-ed combinations of lws_adoption_type flags
166* - fd: union with either .sockfd or .filefd set
167* - vh_prot_name: NULL or vh protocol name to bind raw connection to
168* - parent: NULL or struct lws to attach new_wsi to as a child
169* - opaque: opaque pointer to set on created wsi
170*
171* Either returns new wsi bound to accept_fd, or closes accept_fd and
172* returns NULL, having cleaned up any new wsi pieces.
173*
174* If LWS_ADOPT_SOCKET is set, LWS adopts the socket in http serving mode, it's
175* ready to accept an upgrade to ws or just serve http.
176*
177* parent may be NULL, if given it should be an existing wsi that will become the
178* parent of the new wsi created by this call.
179*/
180LWS_VISIBLE LWS_EXTERN struct lws *
181lws_adopt_descriptor_vhost_via_info(const lws_adopt_desc_t *info);
182
183/**
184 * lws_adopt_socket_readbuf() - adopt foreign socket and first rx as if listen socket accepted it
185 * for the default vhost of context.
186 * \param context: lws context
187 * \param accept_fd: fd of already-accepted socket to adopt
188 * \param readbuf: NULL or pointer to data that must be drained before reading from
189 * accept_fd
190 * \param len: The length of the data held at \p readbuf
191 *
192 * Either returns new wsi bound to accept_fd, or closes accept_fd and
193 * returns NULL, having cleaned up any new wsi pieces.
194 *
195 * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
196 * to ws or just serve http.
197 *
198 * If your external code did not already read from the socket, you can use
199 * lws_adopt_socket() instead.
200 *
201 * This api is guaranteed to use the data at \p readbuf first, before reading from
202 * the socket.
203 *
204 * \p readbuf is limited to the size of the ah rx buf, currently 2048 bytes.
205 */
206LWS_VISIBLE LWS_EXTERN struct lws *
207lws_adopt_socket_readbuf(struct lws_context *context, lws_sockfd_type accept_fd,
208 const char *readbuf, size_t len);
209/**
210 * lws_adopt_socket_vhost_readbuf() - adopt foreign socket and first rx as if listen socket
211 * accepted it for vhost.
212 * \param vhost: lws vhost
213 * \param accept_fd: fd of already-accepted socket to adopt
214 * \param readbuf: NULL or pointer to data that must be drained before reading from accept_fd
215 * \param len: The length of the data held at \p readbuf
216 *
217 * Either returns new wsi bound to accept_fd, or closes accept_fd and
218 * returns NULL, having cleaned up any new wsi pieces.
219 *
220 * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
221 * to ws or just serve http.
222 *
223 * If your external code did not already read from the socket, you can use
224 * lws_adopt_socket() instead.
225 *
226 * This api is guaranteed to use the data at \p readbuf first, before reading from
227 * the socket.
228 *
229 * \p readbuf is limited to the size of the ah rx buf, currently 2048 bytes.
230 */
231LWS_VISIBLE LWS_EXTERN struct lws *
232lws_adopt_socket_vhost_readbuf(struct lws_vhost *vhost,
233 lws_sockfd_type accept_fd, const char *readbuf,
234 size_t len);
235
236#define LWS_CAUDP_BIND (1 << 0)
237#define LWS_CAUDP_BROADCAST (1 << 1)
238#define LWS_CAUDP_PF_PACKET (1 << 2)
239
240#if defined(LWS_WITH_UDP)
241/**
242 * lws_create_adopt_udp() - create, bind and adopt a UDP socket
243 *
244 * \param vhost: lws vhost
245 * \param ads: NULL or address to do dns lookup on
246 * \param port: UDP port to bind to, -1 means unbound
247 * \param flags: 0 or LWS_CAUDP_NO_BIND
248 * \param protocol_name: Name of protocol on vhost to bind wsi to
249 * \param ifname: NULL, for network interface name to bind socket to
250 * \param parent_wsi: NULL or parent wsi new wsi will be a child of
251 * \param opaque: set created wsi opaque ptr to this
252 * \param retry_policy: NULL for vhost default policy else wsi specific policy
253 * \param fi_wsi_name: NULL, or string to inherit Fault Injection rules in
254 * form "wsi=string/rule". "wsi/rule" faults will be
255 * automatically applied as well. It's done at creation
256 * time so the rules can, eg, inject faults related to
257 * creation.
258 *
259 * Either returns new wsi bound to accept_fd, or closes accept_fd and
260 * returns NULL, having cleaned up any new wsi pieces.
261 * */
262LWS_VISIBLE LWS_EXTERN struct lws *
263lws_create_adopt_udp(struct lws_vhost *vhost, const char *ads, int port,
264 int flags, const char *protocol_name, const char *ifname,
265 struct lws *parent_wsi, void *opaque,
266 const lws_retry_bo_t *retry_policy, const char *fi_wsi_name);
267#endif
268
269
270
271///@}
272