include/libwebsockets/lws-adopt.h

   1 /*
   2  * libwebsockets - small server side websockets and web server implementation
   3  *
   4  * Copyright (C) 2010-2018 Andy Green <andy@warmcat.com>
   5  *
   6  *  This library is free software; you can redistribute it and/or
   7  *  modify it under the terms of the GNU Lesser General Public
   8  *  License as published by the Free Software Foundation:
   9  *  version 2.1 of the License.
  10  *
  11  *  This library is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  *  Lesser General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU Lesser General Public
  17  *  License along with this library; if not, write to the Free Software
  18  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  19  *  MA  02110-1301  USA
  20  *
  21  * included from libwebsockets.h
  22  */
  23
  24 /** \defgroup sock-adopt Socket adoption helpers
  25  * ##Socket adoption helpers
  26  *
  27  * When integrating with an external app with its own event loop, these can
  28  * be used to accept connections from someone else's listening socket.
  29  *
  30  * When using lws own event loop, these are not needed.
  31  */
  32 ///@{
  33
  34 /**
  35  * lws_adopt_socket() - adopt foreign socket as if listen socket accepted it
  36  * for the default vhost of context.
  37  *
  38  * \param context: lws context
  39  * \param accept_fd: fd of already-accepted socket to adopt
  40  *
  41  * Either returns new wsi bound to accept_fd, or closes accept_fd and
  42  * returns NULL, having cleaned up any new wsi pieces.
  43  *
  44  * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
  45  * to ws or just serve http.
  46  */
  47 LWS_VISIBLE LWS_EXTERN struct lws *
  48 lws_adopt_socket(struct lws_context *context, lws_sockfd_type accept_fd);
  49 /**
  50  * lws_adopt_socket_vhost() - adopt foreign socket as if listen socket accepted
  51  * it for vhost
  52  *
  53  * \param vh: lws vhost
  54  * \param accept_fd: fd of already-accepted socket to adopt
  55  *
  56  * Either returns new wsi bound to accept_fd, or closes accept_fd and
  57  * returns NULL, having cleaned up any new wsi pieces.
  58  *
  59  * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
  60  * to ws or just serve http.
  61  */
  62 LWS_VISIBLE LWS_EXTERN struct lws *
  63 lws_adopt_socket_vhost(struct lws_vhost *vh, lws_sockfd_type accept_fd);
  64
  65 typedef enum {
  66         LWS_ADOPT_RAW_FILE_DESC = 0,    /* convenience constant */
  67         LWS_ADOPT_HTTP = 1,             /* flag: absent implies RAW */
  68         LWS_ADOPT_SOCKET = 2,           /* flag: absent implies file descr */
  69         LWS_ADOPT_ALLOW_SSL = 4,        /* flag: if set requires LWS_ADOPT_SOCKET */
  70         LWS_ADOPT_FLAG_UDP = 16,        /* flag: socket is UDP */
  71         LWS_ADOPT_FLAG_RAW_PROXY = 32,  /* flag: raw proxy */
  72
  73         LWS_ADOPT_RAW_SOCKET_UDP = LWS_ADOPT_SOCKET | LWS_ADOPT_FLAG_UDP,
  74 } lws_adoption_type;
  75
  76 typedef union {
  77         lws_sockfd_type sockfd;
  78         lws_filefd_type filefd;
  79 } lws_sock_file_fd_type;
  80
  81 #if !defined(LWS_WITH_ESP32) && !defined(LWS_PLAT_OPTEE)
  82 struct lws_udp {
  83         struct sockaddr sa;
  84         socklen_t salen;
  85
  86         struct sockaddr sa_pending;
  87         socklen_t salen_pending;
  88 };
  89 #endif
  90
  91 /**
  92 * lws_adopt_descriptor_vhost() - adopt foreign socket or file descriptor
  93 * if socket descriptor, should already have been accepted from listen socket
  94 *
  95 * \param vh: lws vhost
  96 * \param type: OR-ed combinations of lws_adoption_type flags
  97 * \param fd: union with either .sockfd or .filefd set
  98 * \param vh_prot_name: NULL or vh protocol name to bind raw connection to
  99 * \param parent: NULL or struct lws to attach new_wsi to as a child
 100 *
 101 * Either returns new wsi bound to accept_fd, or closes accept_fd and
 102 * returns NULL, having cleaned up any new wsi pieces.
 103 *
 104 * If LWS_ADOPT_SOCKET is set, LWS adopts the socket in http serving mode, it's
 105 * ready to accept an upgrade to ws or just serve http.
 106 *
 107 * parent may be NULL, if given it should be an existing wsi that will become the
 108 * parent of the new wsi created by this call.
 109 */
 110 LWS_VISIBLE LWS_EXTERN struct lws *
 111 lws_adopt_descriptor_vhost(struct lws_vhost *vh, lws_adoption_type type,
 112                            lws_sock_file_fd_type fd, const char *vh_prot_name,
 113                            struct lws *parent);
 114
 115 /**
 116  * lws_adopt_socket_readbuf() - adopt foreign socket and first rx as if listen socket accepted it
 117  * for the default vhost of context.
 118  * \param context:      lws context
 119  * \param accept_fd:    fd of already-accepted socket to adopt
 120  * \param readbuf:      NULL or pointer to data that must be drained before reading from
 121  *              accept_fd
 122  * \param len:  The length of the data held at \p readbuf
 123  *
 124  * Either returns new wsi bound to accept_fd, or closes accept_fd and
 125  * returns NULL, having cleaned up any new wsi pieces.
 126  *
 127  * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
 128  * to ws or just serve http.
 129  *
 130  * If your external code did not already read from the socket, you can use
 131  * lws_adopt_socket() instead.
 132  *
 133  * This api is guaranteed to use the data at \p readbuf first, before reading from
 134  * the socket.
 135  *
 136  * \p readbuf is limited to the size of the ah rx buf, currently 2048 bytes.
 137  */
 138 LWS_VISIBLE LWS_EXTERN struct lws *
 139 lws_adopt_socket_readbuf(struct lws_context *context, lws_sockfd_type accept_fd,
 140                          const char *readbuf, size_t len);
 141 /**
 142  * lws_adopt_socket_vhost_readbuf() - adopt foreign socket and first rx as if listen socket
 143  * accepted it for vhost.
 144  * \param vhost:        lws vhost
 145  * \param accept_fd:    fd of already-accepted socket to adopt
 146  * \param readbuf:      NULL or pointer to data that must be drained before reading from accept_fd
 147  * \param len:          The length of the data held at \p readbuf
 148  *
 149  * Either returns new wsi bound to accept_fd, or closes accept_fd and
 150  * returns NULL, having cleaned up any new wsi pieces.
 151  *
 152  * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
 153  * to ws or just serve http.
 154  *
 155  * If your external code did not already read from the socket, you can use
 156  * lws_adopt_socket() instead.
 157  *
 158  * This api is guaranteed to use the data at \p readbuf first, before reading from
 159  * the socket.
 160  *
 161  * \p readbuf is limited to the size of the ah rx buf, currently 2048 bytes.
 162  */
 163 LWS_VISIBLE LWS_EXTERN struct lws *
 164 lws_adopt_socket_vhost_readbuf(struct lws_vhost *vhost,
 165                                lws_sockfd_type accept_fd, const char *readbuf,
 166                                size_t len);
 167
 168 #define LWS_CAUDP_BIND 1
 169
 170 /**
 171  * lws_create_adopt_udp() - create, bind and adopt a UDP socket
 172  *
 173  * \param vhost:         lws vhost
 174  * \param port:          UDP port to bind to, -1 means unbound
 175  * \param flags:         0 or LWS_CAUDP_NO_BIND
 176  * \param protocol_name: Name of protocol on vhost to bind wsi to
 177  * \param parent_wsi:    NULL or parent wsi new wsi will be a child of
 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 LWS_VISIBLE LWS_EXTERN struct lws *
 183 lws_create_adopt_udp(struct lws_vhost *vhost, int port, int flags,
 184                      const char *protocol_name, struct lws *parent_wsi);
 185 ///@}