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