lib/libwebsockets.h

   1 /*
   2  * libwebsockets - small server side websockets and web server implementation
   3  *
   4  * Copyright (C) 2010-2016 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
  22 #ifndef LIBWEBSOCKET_H_3060898B846849FF9F88F5DB59B5950C
  23 #define LIBWEBSOCKET_H_3060898B846849FF9F88F5DB59B5950C
  24
  25 #ifdef __cplusplus
  26 #include <cstddef>
  27 #include <cstdarg>
  28 #ifdef MBED_OPERATORS
  29 #include "mbed-drivers/mbed.h"
  30 #include "sal-iface-eth/EthernetInterface.h"
  31 #include "sockets/TCPListener.h"
  32 #include "sal-stack-lwip/lwipv4_init.h"
  33
  34 namespace {
  35 }
  36 using namespace mbed::Sockets::v0;
  37
  38
  39 struct sockaddr_in;
  40 struct lws;
  41
  42 class lws_conn {
  43         public:
  44         lws_conn():
  45                 ts(NULL),
  46                 wsi(NULL),
  47                 writeable(1),
  48                 awaiting_on_writeable(0)
  49         {
  50         }
  51
  52 public:
  53         void set_wsi(struct lws *_wsi) { wsi = _wsi; }
  54         int actual_onRX(Socket *s);
  55         void onRX(Socket *s);
  56         void onError(Socket *s, socket_error_t err);
  57         void onDisconnect(TCPStream *s);
  58         void onSent(Socket *s, uint16_t len);
  59         void serialized_writeable(struct lws *wsi);
  60
  61 public:
  62         TCPStream *ts;
  63
  64 public:
  65         struct lws *wsi;
  66         char writeable;
  67         char awaiting_on_writeable;
  68 };
  69
  70 class lws_conn_listener : lws_conn {
  71 public:
  72         lws_conn_listener():
  73                 srv(SOCKET_STACK_LWIP_IPV4)
  74         {
  75                 srv.setOnError(TCPStream::ErrorHandler_t(this,
  76                                 &lws_conn_listener::onError));
  77         }
  78
  79         void start(const uint16_t port);
  80
  81 protected:
  82         void onRX(Socket *s);
  83         void onError(Socket *s, socket_error_t err);
  84         void onIncoming(TCPListener *s, void *impl);
  85         void onDisconnect(TCPStream *s);
  86
  87 public:
  88         TCPListener srv;
  89 };
  90
  91 #endif
  92
  93 extern "C" {
  94 #else
  95 #include <stdarg.h>
  96 #endif
  97
  98 #ifdef MBED_OPERATORS
  99 struct sockaddr_in;
 100 #define LWS_POSIX 0
 101 #else
 102 #define LWS_POSIX 1
 103 #endif
 104
 105 #include "lws_config.h"
 106
 107 #if defined(WIN32) || defined(_WIN32)
 108 #ifndef WIN32_LEAN_AND_MEAN
 109 #define WIN32_LEAN_AND_MEAN
 110 #endif
 111
 112 #include <winsock2.h>
 113 #include <ws2tcpip.h>
 114 #include <stddef.h>
 115 #include <basetsd.h>
 116 #ifndef _WIN32_WCE
 117 #include <stdint.h>
 118 #include <fcntl.h>
 119 #else
 120 #define _O_RDONLY       0x0000
 121 #define O_RDONLY        _O_RDONLY
 122 #endif
 123
 124 // Visual studio older than 2015 and WIN_CE has only _stricmp
 125 #if (defined(_MSC_VER) && _MSC_VER < 1900) || defined(_WIN32_WCE)
 126 #define strcasecmp _stricmp
 127 #else
 128 #define strcasecmp stricmp
 129 #endif
 130 #define getdtablesize() 30000
 131
 132 #define LWS_INLINE __inline
 133 #define LWS_VISIBLE
 134 #define LWS_WARN_UNUSED_RESULT
 135 #define LWS_WARN_DEPRECATED
 136
 137 #ifdef LWS_DLL
 138 #ifdef LWS_INTERNAL
 139 #define LWS_EXTERN extern __declspec(dllexport)
 140 #else
 141 #define LWS_EXTERN extern __declspec(dllimport)
 142 #endif
 143 #else
 144 #define LWS_EXTERN
 145 #endif
 146
 147 #define LWS_INVALID_FILE INVALID_HANDLE_VALUE
 148 #define LWS_O_RDONLY _O_RDONLY
 149
 150 #if !defined(_MSC_VER) || _MSC_VER < 1900 /* Visual Studio 2015 already defines this in <stdio.h> */
 151 #define snprintf _snprintf
 152 #endif
 153
 154 #ifndef __func__
 155 #define __func__ __FUNCTION__
 156 #endif
 157
 158 #else /* NOT WIN32 */
 159 #include <unistd.h>
 160
 161 #if defined(__NetBSD__) || defined(__FreeBSD__)
 162 #include <netinet/in.h>
 163 #endif
 164
 165 #define LWS_INLINE inline
 166 #define LWS_O_RDONLY O_RDONLY
 167
 168 #ifndef MBED_OPERATORS
 169 #include <poll.h>
 170 #include <netdb.h>
 171 #define LWS_INVALID_FILE -1
 172 #else
 173 #define getdtablesize() (20)
 174 #define LWS_INVALID_FILE NULL
 175 #endif
 176
 177 #if defined(__GNUC__)
 178
 179 /* warn_unused_result attribute only supported by GCC 3.4 or later */
 180 #if __GNUC__ >= 4 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
 181 #define LWS_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
 182 #else
 183 #define LWS_WARN_UNUSED_RESULT
 184 #endif
 185
 186 #define LWS_VISIBLE __attribute__((visibility("default")))
 187 #define LWS_WARN_DEPRECATED __attribute__ ((deprecated))
 188 #else
 189 #define LWS_VISIBLE
 190 #define LWS_WARN_UNUSED_RESULT
 191 #define LWS_WARN_DEPRECATED
 192 #endif
 193
 194 #if defined(__ANDROID__)
 195 #include <unistd.h>
 196 #define getdtablesize() sysconf(_SC_OPEN_MAX)
 197 #endif
 198
 199 #endif
 200
 201 #ifdef LWS_USE_LIBEV
 202 #include <ev.h>
 203 #endif /* LWS_USE_LIBEV */
 204 #ifdef LWS_USE_LIBUV
 205 #include <uv.h>
 206 #endif /* LWS_USE_LIBUV */
 207
 208 #ifndef LWS_EXTERN
 209 #define LWS_EXTERN extern
 210 #endif
 211
 212 #ifdef _WIN32
 213 #define random rand
 214 #else
 215 #include <sys/time.h>
 216 #include <unistd.h>
 217 #endif
 218
 219 #ifdef LWS_OPENSSL_SUPPORT
 220
 221 #ifdef USE_WOLFSSL
 222 #ifdef USE_OLD_CYASSL
 223 #include <cyassl/openssl/ssl.h>
 224 #include <cyassl/error-ssl.h>
 225 #else
 226 #include <wolfssl/openssl/ssl.h>
 227 #include <wolfssl/error-ssl.h>
 228 #endif /* not USE_OLD_CYASSL */
 229 #else
 230 #if defined(LWS_USE_POLARSSL)
 231 #include <polarssl/ssl.h>
 232 struct lws_polarssl_context {
 233         x509_crt ca;
 234         x509_crt certificate;
 235         rsa_context key;
 236 };
 237 typedef struct lws_polarssl_context SSL_CTX;
 238 typedef ssl_context SSL;
 239 #else
 240 #if defined(LWS_USE_MBEDTLS)
 241 #include <mbedtls/ssl.h>
 242 #else
 243 #include <openssl/ssl.h>
 244 #include <openssl/err.h>
 245 #endif /* not USE_MBEDTLS */
 246 #endif /* not USE_POLARSSL */
 247 #endif /* not USE_WOLFSSL */
 248 #endif
 249
 250
 251 #define CONTEXT_PORT_NO_LISTEN -1
 252
 253 enum lws_log_levels {
 254         LLL_ERR = 1 << 0,
 255         LLL_WARN = 1 << 1,
 256         LLL_NOTICE = 1 << 2,
 257         LLL_INFO = 1 << 3,
 258         LLL_DEBUG = 1 << 4,
 259         LLL_PARSER = 1 << 5,
 260         LLL_HEADER = 1 << 6,
 261         LLL_EXT = 1 << 7,
 262         LLL_CLIENT = 1 << 8,
 263         LLL_LATENCY = 1 << 9,
 264
 265         LLL_COUNT = 10 /* set to count of valid flags */
 266 };
 267
 268 LWS_VISIBLE LWS_EXTERN void _lws_log(int filter, const char *format, ...);
 269 LWS_VISIBLE LWS_EXTERN void _lws_logv(int filter, const char *format, va_list vl);
 270 LWS_VISIBLE LWS_EXTERN int
 271 lwsl_timestamp(int level, char *p, int len);
 272
 273 /* notice, warn and log are always compiled in */
 274 #define lwsl_notice(...) _lws_log(LLL_NOTICE, __VA_ARGS__)
 275 #define lwsl_warn(...) _lws_log(LLL_WARN, __VA_ARGS__)
 276 #define lwsl_err(...) _lws_log(LLL_ERR, __VA_ARGS__)
 277 /*
 278  *  weaker logging can be deselected at configure time using --disable-debug
 279  *  that gets rid of the overhead of checking while keeping _warn and _err
 280  *  active
 281  */
 282 #ifdef _DEBUG
 283
 284 #define lwsl_info(...) _lws_log(LLL_INFO, __VA_ARGS__)
 285 #define lwsl_debug(...) _lws_log(LLL_DEBUG, __VA_ARGS__)
 286 #define lwsl_parser(...) _lws_log(LLL_PARSER, __VA_ARGS__)
 287 #define lwsl_header(...)  _lws_log(LLL_HEADER, __VA_ARGS__)
 288 #define lwsl_ext(...)  _lws_log(LLL_EXT, __VA_ARGS__)
 289 #define lwsl_client(...) _lws_log(LLL_CLIENT, __VA_ARGS__)
 290 #define lwsl_latency(...) _lws_log(LLL_LATENCY, __VA_ARGS__)
 291 LWS_VISIBLE LWS_EXTERN void lwsl_hexdump(void *buf, size_t len);
 292
 293 #else /* no debug */
 294
 295 #define lwsl_info(...) {}
 296 #define lwsl_debug(...) {}
 297 #define lwsl_parser(...) {}
 298 #define lwsl_header(...) {}
 299 #define lwsl_ext(...) {}
 300 #define lwsl_client(...) {}
 301 #define lwsl_latency(...) {}
 302 #define lwsl_hexdump(a, b)
 303
 304 #endif
 305
 306 #include <stddef.h>
 307
 308 #ifndef lws_container_of
 309 #define lws_container_of(P,T,M) ((T *)((char *)(P) - offsetof(T, M)))
 310 #endif
 311
 312
 313 struct lws;
 314 #define ARRAY_SIZE(x) (sizeof(x) / sizeof(x[0]))
 315
 316 /* api change list for user code to test against */
 317
 318 #define LWS_FEATURE_SERVE_HTTP_FILE_HAS_OTHER_HEADERS_ARG
 319
 320 /* the struct lws_protocols has the id field present */
 321 #define LWS_FEATURE_PROTOCOLS_HAS_ID_FIELD
 322
 323 /* you can call lws_get_peer_write_allowance */
 324 #define LWS_FEATURE_PROTOCOLS_HAS_PEER_WRITE_ALLOWANCE
 325
 326 /* extra parameter introduced in 917f43ab821 */
 327 #define LWS_FEATURE_SERVE_HTTP_FILE_HAS_OTHER_HEADERS_LEN
 328
 329 /* File operations stuff exists */
 330 #define LWS_FEATURE_FOPS
 331
 332 /*
 333  * NOTE: These public enums are part of the abi.  If you want to add one,
 334  * add it at where specified so existing users are unaffected.
 335  */
 336 enum lws_context_options {
 337         LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT     = (1 << 1) |
 338                                                                   (1 << 12),
 339         LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME            = (1 << 2),
 340         LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT             = (1 << 3) |
 341                                                                   (1 << 12),
 342         LWS_SERVER_OPTION_LIBEV                                 = (1 << 4),
 343         LWS_SERVER_OPTION_DISABLE_IPV6                          = (1 << 5),
 344         LWS_SERVER_OPTION_DISABLE_OS_CA_CERTS                   = (1 << 6),
 345         LWS_SERVER_OPTION_PEER_CERT_NOT_REQUIRED                = (1 << 7),
 346         LWS_SERVER_OPTION_VALIDATE_UTF8                         = (1 << 8),
 347         LWS_SERVER_OPTION_SSL_ECDH                              = (1 << 9) |
 348                                                                   (1 << 12),
 349         LWS_SERVER_OPTION_LIBUV                                 = (1 << 10),
 350         LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS                = (1 << 11) |
 351                                                                   (1 << 3) |
 352                                                                   (1 << 12),
 353         LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT                    = (1 << 12),
 354         LWS_SERVER_OPTION_EXPLICIT_VHOSTS                       = (1 << 13),
 355         LWS_SERVER_OPTION_UNIX_SOCK                             = (1 << 14),
 356         LWS_SERVER_OPTION_STS                                   = (1 << 15),
 357
 358         /****** add new things just above ---^ ******/
 359 };
 360
 361 #define lws_check_opt(c, f) (((c) & (f)) == (f))
 362
 363 /*
 364  * NOTE: These public enums are part of the abi.  If you want to add one,
 365  * add it at where specified so existing users are unaffected.
 366  */
 367 enum lws_callback_reasons {
 368         LWS_CALLBACK_ESTABLISHED                                =  0,
 369         LWS_CALLBACK_CLIENT_CONNECTION_ERROR                    =  1,
 370         LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH                =  2,
 371         LWS_CALLBACK_CLIENT_ESTABLISHED                         =  3,
 372         LWS_CALLBACK_CLOSED                                     =  4,
 373         LWS_CALLBACK_CLOSED_HTTP                                =  5,
 374         LWS_CALLBACK_RECEIVE                                    =  6,
 375         LWS_CALLBACK_RECEIVE_PONG                               =  7,
 376         LWS_CALLBACK_CLIENT_RECEIVE                             =  8,
 377         LWS_CALLBACK_CLIENT_RECEIVE_PONG                        =  9,
 378         LWS_CALLBACK_CLIENT_WRITEABLE                           = 10,
 379         LWS_CALLBACK_SERVER_WRITEABLE                           = 11,
 380         LWS_CALLBACK_HTTP                                       = 12,
 381         LWS_CALLBACK_HTTP_BODY                                  = 13,
 382         LWS_CALLBACK_HTTP_BODY_COMPLETION                       = 14,
 383         LWS_CALLBACK_HTTP_FILE_COMPLETION                       = 15,
 384         LWS_CALLBACK_HTTP_WRITEABLE                             = 16,
 385         LWS_CALLBACK_FILTER_NETWORK_CONNECTION                  = 17,
 386         LWS_CALLBACK_FILTER_HTTP_CONNECTION                     = 18,
 387         LWS_CALLBACK_SERVER_NEW_CLIENT_INSTANTIATED             = 19,
 388         LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION                 = 20,
 389         LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS     = 21,
 390         LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS     = 22,
 391         LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION   = 23,
 392         LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER             = 24,
 393         LWS_CALLBACK_CONFIRM_EXTENSION_OKAY                     = 25,
 394         LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED         = 26,
 395         LWS_CALLBACK_PROTOCOL_INIT                              = 27,
 396         LWS_CALLBACK_PROTOCOL_DESTROY                           = 28,
 397         LWS_CALLBACK_WSI_CREATE /* always protocol[0] */        = 29,
 398         LWS_CALLBACK_WSI_DESTROY /* always protocol[0] */       = 30,
 399         LWS_CALLBACK_GET_THREAD_ID                              = 31,
 400
 401         /* external poll() management support */
 402         LWS_CALLBACK_ADD_POLL_FD                                = 32,
 403         LWS_CALLBACK_DEL_POLL_FD                                = 33,
 404         LWS_CALLBACK_CHANGE_MODE_POLL_FD                        = 34,
 405         LWS_CALLBACK_LOCK_POLL                                  = 35,
 406         LWS_CALLBACK_UNLOCK_POLL                                = 36,
 407
 408         LWS_CALLBACK_OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY       = 37,
 409         LWS_CALLBACK_WS_PEER_INITIATED_CLOSE                    = 38,
 410
 411         LWS_CALLBACK_WS_EXT_DEFAULTS                            = 39,
 412
 413         LWS_CALLBACK_CGI                                        = 40,
 414         LWS_CALLBACK_CGI_TERMINATED                             = 41,
 415         LWS_CALLBACK_CGI_STDIN_DATA                             = 42,
 416         LWS_CALLBACK_CGI_STDIN_COMPLETED                        = 43,
 417         LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP                    = 44,
 418         LWS_CALLBACK_CLOSED_CLIENT_HTTP                         = 45,
 419         LWS_CALLBACK_RECEIVE_CLIENT_HTTP                        = 46,
 420         LWS_CALLBACK_COMPLETED_CLIENT_HTTP                      = 47,
 421         LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ                   = 48,
 422
 423         /****** add new things just above ---^ ******/
 424
 425         LWS_CALLBACK_USER = 1000, /* user code can use any including / above */
 426 };
 427
 428
 429 #if defined(_WIN32)
 430 typedef SOCKET lws_sockfd_type;
 431 typedef HANDLE lws_filefd_type;
 432 #define lws_sockfd_valid(sfd) (!!sfd)
 433 struct lws_pollfd {
 434         lws_sockfd_type fd;
 435         SHORT events;
 436         SHORT revents;
 437 };
 438 #else
 439
 440 #if defined(MBED_OPERATORS)
 441 /* it's a class lws_conn * */
 442 typedef void * lws_sockfd_type;
 443 typedef void * lws_filefd_type;
 444 #define lws_sockfd_valid(sfd) (!!sfd)
 445 struct pollfd {
 446         lws_sockfd_type fd;
 447         short events;
 448         short revents;
 449 };
 450 #define POLLIN          0x0001
 451 #define POLLPRI         0x0002
 452 #define POLLOUT         0x0004
 453 #define POLLERR         0x0008
 454 #define POLLHUP         0x0010
 455 #define POLLNVAL        0x0020
 456
 457 struct lws;
 458
 459 void * mbed3_create_tcp_stream_socket(void);
 460 void mbed3_delete_tcp_stream_socket(void *sockfd);
 461 void mbed3_tcp_stream_bind(void *sock, int port, struct lws *);
 462 void mbed3_tcp_stream_accept(void *sock, struct lws *);
 463 #else
 464 typedef int lws_sockfd_type;
 465 typedef int lws_filefd_type;
 466 #define lws_sockfd_valid(sfd) (sfd >= 0)
 467 #endif
 468
 469 #define lws_pollfd pollfd
 470 #endif
 471
 472 /* argument structure for all external poll related calls
 473  * passed in via 'in'
 474  */
 475 struct lws_pollargs {
 476         lws_sockfd_type fd;             /* applicable socket descriptor */
 477         int events;                     /* the new event mask */
 478         int prev_events;                /* the previous event mask */
 479 };
 480
 481 /**
 482  * struct lws_plat_file_ops - Platform-specific file operations
 483  *
 484  * These provide platform-agnostic ways to deal with filesystem access in the
 485  * library and in the user code.
 486  *
 487  * @open:               Open file (always binary access if plat supports it)
 488  *                       filelen is filled on exit to be the length of the file
 489  *                       flags should be set to O_RDONLY or O_RDWR
 490  * @close:              Close file
 491  * @seek_cur:           Seek from current position
 492  * @read:               Read fron file *amount is set on exit to amount read
 493  * @write:              Write to file *amount is set on exit as amount written
 494  */
 495 struct lws_plat_file_ops {
 496         lws_filefd_type (*open)(struct lws *wsi, const char *filename,
 497                                 unsigned long *filelen, int flags);
 498         int (*close)(struct lws *wsi, lws_filefd_type fd);
 499         unsigned long (*seek_cur)(struct lws *wsi, lws_filefd_type fd,
 500                                   long offset_from_cur_pos);
 501         int (*read)(struct lws *wsi, lws_filefd_type fd, unsigned long *amount,
 502                     unsigned char *buf, unsigned long len);
 503         int (*write)(struct lws *wsi, lws_filefd_type fd, unsigned long *amount,
 504                      unsigned char *buf, unsigned long len);
 505
 506         /* Add new things just above here ---^
 507          * This is part of the ABI, don't needlessly break compatibility */
 508 };
 509
 510 /*
 511  * NOTE: These public enums are part of the abi.  If you want to add one,
 512  * add it at where specified so existing users are unaffected.
 513  */
 514 enum lws_extension_callback_reasons {
 515         LWS_EXT_CB_SERVER_CONTEXT_CONSTRUCT             =  0,
 516         LWS_EXT_CB_CLIENT_CONTEXT_CONSTRUCT             =  1,
 517         LWS_EXT_CB_SERVER_CONTEXT_DESTRUCT              =  2,
 518         LWS_EXT_CB_CLIENT_CONTEXT_DESTRUCT              =  3,
 519         LWS_EXT_CB_CONSTRUCT                            =  4,
 520         LWS_EXT_CB_CLIENT_CONSTRUCT                     =  5,
 521         LWS_EXT_CB_CHECK_OK_TO_REALLY_CLOSE             =  6,
 522         LWS_EXT_CB_CHECK_OK_TO_PROPOSE_EXTENSION        =  7,
 523         LWS_EXT_CB_DESTROY                              =  8,
 524         LWS_EXT_CB_DESTROY_ANY_WSI_CLOSING              =  9,
 525         LWS_EXT_CB_ANY_WSI_ESTABLISHED                  = 10,
 526         LWS_EXT_CB_PACKET_RX_PREPARSE                   = 11,
 527         LWS_EXT_CB_PACKET_TX_PRESEND                    = 12,
 528         LWS_EXT_CB_PACKET_TX_DO_SEND                    = 13,
 529         LWS_EXT_CB_HANDSHAKE_REPLY_TX                   = 14,
 530         LWS_EXT_CB_FLUSH_PENDING_TX                     = 15,
 531         LWS_EXT_CB_EXTENDED_PAYLOAD_RX                  = 16,
 532         LWS_EXT_CB_CAN_PROXY_CLIENT_CONNECTION          = 17,
 533         LWS_EXT_CB_1HZ                                  = 18,
 534         LWS_EXT_CB_REQUEST_ON_WRITEABLE                 = 19,
 535         LWS_EXT_CB_IS_WRITEABLE                         = 20,
 536         LWS_EXT_CB_PAYLOAD_TX                           = 21,
 537         LWS_EXT_CB_PAYLOAD_RX                           = 22,
 538         LWS_EXT_CB_OPTION_DEFAULT                       = 23,
 539         LWS_EXT_CB_OPTION_SET                           = 24,
 540         LWS_EXT_CB_OPTION_CONFIRM                       = 25,
 541         LWS_EXT_CB_NAMED_OPTION_SET                     = 26,
 542
 543         /****** add new things just above ---^ ******/
 544 };
 545
 546 /*
 547  * NOTE: These public enums are part of the abi.  If you want to add one,
 548  * add it at where specified so existing users are unaffected.
 549  */
 550 enum lws_write_protocol {
 551         LWS_WRITE_TEXT                                          = 0,
 552         LWS_WRITE_BINARY                                        = 1,
 553         LWS_WRITE_CONTINUATION                                  = 2,
 554         LWS_WRITE_HTTP                                          = 3,
 555
 556         /* special 04+ opcodes */
 557
 558         /* LWS_WRITE_CLOSE is handled by lws_close_reason() */
 559         LWS_WRITE_PING                                          = 5,
 560         LWS_WRITE_PONG                                          = 6,
 561
 562         /* Same as write_http but we know this write ends the transaction */
 563         LWS_WRITE_HTTP_FINAL                                    = 7,
 564
 565         /* HTTP2 */
 566
 567         LWS_WRITE_HTTP_HEADERS                                  = 8,
 568
 569         /****** add new things just above ---^ ******/
 570
 571         /* flags */
 572
 573         LWS_WRITE_NO_FIN = 0x40,
 574         /*
 575          * client packet payload goes out on wire unmunged
 576          * only useful for security tests since normal servers cannot
 577          * decode the content if used
 578          */
 579         LWS_WRITE_CLIENT_IGNORE_XOR_MASK = 0x80
 580 };
 581
 582 /*
 583  * you need these to look at headers that have been parsed if using the
 584  * LWS_CALLBACK_FILTER_CONNECTION callback.  If a header from the enum
 585  * list below is absent, .token = NULL and token_len = 0.  Otherwise .token
 586  * points to .token_len chars containing that header content.
 587  */
 588
 589 struct lws_tokens {
 590         char *token;
 591         int token_len;
 592 };
 593
 594 /*
 595  * these have to be kept in sync with lextable.h / minilex.c
 596  *
 597  * NOTE: These public enums are part of the abi.  If you want to add one,
 598  * add it at where specified so existing users are unaffected.
 599  */
 600 enum lws_token_indexes {
 601         WSI_TOKEN_GET_URI                                       =  0,
 602         WSI_TOKEN_POST_URI                                      =  1,
 603         WSI_TOKEN_OPTIONS_URI                                   =  2,
 604         WSI_TOKEN_HOST                                          =  3,
 605         WSI_TOKEN_CONNECTION                                    =  4,
 606         WSI_TOKEN_UPGRADE                                       =  5,
 607         WSI_TOKEN_ORIGIN                                        =  6,
 608         WSI_TOKEN_DRAFT                                         =  7,
 609         WSI_TOKEN_CHALLENGE                                     =  8,
 610         WSI_TOKEN_EXTENSIONS                                    =  9,
 611         WSI_TOKEN_KEY1                                          = 10,
 612         WSI_TOKEN_KEY2                                          = 11,
 613         WSI_TOKEN_PROTOCOL                                      = 12,
 614         WSI_TOKEN_ACCEPT                                        = 13,
 615         WSI_TOKEN_NONCE                                         = 14,
 616         WSI_TOKEN_HTTP                                          = 15,
 617         WSI_TOKEN_HTTP2_SETTINGS                                = 16,
 618         WSI_TOKEN_HTTP_ACCEPT                                   = 17,
 619         WSI_TOKEN_HTTP_AC_REQUEST_HEADERS                       = 18,
 620         WSI_TOKEN_HTTP_IF_MODIFIED_SINCE                        = 19,
 621         WSI_TOKEN_HTTP_IF_NONE_MATCH                            = 20,
 622         WSI_TOKEN_HTTP_ACCEPT_ENCODING                          = 21,
 623         WSI_TOKEN_HTTP_ACCEPT_LANGUAGE                          = 22,
 624         WSI_TOKEN_HTTP_PRAGMA                                   = 23,
 625         WSI_TOKEN_HTTP_CACHE_CONTROL                            = 24,
 626         WSI_TOKEN_HTTP_AUTHORIZATION                            = 25,
 627         WSI_TOKEN_HTTP_COOKIE                                   = 26,
 628         WSI_TOKEN_HTTP_CONTENT_LENGTH                           = 27,
 629         WSI_TOKEN_HTTP_CONTENT_TYPE                             = 28,
 630         WSI_TOKEN_HTTP_DATE                                     = 29,
 631         WSI_TOKEN_HTTP_RANGE                                    = 30,
 632         WSI_TOKEN_HTTP_REFERER                                  = 31,
 633         WSI_TOKEN_KEY                                           = 32,
 634         WSI_TOKEN_VERSION                                       = 33,
 635         WSI_TOKEN_SWORIGIN                                      = 34,
 636
 637         WSI_TOKEN_HTTP_COLON_AUTHORITY                          = 35,
 638         WSI_TOKEN_HTTP_COLON_METHOD                             = 36,
 639         WSI_TOKEN_HTTP_COLON_PATH                               = 37,
 640         WSI_TOKEN_HTTP_COLON_SCHEME                             = 38,
 641         WSI_TOKEN_HTTP_COLON_STATUS                             = 39,
 642
 643         WSI_TOKEN_HTTP_ACCEPT_CHARSET                           = 40,
 644         WSI_TOKEN_HTTP_ACCEPT_RANGES                            = 41,
 645         WSI_TOKEN_HTTP_ACCESS_CONTROL_ALLOW_ORIGIN              = 42,
 646         WSI_TOKEN_HTTP_AGE                                      = 43,
 647         WSI_TOKEN_HTTP_ALLOW                                    = 44,
 648         WSI_TOKEN_HTTP_CONTENT_DISPOSITION                      = 45,
 649         WSI_TOKEN_HTTP_CONTENT_ENCODING                         = 46,
 650         WSI_TOKEN_HTTP_CONTENT_LANGUAGE                         = 47,
 651         WSI_TOKEN_HTTP_CONTENT_LOCATION                         = 48,
 652         WSI_TOKEN_HTTP_CONTENT_RANGE                            = 49,
 653         WSI_TOKEN_HTTP_ETAG                                     = 50,
 654         WSI_TOKEN_HTTP_EXPECT                                   = 51,
 655         WSI_TOKEN_HTTP_EXPIRES                                  = 52,
 656         WSI_TOKEN_HTTP_FROM                                     = 53,
 657         WSI_TOKEN_HTTP_IF_MATCH                                 = 54,
 658         WSI_TOKEN_HTTP_IF_RANGE                                 = 55,
 659         WSI_TOKEN_HTTP_IF_UNMODIFIED_SINCE                      = 56,
 660         WSI_TOKEN_HTTP_LAST_MODIFIED                            = 57,
 661         WSI_TOKEN_HTTP_LINK                                     = 58,
 662         WSI_TOKEN_HTTP_LOCATION                                 = 59,
 663         WSI_TOKEN_HTTP_MAX_FORWARDS                             = 60,
 664         WSI_TOKEN_HTTP_PROXY_AUTHENTICATE                       = 61,
 665         WSI_TOKEN_HTTP_PROXY_AUTHORIZATION                      = 62,
 666         WSI_TOKEN_HTTP_REFRESH                                  = 63,
 667         WSI_TOKEN_HTTP_RETRY_AFTER                              = 64,
 668         WSI_TOKEN_HTTP_SERVER                                   = 65,
 669         WSI_TOKEN_HTTP_SET_COOKIE                               = 66,
 670         WSI_TOKEN_HTTP_STRICT_TRANSPORT_SECURITY                = 67,
 671         WSI_TOKEN_HTTP_TRANSFER_ENCODING                        = 68,
 672         WSI_TOKEN_HTTP_USER_AGENT                               = 69,
 673         WSI_TOKEN_HTTP_VARY                                     = 70,
 674         WSI_TOKEN_HTTP_VIA                                      = 71,
 675         WSI_TOKEN_HTTP_WWW_AUTHENTICATE                         = 72,
 676
 677         WSI_TOKEN_PATCH_URI                                     = 73,
 678         WSI_TOKEN_PUT_URI                                       = 74,
 679         WSI_TOKEN_DELETE_URI                                    = 75,
 680
 681         WSI_TOKEN_HTTP_URI_ARGS                                 = 76,
 682         WSI_TOKEN_PROXY                                         = 77,
 683         WSI_TOKEN_HTTP_X_REAL_IP                                = 78,
 684         WSI_TOKEN_HTTP1_0                                       = 79,
 685
 686         /****** add new things just above ---^ ******/
 687
 688         /* use token storage to stash these internally, not for
 689          * user use */
 690
 691         _WSI_TOKEN_CLIENT_SENT_PROTOCOLS,
 692         _WSI_TOKEN_CLIENT_PEER_ADDRESS,
 693         _WSI_TOKEN_CLIENT_URI,
 694         _WSI_TOKEN_CLIENT_HOST,
 695         _WSI_TOKEN_CLIENT_ORIGIN,
 696         _WSI_TOKEN_CLIENT_METHOD,
 697
 698         /* always last real token index*/
 699         WSI_TOKEN_COUNT,
 700
 701         /* parser state additions, no storage associated */
 702         WSI_TOKEN_NAME_PART,
 703         WSI_TOKEN_SKIPPING,
 704         WSI_TOKEN_SKIPPING_SAW_CR,
 705         WSI_PARSING_COMPLETE,
 706         WSI_INIT_TOKEN_MUXURL,
 707 };
 708
 709 struct lws_token_limits {
 710         unsigned short token_limit[WSI_TOKEN_COUNT];
 711 };
 712
 713 /*
 714  * From RFC 6455
 715    1000
 716
 717       1000 indicates a normal closure, meaning that the purpose for
 718       which the connection was established has been fulfilled.
 719
 720    1001
 721
 722       1001 indicates that an endpoint is "going away", such as a server
 723       going down or a browser having navigated away from a page.
 724
 725    1002
 726
 727       1002 indicates that an endpoint is terminating the connection due
 728       to a protocol error.
 729
 730    1003
 731
 732       1003 indicates that an endpoint is terminating the connection
 733       because it has received a type of data it cannot accept (e.g., an
 734       endpoint that understands only text data MAY send this if it
 735       receives a binary message).
 736
 737    1004
 738
 739       Reserved.  The specific meaning might be defined in the future.
 740
 741    1005
 742
 743       1005 is a reserved value and MUST NOT be set as a status code in a
 744       Close control frame by an endpoint.  It is designated for use in
 745       applications expecting a status code to indicate that no status
 746       code was actually present.
 747
 748    1006
 749
 750       1006 is a reserved value and MUST NOT be set as a status code in a
 751       Close control frame by an endpoint.  It is designated for use in
 752       applications expecting a status code to indicate that the
 753       connection was closed abnormally, e.g., without sending or
 754       receiving a Close control frame.
 755
 756    1007
 757
 758       1007 indicates that an endpoint is terminating the connection
 759       because it has received data within a message that was not
 760       consistent with the type of the message (e.g., non-UTF-8 [RFC3629]
 761       data within a text message).
 762
 763    1008
 764
 765       1008 indicates that an endpoint is terminating the connection
 766       because it has received a message that violates its policy.  This
 767       is a generic status code that can be returned when there is no
 768       other more suitable status code (e.g., 1003 or 1009) or if there
 769       is a need to hide specific details about the policy.
 770
 771    1009
 772
 773       1009 indicates that an endpoint is terminating the connection
 774       because it has received a message that is too big for it to
 775       process.
 776
 777    1010
 778
 779       1010 indicates that an endpoint (client) is terminating the
 780       connection because it has expected the server to negotiate one or
 781       more extension, but the server didn't return them in the response
 782       message of the WebSocket handshake.  The list of extensions that
 783       are needed SHOULD appear in the /reason/ part of the Close frame.
 784       Note that this status code is not used by the server, because it
 785       can fail the WebSocket handshake instead.
 786
 787    1011
 788
 789       1011 indicates that a server is terminating the connection because
 790       it encountered an unexpected condition that prevented it from
 791       fulfilling the request.
 792
 793    1015
 794
 795       1015 is a reserved value and MUST NOT be set as a status code in a
 796       Close control frame by an endpoint.  It is designated for use in
 797       applications expecting a status code to indicate that the
 798       connection was closed due to a failure to perform a TLS handshake
 799       (e.g., the server certificate can't be verified).
 800 */
 801
 802 /*
 803  * NOTE: These public enums are part of the abi.  If you want to add one,
 804  * add it at where specified so existing users are unaffected.
 805  */
 806 enum lws_close_status {
 807         LWS_CLOSE_STATUS_NOSTATUS                               =    0,
 808         LWS_CLOSE_STATUS_NORMAL                                 = 1000,
 809         LWS_CLOSE_STATUS_GOINGAWAY                              = 1001,
 810         LWS_CLOSE_STATUS_PROTOCOL_ERR                           = 1002,
 811         LWS_CLOSE_STATUS_UNACCEPTABLE_OPCODE                    = 1003,
 812         LWS_CLOSE_STATUS_RESERVED                               = 1004,
 813         LWS_CLOSE_STATUS_NO_STATUS                              = 1005,
 814         LWS_CLOSE_STATUS_ABNORMAL_CLOSE                         = 1006,
 815         LWS_CLOSE_STATUS_INVALID_PAYLOAD                        = 1007,
 816         LWS_CLOSE_STATUS_POLICY_VIOLATION                       = 1008,
 817         LWS_CLOSE_STATUS_MESSAGE_TOO_LARGE                      = 1009,
 818         LWS_CLOSE_STATUS_EXTENSION_REQUIRED                     = 1010,
 819         LWS_CLOSE_STATUS_UNEXPECTED_CONDITION                   = 1011,
 820         LWS_CLOSE_STATUS_TLS_FAILURE                            = 1015,
 821
 822         /****** add new things just above ---^ ******/
 823
 824         LWS_CLOSE_STATUS_NOSTATUS_CONTEXT_DESTROY               = 9999,
 825 };
 826
 827 enum http_status {
 828         HTTP_STATUS_OK                                          = 200,
 829         HTTP_STATUS_NO_CONTENT                                  = 204,
 830
 831         HTTP_STATUS_MOVED_PERMANENTLY                           = 301,
 832         HTTP_STATUS_FOUND                                       = 302,
 833         HTTP_STATUS_SEE_OTHER                                   = 303,
 834
 835         HTTP_STATUS_BAD_REQUEST                                 = 400,
 836         HTTP_STATUS_UNAUTHORIZED,
 837         HTTP_STATUS_PAYMENT_REQUIRED,
 838         HTTP_STATUS_FORBIDDEN,
 839         HTTP_STATUS_NOT_FOUND,
 840         HTTP_STATUS_METHOD_NOT_ALLOWED,
 841         HTTP_STATUS_NOT_ACCEPTABLE,
 842         HTTP_STATUS_PROXY_AUTH_REQUIRED,
 843         HTTP_STATUS_REQUEST_TIMEOUT,
 844         HTTP_STATUS_CONFLICT,
 845         HTTP_STATUS_GONE,
 846         HTTP_STATUS_LENGTH_REQUIRED,
 847         HTTP_STATUS_PRECONDITION_FAILED,
 848         HTTP_STATUS_REQ_ENTITY_TOO_LARGE,
 849         HTTP_STATUS_REQ_URI_TOO_LONG,
 850         HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE,
 851         HTTP_STATUS_REQ_RANGE_NOT_SATISFIABLE,
 852         HTTP_STATUS_EXPECTATION_FAILED,
 853
 854         HTTP_STATUS_INTERNAL_SERVER_ERROR                       = 500,
 855         HTTP_STATUS_NOT_IMPLEMENTED,
 856         HTTP_STATUS_BAD_GATEWAY,
 857         HTTP_STATUS_SERVICE_UNAVAILABLE,
 858         HTTP_STATUS_GATEWAY_TIMEOUT,
 859         HTTP_STATUS_HTTP_VERSION_NOT_SUPPORTED,
 860 };
 861
 862 struct lws;
 863 struct lws_context;
 864 /* needed even with extensions disabled for create context */
 865 struct lws_extension;
 866
 867 /**
 868  * typedef lws_callback_function() - User server actions
 869  * @wsi:        Opaque websocket instance pointer
 870  * @reason:     The reason for the call
 871  * @user:       Pointer to per-session user data allocated by library
 872  * @in:         Pointer used for some callback reasons
 873  * @len:        Length set for some callback reasons
 874  *
 875  *      This callback is the way the user controls what is served.  All the
 876  *      protocol detail is hidden and handled by the library.
 877  *
 878  *      For each connection / session there is user data allocated that is
 879  *      pointed to by "user".  You set the size of this user data area when
 880  *      the library is initialized with lws_create_server.
 881  *
 882  *      You get an opportunity to initialize user data when called back with
 883  *      LWS_CALLBACK_ESTABLISHED reason.
 884  *
 885  *  LWS_CALLBACK_ESTABLISHED:  after the server completes a handshake with
 886  *                              an incoming client.  If you built the library
 887  *                              with ssl support, @in is a pointer to the
 888  *                              ssl struct associated with the connection or
 889  *                              NULL.
 890  *
 891  *  LWS_CALLBACK_CLIENT_CONNECTION_ERROR: the request client connection has
 892  *        been unable to complete a handshake with the remote server.  If
 893  *        in is non-NULL, you can find an error string of length len where
 894  *        it points to.
 895  *
 896  *  LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH: this is the last chance for the
 897  *                              client user code to examine the http headers
 898  *                              and decide to reject the connection.  If the
 899  *                              content in the headers is interesting to the
 900  *                              client (url, etc) it needs to copy it out at
 901  *                              this point since it will be destroyed before
 902  *                              the CLIENT_ESTABLISHED call
 903  *
 904  *  LWS_CALLBACK_CLIENT_ESTABLISHED: after your client connection completed
 905  *                              a handshake with the remote server
 906  *
 907  *      LWS_CALLBACK_CLOSED: when the websocket session ends
 908  *
 909  *      LWS_CALLBACK_CLOSED_HTTP: when a HTTP (non-websocket) session ends
 910  *
 911  *      LWS_CALLBACK_RECEIVE: data has appeared for this server endpoint from a
 912  *                              remote client, it can be found at *in and is
 913  *                              len bytes long
 914  *
 915  *      LWS_CALLBACK_CLIENT_RECEIVE_PONG: if you elected to see PONG packets,
 916  *                              they appear with this callback reason.  PONG
 917  *                              packets only exist in 04+ protocol
 918  *
 919  *      LWS_CALLBACK_CLIENT_RECEIVE: data has appeared from the server for the
 920  *                              client connection, it can be found at *in and
 921  *                              is len bytes long
 922  *
 923  *      LWS_CALLBACK_HTTP: an http request has come from a client that is not
 924  *                              asking to upgrade the connection to a websocket
 925  *                              one.  This is a chance to serve http content,
 926  *                              for example, to send a script to the client
 927  *                              which will then open the websockets connection.
 928  *                              @in points to the URI path requested and
 929  *                              lws_serve_http_file() makes it very
 930  *                              simple to send back a file to the client.
 931  *                              Normally after sending the file you are done
 932  *                              with the http connection, since the rest of the
 933  *                              activity will come by websockets from the script
 934  *                              that was delivered by http, so you will want to
 935  *                              return 1; to close and free up the connection.
 936  *                              That's important because it uses a slot in the
 937  *                              total number of client connections allowed set
 938  *                              by MAX_CLIENTS.
 939  *
 940  *      LWS_CALLBACK_HTTP_BODY: the next @len bytes data from the http
 941  *              request body HTTP connection is now available in @in.
 942  *
 943  *      LWS_CALLBACK_HTTP_BODY_COMPLETION: the expected amount of http request
 944  *              body has been delivered
 945  *
 946  *      LWS_CALLBACK_HTTP_WRITEABLE: you can write more down the http protocol
 947  *              link now.
 948  *
 949  *      LWS_CALLBACK_HTTP_FILE_COMPLETION: a file requested to be send down
 950  *                              http link has completed.
 951  *
 952  *      LWS_CALLBACK_CLIENT_WRITEABLE:
 953  *      LWS_CALLBACK_SERVER_WRITEABLE:   If you call
 954  *              lws_callback_on_writable() on a connection, you will
 955  *              get one of these callbacks coming when the connection socket
 956  *              is able to accept another write packet without blocking.
 957  *              If it already was able to take another packet without blocking,
 958  *              you'll get this callback at the next call to the service loop
 959  *              function.  Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE
 960  *              and servers get LWS_CALLBACK_SERVER_WRITEABLE.
 961  *
 962  *      LWS_CALLBACK_FILTER_NETWORK_CONNECTION: called when a client connects to
 963  *              the server at network level; the connection is accepted but then
 964  *              passed to this callback to decide whether to hang up immediately
 965  *              or not, based on the client IP.  @in contains the connection
 966  *              socket's descriptor. Since the client connection information is
 967  *              not available yet, @wsi still pointing to the main server socket.
 968  *              Return non-zero to terminate the connection before sending or
 969  *              receiving anything. Because this happens immediately after the
 970  *              network connection from the client, there's no websocket protocol
 971  *              selected yet so this callback is issued only to protocol 0.
 972  *
 973  *      LWS_CALLBACK_SERVER_NEW_CLIENT_INSTANTIATED: A new client just had
 974  *              been connected, accepted, and instantiated into the pool. This
 975  *              callback allows setting any relevant property to it. Because this
 976  *              happens immediately after the instantiation of a new client,
 977  *              there's no websocket protocol selected yet so this callback is
 978  *              issued only to protocol 0. Only @wsi is defined, pointing to the
 979  *              new client, and the return value is ignored.
 980  *
 981  *      LWS_CALLBACK_FILTER_HTTP_CONNECTION: called when the request has
 982  *              been received and parsed from the client, but the response is
 983  *              not sent yet.  Return non-zero to disallow the connection.
 984  *              @user is a pointer to the connection user space allocation,
 985  *              @in is the URI, eg, "/"
 986  *              In your handler you can use the public APIs
 987  *              lws_hdr_total_length() / lws_hdr_copy() to access all of the
 988  *              headers using the header enums lws_token_indexes from
 989  *              libwebsockets.h to check for and read the supported header
 990  *              presence and content before deciding to allow the http
 991  *              connection to proceed or to kill the connection.
 992  *
 993  *      LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION: called when the handshake has
 994  *              been received and parsed from the client, but the response is
 995  *              not sent yet.  Return non-zero to disallow the connection.
 996  *              @user is a pointer to the connection user space allocation,
 997  *              @in is the requested protocol name
 998  *              In your handler you can use the public APIs
 999  *              lws_hdr_total_length() / lws_hdr_copy() to access all of the
1000  *              headers using the header enums lws_token_indexes from
1001  *              libwebsockets.h to check for and read the supported header
1002  *              presence and content before deciding to allow the handshake
1003  *              to proceed or to kill the connection.
1004  *
1005  *      LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS: if configured for
1006  *              including OpenSSL support, this callback allows your user code
1007  *              to perform extra SSL_CTX_load_verify_locations() or similar
1008  *              calls to direct OpenSSL where to find certificates the client
1009  *              can use to confirm the remote server identity.  @user is the
1010  *              OpenSSL SSL_CTX*
1011  *
1012  *      LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS: if configured for
1013  *              including OpenSSL support, this callback allows your user code
1014  *              to load extra certifcates into the server which allow it to
1015  *              verify the validity of certificates returned by clients.  @user
1016  *              is the server's OpenSSL SSL_CTX*
1017  *
1018  *      LWS_CALLBACK_OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY: if configured for
1019  *              including OpenSSL support but no private key file has been
1020  *              specified (ssl_private_key_filepath is NULL), this is called to
1021  *              allow the user to set the private key directly via libopenssl
1022  *              and perform further operations if required; this might be useful
1023  *              in situations where the private key is not directly accessible
1024  *              by the OS, for example if it is stored on a smartcard
1025  *              @user is the server's OpenSSL SSL_CTX*
1026  *
1027  *      LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION: if the
1028  *              libwebsockets context was created with the option
1029  *              LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this
1030  *              callback is generated during OpenSSL verification of the cert
1031  *              sent from the client.  It is sent to protocol[0] callback as
1032  *              no protocol has been negotiated on the connection yet.
1033  *              Notice that the libwebsockets context and wsi are both NULL
1034  *              during this callback.  See
1035  *               http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
1036  *              to understand more detail about the OpenSSL callback that
1037  *              generates this libwebsockets callback and the meanings of the
1038  *              arguments passed.  In this callback, @user is the x509_ctx,
1039  *              @in is the ssl pointer and @len is preverify_ok
1040  *              Notice that this callback maintains libwebsocket return
1041  *              conventions, return 0 to mean the cert is OK or 1 to fail it.
1042  *              This also means that if you don't handle this callback then
1043  *              the default callback action of returning 0 allows the client
1044  *              certificates.
1045  *
1046  *      LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER: this callback happens
1047  *              when a client handshake is being compiled.  @user is NULL,
1048  *              @in is a char **, it's pointing to a char * which holds the
1049  *              next location in the header buffer where you can add
1050  *              headers, and @len is the remaining space in the header buffer,
1051  *              which is typically some hundreds of bytes.  So, to add a canned
1052  *              cookie, your handler code might look similar to:
1053  *
1054  *              char **p = (char **)in;
1055  *
1056  *              if (len < 100)
1057  *                      return 1;
1058  *
1059  *              *p += sprintf(*p, "Cookie: a=b\x0d\x0a");
1060  *
1061  *              return 0;
1062  *
1063  *              Notice if you add anything, you just have to take care about
1064  *              the CRLF on the line you added.  Obviously this callback is
1065  *              optional, if you don't handle it everything is fine.
1066  *
1067  *              Notice the callback is coming to protocols[0] all the time,
1068  *              because there is no specific protocol handshook yet.
1069  *
1070  *      LWS_CALLBACK_CONFIRM_EXTENSION_OKAY: When the server handshake code
1071  *              sees that it does support a requested extension, before
1072  *              accepting the extension by additing to the list sent back to
1073  *              the client it gives this callback just to check that it's okay
1074  *              to use that extension.  It calls back to the requested protocol
1075  *              and with @in being the extension name, @len is 0 and @user is
1076  *              valid.  Note though at this time the ESTABLISHED callback hasn't
1077  *              happened yet so if you initialize @user content there, @user
1078  *              content during this callback might not be useful for anything.
1079  *              Notice this callback comes to protocols[0].
1080  *
1081  *      LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED:        When a client
1082  *              connection is being prepared to start a handshake to a server,
1083  *              each supported extension is checked with protocols[0] callback
1084  *              with this reason, giving the user code a chance to suppress the
1085  *              claim to support that extension by returning non-zero.  If
1086  *              unhandled, by default 0 will be returned and the extension
1087  *              support included in the header to the server.  Notice this
1088  *              callback comes to protocols[0].
1089  *
1090  *      LWS_CALLBACK_PROTOCOL_INIT:     One-time call per protocol so it can
1091  *              do initial setup / allocations etc
1092  *
1093  *      LWS_CALLBACK_PROTOCOL_DESTROY:  One-time call per protocol indicating
1094  *              this protocol won't get used at all after this callback, the
1095  *              context is getting destroyed.  Take the opportunity to
1096  *              deallocate everything that was allocated by the protocol.
1097  *
1098  *      LWS_CALLBACK_WSI_CREATE: outermost (earliest) wsi create notification
1099  *
1100  *      LWS_CALLBACK_WSI_DESTROY: outermost (latest) wsi destroy notification
1101  *
1102  *      The next five reasons are optional and only need taking care of if you
1103  *      will be integrating libwebsockets sockets into an external polling
1104  *      array.
1105  *
1106  *      For these calls, @in points to a struct lws_pollargs that
1107  *      contains @fd, @events and @prev_events members
1108  *
1109  *      LWS_CALLBACK_ADD_POLL_FD: libwebsocket deals with its poll() loop
1110  *              internally, but in the case you are integrating with another
1111  *              server you will need to have libwebsocket sockets share a
1112  *              polling array with the other server.  This and the other
1113  *              POLL_FD related callbacks let you put your specialized
1114  *              poll array interface code in the callback for protocol 0, the
1115  *              first protocol you support, usually the HTTP protocol in the
1116  *              serving case.
1117  *              This callback happens when a socket needs to be
1118  *              added to the polling loop: @in points to a struct
1119  *              lws_pollargs; the @fd member of the struct is the file
1120  *              descriptor, and @events contains the active events.
1121  *
1122  *              If you are using the internal polling loop (the "service"
1123  *              callback), you can just ignore these callbacks.
1124  *
1125  *      LWS_CALLBACK_DEL_POLL_FD: This callback happens when a socket descriptor
1126  *              needs to be removed from an external polling array.  @in is
1127  *              again the struct lws_pollargs containing the @fd member
1128  *              to be removed.  If you are using the internal polling
1129  *              loop, you can just ignore it.
1130  *
1131  *      LWS_CALLBACK_CHANGE_MODE_POLL_FD: This callback happens when
1132  *              libwebsockets wants to modify the events for a connectiion.
1133  *              @in is the struct lws_pollargs with the @fd to change.
1134  *              The new event mask is in @events member and the old mask is in
1135  *              the @prev_events member.
1136  *              If you are using the internal polling loop, you can just ignore
1137  *              it.
1138  *
1139  *      LWS_CALLBACK_LOCK_POLL:
1140  *      LWS_CALLBACK_UNLOCK_POLL: These allow the external poll changes driven
1141  *              by libwebsockets to participate in an external thread locking
1142  *              scheme around the changes, so the whole thing is threadsafe.
1143  *              These are called around three activities in the library,
1144  *                      - inserting a new wsi in the wsi / fd table (len=1)
1145  *                      - deleting a wsi from the wsi / fd table (len=1)
1146  *                      - changing a wsi's POLLIN/OUT state (len=0)
1147  *              Locking and unlocking external synchronization objects when
1148  *              len == 1 allows external threads to be synchronized against
1149  *              wsi lifecycle changes if it acquires the same lock for the
1150  *              duration of wsi dereference from the other thread context.
1151  *
1152  *      LWS_CALLBACK_WS_PEER_INITIATED_CLOSE:
1153  *              The peer has sent an unsolicited Close WS packet.  @in and
1154  *              @len are the optional close code (first 2 bytes, network
1155  *              order) and the optional additional information which is not
1156  *              defined in the standard, and may be a string or non-human-
1157  *              readble data.
1158  *              If you return 0 lws will echo the close and then close the
1159  *              connection.  If you return nonzero lws will just close the
1160  *              connection.
1161  */
1162 typedef int
1163 lws_callback_function(struct lws *wsi, enum lws_callback_reasons reason,
1164                     void *user, void *in, size_t len);
1165
1166 /**
1167  * typedef lws_extension_callback_function() - Hooks to allow extensions to operate
1168  * @context:    Websockets context
1169  * @ext:        This extension
1170  * @wsi:        Opaque websocket instance pointer
1171  * @reason:     The reason for the call
1172  * @user:       Pointer to ptr to per-session user data allocated by library
1173  * @in:         Pointer used for some callback reasons
1174  * @len:        Length set for some callback reasons
1175  *
1176  *      Each extension that is active on a particular connection receives
1177  *      callbacks during the connection lifetime to allow the extension to
1178  *      operate on websocket data and manage itself.
1179  *
1180  *      Libwebsockets takes care of allocating and freeing "user" memory for
1181  *      each active extension on each connection.  That is what is pointed to
1182  *      by the @user parameter.
1183  *
1184  *      LWS_EXT_CB_CONSTRUCT:  called when the server has decided to
1185  *              select this extension from the list provided by the client,
1186  *              just before the server will send back the handshake accepting
1187  *              the connection with this extension active.  This gives the
1188  *              extension a chance to initialize its connection context found
1189  *              in @user.
1190  *
1191  *      LWS_EXT_CB_CLIENT_CONSTRUCT: same as LWS_EXT_CB_CONSTRUCT
1192  *              but called when client is instantiating this extension.  Some
1193  *              extensions will work the same on client and server side and then
1194  *              you can just merge handlers for both CONSTRUCTS.
1195  *
1196  *      LWS_EXT_CB_DESTROY:  called when the connection the extension was
1197  *              being used on is about to be closed and deallocated.  It's the
1198  *              last chance for the extension to deallocate anything it has
1199  *              allocated in the user data (pointed to by @user) before the
1200  *              user data is deleted.  This same callback is used whether you
1201  *              are in client or server instantiation context.
1202  *
1203  *      LWS_EXT_CB_PACKET_RX_PREPARSE: when this extension was active on
1204  *              a connection, and a packet of data arrived at the connection,
1205  *              it is passed to this callback to give the extension a chance to
1206  *              change the data, eg, decompress it.  @user is pointing to the
1207  *              extension's private connection context data, @in is pointing
1208  *              to an lws_tokens struct, it consists of a char * pointer called
1209  *              token, and an int called token_len.  At entry, these are
1210  *              set to point to the received buffer and set to the content
1211  *              length.  If the extension will grow the content, it should use
1212  *              a new buffer allocated in its private user context data and
1213  *              set the pointed-to lws_tokens members to point to its buffer.
1214  *
1215  *      LWS_EXT_CB_PACKET_TX_PRESEND: this works the same way as
1216  *              LWS_EXT_CB_PACKET_RX_PREPARSE above, except it gives the
1217  *              extension a chance to change websocket data just before it will
1218  *              be sent out.  Using the same lws_token pointer scheme in @in,
1219  *              the extension can change the buffer and the length to be
1220  *              transmitted how it likes.  Again if it wants to grow the
1221  *              buffer safely, it should copy the data into its own buffer and
1222  *              set the lws_tokens token pointer to it.
1223  *
1224  *      LWS_EXT_CB_ARGS_VALIDATE:
1225  */
1226 typedef int
1227 lws_extension_callback_function(struct lws_context *context,
1228                               const struct lws_extension *ext, struct lws *wsi,
1229                               enum lws_extension_callback_reasons reason,
1230                               void *user, void *in, size_t len);
1231
1232 /**
1233  * struct lws_protocols -       List of protocols and handlers server
1234  *                                      supports.
1235  * @name:       Protocol name that must match the one given in the client
1236  *              Javascript new WebSocket(url, 'protocol') name.
1237  * @callback:   The service callback used for this protocol.  It allows the
1238  *              service action for an entire protocol to be encapsulated in
1239  *              the protocol-specific callback
1240  * @per_session_data_size:      Each new connection using this protocol gets
1241  *              this much memory allocated on connection establishment and
1242  *              freed on connection takedown.  A pointer to this per-connection
1243  *              allocation is passed into the callback in the 'user' parameter
1244  * @rx_buffer_size: if you want atomic frames delivered to the callback, you
1245  *              should set this to the size of the biggest legal frame that
1246  *              you support.  If the frame size is exceeded, there is no
1247  *              error, but the buffer will spill to the user callback when
1248  *              full, which you can detect by using
1249  *              lws_remaining_packet_payload().  Notice that you
1250  *              just talk about frame size here, the LWS_PRE
1251  *              and post-padding are automatically also allocated on top.
1252  * @id:         ignored by lws, but useful to contain user information bound
1253  *              to the selected protocol.  For example if this protocol was
1254  *              called "myprotocol-v2", you might set id to 2, and the user
1255  *              code that acts differently according to the version can do so by
1256  *              switch (wsi->protocol->id), user code might use some bits as
1257  *              capability flags based on selected protocol version, etc.
1258  * @user:       User provided context data at the protocol level.
1259  *              Accessible via lws_get_protocol(wsi)->user
1260  *              This should not be confused with wsi->user, it is not the same.
1261  *              The library completely ignores any value in here.
1262  *
1263  *      This structure represents one protocol supported by the server.  An
1264  *      array of these structures is passed to lws_create_server()
1265  *      allows as many protocols as you like to be handled by one server.
1266  *
1267  *      The first protocol given has its callback used for user callbacks when
1268  *      there is no agreed protocol name, that's true during HTTP part of the
1269  *      connection and true if the client did not send a Protocol: header.
1270  */
1271
1272 struct lws_protocols {
1273         const char *name;
1274         lws_callback_function *callback;
1275         size_t per_session_data_size;
1276         size_t rx_buffer_size;
1277         unsigned int id;
1278         void *user;
1279
1280         /* Add new things just above here ---^
1281          * This is part of the ABI, don't needlessly break compatibility */
1282 };
1283
1284 enum lws_ext_options_types {
1285         EXTARG_NONE,
1286         EXTARG_DEC,
1287         EXTARG_OPT_DEC
1288
1289         /* Add new things just above here ---^
1290          * This is part of the ABI, don't needlessly break compatibility */
1291 };
1292
1293 /**
1294  * struct lws_ext_options -     Option arguments to the extension.  These are
1295  *                              used in the negotiation at ws upgrade time.
1296  *                              The helper function lws_ext_parse_options()
1297  *                              uses these to generate callbacks
1298  *
1299  * @name:                       Option name, eg, "server_no_context_takeover"
1300  * @type:                       What kind of args the option can take
1301  */
1302 struct lws_ext_options {
1303         const char *name;
1304         enum lws_ext_options_types type;
1305
1306         /* Add new things just above here ---^
1307          * This is part of the ABI, don't needlessly break compatibility */
1308 };
1309
1310 struct lws_ext_option_arg {
1311         const char *option_name; /* may be NULL, option_index used then */
1312         int option_index;
1313         const char *start;
1314         int len;
1315 };
1316
1317 /**
1318  * struct lws_extension -       An extension we know how to cope with
1319  *
1320  * @name:                       Formal extension name, eg, "permessage-deflate"
1321  * @callback:                   Service callback
1322  * @client_offer:               String containing exts and options client offers
1323  */
1324
1325 struct lws_extension {
1326         const char *name;
1327         lws_extension_callback_function *callback;
1328         const char *client_offer;
1329
1330         /* Add new things just above here ---^
1331          * This is part of the ABI, don't needlessly break compatibility */
1332 };
1333
1334
1335 #ifdef LWS_WITH_PLUGINS
1336
1337 /* PLUGINS implies LIBUV */
1338
1339 #define LWS_PLUGIN_API_MAGIC 180
1340
1341 struct lws_plugin_capability {
1342         unsigned int api_magic; /* caller fills this in, plugin fills rest */
1343         const struct lws_protocols *protocols;
1344         int count_protocols;
1345         const struct lws_extension *extensions;
1346         int count_extensions;
1347 };
1348
1349 typedef int (*lws_plugin_init_func)(struct lws_context *,
1350                                     struct lws_plugin_capability *);
1351 typedef int (*lws_plugin_destroy_func)(struct lws_context *);
1352 struct lws_plugin {
1353         struct lws_plugin *list;
1354 #if (UV_VERSION_MAJOR > 0)
1355         uv_lib_t lib;
1356 #else
1357         void *l;
1358 #endif
1359         char name[64];
1360         struct lws_plugin_capability caps;
1361 };
1362
1363 #endif
1364
1365 /*
1366  * The internal exts are part of the public abi
1367  * If we add more extensions, publish the callback here  ------v
1368  */
1369
1370 extern int lws_extension_callback_pm_deflate(
1371         struct lws_context *context, const struct lws_extension *ext,
1372         struct lws *wsi, enum lws_extension_callback_reasons reason,
1373         void *user, void *in, size_t len);
1374
1375 LWS_VISIBLE LWS_EXTERN int
1376 lws_set_extension_option(struct lws *wsi, const char *ext_name,
1377                          const char *opt_name, const char *opt_val);
1378
1379 struct lws_protocol_vhost_options {
1380         const struct lws_protocol_vhost_options *next;
1381         const struct lws_protocol_vhost_options *options;
1382         const char *name;
1383         const char *value;
1384 };
1385
1386 struct lws_http_mount {
1387         struct lws_http_mount *mount_next;
1388         const char *mountpoint; /* mountpoint in http pathspace, eg, "/" */
1389         const char *origin; /* path to be mounted, eg, "/var/www/warmcat.com" */
1390         const char *def; /* default target, eg, "index.html" */
1391
1392         const struct lws_protocol_vhost_options *cgienv;
1393
1394         int cgi_timeout;
1395         int cache_max_age;
1396
1397         unsigned int cache_reusable:1;
1398         unsigned int cache_revalidate:1;
1399         unsigned int cache_intermediaries:1;
1400
1401         unsigned char origin_protocol;
1402         unsigned char mountpoint_len;
1403 };
1404
1405 /**
1406  * struct lws_context_creation_info - parameters to create context with
1407  *
1408  * This is also used to create vhosts.... if LWS_SERVER_OPTION_EXPLICIT_VHOSTS
1409  * is not given, then for backwards compatibility one vhost is created at
1410  * context-creation time using the info from this struct.
1411  *
1412  * If LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, then no vhosts are created
1413  * at the same time as the context, they are expected to be created afterwards.
1414  *
1415  * @port:       VHOST: Port to listen on... you can use CONTEXT_PORT_NO_LISTEN to
1416  *              suppress listening on any port, that's what you want if you are
1417  *              not running a websocket server at all but just using it as a
1418  *              client
1419  * @iface:      VHOST: NULL to bind the listen socket to all interfaces, or the
1420  *              interface name, eg, "eth2"
1421  *              If options specifies LWS_SERVER_OPTION_UNIX_SOCK, this member is
1422  *              the pathname of a UNIX domain socket. you can use the UNIX domain
1423  *              sockets in abstract namespace, by prepending an @ symbole to the
1424  *              socket name.
1425  * @protocols:  VHOST: Array of structures listing supported protocols and a protocol-
1426  *              specific callback for each one.  The list is ended with an
1427  *              entry that has a NULL callback pointer.
1428  *              It's not const because we write the owning_server member
1429  * @extensions: VHOST: NULL or array of lws_extension structs listing the
1430  *              extensions this context supports.  If you configured with
1431  *              --without-extensions, you should give NULL here.
1432  * @token_limits: CONTEXT: NULL or struct lws_token_limits pointer which is initialized
1433  *              with a token length limit for each possible WSI_TOKEN_***
1434  * @ssl_cert_filepath:  VHOST: If libwebsockets was compiled to use ssl, and you want
1435  *                      to listen using SSL, set to the filepath to fetch the
1436  *                      server cert from, otherwise NULL for unencrypted
1437  * @ssl_private_key_filepath: VHOST: filepath to private key if wanting SSL mode;
1438  *                      if this is set to NULL but sll_cert_filepath is set, the
1439  *                      OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY callback is called
1440  *                      to allow setting of the private key directly via openSSL
1441  *                      library calls
1442  * @ssl_ca_filepath: VHOST: CA certificate filepath or NULL
1443  * @ssl_cipher_list:    VHOST: List of valid ciphers to use (eg,
1444  *                      "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
1445  *                      or you can leave it as NULL to get "DEFAULT"
1446  * @http_proxy_address: VHOST: If non-NULL, attempts to proxy via the given address.
1447  *                      If proxy auth is required, use format
1448  *                      "username:password@server:port"
1449  * @http_proxy_port:    VHOST: If http_proxy_address was non-NULL, uses this port at
1450  *                      the address
1451  * @gid:        CONTEXT: group id to change to after setting listen socket, or -1.
1452  * @uid:        CONTEXT: user id to change to after setting listen socket, or -1.
1453  * @options:    VHOST + CONTEXT: 0, or LWS_SERVER_OPTION_... bitfields
1454  * @user:       CONTEXT: optional user pointer that can be recovered via the context
1455  *              pointer using lws_context_user
1456  * @ka_time:    CONTEXT: 0 for no keepalive, otherwise apply this keepalive timeout to
1457  *              all libwebsocket sockets, client or server
1458  * @ka_probes:  CONTEXT: if ka_time was nonzero, after the timeout expires how many
1459  *              times to try to get a response from the peer before giving up
1460  *              and killing the connection
1461  * @ka_interval: CONTEXT: if ka_time was nonzero, how long to wait before each ka_probes
1462  *              attempt
1463  * @provided_client_ssl_ctx: CONTEXT: If non-null, swap out libwebsockets ssl
1464  *              implementation for the one provided by provided_ssl_ctx.
1465  *              Libwebsockets no longer is responsible for freeing the context
1466  *              if this option is selected.
1467  * @max_http_header_data: CONTEXT: The max amount of header payload that can be handled
1468  *              in an http request (unrecognized header payload is dropped)
1469  * @max_http_header_pool: CONTEXT: The max number of connections with http headers that
1470  *              can be processed simultaneously (the corresponding memory is
1471  *              allocated for the lifetime of the context).  If the pool is
1472  *              busy new incoming connections must wait for accept until one
1473  *              becomes free.
1474  * @count_threads: CONTEXT: how many contexts to create in an array, 0 = 1
1475  * @fd_limit_per_thread: CONTEXT: nonzero means restrict each service thread to this
1476  *              many fds, 0 means the default which is divide the process fd
1477  *              limit by the number of threads.
1478  * @timeout_secs: VHOST: various processes involving network roundtrips in the
1479  *              library are protected from hanging forever by timeouts.  If
1480  *              nonzero, this member lets you set the timeout used in seconds.
1481  *              Otherwise a default timeout is used.
1482  * @ecdh_curve: VHOST: if NULL, defaults to initializing server with "prime256v1"
1483  * @vhost_name: VHOST: name of vhost, must match external DNS name used to
1484  *              access the site, like "warmcat.com" as it's used to match
1485  *              Host: header and / or SNI name for SSL.
1486  * @plugin_dirs: CONTEXT: NULL, or NULL-terminated array of directories to
1487  *              scan for lws protocol plugins at context creation time
1488  * @pvo:        VHOST: pointer to optional linked list of per-vhost
1489  *              options made accessible to protocols
1490  * @keepalive_timeout: VHOST: (default = 0 = 60s) seconds to allow remote
1491  *              client to hold on to an idle HTTP/1.1 connection
1492  * @log_filepath: VHOST: filepath to append logs to... this is opened before
1493  *              any dropping of initial privileges
1494  * @mounts:     VHOST: optional linked list of mounts for this vhost
1495  * @server_string: CONTEXT: string used in HTTP headers to identify server
1496  *              software, if NULL, "libwebsockets".
1497  */
1498
1499 struct lws_context_creation_info {
1500         int port;                                       /* VH */
1501         const char *iface;                              /* VH */
1502         const struct lws_protocols *protocols;          /* VH */
1503         const struct lws_extension *extensions;         /* VH */
1504         const struct lws_token_limits *token_limits;    /* context */
1505         const char *ssl_private_key_password;           /* VH */
1506         const char *ssl_cert_filepath;                  /* VH */
1507         const char *ssl_private_key_filepath;           /* VH */
1508         const char *ssl_ca_filepath;                    /* VH */
1509         const char *ssl_cipher_list;                    /* VH */
1510         const char *http_proxy_address;                 /* VH */
1511         unsigned int http_proxy_port;                   /* VH */
1512         int gid;                                        /* context */
1513         int uid;                                        /* context */
1514         unsigned int options;                           /* VH + context */
1515         void *user;                                     /* context */
1516         int ka_time;                                    /* context */
1517         int ka_probes;                                  /* context */
1518         int ka_interval;                                /* context */
1519 #ifdef LWS_OPENSSL_SUPPORT
1520         SSL_CTX *provided_client_ssl_ctx;               /* context */
1521 #else /* maintain structure layout either way */
1522         void *provided_client_ssl_ctx;
1523 #endif
1524
1525         short max_http_header_data;                     /* context */
1526         short max_http_header_pool;                     /* context */
1527
1528         unsigned int count_threads;                     /* context */
1529         unsigned int fd_limit_per_thread;               /* context */
1530         unsigned int timeout_secs;                      /* VH */
1531         const char *ecdh_curve;                         /* VH */
1532         const char *vhost_name;                         /* VH */
1533         const char * const *plugin_dirs;                /* context */
1534         const struct lws_protocol_vhost_options *pvo;   /* VH */
1535         int keepalive_timeout;                          /* VH */
1536         const char *log_filepath;                       /* VH */
1537         const struct lws_http_mount *mounts;            /* VH */
1538         const char *server_string;                      /* context */
1539
1540         /* Add new things just above here ---^
1541          * This is part of the ABI, don't needlessly break compatibility
1542          *
1543          * The below is to ensure later library versions with new
1544          * members added above will see 0 (default) even if the app
1545          * was not built against the newer headers.
1546          */
1547
1548         void *_unused[8];
1549 };
1550
1551 /**
1552  * struct lws_client_connect_info - parameters to connect with when using
1553  *                                  lws_client_connect_via_info()
1554  *
1555  * @context:    lws context to create connection in
1556  * @address:    remote address to connect to
1557  * @port:       remote port to connect to
1558  * @ssl_connection: nonzero for ssl
1559  * @path:       uri path
1560  * @host:       content of host header
1561  * @origin:     content of origin header
1562  * @protocol:   list of ws protocols
1563  * @ietf_version_or_minus_one: currently leave at 0 or -1
1564  * @userdata:   if non-NULL, use this as wsi user_data instead of malloc it
1565  * @client_exts: array of extensions that may be used on connection
1566  * @method:     if non-NULL, do this http method instead of ws[s] upgrade.
1567  *              use "GET" to be a simple http client connection
1568  * @parent_wsi: if another wsi is responsible for this connection, give it here.
1569  *              this is used to make sure if the parent closes so do any
1570  *              child connections first.
1571  * @uri_replace_from: if non-NULL, when this string is found in URIs in
1572  *              text/html content-encoding, it's replaced with @uri_replace_to
1573  * @uri_replace_to: see above
1574  * @vhost:      vhost to bind to (used to determine related SSL_CTX)
1575  */
1576
1577 struct lws_client_connect_info {
1578         struct lws_context *context;
1579         const char *address;
1580         int port;
1581         int ssl_connection;
1582         const char *path;
1583         const char *host;
1584         const char *origin;
1585         const char *protocol;
1586         int ietf_version_or_minus_one;
1587         void *userdata;
1588         const struct lws_extension *client_exts;
1589         const char *method;
1590         struct lws *parent_wsi;
1591         const char *uri_replace_from;
1592         const char *uri_replace_to;
1593         struct lws_vhost *vhost;
1594
1595         /* Add new things just above here ---^
1596          * This is part of the ABI, don't needlessly break compatibility
1597          *
1598          * The below is to ensure later library versions with new
1599          * members added above will see 0 (default) even if the app
1600          * was not built against the newer headers.
1601          */
1602
1603         void *_unused[4];
1604 };
1605
1606 enum {
1607         LWSMPRO_HTTP,
1608         LWSMPRO_HTTPS,
1609         LWSMPRO_FILE,
1610         LWSMPRO_CGI,
1611         LWSMPRO_REDIR_HTTP,
1612         LWSMPRO_REDIR_HTTPS,
1613 };
1614
1615 LWS_VISIBLE LWS_EXTERN int
1616 lws_json_dump_vhost(const struct lws_vhost *vh, char *buf, int len);
1617
1618 LWS_VISIBLE LWS_EXTERN int
1619 lws_json_dump_context(const struct lws_context *context, char *buf, int len);
1620
1621 LWS_VISIBLE LWS_EXTERN void
1622 lws_set_log_level(int level,
1623                   void (*log_emit_function)(int level, const char *line));
1624
1625 LWS_VISIBLE LWS_EXTERN void
1626 lwsl_emit_syslog(int level, const char *line);
1627
1628 LWS_VISIBLE LWS_EXTERN struct lws_context *
1629 lws_create_context(struct lws_context_creation_info *info);
1630
1631 struct lws_vhost;
1632
1633 LWS_EXTERN LWS_VISIBLE struct lws_vhost *
1634 lws_create_vhost(struct lws_context *context,
1635                  struct lws_context_creation_info *info);
1636
1637 LWS_VISIBLE LWS_EXTERN struct lws_vhost *
1638 lws_vhost_get(struct lws *wsi);
1639
1640 LWS_VISIBLE LWS_EXTERN const struct lws_protocols *
1641 lws_protocol_get(struct lws *wsi);
1642
1643 LWS_VISIBLE LWS_EXTERN void *
1644 lws_protocol_vh_priv_zalloc(struct lws_vhost *vhost, const struct lws_protocols *prot,
1645                             int size);
1646 LWS_VISIBLE LWS_EXTERN void *
1647 lws_protocol_vh_priv_get(struct lws_vhost *vhost, const struct lws_protocols *prot);
1648
1649 LWS_VISIBLE LWS_EXTERN int
1650 lws_finalize_startup(struct lws_context *context);
1651
1652 LWS_VISIBLE LWS_EXTERN int
1653 lws_set_proxy(struct lws_vhost *vhost, const char *proxy);
1654
1655 LWS_VISIBLE LWS_EXTERN void
1656 lws_context_destroy(struct lws_context *context);
1657
1658 LWS_VISIBLE LWS_EXTERN int
1659 lws_service(struct lws_context *context, int timeout_ms);
1660
1661 LWS_VISIBLE LWS_EXTERN int
1662 lws_service_tsi(struct lws_context *context, int timeout_ms, int tsi);
1663
1664 LWS_VISIBLE LWS_EXTERN void
1665 lws_cancel_service_pt(struct lws *wsi);
1666
1667 LWS_VISIBLE LWS_EXTERN void
1668 lws_cancel_service(struct lws_context *context);
1669
1670 LWS_VISIBLE LWS_EXTERN int
1671 lws_interface_to_sa(int ipv6, const char *ifname, struct sockaddr_in *addr,
1672                     size_t addrlen);
1673
1674 LWS_VISIBLE LWS_EXTERN const unsigned char *
1675 lws_token_to_string(enum lws_token_indexes token);
1676
1677 /* all the below must be LWS_WARN_UNUSED_RESULT as they can run short */
1678
1679 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1680 lws_add_http_header_by_name(struct lws *wsi, const unsigned char *name,
1681                             const unsigned char *value, int length,
1682                             unsigned char **p, unsigned char *end);
1683 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1684 lws_finalize_http_header(struct lws *wsi, unsigned char **p,
1685                          unsigned char *end);
1686 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1687 lws_add_http_header_by_token(struct lws *wsi, enum lws_token_indexes token,
1688                              const unsigned char *value, int length,
1689                              unsigned char **p, unsigned char *end);
1690 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1691 lws_add_http_header_content_length(struct lws *wsi,
1692                                    unsigned long content_length,
1693                                    unsigned char **p, unsigned char *end);
1694 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1695 lws_add_http_header_status(struct lws *wsi,
1696                            unsigned int code, unsigned char **p,
1697                            unsigned char *end);
1698
1699 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1700 lws_http_redirect(struct lws *wsi, int code, const unsigned char *loc, int len,
1701                   unsigned char **p, unsigned char *end);
1702
1703 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1704 lws_http_transaction_completed(struct lws *wsi);
1705
1706 #ifdef LWS_USE_LIBEV
1707 typedef void (lws_ev_signal_cb_t)(EV_P_ struct ev_signal *w, int revents);
1708
1709 LWS_VISIBLE LWS_EXTERN int
1710 lws_ev_sigint_cfg(struct lws_context *context, int use_ev_sigint,
1711                   lws_ev_signal_cb_t *cb);
1712
1713 LWS_VISIBLE LWS_EXTERN int
1714 lws_ev_initloop(struct lws_context *context, struct ev_loop *loop, int tsi);
1715
1716 LWS_VISIBLE LWS_EXTERN void
1717 lws_ev_sigint_cb(struct ev_loop *loop, struct ev_signal *watcher, int revents);
1718 #endif /* LWS_USE_LIBEV */
1719
1720 #ifdef LWS_USE_LIBUV
1721 LWS_VISIBLE LWS_EXTERN int
1722 lws_uv_sigint_cfg(struct lws_context *context, int use_uv_sigint,
1723                   uv_signal_cb cb);
1724
1725 LWS_VISIBLE LWS_EXTERN void
1726 lws_libuv_run(const struct lws_context *context, int tsi);
1727
1728 LWS_VISIBLE LWS_EXTERN void
1729 lws_libuv_stop(struct lws_context *context);
1730
1731 LWS_VISIBLE LWS_EXTERN int
1732 lws_uv_initloop(struct lws_context *context, uv_loop_t *loop, int tsi);
1733
1734 LWS_VISIBLE LWS_EXTERN uv_loop_t *
1735 lws_uv_getloop(struct lws_context *context, int tsi);
1736
1737 LWS_VISIBLE LWS_EXTERN void
1738 lws_uv_sigint_cb(uv_signal_t *watcher, int signum);
1739 #endif /* LWS_USE_LIBUV */
1740
1741 LWS_VISIBLE LWS_EXTERN int
1742 lws_service_fd(struct lws_context *context, struct lws_pollfd *pollfd);
1743
1744 LWS_VISIBLE LWS_EXTERN int
1745 lws_service_fd_tsi(struct lws_context *context, struct lws_pollfd *pollfd,
1746                    int tsi);
1747
1748 LWS_VISIBLE LWS_EXTERN void *
1749 lws_context_user(struct lws_context *context);
1750
1751 LWS_VISIBLE LWS_EXTERN void *
1752 lws_wsi_user(struct lws *wsi);
1753
1754 /*
1755  * NOTE: These public enums are part of the abi.  If you want to add one,
1756  * add it at where specified so existing users are unaffected.
1757  */
1758 enum pending_timeout {
1759         NO_PENDING_TIMEOUT                                      =  0,
1760         PENDING_TIMEOUT_AWAITING_PROXY_RESPONSE                 =  1,
1761         PENDING_TIMEOUT_AWAITING_CONNECT_RESPONSE               =  2,
1762         PENDING_TIMEOUT_ESTABLISH_WITH_SERVER                   =  3,
1763         PENDING_TIMEOUT_AWAITING_SERVER_RESPONSE                =  4,
1764         PENDING_TIMEOUT_AWAITING_PING                           =  5,
1765         PENDING_TIMEOUT_CLOSE_ACK                               =  6,
1766         PENDING_TIMEOUT_AWAITING_EXTENSION_CONNECT_RESPONSE     =  7,
1767         PENDING_TIMEOUT_SENT_CLIENT_HANDSHAKE                   =  8,
1768         PENDING_TIMEOUT_SSL_ACCEPT                              =  9,
1769         PENDING_TIMEOUT_HTTP_CONTENT                            = 10,
1770         PENDING_TIMEOUT_AWAITING_CLIENT_HS_SEND                 = 11,
1771         PENDING_FLUSH_STORED_SEND_BEFORE_CLOSE                  = 12,
1772         PENDING_TIMEOUT_SHUTDOWN_FLUSH                          = 13,
1773         PENDING_TIMEOUT_CGI                                     = 14,
1774         PENDING_TIMEOUT_HTTP_KEEPALIVE_IDLE                     = 15,
1775
1776         /****** add new things just above ---^ ******/
1777 };
1778
1779 LWS_VISIBLE LWS_EXTERN void
1780 lws_set_timeout(struct lws *wsi, enum pending_timeout reason, int secs);
1781
1782 /*
1783  * IMPORTANT NOTICE!
1784  *
1785  * When sending with websocket protocol
1786  *
1787  * LWS_WRITE_TEXT,
1788  * LWS_WRITE_BINARY,
1789  * LWS_WRITE_CONTINUATION,
1790  * LWS_WRITE_PING,
1791  * LWS_WRITE_PONG
1792  *
1793  * the send buffer has to have LWS_PRE bytes valid BEFORE
1794  * the buffer pointer you pass to lws_write().
1795  *
1796  * This allows us to add protocol info before and after the data, and send as
1797  * one packet on the network without payload copying, for maximum efficiency.
1798  *
1799  * So for example you need this kind of code to use lws_write with a
1800  * 128-byte payload
1801  *
1802  *   char buf[LWS_PRE + 128];
1803  *
1804  *   // fill your part of the buffer... for example here it's all zeros
1805  *   memset(&buf[LWS_PRE], 0, 128);
1806  *
1807  *   lws_write(wsi, &buf[LWS_PRE], 128, LWS_WRITE_TEXT);
1808  *
1809  * When sending HTTP, with
1810  *
1811  * LWS_WRITE_HTTP,
1812  * LWS_WRITE_HTTP_HEADERS
1813  * LWS_WRITE_HTTP_FINAL
1814  *
1815  * there is no protocol data prepended, and don't need to take care about the
1816  * LWS_PRE bytes valid before the buffer pointer.
1817  *
1818  * LWS_PRE is at least the frame nonce + 2 header + 8 length
1819  * LWS_SEND_BUFFER_POST_PADDING is deprecated, it's now 0 and can be left off.
1820  * The example apps no longer use it.
1821  *
1822  * Pad LWS_PRE to the CPU word size, so that word references
1823  * to the address immediately after the padding won't cause an unaligned access
1824  * error. Sometimes for performance reasons the recommended padding is even
1825  * larger than sizeof(void *).
1826  */
1827
1828 #if !defined(LWS_SIZEOFPTR)
1829 #define LWS_SIZEOFPTR (sizeof (void *))
1830 #endif
1831 #if !defined(u_int64_t)
1832 #define u_int64_t unsigned long long
1833 #endif
1834
1835 #if __x86_64__
1836 #define _LWS_PAD_SIZE 16        /* Intel recommended for best performance */
1837 #else
1838 #define _LWS_PAD_SIZE LWS_SIZEOFPTR   /* Size of a pointer on the target arch */
1839 #endif
1840 #define _LWS_PAD(n) (((n) % _LWS_PAD_SIZE) ? \
1841                 ((n) + (_LWS_PAD_SIZE - ((n) % _LWS_PAD_SIZE))) : (n))
1842 #define LWS_PRE _LWS_PAD(4 + 10)
1843 /* used prior to 1.7 and retained for backward compatibility */
1844 #define LWS_SEND_BUFFER_PRE_PADDING LWS_PRE
1845 #define LWS_SEND_BUFFER_POST_PADDING 0
1846
1847 LWS_VISIBLE LWS_EXTERN int
1848 lws_write(struct lws *wsi, unsigned char *buf, size_t len,
1849           enum lws_write_protocol protocol);
1850
1851 /**
1852  * lws_close_reason - Set reason and aux data to send with Close packet
1853  *              If you are going to return nonzero from the callback
1854  *              requesting the connection to close, you can optionally
1855  *              call this to set the reason the peer will be told if
1856  *              possible.
1857  *
1858  * @wsi:        The websocket connection to set the close reason on
1859  * @status:     A valid close status from websocket standard
1860  * @buf:        NULL or buffer containing up to 124 bytes of auxiliary data
1861  * @len:        Length of data in @buf to send
1862  */
1863 LWS_VISIBLE LWS_EXTERN void
1864 lws_close_reason(struct lws *wsi, enum lws_close_status status,
1865                  unsigned char *buf, size_t len);
1866
1867 /* helper for case where buffer may be const */
1868 #define lws_write_http(wsi, buf, len) \
1869         lws_write(wsi, (unsigned char *)(buf), len, LWS_WRITE_HTTP)
1870
1871 LWS_VISIBLE LWS_EXTERN int
1872 lws_serve_http_file(struct lws *wsi, const char *file, const char *content_type,
1873                     const char *other_headers, int other_headers_len);
1874 LWS_VISIBLE LWS_EXTERN int
1875 lws_serve_http_file_fragment(struct lws *wsi);
1876
1877 LWS_VISIBLE LWS_EXTERN int
1878 lws_return_http_status(struct lws *wsi, unsigned int code,
1879                        const char *html_body);
1880
1881 LWS_VISIBLE LWS_EXTERN const struct lws_protocols *
1882 lws_get_protocol(struct lws *wsi);
1883
1884 LWS_VISIBLE LWS_EXTERN int
1885 lws_callback_on_writable(struct lws *wsi);
1886
1887 LWS_VISIBLE LWS_EXTERN int
1888 lws_callback_on_writable_all_protocol(const struct lws_context *context,
1889                                       const struct lws_protocols *protocol);
1890
1891 LWS_VISIBLE LWS_EXTERN int
1892 lws_callback_on_writable_all_protocol_vhost(const struct lws_vhost *vhost,
1893                                       const struct lws_protocols *protocol);
1894
1895 LWS_VISIBLE LWS_EXTERN int
1896 lws_callback_all_protocol(struct lws_context *context,
1897                           const struct lws_protocols *protocol, int reason);
1898
1899 LWS_VISIBLE LWS_EXTERN int
1900 lws_callback_all_protocol_vhost(struct lws_vhost *vh,
1901                           const struct lws_protocols *protocol, int reason);
1902
1903 LWS_VISIBLE LWS_EXTERN int
1904 lws_get_socket_fd(struct lws *wsi);
1905
1906 LWS_VISIBLE LWS_EXTERN int
1907 lws_is_final_fragment(struct lws *wsi);
1908
1909 LWS_VISIBLE LWS_EXTERN unsigned char
1910 lws_get_reserved_bits(struct lws *wsi);
1911
1912 LWS_VISIBLE LWS_EXTERN int
1913 lws_rx_flow_control(struct lws *wsi, int enable);
1914
1915 LWS_VISIBLE LWS_EXTERN void
1916 lws_rx_flow_allow_all_protocol(const struct lws_context *context,
1917                                const struct lws_protocols *protocol);
1918
1919 LWS_VISIBLE LWS_EXTERN size_t
1920 lws_remaining_packet_payload(struct lws *wsi);
1921
1922 /*
1923  * if the protocol does not have any guidance, returns -1.  Currently only
1924  * http2 connections get send window information from this API.  But your code
1925  * should use it so it can work properly with any protocol.
1926  *
1927  * If nonzero return is the amount of payload data the peer or intermediary has
1928  * reported it has buffer space for.  That has NO relationship with the amount
1929  * of buffer space your OS can accept on this connection for a write action.
1930  *
1931  * This number represents the maximum you could send to the peer or intermediary
1932  * on this connection right now without it complaining.
1933  *
1934  * lws manages accounting for send window updates and payload writes
1935  * automatically, so this number reflects the situation at the peer or
1936  * intermediary dynamically.
1937  */
1938 LWS_VISIBLE LWS_EXTERN size_t
1939 lws_get_peer_write_allowance(struct lws *wsi);
1940
1941 /* deprecated, use lws_client_connect_via_info() */
1942 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
1943 lws_client_connect(struct lws_context *clients, const char *address,
1944                    int port, int ssl_connection, const char *path,
1945                    const char *host, const char *origin, const char *protocol,
1946                    int ietf_version_or_minus_one) LWS_WARN_DEPRECATED;
1947 /* deprecated, use lws_client_connect_via_info() */
1948 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
1949 lws_client_connect_extended(struct lws_context *clients, const char *address,
1950                             int port, int ssl_connection, const char *path,
1951                             const char *host, const char *origin,
1952                             const char *protocol, int ietf_version_or_minus_one,
1953                             void *userdata) LWS_WARN_DEPRECATED;
1954
1955 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
1956 lws_client_connect_via_info(struct lws_client_connect_info * ccinfo);
1957
1958 LWS_VISIBLE LWS_EXTERN struct lws *
1959 lws_adopt_socket(struct lws_context *context, lws_sockfd_type accept_fd);
1960 LWS_VISIBLE LWS_EXTERN struct lws *
1961 lws_adopt_socket_readbuf(struct lws_context *context, lws_sockfd_type accept_fd,
1962                 const char *readbuf, size_t len);
1963
1964 LWS_VISIBLE LWS_EXTERN const char * LWS_WARN_UNUSED_RESULT
1965 lws_canonical_hostname(struct lws_context *context);
1966
1967
1968 LWS_VISIBLE LWS_EXTERN void
1969 lws_get_peer_addresses(struct lws *wsi, lws_sockfd_type fd, char *name,
1970                        int name_len, char *rip, int rip_len);
1971
1972 LWS_VISIBLE LWS_EXTERN int
1973 lws_get_random(struct lws_context *context, void *buf, int len);
1974
1975 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1976 lws_daemonize(const char *_lock_path);
1977
1978 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1979 lws_send_pipe_choked(struct lws *wsi);
1980
1981 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1982 lws_partial_buffered(struct lws *wsi);
1983
1984 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1985 lws_frame_is_binary(struct lws *wsi);
1986
1987 LWS_VISIBLE LWS_EXTERN int
1988 lws_is_ssl(struct lws *wsi);
1989
1990 LWS_VISIBLE LWS_EXTERN int
1991 lws_is_cgi(struct lws *wsi);
1992
1993 #ifdef LWS_SHA1_USE_OPENSSL_NAME
1994 #define lws_SHA1 SHA1
1995 #else
1996 LWS_VISIBLE LWS_EXTERN unsigned char *
1997 lws_SHA1(const unsigned char *d, size_t n, unsigned char *md);
1998 #endif
1999
2000 LWS_VISIBLE LWS_EXTERN int
2001 lws_b64_encode_string(const char *in, int in_len, char *out, int out_size);
2002
2003 LWS_VISIBLE LWS_EXTERN int
2004 lws_b64_decode_string(const char *in, char *out, int out_size);
2005
2006 LWS_VISIBLE LWS_EXTERN const char * LWS_WARN_UNUSED_RESULT
2007 lws_get_library_version(void);
2008
2009 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2010 lws_parse_uri(char *p, const char **prot, const char **ads, int *port,
2011               const char **path);
2012
2013 /*
2014  *  Access to http headers
2015  *
2016  *  In lws the client http headers are temporarily malloc'd only for the
2017  *  duration of the http part of the handshake.  It's because in most cases,
2018  *  the header content is ignored for the whole rest of the connection lifetime
2019  *  and would then just be taking up space needlessly.
2020  *
2021  *  During LWS_CALLBACK_HTTP when the URI path is delivered is the last time
2022  *  the http headers are still allocated, you can use these apis then to
2023  *  look at and copy out interesting header content (cookies, etc)
2024  *
2025  *  Notice that the header total length reported does not include a terminating
2026  *  '\0', however you must allocate for it when using the _copy apis.  So the
2027  *  length reported for a header containing "123" is 3, but you must provide
2028  *  a buffer of length 4 so that "123\0" may be copied into it, or the copy
2029  *  will fail with a nonzero return code.
2030  */
2031
2032 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2033 lws_hdr_total_length(struct lws *wsi, enum lws_token_indexes h);
2034
2035 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2036 lws_hdr_fragment_length(struct lws *wsi, enum lws_token_indexes h, int frag_idx);
2037
2038 /*
2039  * copies the whole, aggregated header, even if it was delivered in
2040  * several actual headers piece by piece
2041  */
2042 LWS_VISIBLE LWS_EXTERN int
2043 lws_hdr_copy(struct lws *wsi, char *dest, int len, enum lws_token_indexes h);
2044
2045 /*
2046  * copies only fragment frag_idx of a header.  Normally this is only useful
2047  * to parse URI arguments like ?x=1&y=2, token index WSI_TOKEN_HTTP_URI_ARGS
2048  * fragment 0 will contain "x=1" and fragment 1 "y=2"
2049  */
2050 LWS_VISIBLE LWS_EXTERN int
2051 lws_hdr_copy_fragment(struct lws *wsi, char *dest, int len,
2052                       enum lws_token_indexes h, int frag_idx);
2053
2054
2055 /* get the active file operations struct */
2056 LWS_VISIBLE LWS_EXTERN struct lws_plat_file_ops * LWS_WARN_UNUSED_RESULT
2057 lws_get_fops(struct lws_context *context);
2058
2059 LWS_VISIBLE LWS_EXTERN struct lws_context * LWS_WARN_UNUSED_RESULT
2060 lws_get_context(const struct lws *wsi);
2061
2062 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2063 lws_get_count_threads(struct lws_context *context);
2064
2065 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
2066 lws_get_parent(const struct lws *wsi);
2067
2068 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
2069 lws_get_child(const struct lws *wsi);
2070
2071 #ifdef LWS_WITH_CGI
2072 enum lws_enum_stdinouterr {
2073         LWS_STDIN = 0,
2074         LWS_STDOUT = 1,
2075         LWS_STDERR = 2,
2076 };
2077
2078 enum lws_cgi_hdr_state {
2079         LCHS_HEADER,
2080         LCHS_CR1,
2081         LCHS_LF1,
2082         LCHS_CR2,
2083         LCHS_LF2,
2084         LHCS_PAYLOAD,
2085         LCHS_SINGLE_0A,
2086 };
2087
2088 struct lws_cgi_args {
2089         struct lws **stdwsi; /* get fd with lws_get_socket_fd() */
2090         enum lws_enum_stdinouterr ch;
2091         unsigned char *data; /* for messages with payload */
2092         enum lws_cgi_hdr_state hdr_state;
2093         int len;
2094 };
2095
2096 LWS_VISIBLE LWS_EXTERN int
2097 lws_cgi(struct lws *wsi, const char * const *exec_array,
2098         int script_uri_path_len, int timeout_secs,
2099         const struct lws_protocol_vhost_options *mp_cgienv);
2100
2101 LWS_VISIBLE LWS_EXTERN int
2102 lws_cgi_write_split_stdout_headers(struct lws *wsi);
2103
2104 LWS_VISIBLE LWS_EXTERN int
2105 lws_cgi_kill(struct lws *wsi);
2106 #endif
2107
2108 LWS_VISIBLE LWS_EXTERN int
2109 lws_http_client_read(struct lws *wsi, char **buf, int *len);
2110
2111 /*
2112  * Wsi-associated File Operations access helpers
2113  *
2114  * Use these helper functions if you want to access a file from the perspective
2115  * of a specific wsi, which is usually the case.  If you just want contextless
2116  * file access, use the fops callbacks directly with NULL wsi instead of these
2117  * helpers.
2118  *
2119  * If so, then it calls the platform handler or user overrides where present
2120  * (as defined in info->fops)
2121  *
2122  * The advantage from all this is user code can be portable for file operations
2123  * without having to deal with differences between platforms.
2124  */
2125
2126 static LWS_INLINE lws_filefd_type LWS_WARN_UNUSED_RESULT
2127 lws_plat_file_open(struct lws *wsi, const char *filename,
2128                    unsigned long *filelen, int flags)
2129 {
2130         return lws_get_fops(lws_get_context(wsi))->open(wsi, filename,
2131                                                     filelen, flags);
2132 }
2133
2134 static LWS_INLINE int
2135 lws_plat_file_close(struct lws *wsi, lws_filefd_type fd)
2136 {
2137         return lws_get_fops(lws_get_context(wsi))->close(wsi, fd);
2138 }
2139
2140 static LWS_INLINE unsigned long
2141 lws_plat_file_seek_cur(struct lws *wsi, lws_filefd_type fd, long offset)
2142 {
2143         return lws_get_fops(lws_get_context(wsi))->seek_cur(wsi, fd, offset);
2144 }
2145
2146 static LWS_INLINE int LWS_WARN_UNUSED_RESULT
2147 lws_plat_file_read(struct lws *wsi, lws_filefd_type fd, unsigned long *amount,
2148                    unsigned char *buf, unsigned long len)
2149 {
2150         return lws_get_fops(lws_get_context(wsi))->read(wsi, fd, amount, buf,
2151                                                         len);
2152 }
2153
2154 static LWS_INLINE int LWS_WARN_UNUSED_RESULT
2155 lws_plat_file_write(struct lws *wsi, lws_filefd_type fd, unsigned long *amount,
2156                     unsigned char *buf, unsigned long len)
2157 {
2158         return lws_get_fops(lws_get_context(wsi))->write(wsi, fd, amount, buf,
2159                                                          len);
2160 }
2161
2162 /*
2163  * Note: this is not normally needed as a user api.  It's provided in case it is
2164  * useful when integrating with other app poll loop service code.
2165  */
2166 LWS_VISIBLE LWS_EXTERN int
2167 lws_read(struct lws *wsi, unsigned char *buf, size_t len);
2168
2169 #ifndef LWS_NO_EXTENSIONS
2170 /* Deprecated
2171  *
2172  * There is no longer a set internal extensions table.  The table is provided
2173  * by user code along with application-specific settings.  See the test
2174  * client and server for how to do.
2175  */
2176 static LWS_INLINE LWS_WARN_DEPRECATED const struct lws_extension *
2177 lws_get_internal_extensions() { return NULL; }
2178 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2179 lws_ext_parse_options(const struct lws_extension *ext, struct lws *wsi,
2180                        void *ext_user, const struct lws_ext_options *opts,
2181                        const char *o, int len);
2182 #endif
2183
2184 /*
2185  * custom allocator support
2186  */
2187 LWS_VISIBLE LWS_EXTERN void
2188 lws_set_allocator(void *(*realloc)(void *ptr, size_t size));
2189
2190 #ifdef __cplusplus
2191 }
2192 #endif
2193
2194 #endif