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,
24 #ifndef LIBWEBSOCKET_H_3060898B846849FF9F88F5DB59B5950C
25 #define LIBWEBSOCKET_H_3060898B846849FF9F88F5DB59B5950C
36 static inline int lws_is_be(void) {
37 const int probe = ~0xff;
39 return *(const char *)&probe;
42 #if defined(LWS_WITH_ESP8266)
49 #include "lws_config.h"
51 #if defined(WIN32) || defined(_WIN32)
52 #ifndef WIN32_LEAN_AND_MEAN
53 #define WIN32_LEAN_AND_MEAN
63 #define _O_RDONLY 0x0000
64 #define O_RDONLY _O_RDONLY
67 // Visual studio older than 2015 and WIN_CE has only _stricmp
68 #if (defined(_MSC_VER) && _MSC_VER < 1900) || defined(_WIN32_WCE)
69 #define strcasecmp _stricmp
70 #elif !defined(__MINGW32__)
71 #define strcasecmp stricmp
73 #define getdtablesize() 30000
75 #define LWS_INLINE __inline
77 #define LWS_WARN_UNUSED_RESULT
78 #define LWS_WARN_DEPRECATED
79 #define LWS_FORMAT(string_index)
83 #define LWS_EXTERN extern __declspec(dllexport)
85 #define LWS_EXTERN extern __declspec(dllimport)
91 #define LWS_INVALID_FILE INVALID_HANDLE_VALUE
92 #define LWS_O_RDONLY _O_RDONLY
94 #if !defined(__MINGW32__) && (!defined(_MSC_VER) || _MSC_VER < 1900) /* Visual Studio 2015 already defines this in <stdio.h> */
95 #define lws_snprintf _snprintf
99 #define __func__ __FUNCTION__
102 #else /* NOT WIN32 */
105 #if defined(__NetBSD__) || defined(__FreeBSD__)
106 #include <netinet/in.h>
109 #define LWS_INLINE inline
110 #define LWS_O_RDONLY O_RDONLY
112 #if !defined(LWS_WITH_ESP8266) && !defined(OPTEE_TA) && !defined(LWS_WITH_ESP32)
115 #define LWS_INVALID_FILE -1
117 #define getdtablesize() (30)
118 #if defined(LWS_WITH_ESP32)
119 #define LWS_INVALID_FILE NULL
121 #define LWS_INVALID_FILE NULL
125 #if defined(__GNUC__)
127 /* warn_unused_result attribute only supported by GCC 3.4 or later */
128 #if __GNUC__ >= 4 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
129 #define LWS_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
131 #define LWS_WARN_UNUSED_RESULT
134 #define LWS_VISIBLE __attribute__((visibility("default")))
135 #define LWS_WARN_DEPRECATED __attribute__ ((deprecated))
136 #define LWS_FORMAT(string_index) __attribute__ ((format(printf, string_index, string_index+1)))
139 #define LWS_WARN_UNUSED_RESULT
140 #define LWS_WARN_DEPRECATED
141 #define LWS_FORMAT(string_index)
144 #if defined(__ANDROID__)
146 #define getdtablesize() sysconf(_SC_OPEN_MAX)
153 #endif /* LWS_USE_LIBEV */
156 #ifdef LWS_HAVE_UV_VERSION_H
157 #include <uv-version.h>
159 #endif /* LWS_USE_LIBUV */
160 #ifdef LWS_USE_LIBEVENT
161 #include <event2/event.h>
162 #endif /* LWS_USE_LIBEVENT */
165 #define LWS_EXTERN extern
171 #if !defined(OPTEE_TA)
172 #include <sys/time.h>
177 #ifdef LWS_OPENSSL_SUPPORT
180 #ifdef USE_OLD_CYASSL
181 #include <cyassl/openssl/ssl.h>
182 #include <cyassl/error-ssl.h>
184 #include <wolfssl/openssl/ssl.h>
185 #include <wolfssl/error-ssl.h>
186 #endif /* not USE_OLD_CYASSL */
188 #include <openssl/ssl.h>
189 #if !defined(LWS_WITH_ESP32)
190 #include <openssl/err.h>
192 #endif /* not USE_WOLFSSL */
196 #define CONTEXT_PORT_NO_LISTEN -1
197 #define CONTEXT_PORT_NO_LISTEN_SERVER -2
199 /** \defgroup log Logging
203 * Lws provides flexible and filterable logging facilities, which can be
204 * used inside lws and in user code.
206 * Log categories may be individually filtered bitwise, and directed to built-in
207 * sinks for syslog-compatible logging, or a user-defined function.
211 enum lws_log_levels {
221 LLL_LATENCY = 1 << 9,
224 LLL_COUNT = 11 /* set to count of valid flags */
227 LWS_VISIBLE LWS_EXTERN void _lws_log(int filter, const char *format, ...) LWS_FORMAT(2);
228 LWS_VISIBLE LWS_EXTERN void _lws_logv(int filter, const char *format, va_list vl);
230 * lwsl_timestamp: generate logging timestamp string
232 * \param level: logging level
233 * \param p: char * buffer to take timestamp
234 * \param len: length of p
236 * returns length written in p
238 LWS_VISIBLE LWS_EXTERN int
239 lwsl_timestamp(int level, char *p, int len);
241 /* these guys are unconditionally included */
243 #define lwsl_err(...) _lws_log(LLL_ERR, __VA_ARGS__)
244 #define lwsl_user(...) _lws_log(LLL_USER, __VA_ARGS__)
246 #if !defined(LWS_WITH_NO_LOGS)
247 /* notice and warn are usually included by being compiled in */
248 #define lwsl_warn(...) _lws_log(LLL_WARN, __VA_ARGS__)
249 #define lwsl_notice(...) _lws_log(LLL_NOTICE, __VA_ARGS__)
252 * weaker logging can be deselected by telling CMake to build in RELEASE mode
253 * that gets rid of the overhead of checking while keeping _warn and _err
257 #if defined(LWS_WITH_ESP8266)
262 #if defined(LWS_WITH_NO_LOGS)
263 /* notice, warn and log are always compiled in */
264 #define lwsl_warn(...) _lws_log(LLL_WARN, __VA_ARGS__)
265 #define lwsl_notice(...) _lws_log(LLL_NOTICE, __VA_ARGS__)
267 #define lwsl_info(...) _lws_log(LLL_INFO, __VA_ARGS__)
268 #define lwsl_debug(...) _lws_log(LLL_DEBUG, __VA_ARGS__)
269 #define lwsl_parser(...) _lws_log(LLL_PARSER, __VA_ARGS__)
270 #define lwsl_header(...) _lws_log(LLL_HEADER, __VA_ARGS__)
271 #define lwsl_ext(...) _lws_log(LLL_EXT, __VA_ARGS__)
272 #define lwsl_client(...) _lws_log(LLL_CLIENT, __VA_ARGS__)
273 #define lwsl_latency(...) _lws_log(LLL_LATENCY, __VA_ARGS__)
275 * lwsl_hexdump() - helper to hexdump a buffer (DEBUG builds only)
277 * \param buf: buffer start to dump
278 * \param len: length of buffer to dump
280 LWS_VISIBLE LWS_EXTERN void lwsl_hexdump(void *buf, size_t len);
283 #if defined(LWS_WITH_NO_LOGS)
284 #define lwsl_warn(...) do {} while(0)
285 #define lwsl_notice(...) do {} while(0)
287 #define lwsl_info(...) do {} while(0)
288 #define lwsl_debug(...) do {} while(0)
289 #define lwsl_parser(...) do {} while(0)
290 #define lwsl_header(...) do {} while(0)
291 #define lwsl_ext(...) do {} while(0)
292 #define lwsl_client(...) do {} while(0)
293 #define lwsl_latency(...) do {} while(0)
294 #define lwsl_hexdump(a, b)
299 * lws_set_log_level() - Set the logging bitfield
300 * \param level: OR together the LLL_ debug contexts you want output from
301 * \param log_emit_function: NULL to leave it as it is, or a user-supplied
302 * function to perform log string emission instead of
303 * the default stderr one.
305 * log level defaults to "err", "warn" and "notice" contexts enabled and
306 * emission on stderr.
308 LWS_VISIBLE LWS_EXTERN void
309 lws_set_log_level(int level,
310 void (*log_emit_function)(int level, const char *line));
313 * lwsl_emit_syslog() - helper log emit function writes to system log
315 * \param level: one of LLL_ log level indexes
316 * \param line: log string
318 * You use this by passing the function pointer to lws_set_log_level(), to set
319 * it as the log emit function, it is not called directly.
321 LWS_VISIBLE LWS_EXTERN void
322 lwsl_emit_syslog(int level, const char *line);
325 * lwsl_visible() - returns true if the log level should be printed
327 * \param level: one of LLL_ log level indexes
329 * This is useful if you have to do work to generate the log content, you
330 * can skip the work if the log level used to print it is not actually
331 * enabled at runtime.
333 LWS_VISIBLE LWS_EXTERN int
334 lwsl_visible(int level);
341 #ifndef lws_container_of
342 #define lws_container_of(P,T,M) ((T *)((char *)(P) - offsetof(T, M)))
348 #define ARRAY_SIZE(x) (sizeof(x) / sizeof(x[0]))
351 /* api change list for user code to test against */
353 #define LWS_FEATURE_SERVE_HTTP_FILE_HAS_OTHER_HEADERS_ARG
355 /* the struct lws_protocols has the id field present */
356 #define LWS_FEATURE_PROTOCOLS_HAS_ID_FIELD
358 /* you can call lws_get_peer_write_allowance */
359 #define LWS_FEATURE_PROTOCOLS_HAS_PEER_WRITE_ALLOWANCE
361 /* extra parameter introduced in 917f43ab821 */
362 #define LWS_FEATURE_SERVE_HTTP_FILE_HAS_OTHER_HEADERS_LEN
364 /* File operations stuff exists */
365 #define LWS_FEATURE_FOPS
369 typedef SOCKET lws_sockfd_type;
370 typedef HANDLE lws_filefd_type;
371 #define lws_sockfd_valid(sfd) (!!sfd)
373 lws_sockfd_type fd; /**< file descriptor */
374 SHORT events; /**< which events to respond to */
375 SHORT revents; /**< which events happened */
377 #define LWS_POLLHUP (FD_CLOSE)
378 #define LWS_POLLIN (FD_READ | FD_ACCEPT)
379 #define LWS_POLLOUT (FD_WRITE)
383 #if defined(LWS_WITH_ESP8266)
385 #include <user_interface.h>
388 typedef struct espconn * lws_sockfd_type;
389 typedef void * lws_filefd_type;
390 #define lws_sockfd_valid(sfd) (!!sfd)
392 lws_sockfd_type fd; /**< fd related to */
393 short events; /**< which POLL... events to respond to */
394 short revents; /**< which POLL... events occurred */
396 #define POLLIN 0x0001
397 #define POLLPRI 0x0002
398 #define POLLOUT 0x0004
399 #define POLLERR 0x0008
400 #define POLLHUP 0x0010
401 #define POLLNVAL 0x0020
405 lws_sockfd_type esp8266_create_tcp_listen_socket(struct lws_vhost *vh);
406 void esp8266_tcp_stream_accept(lws_sockfd_type fd, struct lws *wsi);
412 int ets_snprintf(char *str, size_t size, const char *format, ...) LWS_FORMAT(3);
413 #define snprintf ets_snprintf
415 typedef os_timer_t uv_timer_t;
416 typedef void uv_cb_t(uv_timer_t *);
418 void os_timer_disarm(void *);
419 void os_timer_setfn(os_timer_t *, os_timer_func_t *, void *);
421 void ets_timer_arm_new(os_timer_t *, int, int, int);
423 //void os_timer_arm(os_timer_t *, int, int);
425 #define UV_VERSION_MAJOR 1
427 #define lws_uv_getloop(a, b) (NULL)
429 static inline void uv_timer_init(void *l, uv_timer_t *t)
432 memset(t, 0, sizeof(*t));
436 static inline void uv_timer_start(uv_timer_t *t, uv_cb_t *cb, int first, int rep)
438 os_timer_setfn(t, (os_timer_func_t *)cb, t);
440 os_timer_arm(t, first, !!rep);
443 static inline void uv_timer_stop(uv_timer_t *t)
449 #if defined(LWS_WITH_ESP32)
451 typedef int lws_sockfd_type;
452 typedef int lws_filefd_type;
453 #define lws_sockfd_valid(sfd) (sfd >= 0)
455 lws_sockfd_type fd; /**< fd related to */
456 short events; /**< which POLL... events to respond to */
457 short revents; /**< which POLL... events occurred */
459 #define POLLIN 0x0001
460 #define POLLPRI 0x0002
461 #define POLLOUT 0x0004
462 #define POLLERR 0x0008
463 #define POLLHUP 0x0010
464 #define POLLNVAL 0x0020
466 #include <freertos/FreeRTOS.h>
467 #include <freertos/event_groups.h>
469 #include "esp_wifi.h"
470 #include "esp_system.h"
471 #include "esp_event.h"
472 #include "esp_event_loop.h"
474 #include "driver/gpio.h"
475 #include "esp_spi_flash.h"
476 #include "freertos/timers.h"
478 #if !defined(CONFIG_FREERTOS_HZ)
479 #define CONFIG_FREERTOS_HZ 100
482 typedef TimerHandle_t uv_timer_t;
483 typedef void uv_cb_t(uv_timer_t *);
484 typedef void * uv_handle_t;
486 struct timer_mapping {
491 #define UV_VERSION_MAJOR 1
493 #define lws_uv_getloop(a, b) (NULL)
495 static inline void uv_timer_init(void *l, uv_timer_t *t)
501 extern void esp32_uvtimer_cb(TimerHandle_t t);
503 static inline void uv_timer_start(uv_timer_t *t, uv_cb_t *cb, int first, int rep)
505 struct timer_mapping *tm = malloc(sizeof(*tm));
513 *t = xTimerCreate("x", pdMS_TO_TICKS(first), !!rep, tm,
514 (TimerCallbackFunction_t)esp32_uvtimer_cb);
518 static inline void uv_timer_stop(uv_timer_t *t)
523 static inline void uv_close(uv_handle_t *h, void *v)
525 free(pvTimerGetTimerID((uv_timer_t)h));
526 xTimerDelete(*(uv_timer_t *)h, 0);
529 /* ESP32 helper declarations */
531 #define LWS_PLUGIN_STATIC
533 /* user code provides these */
535 extern char lws_esp32_model[16];
538 lws_esp32_is_booting_in_ap_mode(void);
540 lws_esp32_identify_physical_device(void);
542 /* lws-plat-esp32 provides these */
544 extern void (*lws_cb_scan_done)(void *);
545 extern void *lws_cb_scan_done_arg;
547 extern char lws_esp32_serial[], lws_esp32_force_ap, lws_esp32_region;
550 lws_esp32_event_passthru(void *ctx, system_event_t *event);
552 lws_esp32_wlan_config(void);
554 lws_esp32_wlan_start(void);
555 struct lws_context_creation_info;
556 extern struct lws_context *
557 lws_esp32_init(struct lws_context_creation_info *, unsigned int _romfs);
560 typedef int lws_sockfd_type;
561 typedef int lws_filefd_type;
562 #define lws_sockfd_valid(sfd) (sfd >= 0)
566 #define lws_pollfd pollfd
567 #define LWS_POLLHUP (POLLHUP|POLLERR)
568 #define LWS_POLLIN (POLLIN)
569 #define LWS_POLLOUT (POLLOUT)
572 /** struct lws_pollargs - argument structure for all external poll related calls
573 * passed in via 'in' */
574 struct lws_pollargs {
575 lws_sockfd_type fd; /**< applicable socket descriptor */
576 int events; /**< the new event mask */
577 int prev_events; /**< the previous event mask */
581 struct lws_token_limits;
583 /*! \defgroup wsclose Websocket Close
585 * ##Websocket close frame control
587 * When we close a ws connection, we can send a reason code and a short
588 * UTF-8 description back with the close packet.
593 * NOTE: These public enums are part of the abi. If you want to add one,
594 * add it at where specified so existing users are unaffected.
596 /** enum lws_close_status - RFC6455 close status codes */
597 enum lws_close_status {
598 LWS_CLOSE_STATUS_NOSTATUS = 0,
599 LWS_CLOSE_STATUS_NORMAL = 1000,
600 /**< 1000 indicates a normal closure, meaning that the purpose for
601 which the connection was established has been fulfilled. */
602 LWS_CLOSE_STATUS_GOINGAWAY = 1001,
603 /**< 1001 indicates that an endpoint is "going away", such as a server
604 going down or a browser having navigated away from a page. */
605 LWS_CLOSE_STATUS_PROTOCOL_ERR = 1002,
606 /**< 1002 indicates that an endpoint is terminating the connection due
607 to a protocol error. */
608 LWS_CLOSE_STATUS_UNACCEPTABLE_OPCODE = 1003,
609 /**< 1003 indicates that an endpoint is terminating the connection
610 because it has received a type of data it cannot accept (e.g., an
611 endpoint that understands only text data MAY send this if it
612 receives a binary message). */
613 LWS_CLOSE_STATUS_RESERVED = 1004,
614 /**< Reserved. The specific meaning might be defined in the future. */
615 LWS_CLOSE_STATUS_NO_STATUS = 1005,
616 /**< 1005 is a reserved value and MUST NOT be set as a status code in a
617 Close control frame by an endpoint. It is designated for use in
618 applications expecting a status code to indicate that no status
619 code was actually present. */
620 LWS_CLOSE_STATUS_ABNORMAL_CLOSE = 1006,
621 /**< 1006 is a reserved value and MUST NOT be set as a status code in a
622 Close control frame by an endpoint. It is designated for use in
623 applications expecting a status code to indicate that the
624 connection was closed abnormally, e.g., without sending or
625 receiving a Close control frame. */
626 LWS_CLOSE_STATUS_INVALID_PAYLOAD = 1007,
627 /**< 1007 indicates that an endpoint is terminating the connection
628 because it has received data within a message that was not
629 consistent with the type of the message (e.g., non-UTF-8 [RFC3629]
630 data within a text message). */
631 LWS_CLOSE_STATUS_POLICY_VIOLATION = 1008,
632 /**< 1008 indicates that an endpoint is terminating the connection
633 because it has received a message that violates its policy. This
634 is a generic status code that can be returned when there is no
635 other more suitable status code (e.g., 1003 or 1009) or if there
636 is a need to hide specific details about the policy. */
637 LWS_CLOSE_STATUS_MESSAGE_TOO_LARGE = 1009,
638 /**< 1009 indicates that an endpoint is terminating the connection
639 because it has received a message that is too big for it to
641 LWS_CLOSE_STATUS_EXTENSION_REQUIRED = 1010,
642 /**< 1010 indicates that an endpoint (client) is terminating the
643 connection because it has expected the server to negotiate one or
644 more extension, but the server didn't return them in the response
645 message of the WebSocket handshake. The list of extensions that
646 are needed SHOULD appear in the /reason/ part of the Close frame.
647 Note that this status code is not used by the server, because it
648 can fail the WebSocket handshake instead */
649 LWS_CLOSE_STATUS_UNEXPECTED_CONDITION = 1011,
650 /**< 1011 indicates that a server is terminating the connection because
651 it encountered an unexpected condition that prevented it from
652 fulfilling the request. */
653 LWS_CLOSE_STATUS_TLS_FAILURE = 1015,
654 /**< 1015 is a reserved value and MUST NOT be set as a status code in a
655 Close control frame by an endpoint. It is designated for use in
656 applications expecting a status code to indicate that the
657 connection was closed due to a failure to perform a TLS handshake
658 (e.g., the server certificate can't be verified). */
660 /****** add new things just above ---^ ******/
662 LWS_CLOSE_STATUS_NOSTATUS_CONTEXT_DESTROY = 9999,
666 * lws_close_reason - Set reason and aux data to send with Close packet
667 * If you are going to return nonzero from the callback
668 * requesting the connection to close, you can optionally
669 * call this to set the reason the peer will be told if
672 * \param wsi: The websocket connection to set the close reason on
673 * \param status: A valid close status from websocket standard
674 * \param buf: NULL or buffer containing up to 124 bytes of auxiliary data
675 * \param len: Length of data in \param buf to send
677 LWS_VISIBLE LWS_EXTERN void
678 lws_close_reason(struct lws *wsi, enum lws_close_status status,
679 unsigned char *buf, size_t len);
685 /* needed even with extensions disabled for create context */
686 struct lws_extension;
688 /*! \defgroup usercb User Callback
690 * ##User protocol callback
692 * The protocol callback is the primary way lws interacts with
693 * user code. For one of a list of a few dozen reasons the callback gets
694 * called at some event to be handled.
696 * All of the events can be ignored, returning 0 is taken as "OK" and returning
697 * nonzero in most cases indicates that the connection should be closed.
703 * NOTE: These public enums are part of the abi. If you want to add one,
704 * add it at where specified so existing users are unaffected.
706 /** enum lws_callback_reasons - reason you're getting a protocol callback */
707 enum lws_callback_reasons {
708 LWS_CALLBACK_ESTABLISHED = 0,
709 /**< (VH) after the server completes a handshake with an incoming
710 * client. If you built the library with ssl support, in is a
711 * pointer to the ssl struct associated with the connection or NULL.*/
712 LWS_CALLBACK_CLIENT_CONNECTION_ERROR = 1,
713 /**< the request client connection has been unable to complete a
714 * handshake with the remote server. If in is non-NULL, you can
715 * find an error string of length len where it points to
717 * Diagnostic strings that may be returned include
719 * "getaddrinfo (ipv6) failed"
720 * "unknown address family"
721 * "getaddrinfo (ipv4) failed"
722 * "set socket opts failed"
723 * "insert wsi failed"
724 * "lws_ssl_client_connect1 failed"
725 * "lws_ssl_client_connect2 failed"
729 * "HS: Redirect code but no Location"
730 * "HS: URI did not parse"
731 * "HS: Redirect failed"
732 * "HS: Server did not return 200"
734 * "HS: disallowed by client filter"
735 * "HS: disallowed at ESTABLISHED"
736 * "HS: ACCEPT missing"
737 * "HS: ws upgrade response not 101"
738 * "HS: UPGRADE missing"
739 * "HS: Upgrade to something other than websocket"
740 * "HS: CONNECTION missing"
741 * "HS: UPGRADE malformed"
742 * "HS: PROTOCOL malformed"
743 * "HS: Cannot match protocol"
744 * "HS: EXT: list too big"
745 * "HS: EXT: failed setting defaults"
746 * "HS: EXT: failed parsing defaults"
747 * "HS: EXT: failed parsing options"
748 * "HS: EXT: Rejects server options"
749 * "HS: EXT: unknown ext"
750 * "HS: Accept hash wrong"
751 * "HS: Rejected by filter cb"
753 * "HS: SO_SNDBUF failed"
754 * "HS: Rejected at CLIENT_ESTABLISHED"
756 LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH = 2,
757 /**< this is the last chance for the client user code to examine the
758 * http headers and decide to reject the connection. If the
759 * content in the headers is interesting to the
760 * client (url, etc) it needs to copy it out at
761 * this point since it will be destroyed before
762 * the CLIENT_ESTABLISHED call */
763 LWS_CALLBACK_CLIENT_ESTABLISHED = 3,
764 /**< after your client connection completed
765 * a handshake with the remote server */
766 LWS_CALLBACK_CLOSED = 4,
767 /**< when the websocket session ends */
768 LWS_CALLBACK_CLOSED_HTTP = 5,
769 /**< when a HTTP (non-websocket) session ends */
770 LWS_CALLBACK_RECEIVE = 6,
771 /**< data has appeared for this server endpoint from a
772 * remote client, it can be found at *in and is
774 LWS_CALLBACK_RECEIVE_PONG = 7,
775 /**< servers receive PONG packets with this callback reason */
776 LWS_CALLBACK_CLIENT_RECEIVE = 8,
777 /**< data has appeared from the server for the client connection, it
778 * can be found at *in and is len bytes long */
779 LWS_CALLBACK_CLIENT_RECEIVE_PONG = 9,
780 /**< clients receive PONG packets with this callback reason */
781 LWS_CALLBACK_CLIENT_WRITEABLE = 10,
782 /**< If you call lws_callback_on_writable() on a connection, you will
783 * get one of these callbacks coming when the connection socket
784 * is able to accept another write packet without blocking.
785 * If it already was able to take another packet without blocking,
786 * you'll get this callback at the next call to the service loop
787 * function. Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE
788 * and servers get LWS_CALLBACK_SERVER_WRITEABLE. */
789 LWS_CALLBACK_SERVER_WRITEABLE = 11,
790 /**< See LWS_CALLBACK_CLIENT_WRITEABLE */
791 LWS_CALLBACK_HTTP = 12,
792 /**< an http request has come from a client that is not
793 * asking to upgrade the connection to a websocket
794 * one. This is a chance to serve http content,
795 * for example, to send a script to the client
796 * which will then open the websockets connection.
797 * in points to the URI path requested and
798 * lws_serve_http_file() makes it very
799 * simple to send back a file to the client.
800 * Normally after sending the file you are done
801 * with the http connection, since the rest of the
802 * activity will come by websockets from the script
803 * that was delivered by http, so you will want to
804 * return 1; to close and free up the connection. */
805 LWS_CALLBACK_HTTP_BODY = 13,
806 /**< the next len bytes data from the http
807 * request body HTTP connection is now available in in. */
808 LWS_CALLBACK_HTTP_BODY_COMPLETION = 14,
809 /**< the expected amount of http request body has been delivered */
810 LWS_CALLBACK_HTTP_FILE_COMPLETION = 15,
811 /**< a file requested to be sent down http link has completed. */
812 LWS_CALLBACK_HTTP_WRITEABLE = 16,
813 /**< you can write more down the http protocol link now. */
814 LWS_CALLBACK_FILTER_NETWORK_CONNECTION = 17,
815 /**< called when a client connects to
816 * the server at network level; the connection is accepted but then
817 * passed to this callback to decide whether to hang up immediately
818 * or not, based on the client IP. in contains the connection
819 * socket's descriptor. Since the client connection information is
820 * not available yet, wsi still pointing to the main server socket.
821 * Return non-zero to terminate the connection before sending or
822 * receiving anything. Because this happens immediately after the
823 * network connection from the client, there's no websocket protocol
824 * selected yet so this callback is issued only to protocol 0. */
825 LWS_CALLBACK_FILTER_HTTP_CONNECTION = 18,
826 /**< called when the request has
827 * been received and parsed from the client, but the response is
828 * not sent yet. Return non-zero to disallow the connection.
829 * user is a pointer to the connection user space allocation,
830 * in is the URI, eg, "/"
831 * In your handler you can use the public APIs
832 * lws_hdr_total_length() / lws_hdr_copy() to access all of the
833 * headers using the header enums lws_token_indexes from
834 * libwebsockets.h to check for and read the supported header
835 * presence and content before deciding to allow the http
836 * connection to proceed or to kill the connection. */
837 LWS_CALLBACK_SERVER_NEW_CLIENT_INSTANTIATED = 19,
838 /**< A new client just had
839 * been connected, accepted, and instantiated into the pool. This
840 * callback allows setting any relevant property to it. Because this
841 * happens immediately after the instantiation of a new client,
842 * there's no websocket protocol selected yet so this callback is
843 * issued only to protocol 0. Only wsi is defined, pointing to the
844 * new client, and the return value is ignored. */
845 LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION = 20,
846 /**< called when the handshake has
847 * been received and parsed from the client, but the response is
848 * not sent yet. Return non-zero to disallow the connection.
849 * user is a pointer to the connection user space allocation,
850 * in is the requested protocol name
851 * In your handler you can use the public APIs
852 * lws_hdr_total_length() / lws_hdr_copy() to access all of the
853 * headers using the header enums lws_token_indexes from
854 * libwebsockets.h to check for and read the supported header
855 * presence and content before deciding to allow the handshake
856 * to proceed or to kill the connection. */
857 LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS = 21,
858 /**< if configured for
859 * including OpenSSL support, this callback allows your user code
860 * to perform extra SSL_CTX_load_verify_locations() or similar
861 * calls to direct OpenSSL where to find certificates the client
862 * can use to confirm the remote server identity. user is the
863 * OpenSSL SSL_CTX* */
864 LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS = 22,
865 /**< if configured for
866 * including OpenSSL support, this callback allows your user code
867 * to load extra certifcates into the server which allow it to
868 * verify the validity of certificates returned by clients. user
869 * is the server's OpenSSL SSL_CTX* */
870 LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION = 23,
871 /**< if the libwebsockets vhost was created with the option
872 * LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this
873 * callback is generated during OpenSSL verification of the cert
874 * sent from the client. It is sent to protocol[0] callback as
875 * no protocol has been negotiated on the connection yet.
876 * Notice that the libwebsockets context and wsi are both NULL
877 * during this callback. See
878 * http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
879 * to understand more detail about the OpenSSL callback that
880 * generates this libwebsockets callback and the meanings of the
881 * arguments passed. In this callback, user is the x509_ctx,
882 * in is the ssl pointer and len is preverify_ok
883 * Notice that this callback maintains libwebsocket return
884 * conventions, return 0 to mean the cert is OK or 1 to fail it.
885 * This also means that if you don't handle this callback then
886 * the default callback action of returning 0 allows the client
888 LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER = 24,
889 /**< this callback happens
890 * when a client handshake is being compiled. user is NULL,
891 * in is a char **, it's pointing to a char * which holds the
892 * next location in the header buffer where you can add
893 * headers, and len is the remaining space in the header buffer,
894 * which is typically some hundreds of bytes. So, to add a canned
895 * cookie, your handler code might look similar to:
897 * char **p = (char **)in;
902 * *p += sprintf(*p, "Cookie: a=b\x0d\x0a");
906 * Notice if you add anything, you just have to take care about
907 * the CRLF on the line you added. Obviously this callback is
908 * optional, if you don't handle it everything is fine.
910 * Notice the callback is coming to protocols[0] all the time,
911 * because there is no specific protocol negotiated yet. */
912 LWS_CALLBACK_CONFIRM_EXTENSION_OKAY = 25,
913 /**< When the server handshake code
914 * sees that it does support a requested extension, before
915 * accepting the extension by additing to the list sent back to
916 * the client it gives this callback just to check that it's okay
917 * to use that extension. It calls back to the requested protocol
918 * and with in being the extension name, len is 0 and user is
919 * valid. Note though at this time the ESTABLISHED callback hasn't
920 * happened yet so if you initialize user content there, user
921 * content during this callback might not be useful for anything.
922 * Notice this callback comes to protocols[0]. */
923 LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED = 26,
925 * connection is being prepared to start a handshake to a server,
926 * each supported extension is checked with protocols[0] callback
927 * with this reason, giving the user code a chance to suppress the
928 * claim to support that extension by returning non-zero. If
929 * unhandled, by default 0 will be returned and the extension
930 * support included in the header to the server. Notice this
931 * callback comes to protocols[0]. */
932 LWS_CALLBACK_PROTOCOL_INIT = 27,
933 /**< One-time call per protocol, per-vhost using it, so it can
934 * do initial setup / allocations etc */
935 LWS_CALLBACK_PROTOCOL_DESTROY = 28,
936 /**< One-time call per protocol, per-vhost using it, indicating
937 * this protocol won't get used at all after this callback, the
938 * vhost is getting destroyed. Take the opportunity to
939 * deallocate everything that was allocated by the protocol. */
940 LWS_CALLBACK_WSI_CREATE = 29,
941 /**< outermost (earliest) wsi create notification to protocols[0] */
942 LWS_CALLBACK_WSI_DESTROY = 30,
943 /**< outermost (latest) wsi destroy notification to protocols[0] */
944 LWS_CALLBACK_GET_THREAD_ID = 31,
945 /**< lws can accept callback when writable requests from other
946 * threads, if you implement this callback and return an opaque
947 * current thread ID integer. */
949 /* external poll() management support */
950 LWS_CALLBACK_ADD_POLL_FD = 32,
951 /**< lws normally deals with its poll() or other event loop
952 * internally, but in the case you are integrating with another
953 * server you will need to have lws sockets share a
954 * polling array with the other server. This and the other
955 * POLL_FD related callbacks let you put your specialized
956 * poll array interface code in the callback for protocol 0, the
957 * first protocol you support, usually the HTTP protocol in the
959 * This callback happens when a socket needs to be
960 * added to the polling loop: in points to a struct
961 * lws_pollargs; the fd member of the struct is the file
962 * descriptor, and events contains the active events
964 * If you are using the internal lws polling / event loop
965 * you can just ignore these callbacks. */
966 LWS_CALLBACK_DEL_POLL_FD = 33,
967 /**< This callback happens when a socket descriptor
968 * needs to be removed from an external polling array. in is
969 * again the struct lws_pollargs containing the fd member
970 * to be removed. If you are using the internal polling
971 * loop, you can just ignore it. */
972 LWS_CALLBACK_CHANGE_MODE_POLL_FD = 34,
973 /**< This callback happens when lws wants to modify the events for
975 * in is the struct lws_pollargs with the fd to change.
976 * The new event mask is in events member and the old mask is in
977 * the prev_events member.
978 * If you are using the internal polling loop, you can just ignore
980 LWS_CALLBACK_LOCK_POLL = 35,
981 /**< These allow the external poll changes driven
982 * by lws to participate in an external thread locking
983 * scheme around the changes, so the whole thing is threadsafe.
984 * These are called around three activities in the library,
985 * - inserting a new wsi in the wsi / fd table (len=1)
986 * - deleting a wsi from the wsi / fd table (len=1)
987 * - changing a wsi's POLLIN/OUT state (len=0)
988 * Locking and unlocking external synchronization objects when
989 * len == 1 allows external threads to be synchronized against
990 * wsi lifecycle changes if it acquires the same lock for the
991 * duration of wsi dereference from the other thread context. */
992 LWS_CALLBACK_UNLOCK_POLL = 36,
993 /**< See LWS_CALLBACK_LOCK_POLL, ignore if using lws internal poll */
995 LWS_CALLBACK_OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY = 37,
996 /**< if configured for including OpenSSL support but no private key
997 * file has been specified (ssl_private_key_filepath is NULL), this is
998 * called to allow the user to set the private key directly via
999 * libopenssl and perform further operations if required; this might be
1000 * useful in situations where the private key is not directly accessible
1001 * by the OS, for example if it is stored on a smartcard.
1002 * user is the server's OpenSSL SSL_CTX* */
1003 LWS_CALLBACK_WS_PEER_INITIATED_CLOSE = 38,
1004 /**< The peer has sent an unsolicited Close WS packet. in and
1005 * len are the optional close code (first 2 bytes, network
1006 * order) and the optional additional information which is not
1007 * defined in the standard, and may be a string or non-human- readable data.
1008 * If you return 0 lws will echo the close and then close the
1009 * connection. If you return nonzero lws will just close the
1012 LWS_CALLBACK_WS_EXT_DEFAULTS = 39,
1015 LWS_CALLBACK_CGI = 40,
1017 LWS_CALLBACK_CGI_TERMINATED = 41,
1019 LWS_CALLBACK_CGI_STDIN_DATA = 42,
1021 LWS_CALLBACK_CGI_STDIN_COMPLETED = 43,
1023 LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP = 44,
1025 LWS_CALLBACK_CLOSED_CLIENT_HTTP = 45,
1027 LWS_CALLBACK_RECEIVE_CLIENT_HTTP = 46,
1029 LWS_CALLBACK_COMPLETED_CLIENT_HTTP = 47,
1031 LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ = 48,
1033 LWS_CALLBACK_HTTP_BIND_PROTOCOL = 49,
1035 LWS_CALLBACK_HTTP_DROP_PROTOCOL = 50,
1037 LWS_CALLBACK_CHECK_ACCESS_RIGHTS = 51,
1039 LWS_CALLBACK_PROCESS_HTML = 52,
1041 LWS_CALLBACK_ADD_HEADERS = 53,
1043 LWS_CALLBACK_SESSION_INFO = 54,
1046 LWS_CALLBACK_GS_EVENT = 55,
1048 LWS_CALLBACK_HTTP_PMO = 56,
1049 /**< per-mount options for this connection, called before
1050 * the normal LWS_CALLBACK_HTTP when the mount has per-mount
1053 LWS_CALLBACK_CLIENT_HTTP_WRITEABLE = 57,
1054 /**< when doing an HTTP type client connection, you can call
1055 * lws_client_http_body_pending(wsi, 1) from
1056 * LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER to get these callbacks
1057 * sending the HTTP headers.
1059 * From this callback, when you have sent everything, you should let
1060 * lws know by calling lws_client_http_body_pending(wsi, 0)
1062 LWS_CALLBACK_OPENSSL_PERFORM_SERVER_CERT_VERIFICATION = 58,
1063 /**< Similar to LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION
1064 * this callback is called during OpenSSL verification of the cert
1065 * sent from the server to the client. It is sent to protocol[0]
1066 * callback as no protocol has been negotiated on the connection yet.
1067 * Notice that the wsi is set because lws_client_connect_via_info was
1070 * See http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
1071 * to understand more detail about the OpenSSL callback that
1072 * generates this libwebsockets callback and the meanings of the
1073 * arguments passed. In this callback, user is the x509_ctx,
1074 * in is the ssl pointer and len is preverify_ok.
1076 * THIS IS NOT RECOMMENDED BUT if a cert validation error shall be
1077 * overruled and cert shall be accepted as ok,
1078 * X509_STORE_CTX_set_error((X509_STORE_CTX*)user, X509_V_OK); must be
1079 * called and return value must be 0 to mean the cert is OK;
1080 * returning 1 will fail the cert in any case.
1082 * This also means that if you don't handle this callback then
1083 * the default callback action of returning 0 will not accept the
1084 * certificate in case of a validation error decided by the SSL lib.
1086 * This is expected and secure behaviour when validating certificates.
1088 * Note: LCCSCF_ALLOW_SELFSIGNED and
1089 * LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK still work without this
1090 * callback being implemented.
1092 LWS_CALLBACK_RAW_RX = 59,
1093 /**< RAW mode connection RX */
1094 LWS_CALLBACK_RAW_CLOSE = 60,
1095 /**< RAW mode connection is closing */
1096 LWS_CALLBACK_RAW_WRITEABLE = 61,
1097 /**< RAW mode connection may be written */
1098 LWS_CALLBACK_RAW_ADOPT = 62,
1099 /**< RAW mode connection was adopted (equivalent to 'wsi created') */
1100 LWS_CALLBACK_RAW_ADOPT_FILE = 63,
1101 /**< RAW mode file was adopted (equivalent to 'wsi created') */
1102 LWS_CALLBACK_RAW_RX_FILE = 64,
1103 /**< RAW mode file has something to read */
1104 LWS_CALLBACK_RAW_WRITEABLE_FILE = 65,
1105 /**< RAW mode file is writeable */
1106 LWS_CALLBACK_RAW_CLOSE_FILE = 66,
1107 /**< RAW mode wsi that adopted a file is closing */
1109 /****** add new things just above ---^ ******/
1111 LWS_CALLBACK_USER = 1000,
1112 /**< user code can use any including above without fear of clashes */
1118 * typedef lws_callback_function() - User server actions
1119 * \param wsi: Opaque websocket instance pointer
1120 * \param reason: The reason for the call
1121 * \param user: Pointer to per-session user data allocated by library
1122 * \param in: Pointer used for some callback reasons
1123 * \param len: Length set for some callback reasons
1125 * This callback is the way the user controls what is served. All the
1126 * protocol detail is hidden and handled by the library.
1128 * For each connection / session there is user data allocated that is
1129 * pointed to by "user". You set the size of this user data area when
1130 * the library is initialized with lws_create_server.
1133 lws_callback_function(struct lws *wsi, enum lws_callback_reasons reason,
1134 void *user, void *in, size_t len);
1137 /*! \defgroup extensions
1139 * ##Extension releated functions
1141 * Ws defines optional extensions, lws provides the ability to implement these
1142 * in user code if so desired.
1144 * We provide one extensions permessage-deflate.
1149 * NOTE: These public enums are part of the abi. If you want to add one,
1150 * add it at where specified so existing users are unaffected.
1152 enum lws_extension_callback_reasons {
1153 LWS_EXT_CB_SERVER_CONTEXT_CONSTRUCT = 0,
1154 LWS_EXT_CB_CLIENT_CONTEXT_CONSTRUCT = 1,
1155 LWS_EXT_CB_SERVER_CONTEXT_DESTRUCT = 2,
1156 LWS_EXT_CB_CLIENT_CONTEXT_DESTRUCT = 3,
1157 LWS_EXT_CB_CONSTRUCT = 4,
1158 LWS_EXT_CB_CLIENT_CONSTRUCT = 5,
1159 LWS_EXT_CB_CHECK_OK_TO_REALLY_CLOSE = 6,
1160 LWS_EXT_CB_CHECK_OK_TO_PROPOSE_EXTENSION = 7,
1161 LWS_EXT_CB_DESTROY = 8,
1162 LWS_EXT_CB_DESTROY_ANY_WSI_CLOSING = 9,
1163 LWS_EXT_CB_ANY_WSI_ESTABLISHED = 10,
1164 LWS_EXT_CB_PACKET_RX_PREPARSE = 11,
1165 LWS_EXT_CB_PACKET_TX_PRESEND = 12,
1166 LWS_EXT_CB_PACKET_TX_DO_SEND = 13,
1167 LWS_EXT_CB_HANDSHAKE_REPLY_TX = 14,
1168 LWS_EXT_CB_FLUSH_PENDING_TX = 15,
1169 LWS_EXT_CB_EXTENDED_PAYLOAD_RX = 16,
1170 LWS_EXT_CB_CAN_PROXY_CLIENT_CONNECTION = 17,
1171 LWS_EXT_CB_1HZ = 18,
1172 LWS_EXT_CB_REQUEST_ON_WRITEABLE = 19,
1173 LWS_EXT_CB_IS_WRITEABLE = 20,
1174 LWS_EXT_CB_PAYLOAD_TX = 21,
1175 LWS_EXT_CB_PAYLOAD_RX = 22,
1176 LWS_EXT_CB_OPTION_DEFAULT = 23,
1177 LWS_EXT_CB_OPTION_SET = 24,
1178 LWS_EXT_CB_OPTION_CONFIRM = 25,
1179 LWS_EXT_CB_NAMED_OPTION_SET = 26,
1181 /****** add new things just above ---^ ******/
1184 /** enum lws_ext_options_types */
1185 enum lws_ext_options_types {
1186 EXTARG_NONE, /**< does not take an argument */
1187 EXTARG_DEC, /**< requires a decimal argument */
1188 EXTARG_OPT_DEC /**< may have an optional decimal argument */
1190 /* Add new things just above here ---^
1191 * This is part of the ABI, don't needlessly break compatibility */
1194 /** struct lws_ext_options - Option arguments to the extension. These are
1195 * used in the negotiation at ws upgrade time.
1196 * The helper function lws_ext_parse_options()
1197 * uses these to generate callbacks */
1198 struct lws_ext_options {
1199 const char *name; /**< Option name, eg, "server_no_context_takeover" */
1200 enum lws_ext_options_types type; /**< What kind of args the option can take */
1202 /* Add new things just above here ---^
1203 * This is part of the ABI, don't needlessly break compatibility */
1206 /** struct lws_ext_option_arg */
1207 struct lws_ext_option_arg {
1208 const char *option_name; /**< may be NULL, option_index used then */
1209 int option_index; /**< argument ordinal to use if option_name missing */
1210 const char *start; /**< value */
1211 int len; /**< length of value */
1215 * typedef lws_extension_callback_function() - Hooks to allow extensions to operate
1216 * \param context: Websockets context
1217 * \param ext: This extension
1218 * \param wsi: Opaque websocket instance pointer
1219 * \param reason: The reason for the call
1220 * \param user: Pointer to ptr to per-session user data allocated by library
1221 * \param in: Pointer used for some callback reasons
1222 * \param len: Length set for some callback reasons
1224 * Each extension that is active on a particular connection receives
1225 * callbacks during the connection lifetime to allow the extension to
1226 * operate on websocket data and manage itself.
1228 * Libwebsockets takes care of allocating and freeing "user" memory for
1229 * each active extension on each connection. That is what is pointed to
1230 * by the user parameter.
1232 * LWS_EXT_CB_CONSTRUCT: called when the server has decided to
1233 * select this extension from the list provided by the client,
1234 * just before the server will send back the handshake accepting
1235 * the connection with this extension active. This gives the
1236 * extension a chance to initialize its connection context found
1239 * LWS_EXT_CB_CLIENT_CONSTRUCT: same as LWS_EXT_CB_CONSTRUCT
1240 * but called when client is instantiating this extension. Some
1241 * extensions will work the same on client and server side and then
1242 * you can just merge handlers for both CONSTRUCTS.
1244 * LWS_EXT_CB_DESTROY: called when the connection the extension was
1245 * being used on is about to be closed and deallocated. It's the
1246 * last chance for the extension to deallocate anything it has
1247 * allocated in the user data (pointed to by user) before the
1248 * user data is deleted. This same callback is used whether you
1249 * are in client or server instantiation context.
1251 * LWS_EXT_CB_PACKET_RX_PREPARSE: when this extension was active on
1252 * a connection, and a packet of data arrived at the connection,
1253 * it is passed to this callback to give the extension a chance to
1254 * change the data, eg, decompress it. user is pointing to the
1255 * extension's private connection context data, in is pointing
1256 * to an lws_tokens struct, it consists of a char * pointer called
1257 * token, and an int called token_len. At entry, these are
1258 * set to point to the received buffer and set to the content
1259 * length. If the extension will grow the content, it should use
1260 * a new buffer allocated in its private user context data and
1261 * set the pointed-to lws_tokens members to point to its buffer.
1263 * LWS_EXT_CB_PACKET_TX_PRESEND: this works the same way as
1264 * LWS_EXT_CB_PACKET_RX_PREPARSE above, except it gives the
1265 * extension a chance to change websocket data just before it will
1266 * be sent out. Using the same lws_token pointer scheme in in,
1267 * the extension can change the buffer and the length to be
1268 * transmitted how it likes. Again if it wants to grow the
1269 * buffer safely, it should copy the data into its own buffer and
1270 * set the lws_tokens token pointer to it.
1272 * LWS_EXT_CB_ARGS_VALIDATE:
1275 lws_extension_callback_function(struct lws_context *context,
1276 const struct lws_extension *ext, struct lws *wsi,
1277 enum lws_extension_callback_reasons reason,
1278 void *user, void *in, size_t len);
1280 /** struct lws_extension - An extension we support */
1281 struct lws_extension {
1282 const char *name; /**< Formal extension name, eg, "permessage-deflate" */
1283 lws_extension_callback_function *callback; /**< Service callback */
1284 const char *client_offer; /**< String containing exts and options client offers */
1286 /* Add new things just above here ---^
1287 * This is part of the ABI, don't needlessly break compatibility */
1291 * lws_set_extension_option(): set extension option if possible
1293 * \param wsi: websocket connection
1294 * \param ext_name: name of ext, like "permessage-deflate"
1295 * \param opt_name: name of option, like "rx_buf_size"
1296 * \param opt_val: value to set option to
1298 LWS_VISIBLE LWS_EXTERN int
1299 lws_set_extension_option(struct lws *wsi, const char *ext_name,
1300 const char *opt_name, const char *opt_val);
1302 #ifndef LWS_NO_EXTENSIONS
1303 /* lws_get_internal_extensions() - DEPRECATED
1305 * \Deprecated There is no longer a set internal extensions table. The table is provided
1306 * by user code along with application-specific settings. See the test
1307 * client and server for how to do.
1309 static LWS_INLINE LWS_WARN_DEPRECATED const struct lws_extension *
1310 lws_get_internal_extensions(void) { return NULL; }
1313 * lws_ext_parse_options() - deal with parsing negotiated extension options
1315 * \param ext: related extension struct
1316 * \param wsi: websocket connection
1317 * \param ext_user: per-connection extension private data
1318 * \param opts: list of supported options
1319 * \param o: option string to parse
1320 * \param len: length
1322 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
1323 lws_ext_parse_options(const struct lws_extension *ext, struct lws *wsi,
1324 void *ext_user, const struct lws_ext_options *opts,
1325 const char *o, int len);
1328 /** lws_extension_callback_pm_deflate() - extension for RFC7692
1330 * \param context: lws context
1331 * \param ext: related lws_extension struct
1332 * \param wsi: websocket connection
1333 * \param reason: incoming callback reason
1334 * \param user: per-connection extension private data
1335 * \param in: pointer parameter
1336 * \param len: length parameter
1338 * Built-in callback implementing RFC7692 permessage-deflate
1341 int lws_extension_callback_pm_deflate(
1342 struct lws_context *context, const struct lws_extension *ext,
1343 struct lws *wsi, enum lws_extension_callback_reasons reason,
1344 void *user, void *in, size_t len);
1347 * The internal exts are part of the public abi
1348 * If we add more extensions, publish the callback here ------v
1352 /*! \defgroup Protocols-and-Plugins Protocols and Plugins
1355 * ##Protocol and protocol plugin -related apis
1357 * Protocols bind ws protocol names to a custom callback specific to that
1358 * protocol implementaion.
1360 * A list of protocols can be passed in at context creation time, but it is
1361 * also legal to leave that NULL and add the protocols and their callback code
1364 * Plugins are much preferable compared to cut and pasting code into an
1365 * application each time, since they can be used standalone.
1368 /** struct lws_protocols - List of protocols and handlers client or server
1371 struct lws_protocols {
1373 /**< Protocol name that must match the one given in the client
1374 * Javascript new WebSocket(url, 'protocol') name. */
1375 lws_callback_function *callback;
1376 /**< The service callback used for this protocol. It allows the
1377 * service action for an entire protocol to be encapsulated in
1378 * the protocol-specific callback */
1379 size_t per_session_data_size;
1380 /**< Each new connection using this protocol gets
1381 * this much memory allocated on connection establishment and
1382 * freed on connection takedown. A pointer to this per-connection
1383 * allocation is passed into the callback in the 'user' parameter */
1384 size_t rx_buffer_size;
1385 /**< lws allocates this much space for rx data and informs callback
1386 * when something came. Due to rx flow control, the callback may not
1387 * be able to consume it all without having to return to the event
1388 * loop. That is supported in lws.
1390 * This also controls how much may be sent at once at the moment,
1391 * although this is likely to change.
1394 /**< ignored by lws, but useful to contain user information bound
1395 * to the selected protocol. For example if this protocol was
1396 * called "myprotocol-v2", you might set id to 2, and the user
1397 * code that acts differently according to the version can do so by
1398 * switch (wsi->protocol->id), user code might use some bits as
1399 * capability flags based on selected protocol version, etc. */
1400 void *user; /**< ignored by lws, but user code can pass a pointer
1401 here it can later access from the protocol callback */
1403 /* Add new things just above here ---^
1404 * This is part of the ABI, don't needlessly break compatibility */
1410 * lws_vhost_name_to_protocol() - get vhost's protocol object from its name
1412 * \param vh: vhost to search
1413 * \param name: protocol name
1415 * Returns NULL or a pointer to the vhost's protocol of the requested name
1417 LWS_VISIBLE LWS_EXTERN const struct lws_protocols *
1418 lws_vhost_name_to_protocol(struct lws_vhost *vh, const char *name);
1421 * lws_get_protocol() - Returns a protocol pointer from a websocket
1423 * \param wsi: pointer to struct websocket you want to know the protocol of
1426 * Some apis can act on all live connections of a given protocol,
1427 * this is how you can get a pointer to the active protocol if needed.
1429 LWS_VISIBLE LWS_EXTERN const struct lws_protocols *
1430 lws_get_protocol(struct lws *wsi);
1432 /** lws_protocol_get() - deprecated: use lws_get_protocol */
1433 LWS_VISIBLE LWS_EXTERN const struct lws_protocols *
1434 lws_protocol_get(struct lws *wsi) LWS_WARN_DEPRECATED;
1437 * lws_protocol_vh_priv_zalloc() - Allocate and zero down a protocol's per-vhost
1439 * \param vhost: vhost the instance is related to
1440 * \param prot: protocol the instance is related to
1441 * \param size: bytes to allocate
1443 * Protocols often find it useful to allocate a per-vhost struct, this is a
1444 * helper to be called in the per-vhost init LWS_CALLBACK_PROTOCOL_INIT
1446 LWS_VISIBLE LWS_EXTERN void *
1447 lws_protocol_vh_priv_zalloc(struct lws_vhost *vhost, const struct lws_protocols *prot,
1451 * lws_protocol_vh_priv_get() - retreive a protocol's per-vhost storage
1453 * \param vhost: vhost the instance is related to
1454 * \param prot: protocol the instance is related to
1456 * Recover a pointer to the allocated per-vhost storage for the protocol created
1457 * by lws_protocol_vh_priv_zalloc() earlier
1459 LWS_VISIBLE LWS_EXTERN void *
1460 lws_protocol_vh_priv_get(struct lws_vhost *vhost, const struct lws_protocols *prot);
1463 * lws_finalize_startup() - drop initial process privileges
1465 * \param context: lws context
1467 * This is called after the end of the vhost protocol initializations, but
1468 * you may choose to call it earlier
1470 LWS_VISIBLE LWS_EXTERN int
1471 lws_finalize_startup(struct lws_context *context);
1473 LWS_VISIBLE LWS_EXTERN int
1474 lws_protocol_init(struct lws_context *context);
1476 #ifdef LWS_WITH_PLUGINS
1478 /* PLUGINS implies LIBUV */
1480 #define LWS_PLUGIN_API_MAGIC 180
1482 /** struct lws_plugin_capability - how a plugin introduces itself to lws */
1483 struct lws_plugin_capability {
1484 unsigned int api_magic; /**< caller fills this in, plugin fills rest */
1485 const struct lws_protocols *protocols; /**< array of supported protocols provided by plugin */
1486 int count_protocols; /**< how many protocols */
1487 const struct lws_extension *extensions; /**< array of extensions provided by plugin */
1488 int count_extensions; /**< how many extensions */
1491 typedef int (*lws_plugin_init_func)(struct lws_context *,
1492 struct lws_plugin_capability *);
1493 typedef int (*lws_plugin_destroy_func)(struct lws_context *);
1495 /** struct lws_plugin */
1497 struct lws_plugin *list; /**< linked list */
1498 #if (UV_VERSION_MAJOR > 0)
1499 uv_lib_t lib; /**< shared library pointer */
1501 void *l; /**< so we can compile on ancient libuv */
1503 char name[64]; /**< name of the plugin */
1504 struct lws_plugin_capability caps; /**< plugin capabilities */
1512 /*! \defgroup generic-sessions plugin: generic-sessions
1513 * \ingroup Protocols-and-Plugins
1515 * ##Plugin Generic-sessions related
1517 * generic-sessions plugin provides a reusable, generic session and login /
1518 * register / forgot password framework including email verification.
1522 #define LWSGS_EMAIL_CONTENT_SIZE 16384
1523 /**< Maximum size of email we might send */
1525 /* SHA-1 binary and hexified versions */
1526 /** typedef struct lwsgw_hash_bin */
1527 typedef struct { unsigned char bin[20]; /**< binary representation of hash */} lwsgw_hash_bin;
1528 /** typedef struct lwsgw_hash */
1529 typedef struct { char id[41]; /**< ascii hex representation of hash */ } lwsgw_hash;
1531 /** enum lwsgs_auth_bits */
1532 enum lwsgs_auth_bits {
1533 LWSGS_AUTH_LOGGED_IN = 1, /**< user is logged in as somebody */
1534 LWSGS_AUTH_ADMIN = 2, /**< logged in as the admin user */
1535 LWSGS_AUTH_VERIFIED = 4, /**< user has verified his email */
1536 LWSGS_AUTH_FORGOT_FLOW = 8, /**< he just completed "forgot password" flow */
1539 /** struct lws_session_info - information about user session status */
1540 struct lws_session_info {
1541 char username[32]; /**< username logged in as, or empty string */
1542 char email[100]; /**< email address associated with login, or empty string */
1543 char ip[72]; /**< ip address session was started from */
1544 unsigned int mask; /**< access rights mask associated with session
1545 * see enum lwsgs_auth_bits */
1546 char session[42]; /**< session id string, usable as opaque uid when not logged in */
1549 /** enum lws_gs_event */
1551 LWSGSE_CREATED, /**< a new user was created */
1552 LWSGSE_DELETED /**< an existing user was deleted */
1555 /** struct lws_gs_event_args */
1556 struct lws_gs_event_args {
1557 enum lws_gs_event event; /**< which event happened */
1558 const char *username; /**< which username the event happened to */
1559 const char *email; /**< the email address of that user */
1565 /*! \defgroup context-and-vhost
1568 * ##Context and Vhost releated functions
1570 * LWS requires that there is one context, in which you may define multiple
1571 * vhosts. Each vhost is a virtual host, with either its own listen port
1572 * or sharing an existing one. Each vhost has its own SSL context that can
1573 * be set up individually or left disabled.
1575 * If you don't care about multiple "site" support, you can ignore it and
1576 * lws will create a single default vhost at context creation time.
1581 * NOTE: These public enums are part of the abi. If you want to add one,
1582 * add it at where specified so existing users are unaffected.
1585 /** enum lws_context_options - context and vhost options */
1586 enum lws_context_options {
1587 LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT = (1 << 1) |
1589 /**< (VH) Don't allow the connection unless the client has a
1590 * client cert that we recognize; provides
1591 * LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT */
1592 LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME = (1 << 2),
1593 /**< (CTX) Don't try to get the server's hostname */
1594 LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT = (1 << 3) |
1596 /**< (VH) Allow non-SSL (plaintext) connections on the same
1597 * port as SSL is listening... undermines the security of SSL;
1598 * provides LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT */
1599 LWS_SERVER_OPTION_LIBEV = (1 << 4),
1600 /**< (CTX) Use libev event loop */
1601 LWS_SERVER_OPTION_DISABLE_IPV6 = (1 << 5),
1602 /**< (VH) Disable IPV6 support */
1603 LWS_SERVER_OPTION_DISABLE_OS_CA_CERTS = (1 << 6),
1604 /**< (VH) Don't load OS CA certs, you will need to load your
1606 LWS_SERVER_OPTION_PEER_CERT_NOT_REQUIRED = (1 << 7),
1607 /**< (VH) Accept connections with no valid Cert (eg, selfsigned) */
1608 LWS_SERVER_OPTION_VALIDATE_UTF8 = (1 << 8),
1609 /**< (VH) Check UT-8 correctness */
1610 LWS_SERVER_OPTION_SSL_ECDH = (1 << 9) |
1612 /**< (VH) initialize ECDH ciphers */
1613 LWS_SERVER_OPTION_LIBUV = (1 << 10),
1614 /**< (CTX) Use libuv event loop */
1615 LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS = (1 << 11) |
1617 /**< (VH) Use http redirect to force http to https
1618 * (deprecated: use mount redirection) */
1619 LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT = (1 << 12),
1620 /**< (CTX) Initialize the SSL library at all */
1621 LWS_SERVER_OPTION_EXPLICIT_VHOSTS = (1 << 13),
1622 /**< (CTX) Only create the context when calling context
1623 * create api, implies user code will create its own vhosts */
1624 LWS_SERVER_OPTION_UNIX_SOCK = (1 << 14),
1625 /**< (VH) Use Unix socket */
1626 LWS_SERVER_OPTION_STS = (1 << 15),
1627 /**< (VH) Send Strict Transport Security header, making
1628 * clients subsequently go to https even if user asked for http */
1629 LWS_SERVER_OPTION_IPV6_V6ONLY_MODIFY = (1 << 16),
1630 /**< (VH) Enable LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE to take effect */
1631 LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE = (1 << 17),
1632 /**< (VH) if set, only ipv6 allowed on the vhost */
1633 LWS_SERVER_OPTION_UV_NO_SIGSEGV_SIGFPE_SPIN = (1 << 18),
1634 /**< (CTX) Libuv only: Do not spin on SIGSEGV / SIGFPE. A segfault
1635 * normally makes the lib spin so you can attach a debugger to it
1636 * even if it happened without a debugger in place. You can disable
1637 * that by giving this option.
1639 LWS_SERVER_OPTION_JUST_USE_RAW_ORIGIN = (1 << 19),
1640 /**< For backwards-compatibility reasons, by default
1641 * lws prepends "http://" to the origin you give in the client
1642 * connection info struct. If you give this flag when you create
1643 * the context, only the string you give in the client connect
1644 * info for .origin (if any) will be used directly.
1646 LWS_SERVER_OPTION_FALLBACK_TO_RAW = (1 << 20),
1647 /**< (VH) if invalid http is coming in the first line, */
1648 LWS_SERVER_OPTION_LIBEVENT = (1 << 21),
1649 /**< (CTX) Use libevent event loop */
1651 /****** add new things just above ---^ ******/
1654 #define lws_check_opt(c, f) (((c) & (f)) == (f))
1656 struct lws_plat_file_ops;
1658 /** struct lws_context_creation_info - parameters to create context and /or vhost with
1660 * This is also used to create vhosts.... if LWS_SERVER_OPTION_EXPLICIT_VHOSTS
1661 * is not given, then for backwards compatibility one vhost is created at
1662 * context-creation time using the info from this struct.
1664 * If LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, then no vhosts are created
1665 * at the same time as the context, they are expected to be created afterwards.
1667 struct lws_context_creation_info {
1669 /**< VHOST: Port to listen on. Use CONTEXT_PORT_NO_LISTEN to suppress
1670 * listening for a client. Use CONTEXT_PORT_NO_LISTEN_SERVER if you are
1671 * writing a server but you are using \ref sock-adopt instead of the
1672 * built-in listener */
1674 /**< VHOST: NULL to bind the listen socket to all interfaces, or the
1675 * interface name, eg, "eth2"
1676 * If options specifies LWS_SERVER_OPTION_UNIX_SOCK, this member is
1677 * the pathname of a UNIX domain socket. you can use the UNIX domain
1678 * sockets in abstract namespace, by prepending an at symbol to the
1680 const struct lws_protocols *protocols;
1681 /**< VHOST: Array of structures listing supported protocols and a protocol-
1682 * specific callback for each one. The list is ended with an
1683 * entry that has a NULL callback pointer. */
1684 const struct lws_extension *extensions;
1685 /**< VHOST: NULL or array of lws_extension structs listing the
1686 * extensions this context supports. */
1687 const struct lws_token_limits *token_limits;
1688 /**< CONTEXT: NULL or struct lws_token_limits pointer which is initialized
1689 * with a token length limit for each possible WSI_TOKEN_ */
1690 const char *ssl_private_key_password;
1691 /**< VHOST: NULL or the passphrase needed for the private key */
1692 const char *ssl_cert_filepath;
1693 /**< VHOST: If libwebsockets was compiled to use ssl, and you want
1694 * to listen using SSL, set to the filepath to fetch the
1695 * server cert from, otherwise NULL for unencrypted */
1696 const char *ssl_private_key_filepath;
1697 /**< VHOST: filepath to private key if wanting SSL mode;
1698 * if this is set to NULL but sll_cert_filepath is set, the
1699 * OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY callback is called
1700 * to allow setting of the private key directly via openSSL
1702 const char *ssl_ca_filepath;
1703 /**< VHOST: CA certificate filepath or NULL */
1704 const char *ssl_cipher_list;
1705 /**< VHOST: List of valid ciphers to use (eg,
1706 * "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
1707 * or you can leave it as NULL to get "DEFAULT" */
1708 const char *http_proxy_address;
1709 /**< VHOST: If non-NULL, attempts to proxy via the given address.
1710 * If proxy auth is required, use format "username:password\@server:port" */
1711 unsigned int http_proxy_port;
1712 /**< VHOST: If http_proxy_address was non-NULL, uses this port */
1714 /**< CONTEXT: group id to change to after setting listen socket, or -1. */
1716 /**< CONTEXT: user id to change to after setting listen socket, or -1. */
1717 unsigned int options;
1718 /**< VHOST + CONTEXT: 0, or LWS_SERVER_OPTION_... bitfields */
1720 /**< CONTEXT: optional user pointer that can be recovered via the context
1721 * pointer using lws_context_user */
1723 /**< CONTEXT: 0 for no TCP keepalive, otherwise apply this keepalive
1724 * timeout to all libwebsocket sockets, client or server */
1726 /**< CONTEXT: if ka_time was nonzero, after the timeout expires how many
1727 * times to try to get a response from the peer before giving up
1728 * and killing the connection */
1730 /**< CONTEXT: if ka_time was nonzero, how long to wait before each ka_probes
1732 #ifdef LWS_OPENSSL_SUPPORT
1733 SSL_CTX *provided_client_ssl_ctx;
1734 /**< CONTEXT: If non-null, swap out libwebsockets ssl
1735 * implementation for the one provided by provided_ssl_ctx.
1736 * Libwebsockets no longer is responsible for freeing the context
1737 * if this option is selected. */
1738 #else /* maintain structure layout either way */
1739 void *provided_client_ssl_ctx; /**< dummy if ssl disabled */
1742 short max_http_header_data;
1743 /**< CONTEXT: The max amount of header payload that can be handled
1744 * in an http request (unrecognized header payload is dropped) */
1745 short max_http_header_pool;
1746 /**< CONTEXT: The max number of connections with http headers that
1747 * can be processed simultaneously (the corresponding memory is
1748 * allocated for the lifetime of the context). If the pool is
1749 * busy new incoming connections must wait for accept until one
1752 unsigned int count_threads;
1753 /**< CONTEXT: how many contexts to create in an array, 0 = 1 */
1754 unsigned int fd_limit_per_thread;
1755 /**< CONTEXT: nonzero means restrict each service thread to this
1756 * many fds, 0 means the default which is divide the process fd
1757 * limit by the number of threads. */
1758 unsigned int timeout_secs;
1759 /**< VHOST: various processes involving network roundtrips in the
1760 * library are protected from hanging forever by timeouts. If
1761 * nonzero, this member lets you set the timeout used in seconds.
1762 * Otherwise a default timeout is used. */
1763 const char *ecdh_curve;
1764 /**< VHOST: if NULL, defaults to initializing server with "prime256v1" */
1765 const char *vhost_name;
1766 /**< VHOST: name of vhost, must match external DNS name used to
1767 * access the site, like "warmcat.com" as it's used to match
1768 * Host: header and / or SNI name for SSL. */
1769 const char * const *plugin_dirs;
1770 /**< CONTEXT: NULL, or NULL-terminated array of directories to
1771 * scan for lws protocol plugins at context creation time */
1772 const struct lws_protocol_vhost_options *pvo;
1773 /**< VHOST: pointer to optional linked list of per-vhost
1774 * options made accessible to protocols */
1775 int keepalive_timeout;
1776 /**< VHOST: (default = 0 = 60s) seconds to allow remote
1777 * client to hold on to an idle HTTP/1.1 connection */
1778 const char *log_filepath;
1779 /**< VHOST: filepath to append logs to... this is opened before
1780 * any dropping of initial privileges */
1781 const struct lws_http_mount *mounts;
1782 /**< VHOST: optional linked list of mounts for this vhost */
1783 const char *server_string;
1784 /**< CONTEXT: string used in HTTP headers to identify server
1785 * software, if NULL, "libwebsockets". */
1786 unsigned int pt_serv_buf_size;
1787 /**< CONTEXT: 0 = default of 4096. This buffer is used by
1788 * various service related features including file serving, it
1789 * defines the max chunk of file that can be sent at once.
1790 * At the risk of lws having to buffer failed large sends, it
1791 * can be increased to, eg, 128KiB to improve throughput. */
1792 unsigned int max_http_header_data2;
1793 /**< CONTEXT: if max_http_header_data is 0 and this
1794 * is nonzero, this will be used in place of the default. It's
1795 * like this for compatibility with the original short version,
1796 * this is unsigned int length. */
1797 long ssl_options_set;
1798 /**< VHOST: Any bits set here will be set as SSL options */
1799 long ssl_options_clear;
1800 /**< VHOST: Any bits set here will be cleared as SSL options */
1801 unsigned short ws_ping_pong_interval;
1802 /**< CONTEXT: 0 for none, else interval in seconds between sending
1803 * PINGs on idle websocket connections. When the PING is sent,
1804 * the PONG must come within the normal timeout_secs timeout period
1805 * or the connection will be dropped.
1806 * Any RX or TX traffic on the connection restarts the interval timer,
1807 * so a connection which always sends or receives something at intervals
1808 * less than the interval given here will never send PINGs / expect
1809 * PONGs. Conversely as soon as the ws connection is established, an
1810 * idle connection will do the PING / PONG roundtrip as soon as
1811 * ws_ping_pong_interval seconds has passed without traffic
1813 const struct lws_protocol_vhost_options *headers;
1814 /**< VHOST: pointer to optional linked list of per-vhost
1815 * canned headers that are added to server responses */
1817 const struct lws_protocol_vhost_options *reject_service_keywords;
1818 /**< CONTEXT: Optional list of keywords and rejection codes + text.
1820 * The keywords are checked for existing in the user agent string.
1822 * Eg, "badrobot" "404 Not Found"
1824 void *external_baggage_free_on_destroy;
1825 /**< CONTEXT: NULL, or pointer to something externally malloc'd, that
1826 * should be freed when the context is destroyed. This allows you to
1827 * automatically sync the freeing action to the context destruction
1828 * action, so there is no need for an external free() if the context
1829 * succeeded to create.
1832 #ifdef LWS_OPENSSL_SUPPORT
1833 /**< CONTEXT: NULL or struct lws_token_limits pointer which is initialized
1834 * with a token length limit for each possible WSI_TOKEN_ */
1835 const char *client_ssl_private_key_password;
1836 /**< VHOST: NULL or the passphrase needed for the private key */
1837 const char *client_ssl_cert_filepath;
1838 /**< VHOST: If libwebsockets was compiled to use ssl, and you want
1839 * to listen using SSL, set to the filepath to fetch the
1840 * server cert from, otherwise NULL for unencrypted */
1841 const char *client_ssl_private_key_filepath;
1842 /**< VHOST: filepath to private key if wanting SSL mode;
1843 * if this is set to NULL but sll_cert_filepath is set, the
1844 * OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY callback is called
1845 * to allow setting of the private key directly via openSSL
1847 const char *client_ssl_ca_filepath;
1848 /**< VHOST: CA certificate filepath or NULL */
1849 const char *client_ssl_cipher_list;
1850 /**< VHOST: List of valid ciphers to use (eg,
1851 * "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
1852 * or you can leave it as NULL to get "DEFAULT" */
1855 const struct lws_plat_file_ops *fops;
1856 /**< CONTEXT: NULL, or pointer to an array of fops structs, terminated
1857 * by a sentinel with NULL .open.
1859 * If NULL, lws provides just the platform file operations struct for
1860 * backwards compatibility.
1863 /* Add new things just above here ---^
1864 * This is part of the ABI, don't needlessly break compatibility
1866 * The below is to ensure later library versions with new
1867 * members added above will see 0 (default) even if the app
1868 * was not built against the newer headers.
1871 void *_unused[8]; /**< dummy */
1875 * lws_create_context() - Create the websocket handler
1876 * \param info: pointer to struct with parameters
1878 * This function creates the listening socket (if serving) and takes care
1879 * of all initialization in one step.
1881 * If option LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, no vhost is
1882 * created; you're expected to create your own vhosts afterwards using
1883 * lws_create_vhost(). Otherwise a vhost named "default" is also created
1884 * using the information in the vhost-related members, for compatibility.
1886 * After initialization, it returns a struct lws_context * that
1887 * represents this server. After calling, user code needs to take care
1888 * of calling lws_service() with the context pointer to get the
1889 * server's sockets serviced. This must be done in the same process
1890 * context as the initialization call.
1892 * The protocol callback functions are called for a handful of events
1893 * including http requests coming in, websocket connections becoming
1894 * established, and data arriving; it's also called periodically to allow
1895 * async transmission.
1897 * HTTP requests are sent always to the FIRST protocol in protocol, since
1898 * at that time websocket protocol has not been negotiated. Other
1899 * protocols after the first one never see any HTTP callback activity.
1901 * The server created is a simple http server by default; part of the
1902 * websocket standard is upgrading this http connection to a websocket one.
1904 * This allows the same server to provide files like scripts and favicon /
1905 * images or whatever over http and dynamic data over websockets all in
1906 * one place; they're all handled in the user callback.
1908 LWS_VISIBLE LWS_EXTERN struct lws_context *
1909 lws_create_context(struct lws_context_creation_info *info);
1912 * lws_context_destroy() - Destroy the websocket context
1913 * \param context: Websocket context
1915 * This function closes any active connections and then frees the
1916 * context. After calling this, any further use of the context is
1919 LWS_VISIBLE LWS_EXTERN void
1920 lws_context_destroy(struct lws_context *context);
1922 LWS_VISIBLE LWS_EXTERN void
1923 lws_context_destroy2(struct lws_context *context);
1925 typedef int (*lws_reload_func)(void);
1928 * lws_context_deprecate() - Deprecate the websocket context
1929 * \param context: Websocket context
1931 * This function is used on an existing context before superceding it
1932 * with a new context.
1934 * It closes any listen sockets in the context, so new connections are
1937 * And it marks the context to be deleted when the number of active
1938 * connections into it falls to zero.
1940 * Otherwise if you attach the deprecated context to the replacement
1941 * context when it has been created using lws_context_attach_deprecated()
1942 * both any deprecated and the new context will service their connections.
1944 * This is aimed at allowing seamless configuration reloads.
1946 * The callback cb will be called after the listen sockets are actually
1947 * closed and may be reopened. In the callback the new context should be
1948 * configured and created. (With libuv, socket close happens async after
1949 * more loop events).
1951 LWS_VISIBLE LWS_EXTERN void
1952 lws_context_deprecate(struct lws_context *context, lws_reload_func cb);
1954 LWS_VISIBLE LWS_EXTERN int
1955 lws_context_is_deprecated(struct lws_context *context);
1958 * lws_set_proxy() - Setups proxy to lws_context.
1959 * \param vhost: pointer to struct lws_vhost you want set proxy for
1960 * \param proxy: pointer to c string containing proxy in format address:port
1962 * Returns 0 if proxy string was parsed and proxy was setup.
1963 * Returns -1 if proxy is NULL or has incorrect format.
1965 * This is only required if your OS does not provide the http_proxy
1966 * environment variable (eg, OSX)
1968 * IMPORTANT! You should call this function right after creation of the
1969 * lws_context and before call to connect. If you call this
1970 * function after connect behavior is undefined.
1971 * This function will override proxy settings made on lws_context
1972 * creation with genenv() call.
1974 LWS_VISIBLE LWS_EXTERN int
1975 lws_set_proxy(struct lws_vhost *vhost, const char *proxy);
1981 * lws_create_vhost() - Create a vhost (virtual server context)
1982 * \param context: pointer to result of lws_create_context()
1983 * \param info: pointer to struct with parameters
1985 * This function creates a virtual server (vhost) using the vhost-related
1986 * members of the info struct. You can create many vhosts inside one context
1987 * if you created the context with the option LWS_SERVER_OPTION_EXPLICIT_VHOSTS
1989 LWS_EXTERN LWS_VISIBLE struct lws_vhost *
1990 lws_create_vhost(struct lws_context *context,
1991 struct lws_context_creation_info *info);
1994 * lwsws_get_config_globals() - Parse a JSON server config file
1995 * \param info: pointer to struct with parameters
1996 * \param d: filepath of the config file
1997 * \param config_strings: storage for the config strings extracted from JSON,
1998 * the pointer is incremented as strings are stored
1999 * \param len: pointer to the remaining length left in config_strings
2000 * the value is decremented as strings are stored
2002 * This function prepares a n lws_context_creation_info struct with global
2003 * settings from a file d.
2005 * Requires CMake option LWS_WITH_LEJP_CONF to have been enabled
2007 LWS_VISIBLE LWS_EXTERN int
2008 lwsws_get_config_globals(struct lws_context_creation_info *info, const char *d,
2009 char **config_strings, int *len);
2012 * lwsws_get_config_vhosts() - Create vhosts from a JSON server config file
2013 * \param context: pointer to result of lws_create_context()
2014 * \param info: pointer to struct with parameters
2015 * \param d: filepath of the config file
2016 * \param config_strings: storage for the config strings extracted from JSON,
2017 * the pointer is incremented as strings are stored
2018 * \param len: pointer to the remaining length left in config_strings
2019 * the value is decremented as strings are stored
2021 * This function creates vhosts into a context according to the settings in
2022 *JSON files found in directory d.
2024 * Requires CMake option LWS_WITH_LEJP_CONF to have been enabled
2026 LWS_VISIBLE LWS_EXTERN int
2027 lwsws_get_config_vhosts(struct lws_context *context,
2028 struct lws_context_creation_info *info, const char *d,
2029 char **config_strings, int *len);
2031 /** lws_vhost_get() - \deprecated deprecated: use lws_get_vhost() */
2032 LWS_VISIBLE LWS_EXTERN struct lws_vhost *
2033 lws_vhost_get(struct lws *wsi) LWS_WARN_DEPRECATED;
2036 * lws_get_vhost() - return the vhost a wsi belongs to
2038 * \param wsi: which connection
2040 LWS_VISIBLE LWS_EXTERN struct lws_vhost *
2041 lws_get_vhost(struct lws *wsi);
2044 * lws_json_dump_vhost() - describe vhost state and stats in JSON
2046 * \param vh: the vhost
2047 * \param buf: buffer to fill with JSON
2048 * \param len: max length of buf
2050 LWS_VISIBLE LWS_EXTERN int
2051 lws_json_dump_vhost(const struct lws_vhost *vh, char *buf, int len);
2054 * lws_json_dump_context() - describe context state and stats in JSON
2056 * \param context: the context
2057 * \param buf: buffer to fill with JSON
2058 * \param len: max length of buf
2060 LWS_VISIBLE LWS_EXTERN int
2061 lws_json_dump_context(const struct lws_context *context, char *buf, int len,
2065 * lws_context_user() - get the user data associated with the context
2066 * \param context: Websocket context
2068 * This returns the optional user allocation that can be attached to
2069 * the context the sockets live in at context_create time. It's a way
2070 * to let all sockets serviced in the same context share data without
2071 * using globals statics in the user code.
2073 LWS_VISIBLE LWS_EXTERN void *
2074 lws_context_user(struct lws_context *context);
2076 /*! \defgroup vhost-mounts Vhost mounts and options
2077 * \ingroup context-and-vhost-creation
2079 * ##Vhost mounts and options
2082 /** struct lws_protocol_vhost_options - linked list of per-vhost protocol
2083 * name=value options
2085 * This provides a general way to attach a linked-list of name=value pairs,
2086 * which can also have an optional child link-list using the options member.
2088 struct lws_protocol_vhost_options {
2089 const struct lws_protocol_vhost_options *next; /**< linked list */
2090 const struct lws_protocol_vhost_options *options; /**< child linked-list of more options for this node */
2091 const char *name; /**< name of name=value pair */
2092 const char *value; /**< value of name=value pair */
2095 /** enum lws_mount_protocols
2096 * This specifies the mount protocol for a mountpoint, whether it is to be
2097 * served from a filesystem, or it is a cgi etc.
2099 enum lws_mount_protocols {
2100 LWSMPRO_HTTP = 0, /**< not supported yet */
2101 LWSMPRO_HTTPS = 1, /**< not supported yet */
2102 LWSMPRO_FILE = 2, /**< serve from filesystem directory */
2103 LWSMPRO_CGI = 3, /**< pass to CGI to handle */
2104 LWSMPRO_REDIR_HTTP = 4, /**< redirect to http:// url */
2105 LWSMPRO_REDIR_HTTPS = 5, /**< redirect to https:// url */
2106 LWSMPRO_CALLBACK = 6, /**< hand by named protocol's callback */
2109 /** struct lws_http_mount
2111 * arguments for mounting something in a vhost's url namespace
2113 struct lws_http_mount {
2114 const struct lws_http_mount *mount_next;
2115 /**< pointer to next struct lws_http_mount */
2116 const char *mountpoint;
2117 /**< mountpoint in http pathspace, eg, "/" */
2119 /**< path to be mounted, eg, "/var/www/warmcat.com" */
2121 /**< default target, eg, "index.html" */
2122 const char *protocol;
2123 /**<"protocol-name" to handle mount */
2125 const struct lws_protocol_vhost_options *cgienv;
2126 /**< optional linked-list of cgi options. These are created
2127 * as environment variables for the cgi process
2129 const struct lws_protocol_vhost_options *extra_mimetypes;
2130 /**< optional linked-list of mimetype mappings */
2131 const struct lws_protocol_vhost_options *interpret;
2132 /**< optional linked-list of files to be interpreted */
2135 /**< seconds cgi is allowed to live, if cgi://mount type */
2137 /**< max-age for reuse of client cache of files, seconds */
2138 unsigned int auth_mask;
2139 /**< bits set here must be set for authorized client session */
2141 unsigned int cache_reusable:1; /**< set if client cache may reuse this */
2142 unsigned int cache_revalidate:1; /**< set if client cache should revalidate on use */
2143 unsigned int cache_intermediaries:1; /**< set if intermediaries are allowed to cache */
2145 unsigned char origin_protocol; /**< one of enum lws_mount_protocols */
2146 unsigned char mountpoint_len; /**< length of mountpoint string */
2148 const char *basic_auth_login_file;
2149 /**<NULL, or filepath to use to check basic auth logins against */
2151 /* Add new things just above here ---^
2152 * This is part of the ABI, don't needlessly break compatibility
2154 * The below is to ensure later library versions with new
2155 * members added above will see 0 (default) even if the app
2156 * was not built against the newer headers.
2159 void *_unused[2]; /**< dummy */
2164 /*! \defgroup client
2167 * ##Client releated functions
2171 /** enum lws_client_connect_ssl_connection_flags - flags that may be used
2172 * with struct lws_client_connect_info ssl_connection member to control if
2173 * and how SSL checks apply to the client connection being created
2176 enum lws_client_connect_ssl_connection_flags {
2177 LCCSCF_USE_SSL = (1 << 0),
2178 LCCSCF_ALLOW_SELFSIGNED = (1 << 1),
2179 LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK = (1 << 2),
2180 LCCSCF_ALLOW_EXPIRED = (1 << 3)
2183 /** struct lws_client_connect_info - parameters to connect with when using
2184 * lws_client_connect_via_info() */
2186 struct lws_client_connect_info {
2187 struct lws_context *context;
2188 /**< lws context to create connection in */
2189 const char *address;
2190 /**< remote address to connect to */
2192 /**< remote port to connect to */
2194 /**< nonzero for ssl */
2198 /**< content of host header */
2200 /**< content of origin header */
2201 const char *protocol;
2202 /**< list of ws protocols we could accept */
2203 int ietf_version_or_minus_one;
2204 /**< deprecated: currently leave at 0 or -1 */
2206 /**< if non-NULL, use this as wsi user_data instead of malloc it */
2207 const void *client_exts;
2208 /**< UNUSED... provide in info.extensions at context creation time */
2210 /**< if non-NULL, do this http method instead of ws[s] upgrade.
2211 * use "GET" to be a simple http client connection */
2212 struct lws *parent_wsi;
2213 /**< if another wsi is responsible for this connection, give it here.
2214 * this is used to make sure if the parent closes so do any
2215 * child connections first. */
2216 const char *uri_replace_from;
2217 /**< if non-NULL, when this string is found in URIs in
2218 * text/html content-encoding, it's replaced with uri_replace_to */
2219 const char *uri_replace_to;
2220 /**< see uri_replace_from */
2221 struct lws_vhost *vhost;
2222 /**< vhost to bind to (used to determine related SSL_CTX) */
2224 /**< if not NULL, store the new wsi here early in the connection
2225 * process. Although we return the new wsi, the call to create the
2226 * client connection does progress the connection somewhat and may
2227 * meet an error that will result in the connection being scrubbed and
2228 * NULL returned. While the wsi exists though, he may process a
2229 * callback like CLIENT_CONNECTION_ERROR with his wsi: this gives the
2230 * user callback a way to identify which wsi it is that faced the error
2231 * even before the new wsi is returned and even if ultimately no wsi
2235 /* Add new things just above here ---^
2236 * This is part of the ABI, don't needlessly break compatibility
2238 * The below is to ensure later library versions with new
2239 * members added above will see 0 (default) even if the app
2240 * was not built against the newer headers.
2243 void *_unused[4]; /**< dummy */
2247 * lws_client_connect_via_info() - Connect to another websocket server
2248 * \param ccinfo: pointer to lws_client_connect_info struct
2250 * This function creates a connection to a remote server using the
2251 * information provided in ccinfo.
2253 LWS_VISIBLE LWS_EXTERN struct lws *
2254 lws_client_connect_via_info(struct lws_client_connect_info * ccinfo);
2257 * lws_client_connect() - Connect to another websocket server
2258 * \deprecated DEPRECATED use lws_client_connect_via_info
2259 * \param clients: Websocket context
2260 * \param address: Remote server address, eg, "myserver.com"
2261 * \param port: Port to connect to on the remote server, eg, 80
2262 * \param ssl_connection: 0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self
2264 * \param path: Websocket path on server
2265 * \param host: Hostname on server
2266 * \param origin: Socket origin name
2267 * \param protocol: Comma-separated list of protocols being asked for from
2268 * the server, or just one. The server will pick the one it
2269 * likes best. If you don't want to specify a protocol, which is
2270 * legal, use NULL here.
2271 * \param ietf_version_or_minus_one: -1 to ask to connect using the default, latest
2272 * protocol supported, or the specific protocol ordinal
2274 * This function creates a connection to a remote server
2276 /* deprecated, use lws_client_connect_via_info() */
2277 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
2278 lws_client_connect(struct lws_context *clients, const char *address,
2279 int port, int ssl_connection, const char *path,
2280 const char *host, const char *origin, const char *protocol,
2281 int ietf_version_or_minus_one) LWS_WARN_DEPRECATED;
2282 /* deprecated, use lws_client_connect_via_info() */
2284 * lws_client_connect_extended() - Connect to another websocket server
2285 * \deprecated DEPRECATED use lws_client_connect_via_info
2286 * \param clients: Websocket context
2287 * \param address: Remote server address, eg, "myserver.com"
2288 * \param port: Port to connect to on the remote server, eg, 80
2289 * \param ssl_connection: 0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self
2291 * \param path: Websocket path on server
2292 * \param host: Hostname on server
2293 * \param origin: Socket origin name
2294 * \param protocol: Comma-separated list of protocols being asked for from
2295 * the server, or just one. The server will pick the one it
2297 * \param ietf_version_or_minus_one: -1 to ask to connect using the default, latest
2298 * protocol supported, or the specific protocol ordinal
2299 * \param userdata: Pre-allocated user data
2301 * This function creates a connection to a remote server
2303 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
2304 lws_client_connect_extended(struct lws_context *clients, const char *address,
2305 int port, int ssl_connection, const char *path,
2306 const char *host, const char *origin,
2307 const char *protocol, int ietf_version_or_minus_one,
2308 void *userdata) LWS_WARN_DEPRECATED;
2311 * lws_init_vhost_client_ssl() - also enable client SSL on an existing vhost
2313 * \param info: client ssl related info
2314 * \param vhost: which vhost to initialize client ssl operations on
2316 * You only need to call this if you plan on using SSL client connections on
2317 * the vhost. For non-SSL client connections, it's not necessary to call this.
2319 * The following members of info are used during the call
2321 * - options must have LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT set,
2322 * otherwise the call does nothing
2323 * - provided_client_ssl_ctx must be NULL to get a generated client
2324 * ssl context, otherwise you can pass a prepared one in by setting it
2325 * - ssl_cipher_list may be NULL or set to the client valid cipher list
2326 * - ssl_ca_filepath may be NULL or client cert filepath
2327 * - ssl_cert_filepath may be NULL or client cert filepath
2328 * - ssl_private_key_filepath may be NULL or client cert private key
2330 * You must create your vhost explicitly if you want to use this, so you have
2331 * a pointer to the vhost. Create the context first with the option flag
2332 * LWS_SERVER_OPTION_EXPLICIT_VHOSTS and then call lws_create_vhost() with
2333 * the same info struct.
2335 LWS_VISIBLE LWS_EXTERN int
2336 lws_init_vhost_client_ssl(const struct lws_context_creation_info *info,
2337 struct lws_vhost *vhost);
2340 * lws_http_client_read() - consume waiting received http client data
2342 * \param wsi: client connection
2343 * \param buf: pointer to buffer pointer - fill with pointer to your buffer
2344 * \param len: pointer to chunk length - fill with max length of buffer
2346 * This is called when the user code is notified client http data has arrived.
2347 * The user code may choose to delay calling it to consume the data, for example
2348 * waiting until an onward connection is writeable.
2350 * For non-chunked connections, up to len bytes of buf are filled with the
2351 * received content. len is set to the actual amount filled before return.
2353 * For chunked connections, the linear buffer content contains the chunking
2354 * headers and it cannot be passed in one lump. Instead, this function will
2355 * call back LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ with in pointing to the
2356 * chunk start and len set to the chunk length. There will be as many calls
2357 * as there are chunks or partial chunks in the buffer.
2359 LWS_VISIBLE LWS_EXTERN int
2360 lws_http_client_read(struct lws *wsi, char **buf, int *len);
2363 * lws_http_client_http_response() - get last HTTP response code
2365 * \param wsi: client connection
2367 * Returns the last server response code, eg, 200 for client http connections.
2369 LWS_VISIBLE LWS_EXTERN unsigned int
2370 lws_http_client_http_response(struct lws *wsi);
2372 LWS_VISIBLE LWS_EXTERN void
2373 lws_client_http_body_pending(struct lws *wsi, int something_left_to_send);
2376 * lws_client_http_body_pending() - control if client connection neeeds to send body
2378 * \param wsi: client connection
2379 * \param something_left_to_send: nonzero if need to send more body, 0 (default)
2380 * if nothing more to send
2382 * If you will send payload data with your HTTP client connection, eg, for POST,
2383 * when you set the related http headers in
2384 * LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER callback you should also call
2385 * this API with something_left_to_send nonzero, and call
2386 * lws_callback_on_writable(wsi);
2388 * After sending the headers, lws will call your callback with
2389 * LWS_CALLBACK_CLIENT_HTTP_WRITEABLE reason when writable. You can send the
2390 * next part of the http body payload, calling lws_callback_on_writable(wsi);
2391 * if there is more to come, or lws_client_http_body_pending(wsi, 0); to
2392 * let lws know the last part is sent and the connection can move on.
2397 /** \defgroup service Built-in service loop entry
2399 * ##Built-in service loop entry
2401 * If you're not using libev / libuv, these apis are needed to enter the poll()
2402 * wait in lws and service any connections with pending events.
2407 * lws_service() - Service any pending websocket activity
2408 * \param context: Websocket context
2409 * \param timeout_ms: Timeout for poll; 0 means return immediately if nothing needed
2410 * service otherwise block and service immediately, returning
2411 * after the timeout if nothing needed service.
2413 * This function deals with any pending websocket traffic, for three
2414 * kinds of event. It handles these events on both server and client
2415 * types of connection the same.
2417 * 1) Accept new connections to our context's server
2419 * 2) Call the receive callback for incoming frame data received by
2420 * server or client connections.
2422 * You need to call this service function periodically to all the above
2423 * functions to happen; if your application is single-threaded you can
2424 * just call it in your main event loop.
2426 * Alternatively you can fork a new process that asynchronously handles
2427 * calling this service in a loop. In that case you are happy if this
2428 * call blocks your thread until it needs to take care of something and
2429 * would call it with a large nonzero timeout. Your loop then takes no
2430 * CPU while there is nothing happening.
2432 * If you are calling it in a single-threaded app, you don't want it to
2433 * wait around blocking other things in your loop from happening, so you
2434 * would call it with a timeout_ms of 0, so it returns immediately if
2435 * nothing is pending, or as soon as it services whatever was pending.
2437 LWS_VISIBLE LWS_EXTERN int
2438 lws_service(struct lws_context *context, int timeout_ms);
2441 * lws_service() - Service any pending websocket activity
2443 * \param context: Websocket context
2444 * \param timeout_ms: Timeout for poll; 0 means return immediately if nothing needed
2445 * service otherwise block and service immediately, returning
2446 * after the timeout if nothing needed service.
2448 * Same as lws_service(), but for a specific thread service index. Only needed
2449 * if you are spawning multiple service threads.
2451 LWS_VISIBLE LWS_EXTERN int
2452 lws_service_tsi(struct lws_context *context, int timeout_ms, int tsi);
2455 * lws_cancel_service_pt() - Cancel servicing of pending socket activity
2457 * \param wsi: Cancel service on the thread this wsi is serviced by
2459 * This function lets a call to lws_service() waiting for a timeout
2460 * immediately return.
2462 * It works by creating a phony event and then swallowing it silently.
2464 * The reason it may be needed is when waiting in poll(), changes to
2465 * the event masks are ignored by the OS until poll() is reentered. This
2466 * lets you halt the poll() wait and make the reentry happen immediately
2467 * instead of having the wait out the rest of the poll timeout.
2469 LWS_VISIBLE LWS_EXTERN void
2470 lws_cancel_service_pt(struct lws *wsi);
2473 * lws_cancel_service() - Cancel wait for new pending socket activity
2474 * \param context: Websocket context
2476 * This function let a call to lws_service() waiting for a timeout
2477 * immediately return.
2479 * What it basically does is provide a fake event that will be swallowed,
2480 * so the wait in poll() is ended. That's useful because poll() doesn't
2481 * attend to changes in POLLIN/OUT/ERR until it re-enters the wait.
2483 LWS_VISIBLE LWS_EXTERN void
2484 lws_cancel_service(struct lws_context *context);
2487 * lws_service_fd() - Service polled socket with something waiting
2488 * \param context: Websocket context
2489 * \param pollfd: The pollfd entry describing the socket fd and which events
2490 * happened, or NULL to tell lws to do only timeout servicing.
2492 * This function takes a pollfd that has POLLIN or POLLOUT activity and
2493 * services it according to the state of the associated
2496 * The one call deals with all "service" that might happen on a socket
2497 * including listen accepts, http files as well as websocket protocol.
2499 * If a pollfd says it has something, you can just pass it to
2500 * lws_service_fd() whether it is a socket handled by lws or not.
2501 * If it sees it is a lws socket, the traffic will be handled and
2502 * pollfd->revents will be zeroed now.
2504 * If the socket is foreign to lws, it leaves revents alone. So you can
2505 * see if you should service yourself by checking the pollfd revents
2506 * after letting lws try to service it.
2508 * You should also call this with pollfd = NULL to just allow the
2509 * once-per-second global timeout checks; if less than a second since the last
2510 * check it returns immediately then.
2512 LWS_VISIBLE LWS_EXTERN int
2513 lws_service_fd(struct lws_context *context, struct lws_pollfd *pollfd);
2516 * lws_service_fd_tsi() - Service polled socket in specific service thread
2517 * \param context: Websocket context
2518 * \param pollfd: The pollfd entry describing the socket fd and which events
2520 * \param tsi: thread service index
2522 * Same as lws_service_fd() but used with multiple service threads
2524 LWS_VISIBLE LWS_EXTERN int
2525 lws_service_fd_tsi(struct lws_context *context, struct lws_pollfd *pollfd,
2529 * lws_service_adjust_timeout() - Check for any connection needing forced service
2530 * \param context: Websocket context
2531 * \param timeout_ms: The original poll timeout value. You can just set this
2532 * to 1 if you don't really have a poll timeout.
2533 * \param tsi: thread service index
2535 * Under some conditions connections may need service even though there is no
2536 * pending network action on them, this is "forced service". For default
2537 * poll() and libuv / libev, the library takes care of calling this and
2538 * dealing with it for you. But for external poll() integration, you need
2539 * access to the apis.
2541 * If anybody needs "forced service", returned timeout is zero. In that case,
2542 * you can call lws_service_tsi() with a timeout of -1 to only service
2543 * guys who need forced service.
2545 LWS_VISIBLE LWS_EXTERN int
2546 lws_service_adjust_timeout(struct lws_context *context, int timeout_ms, int tsi);
2548 /* Backwards compatibility */
2549 #define lws_plat_service_tsi lws_service_tsi
2553 /*! \defgroup http HTTP
2555 Modules related to handling HTTP
2559 /*! \defgroup httpft HTTP File transfer
2562 APIs for sending local files in response to HTTP requests
2567 * lws_get_mimetype() - Determine mimetype to use from filename
2569 * \param file: filename
2570 * \param m: NULL, or mount context
2572 * This uses a canned list of known filetypes first, if no match and m is
2573 * non-NULL, then tries a list of per-mount file suffix to mimtype mappings.
2575 * Returns either NULL or a pointer to the mimetype matching the file.
2577 LWS_VISIBLE LWS_EXTERN const char *
2578 lws_get_mimetype(const char *file, const struct lws_http_mount *m);
2581 * lws_serve_http_file() - Send a file back to the client using http
2582 * \param wsi: Websocket instance (available from user callback)
2583 * \param file: The file to issue over http
2584 * \param content_type: The http content type, eg, text/html
2585 * \param other_headers: NULL or pointer to header string
2586 * \param other_headers_len: length of the other headers if non-NULL
2588 * This function is intended to be called from the callback in response
2589 * to http requests from the client. It allows the callback to issue
2590 * local files down the http link in a single step.
2592 * Returning <0 indicates error and the wsi should be closed. Returning
2593 * >0 indicates the file was completely sent and
2594 * lws_http_transaction_completed() called on the wsi (and close if != 0)
2595 * ==0 indicates the file transfer is started and needs more service later,
2596 * the wsi should be left alone.
2598 LWS_VISIBLE LWS_EXTERN int
2599 lws_serve_http_file(struct lws *wsi, const char *file, const char *content_type,
2600 const char *other_headers, int other_headers_len);
2602 LWS_VISIBLE LWS_EXTERN int
2603 lws_serve_http_file_fragment(struct lws *wsi);
2606 /*! \defgroup html-chunked-substitution HTML Chunked Substitution
2609 * ##HTML chunked Substitution
2611 * APIs for receiving chunks of text, replacing a set of variable names via
2612 * a callback, and then prepending and appending HTML chunked encoding
2618 HTTP_STATUS_OK = 200,
2619 HTTP_STATUS_NO_CONTENT = 204,
2620 HTTP_STATUS_PARTIAL_CONTENT = 206,
2622 HTTP_STATUS_MOVED_PERMANENTLY = 301,
2623 HTTP_STATUS_FOUND = 302,
2624 HTTP_STATUS_SEE_OTHER = 303,
2625 HTTP_STATUS_NOT_MODIFIED = 304,
2627 HTTP_STATUS_BAD_REQUEST = 400,
2628 HTTP_STATUS_UNAUTHORIZED,
2629 HTTP_STATUS_PAYMENT_REQUIRED,
2630 HTTP_STATUS_FORBIDDEN,
2631 HTTP_STATUS_NOT_FOUND,
2632 HTTP_STATUS_METHOD_NOT_ALLOWED,
2633 HTTP_STATUS_NOT_ACCEPTABLE,
2634 HTTP_STATUS_PROXY_AUTH_REQUIRED,
2635 HTTP_STATUS_REQUEST_TIMEOUT,
2636 HTTP_STATUS_CONFLICT,
2638 HTTP_STATUS_LENGTH_REQUIRED,
2639 HTTP_STATUS_PRECONDITION_FAILED,
2640 HTTP_STATUS_REQ_ENTITY_TOO_LARGE,
2641 HTTP_STATUS_REQ_URI_TOO_LONG,
2642 HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE,
2643 HTTP_STATUS_REQ_RANGE_NOT_SATISFIABLE,
2644 HTTP_STATUS_EXPECTATION_FAILED,
2646 HTTP_STATUS_INTERNAL_SERVER_ERROR = 500,
2647 HTTP_STATUS_NOT_IMPLEMENTED,
2648 HTTP_STATUS_BAD_GATEWAY,
2649 HTTP_STATUS_SERVICE_UNAVAILABLE,
2650 HTTP_STATUS_GATEWAY_TIMEOUT,
2651 HTTP_STATUS_HTTP_VERSION_NOT_SUPPORTED,
2654 struct lws_process_html_args {
2655 char *p; /**< pointer to the buffer containing the data */
2656 int len; /**< length of the original data at p */
2657 int max_len; /**< maximum length we can grow the data to */
2658 int final; /**< set if this is the last chunk of the file */
2661 typedef const char *(*lws_process_html_state_cb)(void *data, int index);
2663 struct lws_process_html_state {
2664 char *start; /**< pointer to start of match */
2665 char swallow[16]; /**< matched character buffer */
2666 int pos; /**< position in match */
2667 void *data; /**< opaque pointer */
2668 const char * const *vars; /**< list of variable names */
2669 int count_vars; /**< count of variable names */
2671 lws_process_html_state_cb replace; /**< called on match to perform substitution */
2674 /*! lws_chunked_html_process() - generic chunked substitution
2675 * \param args: buffer to process using chunked encoding
2676 * \param s: current processing state
2678 LWS_VISIBLE LWS_EXTERN int
2679 lws_chunked_html_process(struct lws_process_html_args *args,
2680 struct lws_process_html_state *s);
2683 /** \defgroup HTTP-headers-read HTTP headers: read
2686 * ##HTTP header releated functions
2688 * In lws the client http headers are temporarily stored in a pool, only for the
2689 * duration of the http part of the handshake. It's because in most cases,
2690 * the header content is ignored for the whole rest of the connection lifetime
2691 * and would then just be taking up space needlessly.
2693 * During LWS_CALLBACK_HTTP when the URI path is delivered is the last time
2694 * the http headers are still allocated, you can use these apis then to
2695 * look at and copy out interesting header content (cookies, etc)
2697 * Notice that the header total length reported does not include a terminating
2698 * '\0', however you must allocate for it when using the _copy apis. So the
2699 * length reported for a header containing "123" is 3, but you must provide
2700 * a buffer of length 4 so that "123\0" may be copied into it, or the copy
2701 * will fail with a nonzero return code.
2703 * In the special case of URL arguments, like ?x=1&y=2, the arguments are
2704 * stored in a token named for the method, eg, WSI_TOKEN_GET_URI if it
2705 * was a GET or WSI_TOKEN_POST_URI if POST. You can check the total
2706 * length to confirm the method.
2708 * For URL arguments, each argument is stored urldecoded in a "fragment", so
2709 * you can use the fragment-aware api lws_hdr_copy_fragment() to access each
2710 * argument in turn: the fragments contain urldecoded strings like x=1 or y=2.
2712 * As a convenience, lws has an api that will find the fragment with a
2713 * given name= part, lws_get_urlarg_by_name().
2717 /** struct lws_tokens
2718 * you need these to look at headers that have been parsed if using the
2719 * LWS_CALLBACK_FILTER_CONNECTION callback. If a header from the enum
2720 * list below is absent, .token = NULL and token_len = 0. Otherwise .token
2721 * points to .token_len chars containing that header content.
2724 char *token; /**< pointer to start of the token */
2725 int token_len; /**< length of the token's value */
2728 /* enum lws_token_indexes
2729 * these have to be kept in sync with lextable.h / minilex.c
2731 * NOTE: These public enums are part of the abi. If you want to add one,
2732 * add it at where specified so existing users are unaffected.
2734 enum lws_token_indexes {
2735 WSI_TOKEN_GET_URI = 0,
2736 WSI_TOKEN_POST_URI = 1,
2737 WSI_TOKEN_OPTIONS_URI = 2,
2739 WSI_TOKEN_CONNECTION = 4,
2740 WSI_TOKEN_UPGRADE = 5,
2741 WSI_TOKEN_ORIGIN = 6,
2742 WSI_TOKEN_DRAFT = 7,
2743 WSI_TOKEN_CHALLENGE = 8,
2744 WSI_TOKEN_EXTENSIONS = 9,
2745 WSI_TOKEN_KEY1 = 10,
2746 WSI_TOKEN_KEY2 = 11,
2747 WSI_TOKEN_PROTOCOL = 12,
2748 WSI_TOKEN_ACCEPT = 13,
2749 WSI_TOKEN_NONCE = 14,
2750 WSI_TOKEN_HTTP = 15,
2751 WSI_TOKEN_HTTP2_SETTINGS = 16,
2752 WSI_TOKEN_HTTP_ACCEPT = 17,
2753 WSI_TOKEN_HTTP_AC_REQUEST_HEADERS = 18,
2754 WSI_TOKEN_HTTP_IF_MODIFIED_SINCE = 19,
2755 WSI_TOKEN_HTTP_IF_NONE_MATCH = 20,
2756 WSI_TOKEN_HTTP_ACCEPT_ENCODING = 21,
2757 WSI_TOKEN_HTTP_ACCEPT_LANGUAGE = 22,
2758 WSI_TOKEN_HTTP_PRAGMA = 23,
2759 WSI_TOKEN_HTTP_CACHE_CONTROL = 24,
2760 WSI_TOKEN_HTTP_AUTHORIZATION = 25,
2761 WSI_TOKEN_HTTP_COOKIE = 26,
2762 WSI_TOKEN_HTTP_CONTENT_LENGTH = 27,
2763 WSI_TOKEN_HTTP_CONTENT_TYPE = 28,
2764 WSI_TOKEN_HTTP_DATE = 29,
2765 WSI_TOKEN_HTTP_RANGE = 30,
2766 WSI_TOKEN_HTTP_REFERER = 31,
2768 WSI_TOKEN_VERSION = 33,
2769 WSI_TOKEN_SWORIGIN = 34,
2771 WSI_TOKEN_HTTP_COLON_AUTHORITY = 35,
2772 WSI_TOKEN_HTTP_COLON_METHOD = 36,
2773 WSI_TOKEN_HTTP_COLON_PATH = 37,
2774 WSI_TOKEN_HTTP_COLON_SCHEME = 38,
2775 WSI_TOKEN_HTTP_COLON_STATUS = 39,
2777 WSI_TOKEN_HTTP_ACCEPT_CHARSET = 40,
2778 WSI_TOKEN_HTTP_ACCEPT_RANGES = 41,
2779 WSI_TOKEN_HTTP_ACCESS_CONTROL_ALLOW_ORIGIN = 42,
2780 WSI_TOKEN_HTTP_AGE = 43,
2781 WSI_TOKEN_HTTP_ALLOW = 44,
2782 WSI_TOKEN_HTTP_CONTENT_DISPOSITION = 45,
2783 WSI_TOKEN_HTTP_CONTENT_ENCODING = 46,
2784 WSI_TOKEN_HTTP_CONTENT_LANGUAGE = 47,
2785 WSI_TOKEN_HTTP_CONTENT_LOCATION = 48,
2786 WSI_TOKEN_HTTP_CONTENT_RANGE = 49,
2787 WSI_TOKEN_HTTP_ETAG = 50,
2788 WSI_TOKEN_HTTP_EXPECT = 51,
2789 WSI_TOKEN_HTTP_EXPIRES = 52,
2790 WSI_TOKEN_HTTP_FROM = 53,
2791 WSI_TOKEN_HTTP_IF_MATCH = 54,
2792 WSI_TOKEN_HTTP_IF_RANGE = 55,
2793 WSI_TOKEN_HTTP_IF_UNMODIFIED_SINCE = 56,
2794 WSI_TOKEN_HTTP_LAST_MODIFIED = 57,
2795 WSI_TOKEN_HTTP_LINK = 58,
2796 WSI_TOKEN_HTTP_LOCATION = 59,
2797 WSI_TOKEN_HTTP_MAX_FORWARDS = 60,
2798 WSI_TOKEN_HTTP_PROXY_AUTHENTICATE = 61,
2799 WSI_TOKEN_HTTP_PROXY_AUTHORIZATION = 62,
2800 WSI_TOKEN_HTTP_REFRESH = 63,
2801 WSI_TOKEN_HTTP_RETRY_AFTER = 64,
2802 WSI_TOKEN_HTTP_SERVER = 65,
2803 WSI_TOKEN_HTTP_SET_COOKIE = 66,
2804 WSI_TOKEN_HTTP_STRICT_TRANSPORT_SECURITY = 67,
2805 WSI_TOKEN_HTTP_TRANSFER_ENCODING = 68,
2806 WSI_TOKEN_HTTP_USER_AGENT = 69,
2807 WSI_TOKEN_HTTP_VARY = 70,
2808 WSI_TOKEN_HTTP_VIA = 71,
2809 WSI_TOKEN_HTTP_WWW_AUTHENTICATE = 72,
2811 WSI_TOKEN_PATCH_URI = 73,
2812 WSI_TOKEN_PUT_URI = 74,
2813 WSI_TOKEN_DELETE_URI = 75,
2815 WSI_TOKEN_HTTP_URI_ARGS = 76,
2816 WSI_TOKEN_PROXY = 77,
2817 WSI_TOKEN_HTTP_X_REAL_IP = 78,
2818 WSI_TOKEN_HTTP1_0 = 79,
2819 WSI_TOKEN_X_FORWARDED_FOR = 80,
2820 WSI_TOKEN_CONNECT = 81,
2821 /****** add new things just above ---^ ******/
2823 /* use token storage to stash these internally, not for
2826 _WSI_TOKEN_CLIENT_SENT_PROTOCOLS,
2827 _WSI_TOKEN_CLIENT_PEER_ADDRESS,
2828 _WSI_TOKEN_CLIENT_URI,
2829 _WSI_TOKEN_CLIENT_HOST,
2830 _WSI_TOKEN_CLIENT_ORIGIN,
2831 _WSI_TOKEN_CLIENT_METHOD,
2833 /* always last real token index*/
2836 /* parser state additions, no storage associated */
2837 WSI_TOKEN_NAME_PART,
2839 WSI_TOKEN_SKIPPING_SAW_CR,
2840 WSI_PARSING_COMPLETE,
2841 WSI_INIT_TOKEN_MUXURL,
2844 struct lws_token_limits {
2845 unsigned short token_limit[WSI_TOKEN_COUNT]; /**< max chars for this token */
2849 * lws_token_to_string() - returns a textual representation of a hdr token index
2851 * \param: token index
2853 LWS_VISIBLE LWS_EXTERN const unsigned char *
2854 lws_token_to_string(enum lws_token_indexes token);
2858 * lws_hdr_total_length: report length of all fragments of a header totalled up
2859 * The returned length does not include the space for a
2862 * \param wsi: websocket connection
2863 * \param h: which header index we are interested in
2865 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2866 lws_hdr_total_length(struct lws *wsi, enum lws_token_indexes h);
2869 * lws_hdr_fragment_length: report length of a single fragment of a header
2870 * The returned length does not include the space for a
2873 * \param wsi: websocket connection
2874 * \param h: which header index we are interested in
2875 * \param frag_idx: which fragment of h we want to get the length of
2877 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2878 lws_hdr_fragment_length(struct lws *wsi, enum lws_token_indexes h, int frag_idx);
2881 * lws_hdr_copy() - copy a single fragment of the given header to a buffer
2882 * The buffer length len must include space for an additional
2883 * terminating '\0', or it will fail returning -1.
2885 * \param wsi: websocket connection
2886 * \param dest: destination buffer
2887 * \param len: length of destination buffer
2888 * \param h: which header index we are interested in
2890 * copies the whole, aggregated header, even if it was delivered in
2891 * several actual headers piece by piece
2893 LWS_VISIBLE LWS_EXTERN int
2894 lws_hdr_copy(struct lws *wsi, char *dest, int len, enum lws_token_indexes h);
2897 * lws_hdr_copy_fragment() - copy a single fragment of the given header to a buffer
2898 * The buffer length len must include space for an additional
2899 * terminating '\0', or it will fail returning -1.
2900 * If the requested fragment index is not present, it fails
2903 * \param wsi: websocket connection
2904 * \param dest: destination buffer
2905 * \param len: length of destination buffer
2906 * \param h: which header index we are interested in
2907 * \param frag_idx: which fragment of h we want to copy
2909 * Normally this is only useful
2910 * to parse URI arguments like ?x=1&y=2, token index WSI_TOKEN_HTTP_URI_ARGS
2911 * fragment 0 will contain "x=1" and fragment 1 "y=2"
2913 LWS_VISIBLE LWS_EXTERN int
2914 lws_hdr_copy_fragment(struct lws *wsi, char *dest, int len,
2915 enum lws_token_indexes h, int frag_idx);
2918 * lws_get_urlarg_by_name() - return pointer to arg value if present
2919 * \param wsi: the connection to check
2920 * \param name: the arg name, like "token="
2921 * \param buf: the buffer to receive the urlarg (including the name= part)
2922 * \param len: the length of the buffer to receive the urlarg
2924 * Returns NULL if not found or a pointer inside buf to just after the
2927 LWS_VISIBLE LWS_EXTERN const char *
2928 lws_get_urlarg_by_name(struct lws *wsi, const char *name, char *buf, int len);
2931 /*! \defgroup HTTP-headers-create HTTP headers: create
2933 * ## HTTP headers: Create
2935 * These apis allow you to create HTTP response headers in a way compatible with
2936 * both HTTP/1.x and HTTP/2.
2938 * They each append to a buffer taking care about the buffer end, which is
2939 * passed in as a pointer. When data is written to the buffer, the current
2940 * position p is updated accordingly.
2942 * All of these apis are LWS_WARN_UNUSED_RESULT as they can run out of space
2943 * and fail with nonzero return.
2947 #define LWSAHH_CODE_MASK ((1 << 16) - 1)
2948 #define LWSAHH_FLAG_NO_SERVER_NAME (1 << 30)
2951 * lws_add_http_header_status() - add the HTTP response status code
2953 * \param wsi: the connection to check
2954 * \param code: an HTTP code like 200, 404 etc (see enum http_status)
2955 * \param p: pointer to current position in buffer pointer
2956 * \param end: pointer to end of buffer
2958 * Adds the initial response code, so should be called first.
2960 * Code may additionally take OR'd flags:
2962 * LWSAHH_FLAG_NO_SERVER_NAME: don't apply server name header this time
2964 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2965 lws_add_http_header_status(struct lws *wsi,
2966 unsigned int code, unsigned char **p,
2967 unsigned char *end);
2969 * lws_add_http_header_by_name() - append named header and value
2971 * \param wsi: the connection to check
2972 * \param name: the hdr name, like "my-header"
2973 * \param value: the value after the = for this header
2974 * \param length: the length of the value
2975 * \param p: pointer to current position in buffer pointer
2976 * \param end: pointer to end of buffer
2978 * Appends name: value to the headers
2980 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2981 lws_add_http_header_by_name(struct lws *wsi, const unsigned char *name,
2982 const unsigned char *value, int length,
2983 unsigned char **p, unsigned char *end);
2985 * lws_add_http_header_by_token() - append given header and value
2987 * \param wsi: the connection to check
2988 * \param token: the token index for the hdr
2989 * \param value: the value after the = for this header
2990 * \param length: the length of the value
2991 * \param p: pointer to current position in buffer pointer
2992 * \param end: pointer to end of buffer
2994 * Appends name=value to the headers, but is able to take advantage of better
2995 * HTTP/2 coding mechanisms where possible.
2997 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
2998 lws_add_http_header_by_token(struct lws *wsi, enum lws_token_indexes token,
2999 const unsigned char *value, int length,
3000 unsigned char **p, unsigned char *end);
3002 * lws_add_http_header_by_name() - append content-length helper
3004 * \param wsi: the connection to check
3005 * \param content_length: the content length to use
3006 * \param p: pointer to current position in buffer pointer
3007 * \param end: pointer to end of buffer
3009 * Appends content-length: content_length to the headers
3011 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
3012 lws_add_http_header_content_length(struct lws *wsi,
3013 unsigned long content_length,
3014 unsigned char **p, unsigned char *end);
3016 * lws_finalize_http_header() - terminate header block
3018 * \param wsi: the connection to check
3019 * \param p: pointer to current position in buffer pointer
3020 * \param end: pointer to end of buffer
3022 * Indicates no more headers will be added
3024 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
3025 lws_finalize_http_header(struct lws *wsi, unsigned char **p,
3026 unsigned char *end);
3029 /** \defgroup form-parsing Form Parsing
3031 * ##POSTed form parsing functions
3033 * These lws_spa (stateful post arguments) apis let you parse and urldecode
3034 * POSTed form arguments, both using simple urlencoded and multipart transfer
3037 * It's capable of handling file uploads as well a named input parsing,
3038 * and the apis are the same for both form upload styles.
3040 * You feed it a list of parameter names and it creates pointers to the
3041 * urldecoded arguments: file upload parameters pass the file data in chunks to
3042 * a user-supplied callback as they come.
3044 * Since it's stateful, it handles the incoming data needing more than one
3045 * POST_BODY callback and has no limit on uploaded file size.
3049 /** enum lws_spa_fileupload_states */
3050 enum lws_spa_fileupload_states {
3052 /**< a chunk of file content has arrived */
3053 LWS_UFS_FINAL_CONTENT,
3054 /**< the last chunk (possibly zero length) of file content has arrived */
3056 /**< a new file is starting to arrive */
3060 * lws_spa_fileupload_cb() - callback to receive file upload data
3062 * \param data: opt_data pointer set in lws_spa_create
3063 * \param name: name of the form field being uploaded
3064 * \param filename: original filename from client
3065 * \param buf: start of data to receive
3066 * \param len: length of data to receive
3067 * \param state: information about how this call relates to file
3069 * Notice name and filename shouldn't be trusted, as they are passed from
3070 * HTTP provided by the client.
3072 typedef int (*lws_spa_fileupload_cb)(void *data, const char *name,
3073 const char *filename, char *buf, int len,
3074 enum lws_spa_fileupload_states state);
3076 /** struct lws_spa - opaque urldecode parser capable of handling multipart
3077 * and file uploads */
3081 * lws_spa_create() - create urldecode parser
3083 * \param wsi: lws connection (used to find Content Type)
3084 * \param param_names: array of form parameter names, like "username"
3085 * \param count_params: count of param_names
3086 * \param max_storage: total amount of form parameter values we can store
3087 * \param opt_cb: NULL, or callback to receive file upload data.
3088 * \param opt_data: NULL, or user pointer provided to opt_cb.
3090 * Creates a urldecode parser and initializes it.
3092 * opt_cb can be NULL if you just want normal name=value parsing, however
3093 * if one or more entries in your form are bulk data (file transfer), you
3094 * can provide this callback and filter on the name callback parameter to
3095 * treat that urldecoded data separately. The callback should return -1
3096 * in case of fatal error, and 0 if OK.
3098 LWS_VISIBLE LWS_EXTERN struct lws_spa *
3099 lws_spa_create(struct lws *wsi, const char * const *param_names,
3100 int count_params, int max_storage, lws_spa_fileupload_cb opt_cb,
3104 * lws_spa_process() - parses a chunk of input data
3106 * \param spa: the parser object previously created
3107 * \param in: incoming, urlencoded data
3108 * \param len: count of bytes valid at \param in
3110 LWS_VISIBLE LWS_EXTERN int
3111 lws_spa_process(struct lws_spa *spa, const char *in, int len);
3114 * lws_spa_finalize() - indicate incoming data completed
3116 * \param spa: the parser object previously created
3118 LWS_VISIBLE LWS_EXTERN int
3119 lws_spa_finalize(struct lws_spa *spa);
3122 * lws_spa_get_length() - return length of parameter value
3124 * \param spa: the parser object previously created
3125 * \param n: parameter ordinal to return length of value for
3127 LWS_VISIBLE LWS_EXTERN int
3128 lws_spa_get_length(struct lws_spa *spa, int n);
3131 * lws_spa_get_string() - return pointer to parameter value
3132 * \param spa: the parser object previously created
3133 * \param n: parameter ordinal to return pointer to value for
3135 LWS_VISIBLE LWS_EXTERN const char *
3136 lws_spa_get_string(struct lws_spa *spa, int n);
3139 * lws_spa_destroy() - destroy parser object
3141 * \param spa: the parser object previously created
3143 LWS_VISIBLE LWS_EXTERN int
3144 lws_spa_destroy(struct lws_spa *spa);
3147 /*! \defgroup urlendec Urlencode and Urldecode
3150 * ##HTML chunked Substitution
3152 * APIs for receiving chunks of text, replacing a set of variable names via
3153 * a callback, and then prepending and appending HTML chunked encoding
3159 * lws_urlencode() - like strncpy but with urlencoding
3161 * \param escaped: output buffer
3162 * \param string: input buffer ('/0' terminated)
3163 * \param len: output buffer max length
3165 * Because urlencoding expands the output string, it's not
3166 * possible to do it in-place, ie, with escaped == string
3168 LWS_VISIBLE LWS_EXTERN const char *
3169 lws_urlencode(char *escaped, const char *string, int len);
3174 * This simple urldecode only operates until the first '\0' and requires the
3175 * data to exist all at once
3178 * lws_urldecode() - like strncpy but with urldecoding
3180 * \param string: output buffer
3181 * \param escaped: input buffer ('\0' terminated)
3182 * \param len: output buffer max length
3184 * This is only useful for '\0' terminated strings
3186 * Since urldecoding only shrinks the output string, it is possible to
3187 * do it in-place, ie, string == escaped
3189 LWS_VISIBLE LWS_EXTERN int
3190 lws_urldecode(char *string, const char *escaped, int len);
3193 * lws_return_http_status() - Return simple http status
3194 * \param wsi: Websocket instance (available from user callback)
3195 * \param code: Status index, eg, 404
3196 * \param html_body: User-readable HTML description < 1KB, or NULL
3198 * Helper to report HTTP errors back to the client cleanly and
3201 LWS_VISIBLE LWS_EXTERN int
3202 lws_return_http_status(struct lws *wsi, unsigned int code,
3203 const char *html_body);
3206 * lws_http_redirect() - write http redirect into buffer
3208 * \param wsi: websocket connection
3209 * \param code: HTTP response code (eg, 301)
3210 * \param loc: where to redirect to
3211 * \param len: length of loc
3212 * \param p: pointer current position in buffer (updated as we write)
3213 * \param end: pointer to end of buffer
3215 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
3216 lws_http_redirect(struct lws *wsi, int code, const unsigned char *loc, int len,
3217 unsigned char **p, unsigned char *end);
3220 * lws_http_transaction_completed() - wait for new http transaction or close
3221 * \param wsi: websocket connection
3223 * Returns 1 if the HTTP connection must close now
3224 * Returns 0 and resets connection to wait for new HTTP header /
3225 * transaction if possible
3227 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
3228 lws_http_transaction_completed(struct lws *wsi);
3231 /*! \defgroup pur Sanitize / purify SQL and JSON helpers
3233 * ##Sanitize / purify SQL and JSON helpers
3235 * APIs for escaping untrusted JSON and SQL safely before use
3240 * lws_sql_purify() - like strncpy but with escaping for sql quotes
3242 * \param escaped: output buffer
3243 * \param string: input buffer ('/0' terminated)
3244 * \param len: output buffer max length
3246 * Because escaping expands the output string, it's not
3247 * possible to do it in-place, ie, with escaped == string
3249 LWS_VISIBLE LWS_EXTERN const char *
3250 lws_sql_purify(char *escaped, const char *string, int len);
3253 * lws_json_purify() - like strncpy but with escaping for json chars
3255 * \param escaped: output buffer
3256 * \param string: input buffer ('/0' terminated)
3257 * \param len: output buffer max length
3259 * Because escaping expands the output string, it's not
3260 * possible to do it in-place, ie, with escaped == string
3262 LWS_VISIBLE LWS_EXTERN const char *
3263 lws_json_purify(char *escaped, const char *string, int len);
3266 /*! \defgroup ev libev helpers
3270 * APIs specific to libev event loop itegration
3274 #ifdef LWS_USE_LIBEV
3275 typedef void (lws_ev_signal_cb_t)(EV_P_ struct ev_signal *w, int revents);
3277 LWS_VISIBLE LWS_EXTERN int
3278 lws_ev_sigint_cfg(struct lws_context *context, int use_ev_sigint,
3279 lws_ev_signal_cb_t *cb);
3281 LWS_VISIBLE LWS_EXTERN int
3282 lws_ev_initloop(struct lws_context *context, struct ev_loop *loop, int tsi);
3284 LWS_VISIBLE LWS_EXTERN void
3285 lws_ev_sigint_cb(struct ev_loop *loop, struct ev_signal *watcher, int revents);
3286 #endif /* LWS_USE_LIBEV */
3290 /*! \defgroup uv libuv helpers
3294 * APIs specific to libuv event loop itegration
3297 #ifdef LWS_USE_LIBUV
3298 LWS_VISIBLE LWS_EXTERN int
3299 lws_uv_sigint_cfg(struct lws_context *context, int use_uv_sigint,
3302 LWS_VISIBLE LWS_EXTERN void
3303 lws_libuv_run(const struct lws_context *context, int tsi);
3305 LWS_VISIBLE LWS_EXTERN void
3306 lws_libuv_stop(struct lws_context *context);
3308 LWS_VISIBLE LWS_EXTERN void
3309 lws_libuv_stop_without_kill(const struct lws_context *context, int tsi);
3311 LWS_VISIBLE LWS_EXTERN int
3312 lws_uv_initloop(struct lws_context *context, uv_loop_t *loop, int tsi);
3314 LWS_VISIBLE LWS_EXTERN uv_loop_t *
3315 lws_uv_getloop(struct lws_context *context, int tsi);
3317 LWS_VISIBLE LWS_EXTERN void
3318 lws_uv_sigint_cb(uv_signal_t *watcher, int signum);
3319 #endif /* LWS_USE_LIBUV */
3322 /*! \defgroup event libevent helpers
3324 * ##libevent helpers
3326 * APIs specific to libevent event loop itegration
3330 #ifdef LWS_USE_LIBEVENT
3331 typedef void (lws_event_signal_cb_t) (evutil_socket_t sock_fd, short revents,
3334 LWS_VISIBLE LWS_EXTERN int
3335 lws_event_sigint_cfg(struct lws_context *context, int use_event_sigint,
3336 lws_event_signal_cb_t cb);
3338 LWS_VISIBLE LWS_EXTERN int
3339 lws_event_initloop(struct lws_context *context, struct event_base *loop,
3342 LWS_VISIBLE LWS_EXTERN void
3343 lws_event_sigint_cb(evutil_socket_t sock_fd, short revents,
3345 #endif /* LWS_USE_LIBEVENT */
3349 /*! \defgroup timeout Connection timeouts
3351 APIs related to setting connection timeouts
3356 * NOTE: These public enums are part of the abi. If you want to add one,
3357 * add it at where specified so existing users are unaffected.
3359 enum pending_timeout {
3360 NO_PENDING_TIMEOUT = 0,
3361 PENDING_TIMEOUT_AWAITING_PROXY_RESPONSE = 1,
3362 PENDING_TIMEOUT_AWAITING_CONNECT_RESPONSE = 2,
3363 PENDING_TIMEOUT_ESTABLISH_WITH_SERVER = 3,
3364 PENDING_TIMEOUT_AWAITING_SERVER_RESPONSE = 4,
3365 PENDING_TIMEOUT_AWAITING_PING = 5,
3366 PENDING_TIMEOUT_CLOSE_ACK = 6,
3367 PENDING_TIMEOUT_AWAITING_EXTENSION_CONNECT_RESPONSE = 7,
3368 PENDING_TIMEOUT_SENT_CLIENT_HANDSHAKE = 8,
3369 PENDING_TIMEOUT_SSL_ACCEPT = 9,
3370 PENDING_TIMEOUT_HTTP_CONTENT = 10,
3371 PENDING_TIMEOUT_AWAITING_CLIENT_HS_SEND = 11,
3372 PENDING_FLUSH_STORED_SEND_BEFORE_CLOSE = 12,
3373 PENDING_TIMEOUT_SHUTDOWN_FLUSH = 13,
3374 PENDING_TIMEOUT_CGI = 14,
3375 PENDING_TIMEOUT_HTTP_KEEPALIVE_IDLE = 15,
3376 PENDING_TIMEOUT_WS_PONG_CHECK_SEND_PING = 16,
3377 PENDING_TIMEOUT_WS_PONG_CHECK_GET_PONG = 17,
3378 PENDING_TIMEOUT_CLIENT_ISSUE_PAYLOAD = 18,
3380 /****** add new things just above ---^ ******/
3384 * lws_set_timeout() - marks the wsi as subject to a timeout
3386 * You will not need this unless you are doing something special
3388 * \param wsi: Websocket connection instance
3389 * \param reason: timeout reason
3390 * \param secs: how many seconds
3392 LWS_VISIBLE LWS_EXTERN void
3393 lws_set_timeout(struct lws *wsi, enum pending_timeout reason, int secs);
3396 /*! \defgroup sending-data Sending data
3398 APIs related to writing data on a connection
3401 #if !defined(LWS_SIZEOFPTR)
3402 #define LWS_SIZEOFPTR (sizeof (void *))
3404 #if !defined(u_int64_t)
3405 #define u_int64_t unsigned long long
3408 #if defined(__x86_64__)
3409 #define _LWS_PAD_SIZE 16 /* Intel recommended for best performance */
3411 #define _LWS_PAD_SIZE LWS_SIZEOFPTR /* Size of a pointer on the target arch */
3413 #define _LWS_PAD(n) (((n) % _LWS_PAD_SIZE) ? \
3414 ((n) + (_LWS_PAD_SIZE - ((n) % _LWS_PAD_SIZE))) : (n))
3415 #define LWS_PRE _LWS_PAD(4 + 10)
3416 /* used prior to 1.7 and retained for backward compatibility */
3417 #define LWS_SEND_BUFFER_PRE_PADDING LWS_PRE
3418 #define LWS_SEND_BUFFER_POST_PADDING 0
3421 * NOTE: These public enums are part of the abi. If you want to add one,
3422 * add it at where specified so existing users are unaffected.
3424 enum lws_write_protocol {
3426 /**< Send a ws TEXT message,the pointer must have LWS_PRE valid
3427 * memory behind it. The receiver expects only valid utf-8 in the
3429 LWS_WRITE_BINARY = 1,
3430 /**< Send a ws BINARY message, the pointer must have LWS_PRE valid
3431 * memory behind it. Any sequence of bytes is valid */
3432 LWS_WRITE_CONTINUATION = 2,
3433 /**< Continue a previous ws message, the pointer must have LWS_PRE valid
3434 * memory behind it */
3436 /**< Send HTTP content */
3438 /* LWS_WRITE_CLOSE is handled by lws_close_reason() */
3442 /* Same as write_http but we know this write ends the transaction */
3443 LWS_WRITE_HTTP_FINAL = 7,
3447 LWS_WRITE_HTTP_HEADERS = 8,
3448 /**< Send http headers (http2 encodes this payload and LWS_WRITE_HTTP
3449 * payload differently, http 1.x links also handle this correctly. so
3450 * to be compatible with both in the future,header response part should
3451 * be sent using this regardless of http version expected)
3454 /****** add new things just above ---^ ******/
3458 LWS_WRITE_NO_FIN = 0x40,
3459 /**< This part of the message is not the end of the message */
3461 LWS_WRITE_CLIENT_IGNORE_XOR_MASK = 0x80
3462 /**< client packet payload goes out on wire unmunged
3463 * only useful for security tests since normal servers cannot
3464 * decode the content if used */
3469 * lws_write() - Apply protocol then write data to client
3470 * \param wsi: Websocket instance (available from user callback)
3471 * \param buf: The data to send. For data being sent on a websocket
3472 * connection (ie, not default http), this buffer MUST have
3473 * LWS_PRE bytes valid BEFORE the pointer.
3474 * This is so the protocol header data can be added in-situ.
3475 * \param len: Count of the data bytes in the payload starting from buf
3476 * \param protocol: Use LWS_WRITE_HTTP to reply to an http connection, and one
3477 * of LWS_WRITE_BINARY or LWS_WRITE_TEXT to send appropriate
3478 * data on a websockets connection. Remember to allow the extra
3479 * bytes before and after buf if LWS_WRITE_BINARY or LWS_WRITE_TEXT
3482 * This function provides the way to issue data back to the client
3483 * for both http and websocket protocols.
3487 * When sending with websocket protocol
3491 * LWS_WRITE_CONTINUATION,
3495 * the send buffer has to have LWS_PRE bytes valid BEFORE
3496 * the buffer pointer you pass to lws_write().
3498 * This allows us to add protocol info before and after the data, and send as
3499 * one packet on the network without payload copying, for maximum efficiency.
3501 * So for example you need this kind of code to use lws_write with a
3504 * char buf[LWS_PRE + 128];
3506 * // fill your part of the buffer... for example here it's all zeros
3507 * memset(&buf[LWS_PRE], 0, 128);
3509 * lws_write(wsi, &buf[LWS_PRE], 128, LWS_WRITE_TEXT);
3511 * When sending HTTP, with
3514 * LWS_WRITE_HTTP_HEADERS
3515 * LWS_WRITE_HTTP_FINAL
3517 * there is no protocol data prepended, and don't need to take care about the
3518 * LWS_PRE bytes valid before the buffer pointer.
3520 * LWS_PRE is at least the frame nonce + 2 header + 8 length
3521 * LWS_SEND_BUFFER_POST_PADDING is deprecated, it's now 0 and can be left off.
3522 * The example apps no longer use it.
3524 * Pad LWS_PRE to the CPU word size, so that word references
3525 * to the address immediately after the padding won't cause an unaligned access
3526 * error. Sometimes for performance reasons the recommended padding is even
3527 * larger than sizeof(void *).
3529 * In the case of sending using websocket protocol, be sure to allocate
3530 * valid storage before and after buf as explained above. This scheme
3531 * allows maximum efficiency of sending data and protocol in a single
3532 * packet while not burdening the user code with any protocol knowledge.
3534 * Return may be -1 for a fatal error needing connection close, or the
3535 * number of bytes sent.
3540 * The OS may not accept everything you asked to write on the connection.
3542 * Posix defines POLLOUT indication from poll() to show that the connection
3543 * will accept more write data, but it doesn't specifiy how much. It may just
3544 * accept one byte of whatever you wanted to send.
3546 * LWS will buffer the remainder automatically, and send it out autonomously.
3548 * During that time, WRITABLE callbacks will be suppressed.
3550 * This is to handle corner cases where unexpectedly the OS refuses what we
3551 * usually expect it to accept. You should try to send in chunks that are
3552 * almost always accepted in order to avoid the inefficiency of the buffering.
3554 LWS_VISIBLE LWS_EXTERN int
3555 lws_write(struct lws *wsi, unsigned char *buf, size_t len,
3556 enum lws_write_protocol protocol);
3558 /* helper for case where buffer may be const */
3559 #define lws_write_http(wsi, buf, len) \
3560 lws_write(wsi, (unsigned char *)(buf), len, LWS_WRITE_HTTP)
3563 /** \defgroup callback-when-writeable Callback when writeable
3565 * ##Callback When Writeable
3567 * lws can only write data on a connection when it is able to accept more
3568 * data without blocking.
3570 * So a basic requirement is we should only use the lws_write() apis when the
3571 * connection we want to write on says that he can accept more data.
3573 * When lws cannot complete your send at the time, it will buffer the data
3574 * and send it in the background, suppressing any further WRITEABLE callbacks
3575 * on that connection until it completes. So it is important to write new
3576 * things in a new writeable callback.
3578 * These apis reflect the various ways we can indicate we would like to be
3579 * called back when one or more connections is writeable.
3584 * lws_callback_on_writable() - Request a callback when this socket
3585 * becomes able to be written to without
3588 * \param wsi: Websocket connection instance to get callback for
3590 * - Which: only this wsi
3591 * - When: when the individual connection becomes writeable
3592 * - What: LWS_CALLBACK_*_WRITEABLE
3594 LWS_VISIBLE LWS_EXTERN int
3595 lws_callback_on_writable(struct lws *wsi);
3598 * lws_callback_on_writable_all_protocol() - Request a callback for all
3599 * connections on same vhost using the given protocol when it
3600 * becomes possible to write to each socket without
3603 * \param context: lws_context
3604 * \param protocol: Protocol whose connections will get callbacks
3606 * - Which: connections using this protocol on ANY VHOST
3607 * - When: when the individual connection becomes writeable
3608 * - What: LWS_CALLBACK_*_WRITEABLE
3610 LWS_VISIBLE LWS_EXTERN int
3611 lws_callback_on_writable_all_protocol(const struct lws_context *context,
3612 const struct lws_protocols *protocol);
3615 * lws_callback_on_writable_all_protocol_vhost() - Request a callback for
3616 * all connections using the given protocol when it
3617 * becomes possible to write to each socket without
3620 * \param vhost: Only consider connections on this lws_vhost
3621 * \param protocol: Protocol whose connections will get callbacks
3623 * - Which: connections using this protocol on GIVEN VHOST ONLY
3624 * - When: when the individual connection becomes writeable
3625 * - What: LWS_CALLBACK_*_WRITEABLE
3627 LWS_VISIBLE LWS_EXTERN int
3628 lws_callback_on_writable_all_protocol_vhost(const struct lws_vhost *vhost,
3629 const struct lws_protocols *protocol);
3632 * lws_callback_all_protocol() - Callback all connections using
3633 * the given protocol with the given reason
3635 * \param context: lws_context
3636 * \param protocol: Protocol whose connections will get callbacks
3637 * \param reason: Callback reason index
3639 * - Which: connections using this protocol on ALL VHOSTS
3640 * - When: before returning
3643 * This isn't normally what you want... normally any update of connection-
3644 * specific information can wait until a network-related callback like rx,
3645 * writable, or close.
3647 LWS_VISIBLE LWS_EXTERN int
3648 lws_callback_all_protocol(struct lws_context *context,
3649 const struct lws_protocols *protocol, int reason);
3652 * lws_callback_all_protocol_vhost() - Callback all connections using
3653 * the given protocol with the given reason
3655 * \param vh: Vhost whose connections will get callbacks
3656 * \param protocol: Which protocol to match
3657 * \param reason: Callback reason index
3659 * - Which: connections using this protocol on GIVEN VHOST ONLY
3663 LWS_VISIBLE LWS_EXTERN int
3664 lws_callback_all_protocol_vhost(struct lws_vhost *vh,
3665 const struct lws_protocols *protocol, int reason);
3668 * lws_callback_vhost_protocols() - Callback all protocols enabled on a vhost
3669 * with the given reason
3671 * \param wsi: wsi whose vhost will get callbacks
3672 * \param reason: Callback reason index
3673 * \param in: in argument to callback
3674 * \param len: len argument to callback
3676 * - Which: connections using this protocol on same VHOST as wsi ONLY
3680 LWS_VISIBLE LWS_EXTERN int
3681 lws_callback_vhost_protocols(struct lws *wsi, int reason, void *in, int len);
3683 LWS_VISIBLE LWS_EXTERN int
3684 lws_callback_http_dummy(struct lws *wsi, enum lws_callback_reasons reason,
3685 void *user, void *in, size_t len);
3688 * lws_get_socket_fd() - returns the socket file descriptor
3690 * You will not need this unless you are doing something special
3692 * \param wsi: Websocket connection instance
3694 LWS_VISIBLE LWS_EXTERN int
3695 lws_get_socket_fd(struct lws *wsi);
3698 * lws_get_peer_write_allowance() - get the amount of data writeable to peer
3701 * \param wsi: Websocket connection instance
3703 * if the protocol does not have any guidance, returns -1. Currently only
3704 * http2 connections get send window information from this API. But your code
3705 * should use it so it can work properly with any protocol.
3707 * If nonzero return is the amount of payload data the peer or intermediary has
3708 * reported it has buffer space for. That has NO relationship with the amount
3709 * of buffer space your OS can accept on this connection for a write action.
3711 * This number represents the maximum you could send to the peer or intermediary
3712 * on this connection right now without the protocol complaining.
3714 * lws manages accounting for send window updates and payload writes
3715 * automatically, so this number reflects the situation at the peer or
3716 * intermediary dynamically.
3718 LWS_VISIBLE LWS_EXTERN size_t
3719 lws_get_peer_write_allowance(struct lws *wsi);
3723 * lws_rx_flow_control() - Enable and disable socket servicing for
3726 * If the output side of a server process becomes choked, this allows flow
3727 * control for the input side.
3729 * \param wsi: Websocket connection instance to get callback for
3730 * \param enable: 0 = disable read servicing for this connection, 1 = enable
3732 LWS_VISIBLE LWS_EXTERN int
3733 lws_rx_flow_control(struct lws *wsi, int enable);
3736 * lws_rx_flow_allow_all_protocol() - Allow all connections with this protocol to receive
3738 * When the user server code realizes it can accept more input, it can
3739 * call this to have the RX flow restriction removed from all connections using
3740 * the given protocol.
3741 * \param context: lws_context
3742 * \param protocol: all connections using this protocol will be allowed to receive
3744 LWS_VISIBLE LWS_EXTERN void
3745 lws_rx_flow_allow_all_protocol(const struct lws_context *context,
3746 const struct lws_protocols *protocol);
3749 * lws_remaining_packet_payload() - Bytes to come before "overall"
3750 * rx packet is complete
3751 * \param wsi: Websocket instance (available from user callback)
3753 * This function is intended to be called from the callback if the
3754 * user code is interested in "complete packets" from the client.
3755 * libwebsockets just passes through payload as it comes and issues a buffer
3756 * additionally when it hits a built-in limit. The LWS_CALLBACK_RECEIVE
3757 * callback handler can use this API to find out if the buffer it has just
3758 * been given is the last piece of a "complete packet" from the client --
3759 * when that is the case lws_remaining_packet_payload() will return
3762 * Many protocols won't care becuse their packets are always small.
3764 LWS_VISIBLE LWS_EXTERN size_t
3765 lws_remaining_packet_payload(struct lws *wsi);
3768 /** \defgroup sock-adopt Socket adoption helpers
3769 * ##Socket adoption helpers
3771 * When integrating with an external app with its own event loop, these can
3772 * be used to accept connections from someone else's listening socket.
3774 * When using lws own event loop, these are not needed.
3779 * lws_adopt_socket() - adopt foreign socket as if listen socket accepted it
3780 * for the default vhost of context.
3781 * \param context: lws context
3782 * \param accept_fd: fd of already-accepted socket to adopt
3784 * Either returns new wsi bound to accept_fd, or closes accept_fd and
3785 * returns NULL, having cleaned up any new wsi pieces.
3787 * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
3788 * to ws or just serve http.
3790 LWS_VISIBLE LWS_EXTERN struct lws *
3791 lws_adopt_socket(struct lws_context *context, lws_sockfd_type accept_fd);
3793 * lws_adopt_socket_vhost() - adopt foreign socket as if listen socket accepted it
3795 * \param vhost: lws vhost
3796 * \param accept_fd: fd of already-accepted socket to adopt
3798 * Either returns new wsi bound to accept_fd, or closes accept_fd and
3799 * returns NULL, having cleaned up any new wsi pieces.
3801 * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
3802 * to ws or just serve http.
3804 LWS_VISIBLE LWS_EXTERN struct lws *
3805 lws_adopt_socket_vhost(struct lws_vhost *vh, lws_sockfd_type accept_fd);
3808 LWS_ADOPT_RAW_FILE_DESC = 0, /* convenience constant */
3809 LWS_ADOPT_HTTP = 1, /* flag: absent implies RAW */
3810 LWS_ADOPT_SOCKET = 2, /* flag: absent implies file descr */
3811 LWS_ADOPT_ALLOW_SSL = 4 /* flag: if set requires LWS_ADOPT_SOCKET */
3812 } lws_adoption_type;
3815 lws_sockfd_type sockfd;
3816 lws_filefd_type filefd;
3817 } lws_sock_file_fd_type;
3820 * lws_adopt_descriptor_vhost() - adopt foreign socket or file descriptor
3821 * if socket descriptor, should already have been accepted from listen socket
3823 * \param vhost: lws vhost
3824 * \param type: OR-ed combinations of lws_adoption_type flags
3825 * \param fd: union with either .sockfd or .filefd set
3826 * \param vh_prot_name: NULL or vh protocol name to bind raw connection to
3827 * \param parent: NULL or struct lws to attach new_wsi to as a child
3829 * Either returns new wsi bound to accept_fd, or closes accept_fd and
3830 * returns NULL, having cleaned up any new wsi pieces.
3832 * If LWS_ADOPT_SOCKET is set, LWS adopts the socket in http serving mode, it's
3833 * ready to accept an upgrade to ws or just serve http.
3835 * parent may be NULL, if given it should be an existing wsi that will become the
3836 * parent of the new wsi created by this call.
3838 LWS_VISIBLE struct lws *
3839 lws_adopt_descriptor_vhost(struct lws_vhost *vh, lws_adoption_type type,
3840 lws_sock_file_fd_type fd, const char *vh_prot_name,
3841 struct lws *parent);
3844 * lws_adopt_socket_readbuf() - adopt foreign socket and first rx as if listen socket accepted it
3845 * for the default vhost of context.
3846 * \param context: lws context
3847 * \param accept_fd: fd of already-accepted socket to adopt
3848 * \param readbuf: NULL or pointer to data that must be drained before reading from
3850 * \param len: The length of the data held at \param readbuf
3852 * Either returns new wsi bound to accept_fd, or closes accept_fd and
3853 * returns NULL, having cleaned up any new wsi pieces.
3855 * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
3856 * to ws or just serve http.
3858 * If your external code did not already read from the socket, you can use
3859 * lws_adopt_socket() instead.
3861 * This api is guaranteed to use the data at \param readbuf first, before reading from
3864 * readbuf is limited to the size of the ah rx buf, currently 2048 bytes.
3866 LWS_VISIBLE LWS_EXTERN struct lws *
3867 lws_adopt_socket_readbuf(struct lws_context *context, lws_sockfd_type accept_fd,
3868 const char *readbuf, size_t len);
3870 * lws_adopt_socket_vhost_readbuf() - adopt foreign socket and first rx as if listen socket
3871 * accepted it for vhost.
3872 * \param vhost: lws vhost
3873 * \param accept_fd: fd of already-accepted socket to adopt
3874 * \param readbuf: NULL or pointer to data that must be drained before reading from
3876 * \param len: The length of the data held at \param readbuf
3878 * Either returns new wsi bound to accept_fd, or closes accept_fd and
3879 * returns NULL, having cleaned up any new wsi pieces.
3881 * LWS adopts the socket in http serving mode, it's ready to accept an upgrade
3882 * to ws or just serve http.
3884 * If your external code did not already read from the socket, you can use
3885 * lws_adopt_socket() instead.
3887 * This api is guaranteed to use the data at \param readbuf first, before reading from
3890 * readbuf is limited to the size of the ah rx buf, currently 2048 bytes.
3892 LWS_VISIBLE LWS_EXTERN struct lws *
3893 lws_adopt_socket_vhost_readbuf(struct lws_vhost *vhost, lws_sockfd_type accept_fd,
3894 const char *readbuf, size_t len);
3897 /** \defgroup net Network related helper APIs
3898 * ##Network related helper APIs
3900 * These wrap miscellaneous useful network-related functions
3905 * lws_canonical_hostname() - returns this host's hostname
3907 * This is typically used by client code to fill in the host parameter
3908 * when making a client connection. You can only call it after the context
3911 * \param context: Websocket context
3913 LWS_VISIBLE LWS_EXTERN const char * LWS_WARN_UNUSED_RESULT
3914 lws_canonical_hostname(struct lws_context *context);
3917 * lws_get_peer_addresses() - Get client address information
3918 * \param wsi: Local struct lws associated with
3919 * \param fd: Connection socket descriptor
3920 * \param name: Buffer to take client address name
3921 * \param name_len: Length of client address name buffer
3922 * \param rip: Buffer to take client address IP dotted quad
3923 * \param rip_len: Length of client address IP buffer
3925 * This function fills in name and rip with the name and IP of
3926 * the client connected with socket descriptor fd. Names may be
3927 * truncated if there is not enough room. If either cannot be
3928 * determined, they will be returned as valid zero-length strings.
3930 LWS_VISIBLE LWS_EXTERN void
3931 lws_get_peer_addresses(struct lws *wsi, lws_sockfd_type fd, char *name,
3932 int name_len, char *rip, int rip_len);
3935 * lws_get_peer_simple() - Get client address information without RDNS
3937 * \param wsi: Local struct lws associated with
3938 * \param name: Buffer to take client address name
3939 * \param namelen: Length of client address name buffer
3941 * This provides a 123.123.123.123 type IP address in name from the
3942 * peer that has connected to wsi
3944 LWS_VISIBLE LWS_EXTERN const char *
3945 lws_get_peer_simple(struct lws *wsi, char *name, int namelen);
3946 #if !defined(LWS_WITH_ESP8266) && !defined(LWS_WITH_ESP32)
3948 * lws_interface_to_sa() - Convert interface name or IP to sockaddr struct
3950 * \param ipv6: Allow IPV6 addresses
3951 * \param ifname: Interface name or IP
3952 * \param addr: struct sockaddr_in * to be written
3953 * \param addrlen: Length of addr
3955 * This converts a textual network interface name to a sockaddr usable by
3956 * other network functions
3958 LWS_VISIBLE LWS_EXTERN int
3959 lws_interface_to_sa(int ipv6, const char *ifname, struct sockaddr_in *addr,
3964 /** \defgroup misc Miscellaneous APIs
3965 * ##Miscellaneous APIs
3967 * Various APIs outside of other categories
3972 * lws_snprintf(): snprintf that truncates the returned length too
3974 * \param str: destination buffer
3975 * \param size: bytes left in destination buffer
3976 * \param format: format string
3977 * \param ...: args for format
3979 * This lets you correctly truncate buffers by concatenating lengths, if you
3980 * reach the limit the reported length doesn't exceed the limit.
3982 LWS_VISIBLE LWS_EXTERN int
3983 lws_snprintf(char *str, size_t size, const char *format, ...) LWS_FORMAT(3);
3986 * lws_get_random(): fill a buffer with platform random data
3988 * \param context: the lws context
3989 * \param buf: buffer to fill
3990 * \param len: how much to fill
3992 * This is intended to be called from the LWS_CALLBACK_RECEIVE callback if
3993 * it's interested to see if the frame it's dealing with was sent in binary
3996 LWS_VISIBLE LWS_EXTERN int
3997 lws_get_random(struct lws_context *context, void *buf, int len);
3999 * lws_daemonize(): make current process run in the background
4001 * \param _lock_path: the filepath to write the lock file
4003 * Spawn lws as a background process, taking care of various things
4005 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
4006 lws_daemonize(const char *_lock_path);
4008 * lws_get_library_version(): return string describing the version of lws
4010 * On unix, also includes the git describe
4012 LWS_VISIBLE LWS_EXTERN const char * LWS_WARN_UNUSED_RESULT
4013 lws_get_library_version(void);
4016 * lws_wsi_user() - get the user data associated with the connection
4017 * \param wsi: lws connection
4019 * Not normally needed since it's passed into the callback
4021 LWS_VISIBLE LWS_EXTERN void *
4022 lws_wsi_user(struct lws *wsi);
4025 * lws_wsi_set_user() - set the user data associated with the client connection
4026 * \param wsi: lws connection
4027 * \param user: user data
4029 * By default lws allocates this and it's not legal to externally set it
4030 * yourself. However client connections may have it set externally when the
4031 * connection is created... if so, this api can be used to modify it at
4032 * runtime additionally.
4034 LWS_VISIBLE LWS_EXTERN void
4035 lws_set_wsi_user(struct lws *wsi, void *user);
4038 * lws_parse_uri: cut up prot:/ads:port/path into pieces
4039 * Notice it does so by dropping '\0' into input string
4040 * and the leading / on the path is consequently lost
4042 * \param p: incoming uri string.. will get written to
4043 * \param prot: result pointer for protocol part (https://)
4044 * \param ads: result pointer for address part
4045 * \param port: result pointer for port part
4046 * \param path: result pointer for path part
4048 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
4049 lws_parse_uri(char *p, const char **prot, const char **ads, int *port,
4053 * lws_now_secs(): return seconds since 1970-1-1
4055 LWS_VISIBLE LWS_EXTERN unsigned long
4059 * lws_get_context - Allow geting lws_context from a Websocket connection
4062 * With this function, users can access context in the callback function.
4063 * Otherwise users may have to declare context as a global variable.
4065 * \param wsi: Websocket connection instance
4067 LWS_VISIBLE LWS_EXTERN struct lws_context * LWS_WARN_UNUSED_RESULT
4068 lws_get_context(const struct lws *wsi);
4071 * lws_get_count_threads(): how many service threads the context uses
4073 * \param context: the lws context
4075 * By default this is always 1, if you asked for more than lws can handle it
4076 * will clip the number of threads. So you can use this to find out how many
4077 * threads are actually in use.
4079 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
4080 lws_get_count_threads(struct lws_context *context);
4083 * lws_get_parent() - get parent wsi or NULL
4084 * \param wsi: lws connection
4086 * Specialized wsi like cgi stdin/out/err are associated to a parent wsi,
4087 * this allows you to get their parent.
4089 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
4090 lws_get_parent(const struct lws *wsi);
4093 * lws_get_child() - get child wsi or NULL
4094 * \param wsi: lws connection
4096 * Allows you to find a related wsi from the parent wsi.
4098 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
4099 lws_get_child(const struct lws *wsi);
4103 * \deprecated DEPRECATED Note: this is not normally needed as a user api.
4104 * It's provided in case it is
4105 * useful when integrating with other app poll loop service code.
4107 LWS_VISIBLE LWS_EXTERN int
4108 lws_read(struct lws *wsi, unsigned char *buf, size_t len);
4111 * lws_set_allocator() - custom allocator support
4115 * Allows you to replace the allocator (and deallocator) used by lws
4117 LWS_VISIBLE LWS_EXTERN void
4118 lws_set_allocator(void *(*realloc)(void *ptr, size_t size));
4121 /** \defgroup wsstatus Websocket status APIs
4122 * ##Websocket connection status APIs
4124 * These provide information about ws connection or message status
4128 * lws_send_pipe_choked() - tests if socket is writable or not
4129 * \param wsi: lws connection
4131 * Allows you to check if you can write more on the socket
4133 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
4134 lws_send_pipe_choked(struct lws *wsi);
4137 * lws_is_final_fragment() - tests if last part of ws message
4138 * \param wsi: lws connection
4140 LWS_VISIBLE LWS_EXTERN int
4141 lws_is_final_fragment(struct lws *wsi);
4144 * lws_get_reserved_bits() - access reserved bits of ws frame
4145 * \param wsi: lws connection
4147 LWS_VISIBLE LWS_EXTERN unsigned char
4148 lws_get_reserved_bits(struct lws *wsi);
4151 * lws_partial_buffered() - find out if lws buffered the last write
4152 * \param wsi: websocket connection to check
4154 * Returns 1 if you cannot use lws_write because the last
4155 * write on this connection is still buffered, and can't be cleared without
4156 * returning to the service loop and waiting for the connection to be
4159 * If you will try to do >1 lws_write call inside a single
4160 * WRITEABLE callback, you must check this after every write and bail if
4161 * set, ask for a new writeable callback and continue writing from there.
4163 * This is never set at the start of a writeable callback, but any write
4166 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
4167 lws_partial_buffered(struct lws *wsi);
4170 * lws_frame_is_binary(): true if the current frame was sent in binary mode
4172 * \param wsi: the connection we are inquiring about
4174 * This is intended to be called from the LWS_CALLBACK_RECEIVE callback if
4175 * it's interested to see if the frame it's dealing with was sent in binary
4178 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
4179 lws_frame_is_binary(struct lws *wsi);
4182 * lws_is_ssl() - Find out if connection is using SSL
4183 * \param wsi: websocket connection to check
4185 * Returns 0 if the connection is not using SSL, 1 if using SSL and
4186 * using verified cert, and 2 if using SSL but the cert was not
4187 * checked (appears for client wsi told to skip check on connection)
4189 LWS_VISIBLE LWS_EXTERN int
4190 lws_is_ssl(struct lws *wsi);
4192 * lws_is_cgi() - find out if this wsi is running a cgi process
4193 * \param wsi: lws connection
4195 LWS_VISIBLE LWS_EXTERN int
4196 lws_is_cgi(struct lws *wsi);
4198 #ifdef LWS_OPENSSL_SUPPORT
4200 * lws_get_ssl() - Return wsi's SSL context structure
4201 * \param wsi: websocket connection
4203 * Returns pointer to the SSL library's context structure
4205 LWS_VISIBLE LWS_EXTERN SSL*
4206 lws_get_ssl(struct lws *wsi);
4211 /** \defgroup sha SHA and B64 helpers
4212 * ##SHA and B64 helpers
4214 * These provide SHA-1 and B64 helper apis
4217 #ifdef LWS_SHA1_USE_OPENSSL_NAME
4218 #define lws_SHA1 SHA1
4221 * lws_SHA1(): make a SHA-1 digest of a buffer
4223 * \param d: incoming buffer
4224 * \param n: length of incoming buffer
4225 * \param md: buffer for message digest (must be >= 20 bytes)
4227 * Reduces any size buffer into a 20-byte SHA-1 hash.
4229 LWS_VISIBLE LWS_EXTERN unsigned char *
4230 lws_SHA1(const unsigned char *d, size_t n, unsigned char *md);
4233 * lws_b64_encode_string(): encode a string into base 64
4235 * \param in: incoming buffer
4236 * \param in_len: length of incoming buffer
4237 * \param out: result buffer
4238 * \param out_size: length of result buffer
4240 * Encodes a string using b64
4242 LWS_VISIBLE LWS_EXTERN int
4243 lws_b64_encode_string(const char *in, int in_len, char *out, int out_size);
4245 * lws_b64_decode_string(): decode a string from base 64
4247 * \param in: incoming buffer
4248 * \param out: result buffer
4249 * \param out_size: length of result buffer
4251 * Decodes a string using b64
4253 LWS_VISIBLE LWS_EXTERN int
4254 lws_b64_decode_string(const char *in, char *out, int out_size);
4258 /*! \defgroup cgi cgi handling
4262 * These functions allow low-level control over stdin/out/err of the cgi.
4264 * However for most cases, binding the cgi to http in and out, the default
4265 * lws implementation already does the right thing.
4268 enum lws_enum_stdinouterr {
4274 enum lws_cgi_hdr_state {
4284 struct lws_cgi_args {
4285 struct lws **stdwsi; /**< get fd with lws_get_socket_fd() */
4286 enum lws_enum_stdinouterr ch; /**< channel index */
4287 unsigned char *data; /**< for messages with payload */
4288 enum lws_cgi_hdr_state hdr_state; /**< track where we are in cgi headers */
4289 int len; /**< length */
4294 * lws_cgi: spawn network-connected cgi process
4296 * \param wsi: connection to own the process
4297 * \param exec_array: array of "exec-name" "arg1" ... "argn" NULL
4298 * \param script_uri_path_len: how many chars on the left of the uri are the path to the cgi
4299 * \param timeout_secs: seconds script should be allowed to run
4300 * \param mp_cgienv: pvo list with per-vhost cgi options to put in env
4302 LWS_VISIBLE LWS_EXTERN int
4303 lws_cgi(struct lws *wsi, const char * const *exec_array,
4304 int script_uri_path_len, int timeout_secs,
4305 const struct lws_protocol_vhost_options *mp_cgienv);
4308 * lws_cgi_write_split_stdout_headers: write cgi output accounting for header part
4310 * \param wsi: connection to own the process
4312 LWS_VISIBLE LWS_EXTERN int
4313 lws_cgi_write_split_stdout_headers(struct lws *wsi);
4316 * lws_cgi_kill: terminate cgi process associated with wsi
4318 * \param wsi: connection to own the process
4320 LWS_VISIBLE LWS_EXTERN int
4321 lws_cgi_kill(struct lws *wsi);
4326 /*! \defgroup fops file operation wrapping
4328 * ##File operation wrapping
4330 * Use these helper functions if you want to access a file from the perspective
4331 * of a specific wsi, which is usually the case. If you just want contextless
4332 * file access, use the fops callbacks directly with NULL wsi instead of these
4335 * If so, then it calls the platform handler or user overrides where present
4336 * (as defined in info->fops)
4338 * The advantage from all this is user code can be portable for file operations
4339 * without having to deal with differences between platforms.
4343 /** struct lws_plat_file_ops - Platform-specific file operations
4345 * These provide platform-agnostic ways to deal with filesystem access in the
4346 * library and in the user code.
4349 #if defined(LWS_WITH_ESP32)
4350 /* sdk preprocessor defs? compiler issue? gets confused with member names */
4351 #define LWS_FOP_OPEN _open
4352 #define LWS_FOP_CLOSE _close
4353 #define LWS_FOP_SEEK_CUR _seek_cur
4354 #define LWS_FOP_READ _read
4355 #define LWS_FOP_WRITE _write
4357 #define LWS_FOP_OPEN open
4358 #define LWS_FOP_CLOSE close
4359 #define LWS_FOP_SEEK_CUR seek_cur
4360 #define LWS_FOP_READ read
4361 #define LWS_FOP_WRITE write
4364 #define LWS_FOP_FLAGS_MASK ((1 << 23) - 1)
4365 #define LWS_FOP_FLAG_COMPR_ACCEPTABLE_GZIP (1 << 24)
4366 #define LWS_FOP_FLAG_COMPR_IS_GZIP (1 << 25)
4367 #define LWS_FOP_FLAG_MOD_TIME_VALID (1 << 26)
4368 #define LWS_FOP_FLAG_VIRTUAL (1 << 27)
4370 struct lws_plat_file_ops;
4372 #if defined(WIN32) || defined(_WIN32)
4374 #if !defined(ssize_t)
4375 typedef SSIZE_T ssize_t;
4379 #if defined(LWS_HAVE_STDINT_H)
4382 #if defined(WIN32) || defined(_WIN32)
4384 typedef unsigned __int32 uint32_t;
4385 typedef unsigned __int16 uint16_t;
4386 typedef unsigned __int8 uint8_t;
4388 typedef unsigned int uint32_t;
4389 typedef unsigned short uint16_t;
4390 typedef unsigned char uint8_t;
4394 typedef size_t lws_filepos_t;
4395 typedef ssize_t lws_fileofs_t;
4396 typedef uint32_t lws_fop_flags_t;
4400 /**< real file descriptor related to the file... */
4401 const struct lws_plat_file_ops *fops;
4402 /**< fops that apply to this fop_fd */
4403 void *filesystem_priv;
4404 /**< ignored by lws; owned by the fops handlers */
4406 /**< generic "position in file" */
4408 /**< generic "length of file" */
4409 lws_fop_flags_t flags;
4410 /**< copy of the returned flags */
4412 /**< optional "modification time of file", only valid if .open()
4413 * set the LWS_FOP_FLAG_MOD_TIME_VALID flag */
4415 typedef struct lws_fop_fd *lws_fop_fd_t;
4417 struct lws_fops_index {
4418 const char *sig; /* NULL or vfs signature, eg, ".zip/" */
4419 uint8_t len; /* length of above string */
4422 struct lws_plat_file_ops {
4423 lws_fop_fd_t (*LWS_FOP_OPEN)(const struct lws_plat_file_ops *fops,
4424 const char *filename, const char *vpath,
4425 lws_fop_flags_t *flags);
4426 /**< Open file (always binary access if plat supports it)
4427 * vpath may be NULL, or if the fops understands it, the point at which
4428 * the filename's virtual part starts.
4429 * *flags & LWS_FOP_FLAGS_MASK should be set to O_RDONLY or O_RDWR.
4430 * If the file may be gzip-compressed,
4431 * LWS_FOP_FLAG_COMPR_ACCEPTABLE_GZIP is set. If it actually is
4432 * gzip-compressed, then the open handler should OR
4433 * LWS_FOP_FLAG_COMPR_IS_GZIP on to *flags before returning.
4435 int (*LWS_FOP_CLOSE)(lws_fop_fd_t *fop_fd);
4436 /**< close file AND set the pointer to NULL */
4437 lws_fileofs_t (*LWS_FOP_SEEK_CUR)(lws_fop_fd_t fop_fd,
4438 lws_fileofs_t offset_from_cur_pos);
4439 /**< seek from current position */
4440 int (*LWS_FOP_READ)(lws_fop_fd_t fop_fd, lws_filepos_t *amount,
4441 uint8_t *buf, lws_filepos_t len);
4442 /**< Read from file, on exit *amount is set to amount actually read */
4443 int (*LWS_FOP_WRITE)(lws_fop_fd_t fop_fd, lws_filepos_t *amount,
4444 uint8_t *buf, lws_filepos_t len);
4445 /**< Write to file, on exit *amount is set to amount actually written */
4447 struct lws_fops_index fi[3];
4448 /**< vfs path signatures implying use of this fops */
4450 const struct lws_plat_file_ops *next;
4451 /**< NULL or next fops in list */
4453 /* Add new things just above here ---^
4454 * This is part of the ABI, don't needlessly break compatibility */
4458 * lws_get_fops() - get current file ops
4460 * \param context: context
4462 LWS_VISIBLE LWS_EXTERN struct lws_plat_file_ops * LWS_WARN_UNUSED_RESULT
4463 lws_get_fops(struct lws_context *context);
4464 LWS_VISIBLE LWS_EXTERN void
4465 lws_set_fops(struct lws_context *context, const struct lws_plat_file_ops *fops);
4467 * lws_vfs_tell() - get current file position
4469 * \param fop_fd: fop_fd we are asking about
4471 LWS_VISIBLE LWS_EXTERN lws_filepos_t LWS_WARN_UNUSED_RESULT
4472 lws_vfs_tell(lws_fop_fd_t fop_fd);
4474 * lws_vfs_get_length() - get current file total length in bytes
4476 * \param fop_fd: fop_fd we are asking about
4478 LWS_VISIBLE LWS_EXTERN lws_filepos_t LWS_WARN_UNUSED_RESULT
4479 lws_vfs_get_length(lws_fop_fd_t fop_fd);
4481 * lws_vfs_get_mod_time() - get time file last modified
4483 * \param fop_fd: fop_fd we are asking about
4485 LWS_VISIBLE LWS_EXTERN uint32_t LWS_WARN_UNUSED_RESULT
4486 lws_vfs_get_mod_time(lws_fop_fd_t fop_fd);
4488 * lws_vfs_file_seek_set() - seek relative to start of file
4490 * \param fop_fd: fop_fd we are seeking in
4491 * \param offset: offset from start of file
4493 LWS_VISIBLE LWS_EXTERN lws_fileofs_t
4494 lws_vfs_file_seek_set(lws_fop_fd_t fop_fd, lws_fileofs_t offset);
4496 * lws_vfs_file_seek_end() - seek relative to end of file
4498 * \param fop_fd: fop_fd we are seeking in
4499 * \param offset: offset from start of file
4501 LWS_VISIBLE LWS_EXTERN lws_fileofs_t
4502 lws_vfs_file_seek_end(lws_fop_fd_t fop_fd, lws_fileofs_t offset);
4504 extern struct lws_plat_file_ops fops_zip;
4507 * lws_plat_file_open() - open vfs filepath
4509 * \param fops: file ops struct that applies to this descriptor
4510 * \param vfs_path: filename to open
4511 * \param flags: pointer to open flags
4513 * The vfs_path is scanned for known fops signatures, and the open directed
4514 * to any matching fops open.
4516 * User code should use this api to perform vfs opens.
4518 * returns semi-opaque handle
4520 LWS_VISIBLE LWS_EXTERN lws_fop_fd_t LWS_WARN_UNUSED_RESULT
4521 lws_vfs_file_open(const struct lws_plat_file_ops *fops, const char *vfs_path,
4522 lws_fop_flags_t *flags);
4525 * lws_plat_file_close() - close file
4527 * \param fop_fd: file handle to close
4529 static LWS_INLINE int
4530 lws_vfs_file_close(lws_fop_fd_t *fop_fd)
4532 return (*fop_fd)->fops->LWS_FOP_CLOSE(fop_fd);
4536 * lws_plat_file_seek_cur() - close file
4539 * \param fop_fd: file handle
4540 * \param offset: position to seek to
4542 static LWS_INLINE lws_fileofs_t
4543 lws_vfs_file_seek_cur(lws_fop_fd_t fop_fd, lws_fileofs_t offset)
4545 return fop_fd->fops->LWS_FOP_SEEK_CUR(fop_fd, offset);
4548 * lws_plat_file_read() - read from file
4550 * \param fop_fd: file handle
4551 * \param amount: how much to read (rewritten by call)
4552 * \param buf: buffer to write to
4553 * \param len: max length
4555 static LWS_INLINE int LWS_WARN_UNUSED_RESULT
4556 lws_vfs_file_read(lws_fop_fd_t fop_fd, lws_filepos_t *amount,
4557 uint8_t *buf, lws_filepos_t len)
4559 return fop_fd->fops->LWS_FOP_READ(fop_fd, amount, buf, len);
4562 * lws_plat_file_write() - write from file
4564 * \param fop_fd: file handle
4565 * \param amount: how much to write (rewritten by call)
4566 * \param buf: buffer to read from
4567 * \param len: max length
4569 static LWS_INLINE int LWS_WARN_UNUSED_RESULT
4570 lws_vfs_file_write(lws_fop_fd_t fop_fd, lws_filepos_t *amount,
4571 uint8_t *buf, lws_filepos_t len)
4573 return fop_fd->fops->LWS_FOP_WRITE(fop_fd, amount, buf, len);
4576 /* these are the platform file operations implementations... they can
4577 * be called directly and used in fops arrays
4580 LWS_VISIBLE LWS_EXTERN lws_fop_fd_t
4581 _lws_plat_file_open(const struct lws_plat_file_ops *fops, const char *filename,
4582 const char *vpath, lws_fop_flags_t *flags);
4583 LWS_VISIBLE LWS_EXTERN int
4584 _lws_plat_file_close(lws_fop_fd_t *fop_fd);
4585 LWS_VISIBLE LWS_EXTERN lws_fileofs_t
4586 _lws_plat_file_seek_cur(lws_fop_fd_t fop_fd, lws_fileofs_t offset);
4587 LWS_VISIBLE LWS_EXTERN int
4588 _lws_plat_file_read(lws_fop_fd_t fop_fd, lws_filepos_t *amount,
4589 uint8_t *buf, lws_filepos_t len);
4590 LWS_VISIBLE LWS_EXTERN int
4591 _lws_plat_file_write(lws_fop_fd_t fop_fd, lws_filepos_t *amount,
4592 uint8_t *buf, lws_filepos_t len);
4598 * ##SMTP related functions
4600 * These apis let you communicate with a local SMTP server to send email from
4601 * lws. It handles all the SMTP sequencing and protocol actions.
4603 * Your system should have postfix, sendmail or another MTA listening on port
4604 * 25 and able to send email using the "mail" commandline app. Usually distro
4605 * MTAs are configured for this by default.
4607 * It runs via its own libuv events if initialized (which requires giving it
4608 * a libuv loop to attach to).
4610 * It operates using three callbacks, on_next() queries if there is a new email
4611 * to send, on_get_body() asks for the body of the email, and on_sent() is
4612 * called after the email is successfully sent.
4616 * - create an lws_email struct
4618 * - initialize data, loop, the email_* strings, max_content_size and
4621 * - call lws_email_init()
4623 * When you have at least one email to send, call lws_email_check() to
4624 * schedule starting to send it.
4627 #ifdef LWS_WITH_SMTP
4629 /** enum lwsgs_smtp_states - where we are in SMTP protocol sequence */
4630 enum lwsgs_smtp_states {
4631 LGSSMTP_IDLE, /**< awaiting new email */
4632 LGSSMTP_CONNECTING, /**< opening tcp connection to MTA */
4633 LGSSMTP_CONNECTED, /**< tcp connection to MTA is connected */
4634 LGSSMTP_SENT_HELO, /**< sent the HELO */
4635 LGSSMTP_SENT_FROM, /**< sent FROM */
4636 LGSSMTP_SENT_TO, /**< sent TO */
4637 LGSSMTP_SENT_DATA, /**< sent DATA request */
4638 LGSSMTP_SENT_BODY, /**< sent the email body */
4639 LGSSMTP_SENT_QUIT, /**< sent the session quit */
4642 /** struct lws_email - abstract context for performing SMTP operations */
4645 /**< opaque pointer set by user code and available to the callbacks */
4647 /**< the libuv loop we will work on */
4649 char email_smtp_ip[32]; /**< Fill before init, eg, "127.0.0.1" */
4650 char email_helo[32]; /**< Fill before init, eg, "myserver.com" */
4651 char email_from[100]; /**< Fill before init or on_next */
4652 char email_to[100]; /**< Fill before init or on_next */
4654 unsigned int max_content_size;
4655 /**< largest possible email body size */
4657 /* Fill all the callbacks before init */
4659 int (*on_next)(struct lws_email *email);
4660 /**< (Fill in before calling lws_email_init)
4661 * called when idle, 0 = another email to send, nonzero is idle.
4662 * If you return 0, all of the email_* char arrays must be set
4663 * to something useful. */
4664 int (*on_sent)(struct lws_email *email);
4665 /**< (Fill in before calling lws_email_init)
4666 * called when transfer of the email to the SMTP server was
4667 * successful, your callback would remove the current email
4669 int (*on_get_body)(struct lws_email *email, char *buf, int len);
4670 /**< (Fill in before calling lws_email_init)
4671 * called when the body part of the queued email is about to be
4672 * sent to the SMTP server. */
4675 /* private things */
4676 uv_timer_t timeout_email; /**< private */
4677 enum lwsgs_smtp_states estate; /**< private */
4678 uv_connect_t email_connect_req; /**< private */
4679 uv_tcp_t email_client; /**< private */
4680 time_t email_connect_started; /**< private */
4681 char email_buf[256]; /**< private */
4682 char *content; /**< private */
4686 * lws_email_init() - Initialize a struct lws_email
4688 * \param email: struct lws_email to init
4689 * \param loop: libuv loop to use
4690 * \param max_content: max email content size
4692 * Prepares a struct lws_email for use ending SMTP
4694 LWS_VISIBLE LWS_EXTERN int
4695 lws_email_init(struct lws_email *email, uv_loop_t *loop, int max_content);
4698 * lws_email_check() - Request check for new email
4700 * \param email: struct lws_email context to check
4702 * Schedules a check for new emails in 1s... call this when you have queued an
4705 LWS_VISIBLE LWS_EXTERN void
4706 lws_email_check(struct lws_email *email);
4708 * lws_email_destroy() - stop using the struct lws_email
4710 * \param email: the struct lws_email context
4712 * Stop sending email using email and free allocations
4714 LWS_VISIBLE LWS_EXTERN void
4715 lws_email_destroy(struct lws_email *email);