lib/libwebsockets.h

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