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