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