2 * libwebsockets - small server side websockets and web server implementation
4 * Copyright (C) 2010-2016 Andy Green <andy@warmcat.com>
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.
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.
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,
22 #ifndef LIBWEBSOCKET_H_3060898B846849FF9F88F5DB59B5950C
23 #define LIBWEBSOCKET_H_3060898B846849FF9F88F5DB59B5950C
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"
36 using namespace mbed::Sockets::v0;
48 awaiting_on_writeable(0)
53 void set_wsi(struct lws *_wsi) { wsi = _wsi; }
54 int actual_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);
67 char awaiting_on_writeable;
70 class lws_conn_listener : lws_conn {
73 srv(SOCKET_STACK_LWIP_IPV4)
75 srv.setOnError(TCPStream::ErrorHandler_t(this,
76 &lws_conn_listener::onError));
79 void start(const uint16_t port);
83 void onError(Socket *s, socket_error_t err);
84 void onIncoming(TCPListener *s, void *impl);
85 void onDisconnect(TCPStream *s);
105 #include "lws_config.h"
107 #if defined(WIN32) || defined(_WIN32)
108 #ifndef WIN32_LEAN_AND_MEAN
109 #define WIN32_LEAN_AND_MEAN
112 #include <winsock2.h>
113 #include <ws2tcpip.h>
120 #define _O_RDONLY 0x0000
121 #define O_RDONLY _O_RDONLY
124 // Visual studio older than 2015 and WIN_CE has only _stricmp
125 #if (defined(_MSC_VER) && _MSC_VER < 1900) || defined(_WIN32_WCE)
126 #define strcasecmp _stricmp
128 #define strcasecmp stricmp
130 #define getdtablesize() 30000
132 #define LWS_INLINE __inline
134 #define LWS_WARN_UNUSED_RESULT
135 #define LWS_WARN_DEPRECATED
139 #define LWS_EXTERN extern __declspec(dllexport)
141 #define LWS_EXTERN extern __declspec(dllimport)
147 #define LWS_INVALID_FILE INVALID_HANDLE_VALUE
148 #define LWS_O_RDONLY _O_RDONLY
150 #if !defined(_MSC_VER) || _MSC_VER < 1900 /* Visual Studio 2015 already defines this in <stdio.h> */
151 #define snprintf _snprintf
155 #define __func__ __FUNCTION__
158 #else /* NOT WIN32 */
161 #if defined(__NetBSD__) || defined(__FreeBSD__)
162 #include <netinet/in.h>
165 #define LWS_INLINE inline
166 #define LWS_O_RDONLY O_RDONLY
168 #ifndef MBED_OPERATORS
171 #define LWS_INVALID_FILE -1
173 #define getdtablesize() (20)
174 #define LWS_INVALID_FILE NULL
177 #if defined(__GNUC__)
179 /* warn_unused_result attribute only supported by GCC 3.4 or later */
180 #if __GNUC__ >= 4 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
181 #define LWS_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
183 #define LWS_WARN_UNUSED_RESULT
186 #define LWS_VISIBLE __attribute__((visibility("default")))
187 #define LWS_WARN_DEPRECATED __attribute__ ((deprecated))
190 #define LWS_WARN_UNUSED_RESULT
191 #define LWS_WARN_DEPRECATED
194 #if defined(__ANDROID__)
196 #define getdtablesize() sysconf(_SC_OPEN_MAX)
203 #endif /* LWS_USE_LIBEV */
206 #endif /* LWS_USE_LIBUV */
209 #define LWS_EXTERN extern
215 #include <sys/time.h>
219 #ifdef LWS_OPENSSL_SUPPORT
222 #ifdef USE_OLD_CYASSL
223 #include <cyassl/openssl/ssl.h>
224 #include <cyassl/error-ssl.h>
226 #include <wolfssl/openssl/ssl.h>
227 #include <wolfssl/error-ssl.h>
228 #endif /* not USE_OLD_CYASSL */
230 #if defined(LWS_USE_POLARSSL)
231 #include <polarssl/ssl.h>
232 struct lws_polarssl_context {
234 x509_crt certificate;
237 typedef struct lws_polarssl_context SSL_CTX;
238 typedef ssl_context SSL;
240 #if defined(LWS_USE_MBEDTLS)
241 #include <mbedtls/ssl.h>
243 #include <openssl/ssl.h>
244 #include <openssl/err.h>
245 #endif /* not USE_MBEDTLS */
246 #endif /* not USE_POLARSSL */
247 #endif /* not USE_WOLFSSL */
251 #define CONTEXT_PORT_NO_LISTEN -1
253 enum lws_log_levels {
263 LLL_LATENCY = 1 << 9,
265 LLL_COUNT = 10 /* set to count of valid flags */
268 LWS_VISIBLE LWS_EXTERN void _lws_log(int filter, const char *format, ...);
269 LWS_VISIBLE LWS_EXTERN void _lws_logv(int filter, const char *format, va_list vl);
270 LWS_VISIBLE LWS_EXTERN int
271 lwsl_timestamp(int level, char *p, int len);
273 /* notice, warn and log are always compiled in */
274 #define lwsl_notice(...) _lws_log(LLL_NOTICE, __VA_ARGS__)
275 #define lwsl_warn(...) _lws_log(LLL_WARN, __VA_ARGS__)
276 #define lwsl_err(...) _lws_log(LLL_ERR, __VA_ARGS__)
278 * weaker logging can be deselected at configure time using --disable-debug
279 * that gets rid of the overhead of checking while keeping _warn and _err
284 #define lwsl_info(...) _lws_log(LLL_INFO, __VA_ARGS__)
285 #define lwsl_debug(...) _lws_log(LLL_DEBUG, __VA_ARGS__)
286 #define lwsl_parser(...) _lws_log(LLL_PARSER, __VA_ARGS__)
287 #define lwsl_header(...) _lws_log(LLL_HEADER, __VA_ARGS__)
288 #define lwsl_ext(...) _lws_log(LLL_EXT, __VA_ARGS__)
289 #define lwsl_client(...) _lws_log(LLL_CLIENT, __VA_ARGS__)
290 #define lwsl_latency(...) _lws_log(LLL_LATENCY, __VA_ARGS__)
291 LWS_VISIBLE LWS_EXTERN void lwsl_hexdump(void *buf, size_t len);
295 #define lwsl_info(...) {}
296 #define lwsl_debug(...) {}
297 #define lwsl_parser(...) {}
298 #define lwsl_header(...) {}
299 #define lwsl_ext(...) {}
300 #define lwsl_client(...) {}
301 #define lwsl_latency(...) {}
302 #define lwsl_hexdump(a, b)
308 #ifndef lws_container_of
309 #define lws_container_of(P,T,M) ((T *)((char *)(P) - offsetof(T, M)))
314 #define ARRAY_SIZE(x) (sizeof(x) / sizeof(x[0]))
316 /* api change list for user code to test against */
318 #define LWS_FEATURE_SERVE_HTTP_FILE_HAS_OTHER_HEADERS_ARG
320 /* the struct lws_protocols has the id field present */
321 #define LWS_FEATURE_PROTOCOLS_HAS_ID_FIELD
323 /* you can call lws_get_peer_write_allowance */
324 #define LWS_FEATURE_PROTOCOLS_HAS_PEER_WRITE_ALLOWANCE
326 /* extra parameter introduced in 917f43ab821 */
327 #define LWS_FEATURE_SERVE_HTTP_FILE_HAS_OTHER_HEADERS_LEN
329 /* File operations stuff exists */
330 #define LWS_FEATURE_FOPS
333 * NOTE: These public enums are part of the abi. If you want to add one,
334 * add it at where specified so existing users are unaffected.
336 enum lws_context_options {
337 LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT = (1 << 1) |
339 LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME = (1 << 2),
340 LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT = (1 << 3) |
342 LWS_SERVER_OPTION_LIBEV = (1 << 4),
343 LWS_SERVER_OPTION_DISABLE_IPV6 = (1 << 5),
344 LWS_SERVER_OPTION_DISABLE_OS_CA_CERTS = (1 << 6),
345 LWS_SERVER_OPTION_PEER_CERT_NOT_REQUIRED = (1 << 7),
346 LWS_SERVER_OPTION_VALIDATE_UTF8 = (1 << 8),
347 LWS_SERVER_OPTION_SSL_ECDH = (1 << 9) |
349 LWS_SERVER_OPTION_LIBUV = (1 << 10),
350 LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS = (1 << 11) |
353 LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT = (1 << 12),
354 LWS_SERVER_OPTION_EXPLICIT_VHOSTS = (1 << 13),
355 LWS_SERVER_OPTION_UNIX_SOCK = (1 << 14),
356 LWS_SERVER_OPTION_STS = (1 << 15),
357 LWS_SERVER_OPTION_IPV6_V6ONLY_MODIFY = (1 << 16),
358 LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE = (1 << 17),
360 /****** add new things just above ---^ ******/
363 #define lws_check_opt(c, f) (((c) & (f)) == (f))
366 * NOTE: These public enums are part of the abi. If you want to add one,
367 * add it at where specified so existing users are unaffected.
369 enum lws_callback_reasons {
370 LWS_CALLBACK_ESTABLISHED = 0,
371 LWS_CALLBACK_CLIENT_CONNECTION_ERROR = 1,
372 LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH = 2,
373 LWS_CALLBACK_CLIENT_ESTABLISHED = 3,
374 LWS_CALLBACK_CLOSED = 4,
375 LWS_CALLBACK_CLOSED_HTTP = 5,
376 LWS_CALLBACK_RECEIVE = 6,
377 LWS_CALLBACK_RECEIVE_PONG = 7,
378 LWS_CALLBACK_CLIENT_RECEIVE = 8,
379 LWS_CALLBACK_CLIENT_RECEIVE_PONG = 9,
380 LWS_CALLBACK_CLIENT_WRITEABLE = 10,
381 LWS_CALLBACK_SERVER_WRITEABLE = 11,
382 LWS_CALLBACK_HTTP = 12,
383 LWS_CALLBACK_HTTP_BODY = 13,
384 LWS_CALLBACK_HTTP_BODY_COMPLETION = 14,
385 LWS_CALLBACK_HTTP_FILE_COMPLETION = 15,
386 LWS_CALLBACK_HTTP_WRITEABLE = 16,
387 LWS_CALLBACK_FILTER_NETWORK_CONNECTION = 17,
388 LWS_CALLBACK_FILTER_HTTP_CONNECTION = 18,
389 LWS_CALLBACK_SERVER_NEW_CLIENT_INSTANTIATED = 19,
390 LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION = 20,
391 LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS = 21,
392 LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS = 22,
393 LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION = 23,
394 LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER = 24,
395 LWS_CALLBACK_CONFIRM_EXTENSION_OKAY = 25,
396 LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED = 26,
397 LWS_CALLBACK_PROTOCOL_INIT = 27,
398 LWS_CALLBACK_PROTOCOL_DESTROY = 28,
399 LWS_CALLBACK_WSI_CREATE /* always protocol[0] */ = 29,
400 LWS_CALLBACK_WSI_DESTROY /* always protocol[0] */ = 30,
401 LWS_CALLBACK_GET_THREAD_ID = 31,
403 /* external poll() management support */
404 LWS_CALLBACK_ADD_POLL_FD = 32,
405 LWS_CALLBACK_DEL_POLL_FD = 33,
406 LWS_CALLBACK_CHANGE_MODE_POLL_FD = 34,
407 LWS_CALLBACK_LOCK_POLL = 35,
408 LWS_CALLBACK_UNLOCK_POLL = 36,
410 LWS_CALLBACK_OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY = 37,
411 LWS_CALLBACK_WS_PEER_INITIATED_CLOSE = 38,
413 LWS_CALLBACK_WS_EXT_DEFAULTS = 39,
415 LWS_CALLBACK_CGI = 40,
416 LWS_CALLBACK_CGI_TERMINATED = 41,
417 LWS_CALLBACK_CGI_STDIN_DATA = 42,
418 LWS_CALLBACK_CGI_STDIN_COMPLETED = 43,
419 LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP = 44,
420 LWS_CALLBACK_CLOSED_CLIENT_HTTP = 45,
421 LWS_CALLBACK_RECEIVE_CLIENT_HTTP = 46,
422 LWS_CALLBACK_COMPLETED_CLIENT_HTTP = 47,
423 LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ = 48,
425 /****** add new things just above ---^ ******/
427 LWS_CALLBACK_USER = 1000, /* user code can use any including / above */
432 typedef SOCKET lws_sockfd_type;
433 typedef HANDLE lws_filefd_type;
434 #define lws_sockfd_valid(sfd) (!!sfd)
442 #if defined(MBED_OPERATORS)
443 /* it's a class lws_conn * */
444 typedef void * lws_sockfd_type;
445 typedef void * lws_filefd_type;
446 #define lws_sockfd_valid(sfd) (!!sfd)
452 #define POLLIN 0x0001
453 #define POLLPRI 0x0002
454 #define POLLOUT 0x0004
455 #define POLLERR 0x0008
456 #define POLLHUP 0x0010
457 #define POLLNVAL 0x0020
461 void * mbed3_create_tcp_stream_socket(void);
462 void mbed3_delete_tcp_stream_socket(void *sockfd);
463 void mbed3_tcp_stream_bind(void *sock, int port, struct lws *);
464 void mbed3_tcp_stream_accept(void *sock, struct lws *);
466 typedef int lws_sockfd_type;
467 typedef int lws_filefd_type;
468 #define lws_sockfd_valid(sfd) (sfd >= 0)
471 #define lws_pollfd pollfd
474 /* argument structure for all external poll related calls
477 struct lws_pollargs {
478 lws_sockfd_type fd; /* applicable socket descriptor */
479 int events; /* the new event mask */
480 int prev_events; /* the previous event mask */
484 * struct lws_plat_file_ops - Platform-specific file operations
486 * These provide platform-agnostic ways to deal with filesystem access in the
487 * library and in the user code.
489 * @open: Open file (always binary access if plat supports it)
490 * filelen is filled on exit to be the length of the file
491 * flags should be set to O_RDONLY or O_RDWR
493 * @seek_cur: Seek from current position
494 * @read: Read fron file *amount is set on exit to amount read
495 * @write: Write to file *amount is set on exit as amount written
497 struct lws_plat_file_ops {
498 lws_filefd_type (*open)(struct lws *wsi, const char *filename,
499 unsigned long *filelen, int flags);
500 int (*close)(struct lws *wsi, lws_filefd_type fd);
501 unsigned long (*seek_cur)(struct lws *wsi, lws_filefd_type fd,
502 long offset_from_cur_pos);
503 int (*read)(struct lws *wsi, lws_filefd_type fd, unsigned long *amount,
504 unsigned char *buf, unsigned long len);
505 int (*write)(struct lws *wsi, lws_filefd_type fd, unsigned long *amount,
506 unsigned char *buf, unsigned long len);
508 /* Add new things just above here ---^
509 * This is part of the ABI, don't needlessly break compatibility */
513 * NOTE: These public enums are part of the abi. If you want to add one,
514 * add it at where specified so existing users are unaffected.
516 enum lws_extension_callback_reasons {
517 LWS_EXT_CB_SERVER_CONTEXT_CONSTRUCT = 0,
518 LWS_EXT_CB_CLIENT_CONTEXT_CONSTRUCT = 1,
519 LWS_EXT_CB_SERVER_CONTEXT_DESTRUCT = 2,
520 LWS_EXT_CB_CLIENT_CONTEXT_DESTRUCT = 3,
521 LWS_EXT_CB_CONSTRUCT = 4,
522 LWS_EXT_CB_CLIENT_CONSTRUCT = 5,
523 LWS_EXT_CB_CHECK_OK_TO_REALLY_CLOSE = 6,
524 LWS_EXT_CB_CHECK_OK_TO_PROPOSE_EXTENSION = 7,
525 LWS_EXT_CB_DESTROY = 8,
526 LWS_EXT_CB_DESTROY_ANY_WSI_CLOSING = 9,
527 LWS_EXT_CB_ANY_WSI_ESTABLISHED = 10,
528 LWS_EXT_CB_PACKET_RX_PREPARSE = 11,
529 LWS_EXT_CB_PACKET_TX_PRESEND = 12,
530 LWS_EXT_CB_PACKET_TX_DO_SEND = 13,
531 LWS_EXT_CB_HANDSHAKE_REPLY_TX = 14,
532 LWS_EXT_CB_FLUSH_PENDING_TX = 15,
533 LWS_EXT_CB_EXTENDED_PAYLOAD_RX = 16,
534 LWS_EXT_CB_CAN_PROXY_CLIENT_CONNECTION = 17,
536 LWS_EXT_CB_REQUEST_ON_WRITEABLE = 19,
537 LWS_EXT_CB_IS_WRITEABLE = 20,
538 LWS_EXT_CB_PAYLOAD_TX = 21,
539 LWS_EXT_CB_PAYLOAD_RX = 22,
540 LWS_EXT_CB_OPTION_DEFAULT = 23,
541 LWS_EXT_CB_OPTION_SET = 24,
542 LWS_EXT_CB_OPTION_CONFIRM = 25,
543 LWS_EXT_CB_NAMED_OPTION_SET = 26,
545 /****** add new things just above ---^ ******/
549 * NOTE: These public enums are part of the abi. If you want to add one,
550 * add it at where specified so existing users are unaffected.
552 enum lws_write_protocol {
554 LWS_WRITE_BINARY = 1,
555 LWS_WRITE_CONTINUATION = 2,
558 /* special 04+ opcodes */
560 /* LWS_WRITE_CLOSE is handled by lws_close_reason() */
564 /* Same as write_http but we know this write ends the transaction */
565 LWS_WRITE_HTTP_FINAL = 7,
569 LWS_WRITE_HTTP_HEADERS = 8,
571 /****** add new things just above ---^ ******/
575 LWS_WRITE_NO_FIN = 0x40,
577 * client packet payload goes out on wire unmunged
578 * only useful for security tests since normal servers cannot
579 * decode the content if used
581 LWS_WRITE_CLIENT_IGNORE_XOR_MASK = 0x80
585 * you need these to look at headers that have been parsed if using the
586 * LWS_CALLBACK_FILTER_CONNECTION callback. If a header from the enum
587 * list below is absent, .token = NULL and token_len = 0. Otherwise .token
588 * points to .token_len chars containing that header content.
597 * these have to be kept in sync with lextable.h / minilex.c
599 * NOTE: These public enums are part of the abi. If you want to add one,
600 * add it at where specified so existing users are unaffected.
602 enum lws_token_indexes {
603 WSI_TOKEN_GET_URI = 0,
604 WSI_TOKEN_POST_URI = 1,
605 WSI_TOKEN_OPTIONS_URI = 2,
607 WSI_TOKEN_CONNECTION = 4,
608 WSI_TOKEN_UPGRADE = 5,
609 WSI_TOKEN_ORIGIN = 6,
611 WSI_TOKEN_CHALLENGE = 8,
612 WSI_TOKEN_EXTENSIONS = 9,
615 WSI_TOKEN_PROTOCOL = 12,
616 WSI_TOKEN_ACCEPT = 13,
617 WSI_TOKEN_NONCE = 14,
619 WSI_TOKEN_HTTP2_SETTINGS = 16,
620 WSI_TOKEN_HTTP_ACCEPT = 17,
621 WSI_TOKEN_HTTP_AC_REQUEST_HEADERS = 18,
622 WSI_TOKEN_HTTP_IF_MODIFIED_SINCE = 19,
623 WSI_TOKEN_HTTP_IF_NONE_MATCH = 20,
624 WSI_TOKEN_HTTP_ACCEPT_ENCODING = 21,
625 WSI_TOKEN_HTTP_ACCEPT_LANGUAGE = 22,
626 WSI_TOKEN_HTTP_PRAGMA = 23,
627 WSI_TOKEN_HTTP_CACHE_CONTROL = 24,
628 WSI_TOKEN_HTTP_AUTHORIZATION = 25,
629 WSI_TOKEN_HTTP_COOKIE = 26,
630 WSI_TOKEN_HTTP_CONTENT_LENGTH = 27,
631 WSI_TOKEN_HTTP_CONTENT_TYPE = 28,
632 WSI_TOKEN_HTTP_DATE = 29,
633 WSI_TOKEN_HTTP_RANGE = 30,
634 WSI_TOKEN_HTTP_REFERER = 31,
636 WSI_TOKEN_VERSION = 33,
637 WSI_TOKEN_SWORIGIN = 34,
639 WSI_TOKEN_HTTP_COLON_AUTHORITY = 35,
640 WSI_TOKEN_HTTP_COLON_METHOD = 36,
641 WSI_TOKEN_HTTP_COLON_PATH = 37,
642 WSI_TOKEN_HTTP_COLON_SCHEME = 38,
643 WSI_TOKEN_HTTP_COLON_STATUS = 39,
645 WSI_TOKEN_HTTP_ACCEPT_CHARSET = 40,
646 WSI_TOKEN_HTTP_ACCEPT_RANGES = 41,
647 WSI_TOKEN_HTTP_ACCESS_CONTROL_ALLOW_ORIGIN = 42,
648 WSI_TOKEN_HTTP_AGE = 43,
649 WSI_TOKEN_HTTP_ALLOW = 44,
650 WSI_TOKEN_HTTP_CONTENT_DISPOSITION = 45,
651 WSI_TOKEN_HTTP_CONTENT_ENCODING = 46,
652 WSI_TOKEN_HTTP_CONTENT_LANGUAGE = 47,
653 WSI_TOKEN_HTTP_CONTENT_LOCATION = 48,
654 WSI_TOKEN_HTTP_CONTENT_RANGE = 49,
655 WSI_TOKEN_HTTP_ETAG = 50,
656 WSI_TOKEN_HTTP_EXPECT = 51,
657 WSI_TOKEN_HTTP_EXPIRES = 52,
658 WSI_TOKEN_HTTP_FROM = 53,
659 WSI_TOKEN_HTTP_IF_MATCH = 54,
660 WSI_TOKEN_HTTP_IF_RANGE = 55,
661 WSI_TOKEN_HTTP_IF_UNMODIFIED_SINCE = 56,
662 WSI_TOKEN_HTTP_LAST_MODIFIED = 57,
663 WSI_TOKEN_HTTP_LINK = 58,
664 WSI_TOKEN_HTTP_LOCATION = 59,
665 WSI_TOKEN_HTTP_MAX_FORWARDS = 60,
666 WSI_TOKEN_HTTP_PROXY_AUTHENTICATE = 61,
667 WSI_TOKEN_HTTP_PROXY_AUTHORIZATION = 62,
668 WSI_TOKEN_HTTP_REFRESH = 63,
669 WSI_TOKEN_HTTP_RETRY_AFTER = 64,
670 WSI_TOKEN_HTTP_SERVER = 65,
671 WSI_TOKEN_HTTP_SET_COOKIE = 66,
672 WSI_TOKEN_HTTP_STRICT_TRANSPORT_SECURITY = 67,
673 WSI_TOKEN_HTTP_TRANSFER_ENCODING = 68,
674 WSI_TOKEN_HTTP_USER_AGENT = 69,
675 WSI_TOKEN_HTTP_VARY = 70,
676 WSI_TOKEN_HTTP_VIA = 71,
677 WSI_TOKEN_HTTP_WWW_AUTHENTICATE = 72,
679 WSI_TOKEN_PATCH_URI = 73,
680 WSI_TOKEN_PUT_URI = 74,
681 WSI_TOKEN_DELETE_URI = 75,
683 WSI_TOKEN_HTTP_URI_ARGS = 76,
684 WSI_TOKEN_PROXY = 77,
685 WSI_TOKEN_HTTP_X_REAL_IP = 78,
686 WSI_TOKEN_HTTP1_0 = 79,
688 /****** add new things just above ---^ ******/
690 /* use token storage to stash these internally, not for
693 _WSI_TOKEN_CLIENT_SENT_PROTOCOLS,
694 _WSI_TOKEN_CLIENT_PEER_ADDRESS,
695 _WSI_TOKEN_CLIENT_URI,
696 _WSI_TOKEN_CLIENT_HOST,
697 _WSI_TOKEN_CLIENT_ORIGIN,
698 _WSI_TOKEN_CLIENT_METHOD,
700 /* always last real token index*/
703 /* parser state additions, no storage associated */
706 WSI_TOKEN_SKIPPING_SAW_CR,
707 WSI_PARSING_COMPLETE,
708 WSI_INIT_TOKEN_MUXURL,
711 struct lws_token_limits {
712 unsigned short token_limit[WSI_TOKEN_COUNT];
719 1000 indicates a normal closure, meaning that the purpose for
720 which the connection was established has been fulfilled.
724 1001 indicates that an endpoint is "going away", such as a server
725 going down or a browser having navigated away from a page.
729 1002 indicates that an endpoint is terminating the connection due
734 1003 indicates that an endpoint is terminating the connection
735 because it has received a type of data it cannot accept (e.g., an
736 endpoint that understands only text data MAY send this if it
737 receives a binary message).
741 Reserved. The specific meaning might be defined in the future.
745 1005 is a reserved value and MUST NOT be set as a status code in a
746 Close control frame by an endpoint. It is designated for use in
747 applications expecting a status code to indicate that no status
748 code was actually present.
752 1006 is a reserved value and MUST NOT be set as a status code in a
753 Close control frame by an endpoint. It is designated for use in
754 applications expecting a status code to indicate that the
755 connection was closed abnormally, e.g., without sending or
756 receiving a Close control frame.
760 1007 indicates that an endpoint is terminating the connection
761 because it has received data within a message that was not
762 consistent with the type of the message (e.g., non-UTF-8 [RFC3629]
763 data within a text message).
767 1008 indicates that an endpoint is terminating the connection
768 because it has received a message that violates its policy. This
769 is a generic status code that can be returned when there is no
770 other more suitable status code (e.g., 1003 or 1009) or if there
771 is a need to hide specific details about the policy.
775 1009 indicates that an endpoint is terminating the connection
776 because it has received a message that is too big for it to
781 1010 indicates that an endpoint (client) is terminating the
782 connection because it has expected the server to negotiate one or
783 more extension, but the server didn't return them in the response
784 message of the WebSocket handshake. The list of extensions that
785 are needed SHOULD appear in the /reason/ part of the Close frame.
786 Note that this status code is not used by the server, because it
787 can fail the WebSocket handshake instead.
791 1011 indicates that a server is terminating the connection because
792 it encountered an unexpected condition that prevented it from
793 fulfilling the request.
797 1015 is a reserved value and MUST NOT be set as a status code in a
798 Close control frame by an endpoint. It is designated for use in
799 applications expecting a status code to indicate that the
800 connection was closed due to a failure to perform a TLS handshake
801 (e.g., the server certificate can't be verified).
805 * NOTE: These public enums are part of the abi. If you want to add one,
806 * add it at where specified so existing users are unaffected.
808 enum lws_close_status {
809 LWS_CLOSE_STATUS_NOSTATUS = 0,
810 LWS_CLOSE_STATUS_NORMAL = 1000,
811 LWS_CLOSE_STATUS_GOINGAWAY = 1001,
812 LWS_CLOSE_STATUS_PROTOCOL_ERR = 1002,
813 LWS_CLOSE_STATUS_UNACCEPTABLE_OPCODE = 1003,
814 LWS_CLOSE_STATUS_RESERVED = 1004,
815 LWS_CLOSE_STATUS_NO_STATUS = 1005,
816 LWS_CLOSE_STATUS_ABNORMAL_CLOSE = 1006,
817 LWS_CLOSE_STATUS_INVALID_PAYLOAD = 1007,
818 LWS_CLOSE_STATUS_POLICY_VIOLATION = 1008,
819 LWS_CLOSE_STATUS_MESSAGE_TOO_LARGE = 1009,
820 LWS_CLOSE_STATUS_EXTENSION_REQUIRED = 1010,
821 LWS_CLOSE_STATUS_UNEXPECTED_CONDITION = 1011,
822 LWS_CLOSE_STATUS_TLS_FAILURE = 1015,
824 /****** add new things just above ---^ ******/
826 LWS_CLOSE_STATUS_NOSTATUS_CONTEXT_DESTROY = 9999,
830 HTTP_STATUS_OK = 200,
831 HTTP_STATUS_NO_CONTENT = 204,
833 HTTP_STATUS_MOVED_PERMANENTLY = 301,
834 HTTP_STATUS_FOUND = 302,
835 HTTP_STATUS_SEE_OTHER = 303,
837 HTTP_STATUS_BAD_REQUEST = 400,
838 HTTP_STATUS_UNAUTHORIZED,
839 HTTP_STATUS_PAYMENT_REQUIRED,
840 HTTP_STATUS_FORBIDDEN,
841 HTTP_STATUS_NOT_FOUND,
842 HTTP_STATUS_METHOD_NOT_ALLOWED,
843 HTTP_STATUS_NOT_ACCEPTABLE,
844 HTTP_STATUS_PROXY_AUTH_REQUIRED,
845 HTTP_STATUS_REQUEST_TIMEOUT,
846 HTTP_STATUS_CONFLICT,
848 HTTP_STATUS_LENGTH_REQUIRED,
849 HTTP_STATUS_PRECONDITION_FAILED,
850 HTTP_STATUS_REQ_ENTITY_TOO_LARGE,
851 HTTP_STATUS_REQ_URI_TOO_LONG,
852 HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE,
853 HTTP_STATUS_REQ_RANGE_NOT_SATISFIABLE,
854 HTTP_STATUS_EXPECTATION_FAILED,
856 HTTP_STATUS_INTERNAL_SERVER_ERROR = 500,
857 HTTP_STATUS_NOT_IMPLEMENTED,
858 HTTP_STATUS_BAD_GATEWAY,
859 HTTP_STATUS_SERVICE_UNAVAILABLE,
860 HTTP_STATUS_GATEWAY_TIMEOUT,
861 HTTP_STATUS_HTTP_VERSION_NOT_SUPPORTED,
866 /* needed even with extensions disabled for create context */
867 struct lws_extension;
870 * typedef lws_callback_function() - User server actions
871 * @wsi: Opaque websocket instance pointer
872 * @reason: The reason for the call
873 * @user: Pointer to per-session user data allocated by library
874 * @in: Pointer used for some callback reasons
875 * @len: Length set for some callback reasons
877 * This callback is the way the user controls what is served. All the
878 * protocol detail is hidden and handled by the library.
880 * For each connection / session there is user data allocated that is
881 * pointed to by "user". You set the size of this user data area when
882 * the library is initialized with lws_create_server.
884 * You get an opportunity to initialize user data when called back with
885 * LWS_CALLBACK_ESTABLISHED reason.
887 * LWS_CALLBACK_ESTABLISHED: after the server completes a handshake with
888 * an incoming client. If you built the library
889 * with ssl support, @in is a pointer to the
890 * ssl struct associated with the connection or
893 * LWS_CALLBACK_CLIENT_CONNECTION_ERROR: the request client connection has
894 * been unable to complete a handshake with the remote server. If
895 * in is non-NULL, you can find an error string of length len where
898 * LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH: this is the last chance for the
899 * client user code to examine the http headers
900 * and decide to reject the connection. If the
901 * content in the headers is interesting to the
902 * client (url, etc) it needs to copy it out at
903 * this point since it will be destroyed before
904 * the CLIENT_ESTABLISHED call
906 * LWS_CALLBACK_CLIENT_ESTABLISHED: after your client connection completed
907 * a handshake with the remote server
909 * LWS_CALLBACK_CLOSED: when the websocket session ends
911 * LWS_CALLBACK_CLOSED_HTTP: when a HTTP (non-websocket) session ends
913 * LWS_CALLBACK_RECEIVE: data has appeared for this server endpoint from a
914 * remote client, it can be found at *in and is
917 * LWS_CALLBACK_CLIENT_RECEIVE_PONG: if you elected to see PONG packets,
918 * they appear with this callback reason. PONG
919 * packets only exist in 04+ protocol
921 * LWS_CALLBACK_CLIENT_RECEIVE: data has appeared from the server for the
922 * client connection, it can be found at *in and
925 * LWS_CALLBACK_HTTP: an http request has come from a client that is not
926 * asking to upgrade the connection to a websocket
927 * one. This is a chance to serve http content,
928 * for example, to send a script to the client
929 * which will then open the websockets connection.
930 * @in points to the URI path requested and
931 * lws_serve_http_file() makes it very
932 * simple to send back a file to the client.
933 * Normally after sending the file you are done
934 * with the http connection, since the rest of the
935 * activity will come by websockets from the script
936 * that was delivered by http, so you will want to
937 * return 1; to close and free up the connection.
938 * That's important because it uses a slot in the
939 * total number of client connections allowed set
942 * LWS_CALLBACK_HTTP_BODY: the next @len bytes data from the http
943 * request body HTTP connection is now available in @in.
945 * LWS_CALLBACK_HTTP_BODY_COMPLETION: the expected amount of http request
946 * body has been delivered
948 * LWS_CALLBACK_HTTP_WRITEABLE: you can write more down the http protocol
951 * LWS_CALLBACK_HTTP_FILE_COMPLETION: a file requested to be send down
952 * http link has completed.
954 * LWS_CALLBACK_CLIENT_WRITEABLE:
955 * LWS_CALLBACK_SERVER_WRITEABLE: If you call
956 * lws_callback_on_writable() on a connection, you will
957 * get one of these callbacks coming when the connection socket
958 * is able to accept another write packet without blocking.
959 * If it already was able to take another packet without blocking,
960 * you'll get this callback at the next call to the service loop
961 * function. Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE
962 * and servers get LWS_CALLBACK_SERVER_WRITEABLE.
964 * LWS_CALLBACK_FILTER_NETWORK_CONNECTION: called when a client connects to
965 * the server at network level; the connection is accepted but then
966 * passed to this callback to decide whether to hang up immediately
967 * or not, based on the client IP. @in contains the connection
968 * socket's descriptor. Since the client connection information is
969 * not available yet, @wsi still pointing to the main server socket.
970 * Return non-zero to terminate the connection before sending or
971 * receiving anything. Because this happens immediately after the
972 * network connection from the client, there's no websocket protocol
973 * selected yet so this callback is issued only to protocol 0.
975 * LWS_CALLBACK_SERVER_NEW_CLIENT_INSTANTIATED: A new client just had
976 * been connected, accepted, and instantiated into the pool. This
977 * callback allows setting any relevant property to it. Because this
978 * happens immediately after the instantiation of a new client,
979 * there's no websocket protocol selected yet so this callback is
980 * issued only to protocol 0. Only @wsi is defined, pointing to the
981 * new client, and the return value is ignored.
983 * LWS_CALLBACK_FILTER_HTTP_CONNECTION: called when the request has
984 * been received and parsed from the client, but the response is
985 * not sent yet. Return non-zero to disallow the connection.
986 * @user is a pointer to the connection user space allocation,
987 * @in is the URI, eg, "/"
988 * In your handler you can use the public APIs
989 * lws_hdr_total_length() / lws_hdr_copy() to access all of the
990 * headers using the header enums lws_token_indexes from
991 * libwebsockets.h to check for and read the supported header
992 * presence and content before deciding to allow the http
993 * connection to proceed or to kill the connection.
995 * LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION: called when the handshake has
996 * been received and parsed from the client, but the response is
997 * not sent yet. Return non-zero to disallow the connection.
998 * @user is a pointer to the connection user space allocation,
999 * @in is the requested protocol name
1000 * In your handler you can use the public APIs
1001 * lws_hdr_total_length() / lws_hdr_copy() to access all of the
1002 * headers using the header enums lws_token_indexes from
1003 * libwebsockets.h to check for and read the supported header
1004 * presence and content before deciding to allow the handshake
1005 * to proceed or to kill the connection.
1007 * LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS: if configured for
1008 * including OpenSSL support, this callback allows your user code
1009 * to perform extra SSL_CTX_load_verify_locations() or similar
1010 * calls to direct OpenSSL where to find certificates the client
1011 * can use to confirm the remote server identity. @user is the
1014 * LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS: if configured for
1015 * including OpenSSL support, this callback allows your user code
1016 * to load extra certifcates into the server which allow it to
1017 * verify the validity of certificates returned by clients. @user
1018 * is the server's OpenSSL SSL_CTX*
1020 * LWS_CALLBACK_OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY: if configured for
1021 * including OpenSSL support but no private key file has been
1022 * specified (ssl_private_key_filepath is NULL), this is called to
1023 * allow the user to set the private key directly via libopenssl
1024 * and perform further operations if required; this might be useful
1025 * in situations where the private key is not directly accessible
1026 * by the OS, for example if it is stored on a smartcard
1027 * @user is the server's OpenSSL SSL_CTX*
1029 * LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION: if the
1030 * libwebsockets context was created with the option
1031 * LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this
1032 * callback is generated during OpenSSL verification of the cert
1033 * sent from the client. It is sent to protocol[0] callback as
1034 * no protocol has been negotiated on the connection yet.
1035 * Notice that the libwebsockets context and wsi are both NULL
1036 * during this callback. See
1037 * http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
1038 * to understand more detail about the OpenSSL callback that
1039 * generates this libwebsockets callback and the meanings of the
1040 * arguments passed. In this callback, @user is the x509_ctx,
1041 * @in is the ssl pointer and @len is preverify_ok
1042 * Notice that this callback maintains libwebsocket return
1043 * conventions, return 0 to mean the cert is OK or 1 to fail it.
1044 * This also means that if you don't handle this callback then
1045 * the default callback action of returning 0 allows the client
1048 * LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER: this callback happens
1049 * when a client handshake is being compiled. @user is NULL,
1050 * @in is a char **, it's pointing to a char * which holds the
1051 * next location in the header buffer where you can add
1052 * headers, and @len is the remaining space in the header buffer,
1053 * which is typically some hundreds of bytes. So, to add a canned
1054 * cookie, your handler code might look similar to:
1056 * char **p = (char **)in;
1061 * *p += sprintf(*p, "Cookie: a=b\x0d\x0a");
1065 * Notice if you add anything, you just have to take care about
1066 * the CRLF on the line you added. Obviously this callback is
1067 * optional, if you don't handle it everything is fine.
1069 * Notice the callback is coming to protocols[0] all the time,
1070 * because there is no specific protocol handshook yet.
1072 * LWS_CALLBACK_CONFIRM_EXTENSION_OKAY: When the server handshake code
1073 * sees that it does support a requested extension, before
1074 * accepting the extension by additing to the list sent back to
1075 * the client it gives this callback just to check that it's okay
1076 * to use that extension. It calls back to the requested protocol
1077 * and with @in being the extension name, @len is 0 and @user is
1078 * valid. Note though at this time the ESTABLISHED callback hasn't
1079 * happened yet so if you initialize @user content there, @user
1080 * content during this callback might not be useful for anything.
1081 * Notice this callback comes to protocols[0].
1083 * LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED: When a client
1084 * connection is being prepared to start a handshake to a server,
1085 * each supported extension is checked with protocols[0] callback
1086 * with this reason, giving the user code a chance to suppress the
1087 * claim to support that extension by returning non-zero. If
1088 * unhandled, by default 0 will be returned and the extension
1089 * support included in the header to the server. Notice this
1090 * callback comes to protocols[0].
1092 * LWS_CALLBACK_PROTOCOL_INIT: One-time call per protocol so it can
1093 * do initial setup / allocations etc
1095 * LWS_CALLBACK_PROTOCOL_DESTROY: One-time call per protocol indicating
1096 * this protocol won't get used at all after this callback, the
1097 * context is getting destroyed. Take the opportunity to
1098 * deallocate everything that was allocated by the protocol.
1100 * LWS_CALLBACK_WSI_CREATE: outermost (earliest) wsi create notification
1102 * LWS_CALLBACK_WSI_DESTROY: outermost (latest) wsi destroy notification
1104 * The next five reasons are optional and only need taking care of if you
1105 * will be integrating libwebsockets sockets into an external polling
1108 * For these calls, @in points to a struct lws_pollargs that
1109 * contains @fd, @events and @prev_events members
1111 * LWS_CALLBACK_ADD_POLL_FD: libwebsocket deals with its poll() loop
1112 * internally, but in the case you are integrating with another
1113 * server you will need to have libwebsocket sockets share a
1114 * polling array with the other server. This and the other
1115 * POLL_FD related callbacks let you put your specialized
1116 * poll array interface code in the callback for protocol 0, the
1117 * first protocol you support, usually the HTTP protocol in the
1119 * This callback happens when a socket needs to be
1120 * added to the polling loop: @in points to a struct
1121 * lws_pollargs; the @fd member of the struct is the file
1122 * descriptor, and @events contains the active events.
1124 * If you are using the internal polling loop (the "service"
1125 * callback), you can just ignore these callbacks.
1127 * LWS_CALLBACK_DEL_POLL_FD: This callback happens when a socket descriptor
1128 * needs to be removed from an external polling array. @in is
1129 * again the struct lws_pollargs containing the @fd member
1130 * to be removed. If you are using the internal polling
1131 * loop, you can just ignore it.
1133 * LWS_CALLBACK_CHANGE_MODE_POLL_FD: This callback happens when
1134 * libwebsockets wants to modify the events for a connectiion.
1135 * @in is the struct lws_pollargs with the @fd to change.
1136 * The new event mask is in @events member and the old mask is in
1137 * the @prev_events member.
1138 * If you are using the internal polling loop, you can just ignore
1141 * LWS_CALLBACK_LOCK_POLL:
1142 * LWS_CALLBACK_UNLOCK_POLL: These allow the external poll changes driven
1143 * by libwebsockets to participate in an external thread locking
1144 * scheme around the changes, so the whole thing is threadsafe.
1145 * These are called around three activities in the library,
1146 * - inserting a new wsi in the wsi / fd table (len=1)
1147 * - deleting a wsi from the wsi / fd table (len=1)
1148 * - changing a wsi's POLLIN/OUT state (len=0)
1149 * Locking and unlocking external synchronization objects when
1150 * len == 1 allows external threads to be synchronized against
1151 * wsi lifecycle changes if it acquires the same lock for the
1152 * duration of wsi dereference from the other thread context.
1154 * LWS_CALLBACK_WS_PEER_INITIATED_CLOSE:
1155 * The peer has sent an unsolicited Close WS packet. @in and
1156 * @len are the optional close code (first 2 bytes, network
1157 * order) and the optional additional information which is not
1158 * defined in the standard, and may be a string or non-human-
1160 * If you return 0 lws will echo the close and then close the
1161 * connection. If you return nonzero lws will just close the
1165 lws_callback_function(struct lws *wsi, enum lws_callback_reasons reason,
1166 void *user, void *in, size_t len);
1169 * typedef lws_extension_callback_function() - Hooks to allow extensions to operate
1170 * @context: Websockets context
1171 * @ext: This extension
1172 * @wsi: Opaque websocket instance pointer
1173 * @reason: The reason for the call
1174 * @user: Pointer to ptr to per-session user data allocated by library
1175 * @in: Pointer used for some callback reasons
1176 * @len: Length set for some callback reasons
1178 * Each extension that is active on a particular connection receives
1179 * callbacks during the connection lifetime to allow the extension to
1180 * operate on websocket data and manage itself.
1182 * Libwebsockets takes care of allocating and freeing "user" memory for
1183 * each active extension on each connection. That is what is pointed to
1184 * by the @user parameter.
1186 * LWS_EXT_CB_CONSTRUCT: called when the server has decided to
1187 * select this extension from the list provided by the client,
1188 * just before the server will send back the handshake accepting
1189 * the connection with this extension active. This gives the
1190 * extension a chance to initialize its connection context found
1193 * LWS_EXT_CB_CLIENT_CONSTRUCT: same as LWS_EXT_CB_CONSTRUCT
1194 * but called when client is instantiating this extension. Some
1195 * extensions will work the same on client and server side and then
1196 * you can just merge handlers for both CONSTRUCTS.
1198 * LWS_EXT_CB_DESTROY: called when the connection the extension was
1199 * being used on is about to be closed and deallocated. It's the
1200 * last chance for the extension to deallocate anything it has
1201 * allocated in the user data (pointed to by @user) before the
1202 * user data is deleted. This same callback is used whether you
1203 * are in client or server instantiation context.
1205 * LWS_EXT_CB_PACKET_RX_PREPARSE: when this extension was active on
1206 * a connection, and a packet of data arrived at the connection,
1207 * it is passed to this callback to give the extension a chance to
1208 * change the data, eg, decompress it. @user is pointing to the
1209 * extension's private connection context data, @in is pointing
1210 * to an lws_tokens struct, it consists of a char * pointer called
1211 * token, and an int called token_len. At entry, these are
1212 * set to point to the received buffer and set to the content
1213 * length. If the extension will grow the content, it should use
1214 * a new buffer allocated in its private user context data and
1215 * set the pointed-to lws_tokens members to point to its buffer.
1217 * LWS_EXT_CB_PACKET_TX_PRESEND: this works the same way as
1218 * LWS_EXT_CB_PACKET_RX_PREPARSE above, except it gives the
1219 * extension a chance to change websocket data just before it will
1220 * be sent out. Using the same lws_token pointer scheme in @in,
1221 * the extension can change the buffer and the length to be
1222 * transmitted how it likes. Again if it wants to grow the
1223 * buffer safely, it should copy the data into its own buffer and
1224 * set the lws_tokens token pointer to it.
1226 * LWS_EXT_CB_ARGS_VALIDATE:
1229 lws_extension_callback_function(struct lws_context *context,
1230 const struct lws_extension *ext, struct lws *wsi,
1231 enum lws_extension_callback_reasons reason,
1232 void *user, void *in, size_t len);
1235 * struct lws_protocols - List of protocols and handlers server
1237 * @name: Protocol name that must match the one given in the client
1238 * Javascript new WebSocket(url, 'protocol') name.
1239 * @callback: The service callback used for this protocol. It allows the
1240 * service action for an entire protocol to be encapsulated in
1241 * the protocol-specific callback
1242 * @per_session_data_size: Each new connection using this protocol gets
1243 * this much memory allocated on connection establishment and
1244 * freed on connection takedown. A pointer to this per-connection
1245 * allocation is passed into the callback in the 'user' parameter
1246 * @rx_buffer_size: if you want atomic frames delivered to the callback, you
1247 * should set this to the size of the biggest legal frame that
1248 * you support. If the frame size is exceeded, there is no
1249 * error, but the buffer will spill to the user callback when
1250 * full, which you can detect by using
1251 * lws_remaining_packet_payload(). Notice that you
1252 * just talk about frame size here, the LWS_PRE
1253 * and post-padding are automatically also allocated on top.
1254 * @id: ignored by lws, but useful to contain user information bound
1255 * to the selected protocol. For example if this protocol was
1256 * called "myprotocol-v2", you might set id to 2, and the user
1257 * code that acts differently according to the version can do so by
1258 * switch (wsi->protocol->id), user code might use some bits as
1259 * capability flags based on selected protocol version, etc.
1260 * @user: User provided context data at the protocol level.
1261 * Accessible via lws_get_protocol(wsi)->user
1262 * This should not be confused with wsi->user, it is not the same.
1263 * The library completely ignores any value in here.
1265 * This structure represents one protocol supported by the server. An
1266 * array of these structures is passed to lws_create_server()
1267 * allows as many protocols as you like to be handled by one server.
1269 * The first protocol given has its callback used for user callbacks when
1270 * there is no agreed protocol name, that's true during HTTP part of the
1271 * connection and true if the client did not send a Protocol: header.
1274 struct lws_protocols {
1276 lws_callback_function *callback;
1277 size_t per_session_data_size;
1278 size_t rx_buffer_size;
1282 /* Add new things just above here ---^
1283 * This is part of the ABI, don't needlessly break compatibility */
1286 enum lws_ext_options_types {
1291 /* Add new things just above here ---^
1292 * This is part of the ABI, don't needlessly break compatibility */
1296 * struct lws_ext_options - Option arguments to the extension. These are
1297 * used in the negotiation at ws upgrade time.
1298 * The helper function lws_ext_parse_options()
1299 * uses these to generate callbacks
1301 * @name: Option name, eg, "server_no_context_takeover"
1302 * @type: What kind of args the option can take
1304 struct lws_ext_options {
1306 enum lws_ext_options_types type;
1308 /* Add new things just above here ---^
1309 * This is part of the ABI, don't needlessly break compatibility */
1312 struct lws_ext_option_arg {
1313 const char *option_name; /* may be NULL, option_index used then */
1320 * struct lws_extension - An extension we know how to cope with
1322 * @name: Formal extension name, eg, "permessage-deflate"
1323 * @callback: Service callback
1324 * @client_offer: String containing exts and options client offers
1327 struct lws_extension {
1329 lws_extension_callback_function *callback;
1330 const char *client_offer;
1332 /* Add new things just above here ---^
1333 * This is part of the ABI, don't needlessly break compatibility */
1337 #ifdef LWS_WITH_PLUGINS
1339 /* PLUGINS implies LIBUV */
1341 #define LWS_PLUGIN_API_MAGIC 180
1343 struct lws_plugin_capability {
1344 unsigned int api_magic; /* caller fills this in, plugin fills rest */
1345 const struct lws_protocols *protocols;
1346 int count_protocols;
1347 const struct lws_extension *extensions;
1348 int count_extensions;
1351 typedef int (*lws_plugin_init_func)(struct lws_context *,
1352 struct lws_plugin_capability *);
1353 typedef int (*lws_plugin_destroy_func)(struct lws_context *);
1355 struct lws_plugin *list;
1356 #if (UV_VERSION_MAJOR > 0)
1362 struct lws_plugin_capability caps;
1368 * The internal exts are part of the public abi
1369 * If we add more extensions, publish the callback here ------v
1373 int lws_extension_callback_pm_deflate(
1374 struct lws_context *context, const struct lws_extension *ext,
1375 struct lws *wsi, enum lws_extension_callback_reasons reason,
1376 void *user, void *in, size_t len);
1378 LWS_VISIBLE LWS_EXTERN int
1379 lws_set_extension_option(struct lws *wsi, const char *ext_name,
1380 const char *opt_name, const char *opt_val);
1382 struct lws_protocol_vhost_options {
1383 const struct lws_protocol_vhost_options *next;
1384 const struct lws_protocol_vhost_options *options;
1389 struct lws_http_mount {
1390 struct lws_http_mount *mount_next;
1391 const char *mountpoint; /* mountpoint in http pathspace, eg, "/" */
1392 const char *origin; /* path to be mounted, eg, "/var/www/warmcat.com" */
1393 const char *def; /* default target, eg, "index.html" */
1395 const struct lws_protocol_vhost_options *cgienv;
1396 const struct lws_protocol_vhost_options *extra_mimetypes;
1401 unsigned int cache_reusable:1;
1402 unsigned int cache_revalidate:1;
1403 unsigned int cache_intermediaries:1;
1405 unsigned char origin_protocol;
1406 unsigned char mountpoint_len;
1410 * struct lws_context_creation_info - parameters to create context with
1412 * This is also used to create vhosts.... if LWS_SERVER_OPTION_EXPLICIT_VHOSTS
1413 * is not given, then for backwards compatibility one vhost is created at
1414 * context-creation time using the info from this struct.
1416 * If LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, then no vhosts are created
1417 * at the same time as the context, they are expected to be created afterwards.
1419 * @port: VHOST: Port to listen on... you can use CONTEXT_PORT_NO_LISTEN to
1420 * suppress listening on any port, that's what you want if you are
1421 * not running a websocket server at all but just using it as a
1423 * @iface: VHOST: NULL to bind the listen socket to all interfaces, or the
1424 * interface name, eg, "eth2"
1425 * If options specifies LWS_SERVER_OPTION_UNIX_SOCK, this member is
1426 * the pathname of a UNIX domain socket. you can use the UNIX domain
1427 * sockets in abstract namespace, by prepending an @ symbole to the
1429 * @protocols: VHOST: Array of structures listing supported protocols and a protocol-
1430 * specific callback for each one. The list is ended with an
1431 * entry that has a NULL callback pointer.
1432 * It's not const because we write the owning_server member
1433 * @extensions: VHOST: NULL or array of lws_extension structs listing the
1434 * extensions this context supports. If you configured with
1435 * --without-extensions, you should give NULL here.
1436 * @token_limits: CONTEXT: NULL or struct lws_token_limits pointer which is initialized
1437 * with a token length limit for each possible WSI_TOKEN_***
1438 * @ssl_cert_filepath: VHOST: If libwebsockets was compiled to use ssl, and you want
1439 * to listen using SSL, set to the filepath to fetch the
1440 * server cert from, otherwise NULL for unencrypted
1441 * @ssl_private_key_filepath: VHOST: filepath to private key if wanting SSL mode;
1442 * if this is set to NULL but sll_cert_filepath is set, the
1443 * OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY callback is called
1444 * to allow setting of the private key directly via openSSL
1446 * @ssl_ca_filepath: VHOST: CA certificate filepath or NULL
1447 * @ssl_cipher_list: VHOST: List of valid ciphers to use (eg,
1448 * "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
1449 * or you can leave it as NULL to get "DEFAULT"
1450 * @http_proxy_address: VHOST: If non-NULL, attempts to proxy via the given address.
1451 * If proxy auth is required, use format
1452 * "username:password@server:port"
1453 * @http_proxy_port: VHOST: If http_proxy_address was non-NULL, uses this port at
1455 * @gid: CONTEXT: group id to change to after setting listen socket, or -1.
1456 * @uid: CONTEXT: user id to change to after setting listen socket, or -1.
1457 * @options: VHOST + CONTEXT: 0, or LWS_SERVER_OPTION_... bitfields
1458 * @user: CONTEXT: optional user pointer that can be recovered via the context
1459 * pointer using lws_context_user
1460 * @ka_time: CONTEXT: 0 for no keepalive, otherwise apply this keepalive timeout to
1461 * all libwebsocket sockets, client or server
1462 * @ka_probes: CONTEXT: if ka_time was nonzero, after the timeout expires how many
1463 * times to try to get a response from the peer before giving up
1464 * and killing the connection
1465 * @ka_interval: CONTEXT: if ka_time was nonzero, how long to wait before each ka_probes
1467 * @provided_client_ssl_ctx: CONTEXT: If non-null, swap out libwebsockets ssl
1468 * implementation for the one provided by provided_ssl_ctx.
1469 * Libwebsockets no longer is responsible for freeing the context
1470 * if this option is selected.
1471 * @max_http_header_data: CONTEXT: The max amount of header payload that can be handled
1472 * in an http request (unrecognized header payload is dropped)
1473 * @max_http_header_pool: CONTEXT: The max number of connections with http headers that
1474 * can be processed simultaneously (the corresponding memory is
1475 * allocated for the lifetime of the context). If the pool is
1476 * busy new incoming connections must wait for accept until one
1478 * @count_threads: CONTEXT: how many contexts to create in an array, 0 = 1
1479 * @fd_limit_per_thread: CONTEXT: nonzero means restrict each service thread to this
1480 * many fds, 0 means the default which is divide the process fd
1481 * limit by the number of threads.
1482 * @timeout_secs: VHOST: various processes involving network roundtrips in the
1483 * library are protected from hanging forever by timeouts. If
1484 * nonzero, this member lets you set the timeout used in seconds.
1485 * Otherwise a default timeout is used.
1486 * @ecdh_curve: VHOST: if NULL, defaults to initializing server with "prime256v1"
1487 * @vhost_name: VHOST: name of vhost, must match external DNS name used to
1488 * access the site, like "warmcat.com" as it's used to match
1489 * Host: header and / or SNI name for SSL.
1490 * @plugin_dirs: CONTEXT: NULL, or NULL-terminated array of directories to
1491 * scan for lws protocol plugins at context creation time
1492 * @pvo: VHOST: pointer to optional linked list of per-vhost
1493 * options made accessible to protocols
1494 * @keepalive_timeout: VHOST: (default = 0 = 60s) seconds to allow remote
1495 * client to hold on to an idle HTTP/1.1 connection
1496 * @log_filepath: VHOST: filepath to append logs to... this is opened before
1497 * any dropping of initial privileges
1498 * @mounts: VHOST: optional linked list of mounts for this vhost
1499 * @server_string: CONTEXT: string used in HTTP headers to identify server
1500 * software, if NULL, "libwebsockets".
1501 * @pt_serv_buf_size: CONTEXT: 0 = default of 4096. This buffer is used by
1502 * various service related features including file serving, it
1503 * defines the max chunk of file that can be sent at once.
1504 * At the risk of lws having to buffer failed large sends, it
1505 * can be increased to, eg, 128KiB to improve throughput.
1506 * @max_http_header_data2 CONTEXT: if @max_http_header_data is 0 and this
1507 * is nonzero, this will be used in place of the default. It's
1508 * like this for compatibility with the original short version,
1509 * this is unsigned int length.
1512 struct lws_context_creation_info {
1514 const char *iface; /* VH */
1515 const struct lws_protocols *protocols; /* VH */
1516 const struct lws_extension *extensions; /* VH */
1517 const struct lws_token_limits *token_limits; /* context */
1518 const char *ssl_private_key_password; /* VH */
1519 const char *ssl_cert_filepath; /* VH */
1520 const char *ssl_private_key_filepath; /* VH */
1521 const char *ssl_ca_filepath; /* VH */
1522 const char *ssl_cipher_list; /* VH */
1523 const char *http_proxy_address; /* VH */
1524 unsigned int http_proxy_port; /* VH */
1525 int gid; /* context */
1526 int uid; /* context */
1527 unsigned int options; /* VH + context */
1528 void *user; /* context */
1529 int ka_time; /* context */
1530 int ka_probes; /* context */
1531 int ka_interval; /* context */
1532 #ifdef LWS_OPENSSL_SUPPORT
1533 SSL_CTX *provided_client_ssl_ctx; /* context */
1534 #else /* maintain structure layout either way */
1535 void *provided_client_ssl_ctx;
1538 short max_http_header_data; /* context */
1539 short max_http_header_pool; /* context */
1541 unsigned int count_threads; /* context */
1542 unsigned int fd_limit_per_thread; /* context */
1543 unsigned int timeout_secs; /* VH */
1544 const char *ecdh_curve; /* VH */
1545 const char *vhost_name; /* VH */
1546 const char * const *plugin_dirs; /* context */
1547 const struct lws_protocol_vhost_options *pvo; /* VH */
1548 int keepalive_timeout; /* VH */
1549 const char *log_filepath; /* VH */
1550 const struct lws_http_mount *mounts; /* VH */
1551 const char *server_string; /* context */
1552 unsigned int pt_serv_buf_size; /* context */
1553 unsigned int max_http_header_data2; /* context */
1555 /* Add new things just above here ---^
1556 * This is part of the ABI, don't needlessly break compatibility
1558 * The below is to ensure later library versions with new
1559 * members added above will see 0 (default) even if the app
1560 * was not built against the newer headers.
1567 * struct lws_client_connect_info - parameters to connect with when using
1568 * lws_client_connect_via_info()
1570 * @context: lws context to create connection in
1571 * @address: remote address to connect to
1572 * @port: remote port to connect to
1573 * @ssl_connection: nonzero for ssl
1575 * @host: content of host header
1576 * @origin: content of origin header
1577 * @protocol: list of ws protocols
1578 * @ietf_version_or_minus_one: currently leave at 0 or -1
1579 * @userdata: if non-NULL, use this as wsi user_data instead of malloc it
1580 * @client_exts: array of extensions that may be used on connection
1581 * @method: if non-NULL, do this http method instead of ws[s] upgrade.
1582 * use "GET" to be a simple http client connection
1583 * @parent_wsi: if another wsi is responsible for this connection, give it here.
1584 * this is used to make sure if the parent closes so do any
1585 * child connections first.
1586 * @uri_replace_from: if non-NULL, when this string is found in URIs in
1587 * text/html content-encoding, it's replaced with @uri_replace_to
1588 * @uri_replace_to: see above
1589 * @vhost: vhost to bind to (used to determine related SSL_CTX)
1592 struct lws_client_connect_info {
1593 struct lws_context *context;
1594 const char *address;
1600 const char *protocol;
1601 int ietf_version_or_minus_one;
1603 const struct lws_extension *client_exts;
1605 struct lws *parent_wsi;
1606 const char *uri_replace_from;
1607 const char *uri_replace_to;
1608 struct lws_vhost *vhost;
1610 /* Add new things just above here ---^
1611 * This is part of the ABI, don't needlessly break compatibility
1613 * The below is to ensure later library versions with new
1614 * members added above will see 0 (default) even if the app
1615 * was not built against the newer headers.
1626 LWSMPRO_REDIR_HTTP = 4,
1627 LWSMPRO_REDIR_HTTPS = 5,
1628 LWSMPRO_CALLBACK = 6,
1631 LWS_VISIBLE LWS_EXTERN int
1632 lws_json_dump_vhost(const struct lws_vhost *vh, char *buf, int len);
1634 LWS_VISIBLE LWS_EXTERN int
1635 lws_json_dump_context(const struct lws_context *context, char *buf, int len);
1637 LWS_VISIBLE LWS_EXTERN void
1638 lws_set_log_level(int level,
1639 void (*log_emit_function)(int level, const char *line));
1641 LWS_VISIBLE LWS_EXTERN void
1642 lwsl_emit_syslog(int level, const char *line);
1644 LWS_VISIBLE LWS_EXTERN struct lws_context *
1645 lws_create_context(struct lws_context_creation_info *info);
1649 LWS_EXTERN LWS_VISIBLE struct lws_vhost *
1650 lws_create_vhost(struct lws_context *context,
1651 struct lws_context_creation_info *info);
1653 LWS_VISIBLE LWS_EXTERN int
1654 lws_init_vhost_client_ssl(const struct lws_context_creation_info *info,
1655 struct lws_vhost *vhost);
1657 /* deprecated: use lws_get_vhost() */
1658 LWS_VISIBLE LWS_EXTERN struct lws_vhost *
1659 lws_vhost_get(struct lws *wsi) LWS_WARN_DEPRECATED;
1661 LWS_VISIBLE LWS_EXTERN struct lws_vhost *
1662 lws_get_vhost(struct lws *wsi);
1664 /* deprecated: use lws_get_protocol */
1665 LWS_VISIBLE LWS_EXTERN const struct lws_protocols *
1666 lws_protocol_get(struct lws *wsi) LWS_WARN_DEPRECATED;
1668 LWS_VISIBLE LWS_EXTERN void *
1669 lws_protocol_vh_priv_zalloc(struct lws_vhost *vhost, const struct lws_protocols *prot,
1671 LWS_VISIBLE LWS_EXTERN void *
1672 lws_protocol_vh_priv_get(struct lws_vhost *vhost, const struct lws_protocols *prot);
1674 LWS_VISIBLE LWS_EXTERN int
1675 lws_finalize_startup(struct lws_context *context);
1677 LWS_VISIBLE LWS_EXTERN int
1678 lws_set_proxy(struct lws_vhost *vhost, const char *proxy);
1680 LWS_VISIBLE LWS_EXTERN void
1681 lws_context_destroy(struct lws_context *context);
1683 LWS_VISIBLE LWS_EXTERN int
1684 lws_service(struct lws_context *context, int timeout_ms);
1686 LWS_VISIBLE LWS_EXTERN int
1687 lws_service_tsi(struct lws_context *context, int timeout_ms, int tsi);
1689 LWS_VISIBLE LWS_EXTERN void
1690 lws_cancel_service_pt(struct lws *wsi);
1692 LWS_VISIBLE LWS_EXTERN void
1693 lws_cancel_service(struct lws_context *context);
1695 LWS_VISIBLE LWS_EXTERN int
1696 lws_interface_to_sa(int ipv6, const char *ifname, struct sockaddr_in *addr,
1699 LWS_VISIBLE LWS_EXTERN const unsigned char *
1700 lws_token_to_string(enum lws_token_indexes token);
1702 /* all the below must be LWS_WARN_UNUSED_RESULT as they can run short */
1704 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1705 lws_add_http_header_by_name(struct lws *wsi, const unsigned char *name,
1706 const unsigned char *value, int length,
1707 unsigned char **p, unsigned char *end);
1708 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1709 lws_finalize_http_header(struct lws *wsi, unsigned char **p,
1710 unsigned char *end);
1711 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1712 lws_add_http_header_by_token(struct lws *wsi, enum lws_token_indexes token,
1713 const unsigned char *value, int length,
1714 unsigned char **p, unsigned char *end);
1715 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1716 lws_add_http_header_content_length(struct lws *wsi,
1717 unsigned long content_length,
1718 unsigned char **p, unsigned char *end);
1719 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1720 lws_add_http_header_status(struct lws *wsi,
1721 unsigned int code, unsigned char **p,
1722 unsigned char *end);
1724 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1725 lws_http_redirect(struct lws *wsi, int code, const unsigned char *loc, int len,
1726 unsigned char **p, unsigned char *end);
1728 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1729 lws_http_transaction_completed(struct lws *wsi);
1731 #ifdef LWS_USE_LIBEV
1732 typedef void (lws_ev_signal_cb_t)(EV_P_ struct ev_signal *w, int revents);
1734 LWS_VISIBLE LWS_EXTERN int
1735 lws_ev_sigint_cfg(struct lws_context *context, int use_ev_sigint,
1736 lws_ev_signal_cb_t *cb);
1738 LWS_VISIBLE LWS_EXTERN int
1739 lws_ev_initloop(struct lws_context *context, struct ev_loop *loop, int tsi);
1741 LWS_VISIBLE LWS_EXTERN void
1742 lws_ev_sigint_cb(struct ev_loop *loop, struct ev_signal *watcher, int revents);
1743 #endif /* LWS_USE_LIBEV */
1745 #ifdef LWS_USE_LIBUV
1746 LWS_VISIBLE LWS_EXTERN int
1747 lws_uv_sigint_cfg(struct lws_context *context, int use_uv_sigint,
1750 LWS_VISIBLE LWS_EXTERN void
1751 lws_libuv_run(const struct lws_context *context, int tsi);
1753 LWS_VISIBLE LWS_EXTERN void
1754 lws_libuv_stop(struct lws_context *context);
1756 LWS_VISIBLE LWS_EXTERN int
1757 lws_uv_initloop(struct lws_context *context, uv_loop_t *loop, int tsi);
1759 LWS_VISIBLE LWS_EXTERN uv_loop_t *
1760 lws_uv_getloop(struct lws_context *context, int tsi);
1762 LWS_VISIBLE LWS_EXTERN void
1763 lws_uv_sigint_cb(uv_signal_t *watcher, int signum);
1764 #endif /* LWS_USE_LIBUV */
1766 LWS_VISIBLE LWS_EXTERN int
1767 lws_service_fd(struct lws_context *context, struct lws_pollfd *pollfd);
1769 LWS_VISIBLE LWS_EXTERN int
1770 lws_service_fd_tsi(struct lws_context *context, struct lws_pollfd *pollfd,
1773 LWS_VISIBLE LWS_EXTERN void *
1774 lws_context_user(struct lws_context *context);
1776 LWS_VISIBLE LWS_EXTERN void *
1777 lws_wsi_user(struct lws *wsi);
1780 * NOTE: These public enums are part of the abi. If you want to add one,
1781 * add it at where specified so existing users are unaffected.
1783 enum pending_timeout {
1784 NO_PENDING_TIMEOUT = 0,
1785 PENDING_TIMEOUT_AWAITING_PROXY_RESPONSE = 1,
1786 PENDING_TIMEOUT_AWAITING_CONNECT_RESPONSE = 2,
1787 PENDING_TIMEOUT_ESTABLISH_WITH_SERVER = 3,
1788 PENDING_TIMEOUT_AWAITING_SERVER_RESPONSE = 4,
1789 PENDING_TIMEOUT_AWAITING_PING = 5,
1790 PENDING_TIMEOUT_CLOSE_ACK = 6,
1791 PENDING_TIMEOUT_AWAITING_EXTENSION_CONNECT_RESPONSE = 7,
1792 PENDING_TIMEOUT_SENT_CLIENT_HANDSHAKE = 8,
1793 PENDING_TIMEOUT_SSL_ACCEPT = 9,
1794 PENDING_TIMEOUT_HTTP_CONTENT = 10,
1795 PENDING_TIMEOUT_AWAITING_CLIENT_HS_SEND = 11,
1796 PENDING_FLUSH_STORED_SEND_BEFORE_CLOSE = 12,
1797 PENDING_TIMEOUT_SHUTDOWN_FLUSH = 13,
1798 PENDING_TIMEOUT_CGI = 14,
1799 PENDING_TIMEOUT_HTTP_KEEPALIVE_IDLE = 15,
1801 /****** add new things just above ---^ ******/
1804 LWS_VISIBLE LWS_EXTERN void
1805 lws_set_timeout(struct lws *wsi, enum pending_timeout reason, int secs);
1810 * When sending with websocket protocol
1814 * LWS_WRITE_CONTINUATION,
1818 * the send buffer has to have LWS_PRE bytes valid BEFORE
1819 * the buffer pointer you pass to lws_write().
1821 * This allows us to add protocol info before and after the data, and send as
1822 * one packet on the network without payload copying, for maximum efficiency.
1824 * So for example you need this kind of code to use lws_write with a
1827 * char buf[LWS_PRE + 128];
1829 * // fill your part of the buffer... for example here it's all zeros
1830 * memset(&buf[LWS_PRE], 0, 128);
1832 * lws_write(wsi, &buf[LWS_PRE], 128, LWS_WRITE_TEXT);
1834 * When sending HTTP, with
1837 * LWS_WRITE_HTTP_HEADERS
1838 * LWS_WRITE_HTTP_FINAL
1840 * there is no protocol data prepended, and don't need to take care about the
1841 * LWS_PRE bytes valid before the buffer pointer.
1843 * LWS_PRE is at least the frame nonce + 2 header + 8 length
1844 * LWS_SEND_BUFFER_POST_PADDING is deprecated, it's now 0 and can be left off.
1845 * The example apps no longer use it.
1847 * Pad LWS_PRE to the CPU word size, so that word references
1848 * to the address immediately after the padding won't cause an unaligned access
1849 * error. Sometimes for performance reasons the recommended padding is even
1850 * larger than sizeof(void *).
1853 #if !defined(LWS_SIZEOFPTR)
1854 #define LWS_SIZEOFPTR (sizeof (void *))
1856 #if !defined(u_int64_t)
1857 #define u_int64_t unsigned long long
1861 #define _LWS_PAD_SIZE 16 /* Intel recommended for best performance */
1863 #define _LWS_PAD_SIZE LWS_SIZEOFPTR /* Size of a pointer on the target arch */
1865 #define _LWS_PAD(n) (((n) % _LWS_PAD_SIZE) ? \
1866 ((n) + (_LWS_PAD_SIZE - ((n) % _LWS_PAD_SIZE))) : (n))
1867 #define LWS_PRE _LWS_PAD(4 + 10)
1868 /* used prior to 1.7 and retained for backward compatibility */
1869 #define LWS_SEND_BUFFER_PRE_PADDING LWS_PRE
1870 #define LWS_SEND_BUFFER_POST_PADDING 0
1872 LWS_VISIBLE LWS_EXTERN int
1873 lws_write(struct lws *wsi, unsigned char *buf, size_t len,
1874 enum lws_write_protocol protocol);
1877 * lws_close_reason - Set reason and aux data to send with Close packet
1878 * If you are going to return nonzero from the callback
1879 * requesting the connection to close, you can optionally
1880 * call this to set the reason the peer will be told if
1883 * @wsi: The websocket connection to set the close reason on
1884 * @status: A valid close status from websocket standard
1885 * @buf: NULL or buffer containing up to 124 bytes of auxiliary data
1886 * @len: Length of data in @buf to send
1888 LWS_VISIBLE LWS_EXTERN void
1889 lws_close_reason(struct lws *wsi, enum lws_close_status status,
1890 unsigned char *buf, size_t len);
1892 /* helper for case where buffer may be const */
1893 #define lws_write_http(wsi, buf, len) \
1894 lws_write(wsi, (unsigned char *)(buf), len, LWS_WRITE_HTTP)
1896 LWS_VISIBLE LWS_EXTERN int
1897 lws_serve_http_file(struct lws *wsi, const char *file, const char *content_type,
1898 const char *other_headers, int other_headers_len);
1899 LWS_VISIBLE LWS_EXTERN int
1900 lws_serve_http_file_fragment(struct lws *wsi);
1902 LWS_VISIBLE LWS_EXTERN int
1903 lws_return_http_status(struct lws *wsi, unsigned int code,
1904 const char *html_body);
1906 LWS_VISIBLE LWS_EXTERN const struct lws_protocols *
1907 lws_get_protocol(struct lws *wsi);
1909 LWS_VISIBLE LWS_EXTERN int
1910 lws_callback_on_writable(struct lws *wsi);
1912 LWS_VISIBLE LWS_EXTERN int
1913 lws_callback_on_writable_all_protocol(const struct lws_context *context,
1914 const struct lws_protocols *protocol);
1916 LWS_VISIBLE LWS_EXTERN int
1917 lws_callback_on_writable_all_protocol_vhost(const struct lws_vhost *vhost,
1918 const struct lws_protocols *protocol);
1920 LWS_VISIBLE LWS_EXTERN int
1921 lws_callback_all_protocol(struct lws_context *context,
1922 const struct lws_protocols *protocol, int reason);
1924 LWS_VISIBLE LWS_EXTERN int
1925 lws_callback_all_protocol_vhost(struct lws_vhost *vh,
1926 const struct lws_protocols *protocol, int reason);
1928 LWS_VISIBLE LWS_EXTERN int
1929 lws_get_socket_fd(struct lws *wsi);
1931 LWS_VISIBLE LWS_EXTERN int
1932 lws_is_final_fragment(struct lws *wsi);
1934 LWS_VISIBLE LWS_EXTERN unsigned char
1935 lws_get_reserved_bits(struct lws *wsi);
1937 LWS_VISIBLE LWS_EXTERN int
1938 lws_rx_flow_control(struct lws *wsi, int enable);
1940 LWS_VISIBLE LWS_EXTERN void
1941 lws_rx_flow_allow_all_protocol(const struct lws_context *context,
1942 const struct lws_protocols *protocol);
1944 LWS_VISIBLE LWS_EXTERN size_t
1945 lws_remaining_packet_payload(struct lws *wsi);
1948 * if the protocol does not have any guidance, returns -1. Currently only
1949 * http2 connections get send window information from this API. But your code
1950 * should use it so it can work properly with any protocol.
1952 * If nonzero return is the amount of payload data the peer or intermediary has
1953 * reported it has buffer space for. That has NO relationship with the amount
1954 * of buffer space your OS can accept on this connection for a write action.
1956 * This number represents the maximum you could send to the peer or intermediary
1957 * on this connection right now without it complaining.
1959 * lws manages accounting for send window updates and payload writes
1960 * automatically, so this number reflects the situation at the peer or
1961 * intermediary dynamically.
1963 LWS_VISIBLE LWS_EXTERN size_t
1964 lws_get_peer_write_allowance(struct lws *wsi);
1966 /* deprecated, use lws_client_connect_via_info() */
1967 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
1968 lws_client_connect(struct lws_context *clients, const char *address,
1969 int port, int ssl_connection, const char *path,
1970 const char *host, const char *origin, const char *protocol,
1971 int ietf_version_or_minus_one) LWS_WARN_DEPRECATED;
1972 /* deprecated, use lws_client_connect_via_info() */
1973 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
1974 lws_client_connect_extended(struct lws_context *clients, const char *address,
1975 int port, int ssl_connection, const char *path,
1976 const char *host, const char *origin,
1977 const char *protocol, int ietf_version_or_minus_one,
1978 void *userdata) LWS_WARN_DEPRECATED;
1980 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
1981 lws_client_connect_via_info(struct lws_client_connect_info * ccinfo);
1983 LWS_VISIBLE LWS_EXTERN struct lws *
1984 lws_adopt_socket(struct lws_context *context, lws_sockfd_type accept_fd);
1985 LWS_VISIBLE LWS_EXTERN struct lws *
1986 lws_adopt_socket_readbuf(struct lws_context *context, lws_sockfd_type accept_fd,
1987 const char *readbuf, size_t len);
1989 LWS_VISIBLE LWS_EXTERN const char * LWS_WARN_UNUSED_RESULT
1990 lws_canonical_hostname(struct lws_context *context);
1993 LWS_VISIBLE LWS_EXTERN void
1994 lws_get_peer_addresses(struct lws *wsi, lws_sockfd_type fd, char *name,
1995 int name_len, char *rip, int rip_len);
1997 LWS_VISIBLE LWS_EXTERN const char *
1998 lws_get_peer_simple(struct lws *wsi, char *name, int namelen);
2000 LWS_VISIBLE LWS_EXTERN int
2001 lws_get_random(struct lws_context *context, void *buf, int len);
2003 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2004 lws_daemonize(const char *_lock_path);
2006 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2007 lws_send_pipe_choked(struct lws *wsi);
2009 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2010 lws_partial_buffered(struct lws *wsi);
2012 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2013 lws_frame_is_binary(struct lws *wsi);
2015 LWS_VISIBLE LWS_EXTERN int
2016 lws_is_ssl(struct lws *wsi);
2018 LWS_VISIBLE LWS_EXTERN int
2019 lws_is_cgi(struct lws *wsi);
2021 #ifdef LWS_SHA1_USE_OPENSSL_NAME
2022 #define lws_SHA1 SHA1
2024 LWS_VISIBLE LWS_EXTERN unsigned char *
2025 lws_SHA1(const unsigned char *d, size_t n, unsigned char *md);
2028 LWS_VISIBLE LWS_EXTERN int
2029 lws_b64_encode_string(const char *in, int in_len, char *out, int out_size);
2031 LWS_VISIBLE LWS_EXTERN int
2032 lws_b64_decode_string(const char *in, char *out, int out_size);
2034 LWS_VISIBLE LWS_EXTERN const char * LWS_WARN_UNUSED_RESULT
2035 lws_get_library_version(void);
2037 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2038 lws_parse_uri(char *p, const char **prot, const char **ads, int *port,
2042 * Access to http headers
2044 * In lws the client http headers are temporarily malloc'd only for the
2045 * duration of the http part of the handshake. It's because in most cases,
2046 * the header content is ignored for the whole rest of the connection lifetime
2047 * and would then just be taking up space needlessly.
2049 * During LWS_CALLBACK_HTTP when the URI path is delivered is the last time
2050 * the http headers are still allocated, you can use these apis then to
2051 * look at and copy out interesting header content (cookies, etc)
2053 * Notice that the header total length reported does not include a terminating
2054 * '\0', however you must allocate for it when using the _copy apis. So the
2055 * length reported for a header containing "123" is 3, but you must provide
2056 * a buffer of length 4 so that "123\0" may be copied into it, or the copy
2057 * will fail with a nonzero return code.
2060 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2061 lws_hdr_total_length(struct lws *wsi, enum lws_token_indexes h);
2063 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2064 lws_hdr_fragment_length(struct lws *wsi, enum lws_token_indexes h, int frag_idx);
2067 * copies the whole, aggregated header, even if it was delivered in
2068 * several actual headers piece by piece
2070 LWS_VISIBLE LWS_EXTERN int
2071 lws_hdr_copy(struct lws *wsi, char *dest, int len, enum lws_token_indexes h);
2074 * copies only fragment frag_idx of a header. Normally this is only useful
2075 * to parse URI arguments like ?x=1&y=2, token index WSI_TOKEN_HTTP_URI_ARGS
2076 * fragment 0 will contain "x=1" and fragment 1 "y=2"
2078 LWS_VISIBLE LWS_EXTERN int
2079 lws_hdr_copy_fragment(struct lws *wsi, char *dest, int len,
2080 enum lws_token_indexes h, int frag_idx);
2082 LWS_VISIBLE LWS_EXTERN const char *
2083 lws_get_urlarg_by_name(struct lws *wsi, const char *name, char *buf, int len);
2086 /* get the active file operations struct */
2087 LWS_VISIBLE LWS_EXTERN struct lws_plat_file_ops * LWS_WARN_UNUSED_RESULT
2088 lws_get_fops(struct lws_context *context);
2090 LWS_VISIBLE LWS_EXTERN struct lws_context * LWS_WARN_UNUSED_RESULT
2091 lws_get_context(const struct lws *wsi);
2093 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2094 lws_get_count_threads(struct lws_context *context);
2096 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
2097 lws_get_parent(const struct lws *wsi);
2099 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
2100 lws_get_child(const struct lws *wsi);
2103 enum lws_enum_stdinouterr {
2109 enum lws_cgi_hdr_state {
2119 struct lws_cgi_args {
2120 struct lws **stdwsi; /* get fd with lws_get_socket_fd() */
2121 enum lws_enum_stdinouterr ch;
2122 unsigned char *data; /* for messages with payload */
2123 enum lws_cgi_hdr_state hdr_state;
2127 LWS_VISIBLE LWS_EXTERN int
2128 lws_cgi(struct lws *wsi, const char * const *exec_array,
2129 int script_uri_path_len, int timeout_secs,
2130 const struct lws_protocol_vhost_options *mp_cgienv);
2132 LWS_VISIBLE LWS_EXTERN int
2133 lws_cgi_write_split_stdout_headers(struct lws *wsi);
2135 LWS_VISIBLE LWS_EXTERN int
2136 lws_cgi_kill(struct lws *wsi);
2139 LWS_VISIBLE LWS_EXTERN int
2140 lws_http_client_read(struct lws *wsi, char **buf, int *len);
2145 LWS_VISIBLE LWS_EXTERN int
2146 lwsws_get_config_globals(struct lws_context_creation_info *info, const char *d,
2147 char **config_strings, int *len);
2149 LWS_VISIBLE LWS_EXTERN int
2150 lwsws_get_config_vhosts(struct lws_context *context,
2151 struct lws_context_creation_info *info, const char *d,
2152 char **config_strings, int *len);
2155 * Wsi-associated File Operations access helpers
2157 * Use these helper functions if you want to access a file from the perspective
2158 * of a specific wsi, which is usually the case. If you just want contextless
2159 * file access, use the fops callbacks directly with NULL wsi instead of these
2162 * If so, then it calls the platform handler or user overrides where present
2163 * (as defined in info->fops)
2165 * The advantage from all this is user code can be portable for file operations
2166 * without having to deal with differences between platforms.
2169 static LWS_INLINE lws_filefd_type LWS_WARN_UNUSED_RESULT
2170 lws_plat_file_open(struct lws *wsi, const char *filename,
2171 unsigned long *filelen, int flags)
2173 return lws_get_fops(lws_get_context(wsi))->open(wsi, filename,
2177 static LWS_INLINE int
2178 lws_plat_file_close(struct lws *wsi, lws_filefd_type fd)
2180 return lws_get_fops(lws_get_context(wsi))->close(wsi, fd);
2183 static LWS_INLINE unsigned long
2184 lws_plat_file_seek_cur(struct lws *wsi, lws_filefd_type fd, long offset)
2186 return lws_get_fops(lws_get_context(wsi))->seek_cur(wsi, fd, offset);
2189 static LWS_INLINE int LWS_WARN_UNUSED_RESULT
2190 lws_plat_file_read(struct lws *wsi, lws_filefd_type fd, unsigned long *amount,
2191 unsigned char *buf, unsigned long len)
2193 return lws_get_fops(lws_get_context(wsi))->read(wsi, fd, amount, buf,
2197 static LWS_INLINE int LWS_WARN_UNUSED_RESULT
2198 lws_plat_file_write(struct lws *wsi, lws_filefd_type fd, unsigned long *amount,
2199 unsigned char *buf, unsigned long len)
2201 return lws_get_fops(lws_get_context(wsi))->write(wsi, fd, amount, buf,
2206 * Note: this is not normally needed as a user api. It's provided in case it is
2207 * useful when integrating with other app poll loop service code.
2209 LWS_VISIBLE LWS_EXTERN int
2210 lws_read(struct lws *wsi, unsigned char *buf, size_t len);
2212 #ifndef LWS_NO_EXTENSIONS
2215 * There is no longer a set internal extensions table. The table is provided
2216 * by user code along with application-specific settings. See the test
2217 * client and server for how to do.
2219 static LWS_INLINE LWS_WARN_DEPRECATED const struct lws_extension *
2220 lws_get_internal_extensions() { return NULL; }
2221 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2222 lws_ext_parse_options(const struct lws_extension *ext, struct lws *wsi,
2223 void *ext_user, const struct lws_ext_options *opts,
2224 const char *o, int len);
2228 * custom allocator support
2230 LWS_VISIBLE LWS_EXTERN void
2231 lws_set_allocator(void *(*realloc)(void *ptr, size_t size));