2 * libwebsockets - small server side websockets and web server implementation
4 * Copyright (C) 2010-2015 Andy Green <andy@warmcat.com>
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation:
9 * version 2.1 of the License.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
22 #ifndef LIBWEBSOCKET_H_3060898B846849FF9F88F5DB59B5950C
23 #define LIBWEBSOCKET_H_3060898B846849FF9F88F5DB59B5950C
32 #include "lws_config.h"
35 #if defined(WIN32) || defined(_WIN32)
37 #ifndef WIN32_LEAN_AND_MEAN
38 #define WIN32_LEAN_AND_MEAN
46 #define strcasecmp stricmp
47 #define getdtablesize() 30000
53 #define LWS_EXTERN extern __declspec(dllexport)
55 #define LWS_EXTERN extern __declspec(dllimport)
68 #define LWS_VISIBLE __attribute__((visibility("default")))
77 #endif /* LWS_USE_LIBEV */
82 #define LWS_EXTERN extern
92 #ifdef LWS_OPENSSL_SUPPORT
94 #include <cyassl/openssl/ssl.h>
96 #include <openssl/ssl.h>
97 #endif /* not USE_CYASSL */
100 #define CONTEXT_PORT_NO_LISTEN -1
101 #define MAX_MUX_RECURSION 2
103 enum lws_log_levels {
113 LLL_LATENCY = 1 << 9,
115 LLL_COUNT = 10 /* set to count of valid flags */
118 LWS_VISIBLE LWS_EXTERN void _lws_log(int filter, const char *format, ...);
119 LWS_VISIBLE LWS_EXTERN void _lws_logv(int filter, const char *format, va_list vl);
121 /* notice, warn and log are always compiled in */
122 #define lwsl_notice(...) _lws_log(LLL_NOTICE, __VA_ARGS__)
123 #define lwsl_warn(...) _lws_log(LLL_WARN, __VA_ARGS__)
124 #define lwsl_err(...) _lws_log(LLL_ERR, __VA_ARGS__)
126 * weaker logging can be deselected at configure time using --disable-debug
127 * that gets rid of the overhead of checking while keeping _warn and _err
132 #define lwsl_info(...) _lws_log(LLL_INFO, __VA_ARGS__)
133 #define lwsl_debug(...) _lws_log(LLL_DEBUG, __VA_ARGS__)
134 #define lwsl_parser(...) _lws_log(LLL_PARSER, __VA_ARGS__)
135 #define lwsl_header(...) _lws_log(LLL_HEADER, __VA_ARGS__)
136 #define lwsl_ext(...) _lws_log(LLL_EXT, __VA_ARGS__)
137 #define lwsl_client(...) _lws_log(LLL_CLIENT, __VA_ARGS__)
138 #define lwsl_latency(...) _lws_log(LLL_LATENCY, __VA_ARGS__)
139 LWS_VISIBLE LWS_EXTERN void lwsl_hexdump(void *buf, size_t len);
143 #define lwsl_info(...)
144 #define lwsl_debug(...)
145 #define lwsl_parser(...)
146 #define lwsl_header(...)
147 #define lwsl_ext(...)
148 #define lwsl_client(...)
149 #define lwsl_latency(...)
150 #define lwsl_hexdump(a, b)
154 #define ARRAY_SIZE(x) (sizeof(x) / sizeof(x[0]))
156 /* api change list for user code to test against */
158 #define LWS_FEATURE_SERVE_HTTP_FILE_HAS_OTHER_HEADERS_ARG
160 /* the struct libwebsocket_protocols has the id field present */
161 #define LWS_FEATURE_PROTOCOLS_HAS_ID_FIELD
163 /* you can call lws_get_peer_write_allowance */
164 #define LWS_FEATURE_PROTOCOLS_HAS_PEER_WRITE_ALLOWANCE
166 /* extra parameter introduced in 917f43ab821 */
167 #define LWS_FEATURE_SERVE_HTTP_FILE_HAS_OTHER_HEADERS_LEN
169 enum libwebsocket_context_options {
170 LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT = 2,
171 LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME = 4,
172 LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT = 8,
173 LWS_SERVER_OPTION_LIBEV = 16,
174 LWS_SERVER_OPTION_DISABLE_IPV6 = 32,
175 LWS_SERVER_OPTION_DISABLE_OS_CA_CERTS = 64,
178 enum libwebsocket_callback_reasons {
179 LWS_CALLBACK_ESTABLISHED,
180 LWS_CALLBACK_CLIENT_CONNECTION_ERROR,
181 LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH,
182 LWS_CALLBACK_CLIENT_ESTABLISHED,
184 LWS_CALLBACK_CLOSED_HTTP,
185 LWS_CALLBACK_RECEIVE,
186 LWS_CALLBACK_CLIENT_RECEIVE,
187 LWS_CALLBACK_CLIENT_RECEIVE_PONG,
188 LWS_CALLBACK_CLIENT_WRITEABLE,
189 LWS_CALLBACK_SERVER_WRITEABLE,
191 LWS_CALLBACK_HTTP_BODY,
192 LWS_CALLBACK_HTTP_BODY_COMPLETION,
193 LWS_CALLBACK_HTTP_FILE_COMPLETION,
194 LWS_CALLBACK_HTTP_WRITEABLE,
195 LWS_CALLBACK_FILTER_NETWORK_CONNECTION,
196 LWS_CALLBACK_FILTER_HTTP_CONNECTION,
197 LWS_CALLBACK_SERVER_NEW_CLIENT_INSTANTIATED,
198 LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION,
199 LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS,
200 LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS,
201 LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION,
202 LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER,
203 LWS_CALLBACK_CONFIRM_EXTENSION_OKAY,
204 LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED,
205 LWS_CALLBACK_PROTOCOL_INIT,
206 LWS_CALLBACK_PROTOCOL_DESTROY,
207 LWS_CALLBACK_WSI_CREATE, /* always protocol[0] */
208 LWS_CALLBACK_WSI_DESTROY, /* always protocol[0] */
209 LWS_CALLBACK_GET_THREAD_ID,
211 /* external poll() management support */
212 LWS_CALLBACK_ADD_POLL_FD,
213 LWS_CALLBACK_DEL_POLL_FD,
214 LWS_CALLBACK_CHANGE_MODE_POLL_FD,
215 LWS_CALLBACK_LOCK_POLL,
216 LWS_CALLBACK_UNLOCK_POLL,
218 LWS_CALLBACK_OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY,
220 LWS_CALLBACK_USER = 1000, /* user code can use any including / above */
223 // argument structure for all external poll related calls
224 // passed in via 'in'
225 struct libwebsocket_pollargs {
226 int fd; // applicable file descriptor
227 int events; // the new event mask
228 int prev_events; // the previous event mask
232 struct libwebsocket_pollfd {
238 #define libwebsocket_pollfd pollfd
241 enum libwebsocket_extension_callback_reasons {
242 LWS_EXT_CALLBACK_SERVER_CONTEXT_CONSTRUCT,
243 LWS_EXT_CALLBACK_CLIENT_CONTEXT_CONSTRUCT,
244 LWS_EXT_CALLBACK_SERVER_CONTEXT_DESTRUCT,
245 LWS_EXT_CALLBACK_CLIENT_CONTEXT_DESTRUCT,
246 LWS_EXT_CALLBACK_CONSTRUCT,
247 LWS_EXT_CALLBACK_CLIENT_CONSTRUCT,
248 LWS_EXT_CALLBACK_CHECK_OK_TO_REALLY_CLOSE,
249 LWS_EXT_CALLBACK_CHECK_OK_TO_PROPOSE_EXTENSION,
250 LWS_EXT_CALLBACK_DESTROY,
251 LWS_EXT_CALLBACK_DESTROY_ANY_WSI_CLOSING,
252 LWS_EXT_CALLBACK_ANY_WSI_ESTABLISHED,
253 LWS_EXT_CALLBACK_PACKET_RX_PREPARSE,
254 LWS_EXT_CALLBACK_PACKET_TX_PRESEND,
255 LWS_EXT_CALLBACK_PACKET_TX_DO_SEND,
256 LWS_EXT_CALLBACK_HANDSHAKE_REPLY_TX,
257 LWS_EXT_CALLBACK_FLUSH_PENDING_TX,
258 LWS_EXT_CALLBACK_EXTENDED_PAYLOAD_RX,
259 LWS_EXT_CALLBACK_CAN_PROXY_CLIENT_CONNECTION,
260 LWS_EXT_CALLBACK_1HZ,
261 LWS_EXT_CALLBACK_REQUEST_ON_WRITEABLE,
262 LWS_EXT_CALLBACK_IS_WRITEABLE,
263 LWS_EXT_CALLBACK_PAYLOAD_TX,
264 LWS_EXT_CALLBACK_PAYLOAD_RX,
267 enum libwebsocket_write_protocol {
270 LWS_WRITE_CONTINUATION,
273 /* special 04+ opcodes */
279 /* Same as write_http but we know this write ends the transaction */
280 LWS_WRITE_HTTP_FINAL,
284 LWS_WRITE_HTTP_HEADERS,
288 LWS_WRITE_NO_FIN = 0x40,
290 * client packet payload goes out on wire unmunged
291 * only useful for security tests since normal servers cannot
292 * decode the content if used
294 LWS_WRITE_CLIENT_IGNORE_XOR_MASK = 0x80
298 * you need these to look at headers that have been parsed if using the
299 * LWS_CALLBACK_FILTER_CONNECTION callback. If a header from the enum
300 * list below is absent, .token = NULL and token_len = 0. Otherwise .token
301 * points to .token_len chars containing that header content.
310 * don't forget to update test server header dump accordingly
312 * these have to be kept in sync with lextable.h / minilex.c
315 enum lws_token_indexes {
318 WSI_TOKEN_OPTIONS_URI,
320 WSI_TOKEN_CONNECTION,
325 WSI_TOKEN_EXTENSIONS,
332 WSI_TOKEN_HTTP2_SETTINGS,
333 WSI_TOKEN_HTTP_ACCEPT,
334 WSI_TOKEN_HTTP_AC_REQUEST_HEADERS,
335 WSI_TOKEN_HTTP_IF_MODIFIED_SINCE,
336 WSI_TOKEN_HTTP_IF_NONE_MATCH,
337 WSI_TOKEN_HTTP_ACCEPT_ENCODING,
338 WSI_TOKEN_HTTP_ACCEPT_LANGUAGE,
339 WSI_TOKEN_HTTP_PRAGMA,
340 WSI_TOKEN_HTTP_CACHE_CONTROL,
341 WSI_TOKEN_HTTP_AUTHORIZATION,
342 WSI_TOKEN_HTTP_COOKIE,
343 WSI_TOKEN_HTTP_CONTENT_LENGTH,
344 WSI_TOKEN_HTTP_CONTENT_TYPE,
346 WSI_TOKEN_HTTP_RANGE,
347 WSI_TOKEN_HTTP_REFERER,
352 WSI_TOKEN_HTTP_COLON_AUTHORITY,
353 WSI_TOKEN_HTTP_COLON_METHOD,
354 WSI_TOKEN_HTTP_COLON_PATH,
355 WSI_TOKEN_HTTP_COLON_SCHEME,
356 WSI_TOKEN_HTTP_COLON_STATUS,
358 WSI_TOKEN_HTTP_ACCEPT_CHARSET,
359 WSI_TOKEN_HTTP_ACCEPT_RANGES,
360 WSI_TOKEN_HTTP_ACCESS_CONTROL_ALLOW_ORIGIN,
362 WSI_TOKEN_HTTP_ALLOW,
363 WSI_TOKEN_HTTP_CONTENT_DISPOSITION,
364 WSI_TOKEN_HTTP_CONTENT_ENCODING,
365 WSI_TOKEN_HTTP_CONTENT_LANGUAGE,
366 WSI_TOKEN_HTTP_CONTENT_LOCATION,
367 WSI_TOKEN_HTTP_CONTENT_RANGE,
369 WSI_TOKEN_HTTP_EXPECT,
370 WSI_TOKEN_HTTP_EXPIRES,
372 WSI_TOKEN_HTTP_IF_MATCH,
373 WSI_TOKEN_HTTP_IF_RANGE,
374 WSI_TOKEN_HTTP_IF_UNMODIFIED_SINCE,
375 WSI_TOKEN_HTTP_LAST_MODIFIED,
377 WSI_TOKEN_HTTP_LOCATION,
378 WSI_TOKEN_HTTP_MAX_FORWARDS,
379 WSI_TOKEN_HTTP_PROXY_AUTHENTICATE,
380 WSI_TOKEN_HTTP_PROXY_AUTHORIZATION,
381 WSI_TOKEN_HTTP_REFRESH,
382 WSI_TOKEN_HTTP_RETRY_AFTER,
383 WSI_TOKEN_HTTP_SERVER,
384 WSI_TOKEN_HTTP_SET_COOKIE,
385 WSI_TOKEN_HTTP_STRICT_TRANSPORT_SECURITY,
386 WSI_TOKEN_HTTP_TRANSFER_ENCODING,
387 WSI_TOKEN_HTTP_USER_AGENT,
390 WSI_TOKEN_HTTP_WWW_AUTHENTICATE,
395 WSI_TOKEN_DELETE_URI,
397 WSI_TOKEN_HTTP_URI_ARGS,
399 /* use token storage to stash these */
401 _WSI_TOKEN_CLIENT_SENT_PROTOCOLS,
402 _WSI_TOKEN_CLIENT_PEER_ADDRESS,
403 _WSI_TOKEN_CLIENT_URI,
404 _WSI_TOKEN_CLIENT_HOST,
405 _WSI_TOKEN_CLIENT_ORIGIN,
407 /* always last real token index*/
409 /* parser state additions */
412 WSI_TOKEN_SKIPPING_SAW_CR,
413 WSI_PARSING_COMPLETE,
414 WSI_INIT_TOKEN_MUXURL,
417 struct lws_token_limits {
418 unsigned short token_limit[WSI_TOKEN_COUNT];
425 1000 indicates a normal closure, meaning that the purpose for
426 which the connection was established has been fulfilled.
430 1001 indicates that an endpoint is "going away", such as a server
431 going down or a browser having navigated away from a page.
435 1002 indicates that an endpoint is terminating the connection due
440 1003 indicates that an endpoint is terminating the connection
441 because it has received a type of data it cannot accept (e.g., an
442 endpoint that understands only text data MAY send this if it
443 receives a binary message).
447 Reserved. The specific meaning might be defined in the future.
451 1005 is a reserved value and MUST NOT be set as a status code in a
452 Close control frame by an endpoint. It is designated for use in
453 applications expecting a status code to indicate that no status
454 code was actually present.
458 1006 is a reserved value and MUST NOT be set as a status code in a
459 Close control frame by an endpoint. It is designated for use in
460 applications expecting a status code to indicate that the
461 connection was closed abnormally, e.g., without sending or
462 receiving a Close control frame.
466 1007 indicates that an endpoint is terminating the connection
467 because it has received data within a message that was not
468 consistent with the type of the message (e.g., non-UTF-8 [RFC3629]
469 data within a text message).
473 1008 indicates that an endpoint is terminating the connection
474 because it has received a message that violates its policy. This
475 is a generic status code that can be returned when there is no
476 other more suitable status code (e.g., 1003 or 1009) or if there
477 is a need to hide specific details about the policy.
481 1009 indicates that an endpoint is terminating the connection
482 because it has received a message that is too big for it to
487 1010 indicates that an endpoint (client) is terminating the
488 connection because it has expected the server to negotiate one or
489 more extension, but the server didn't return them in the response
490 message of the WebSocket handshake. The list of extensions that
491 are needed SHOULD appear in the /reason/ part of the Close frame.
492 Note that this status code is not used by the server, because it
493 can fail the WebSocket handshake instead.
497 1011 indicates that a server is terminating the connection because
498 it encountered an unexpected condition that prevented it from
499 fulfilling the request.
503 1015 is a reserved value and MUST NOT be set as a status code in a
504 Close control frame by an endpoint. It is designated for use in
505 applications expecting a status code to indicate that the
506 connection was closed due to a failure to perform a TLS handshake
507 (e.g., the server certificate can't be verified).
510 enum lws_close_status {
511 LWS_CLOSE_STATUS_NOSTATUS = 0,
512 LWS_CLOSE_STATUS_NORMAL = 1000,
513 LWS_CLOSE_STATUS_GOINGAWAY = 1001,
514 LWS_CLOSE_STATUS_PROTOCOL_ERR = 1002,
515 LWS_CLOSE_STATUS_UNACCEPTABLE_OPCODE = 1003,
516 LWS_CLOSE_STATUS_RESERVED = 1004,
517 LWS_CLOSE_STATUS_NO_STATUS = 1005,
518 LWS_CLOSE_STATUS_ABNORMAL_CLOSE = 1006,
519 LWS_CLOSE_STATUS_INVALID_PAYLOAD = 1007,
520 LWS_CLOSE_STATUS_POLICY_VIOLATION = 1008,
521 LWS_CLOSE_STATUS_MESSAGE_TOO_LARGE = 1009,
522 LWS_CLOSE_STATUS_EXTENSION_REQUIRED = 1010,
523 LWS_CLOSE_STATUS_UNEXPECTED_CONDITION = 1011,
524 LWS_CLOSE_STATUS_TLS_FAILURE = 1015,
528 HTTP_STATUS_OK = 200,
529 HTTP_STATUS_NO_CONTENT = 204,
531 HTTP_STATUS_BAD_REQUEST = 400,
532 HTTP_STATUS_UNAUTHORIZED,
533 HTTP_STATUS_PAYMENT_REQUIRED,
534 HTTP_STATUS_FORBIDDEN,
535 HTTP_STATUS_NOT_FOUND,
536 HTTP_STATUS_METHOD_NOT_ALLOWED,
537 HTTP_STATUS_NOT_ACCEPTABLE,
538 HTTP_STATUS_PROXY_AUTH_REQUIRED,
539 HTTP_STATUS_REQUEST_TIMEOUT,
540 HTTP_STATUS_CONFLICT,
542 HTTP_STATUS_LENGTH_REQUIRED,
543 HTTP_STATUS_PRECONDITION_FAILED,
544 HTTP_STATUS_REQ_ENTITY_TOO_LARGE,
545 HTTP_STATUS_REQ_URI_TOO_LONG,
546 HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE,
547 HTTP_STATUS_REQ_RANGE_NOT_SATISFIABLE,
548 HTTP_STATUS_EXPECTATION_FAILED,
550 HTTP_STATUS_INTERNAL_SERVER_ERROR = 500,
551 HTTP_STATUS_NOT_IMPLEMENTED,
552 HTTP_STATUS_BAD_GATEWAY,
553 HTTP_STATUS_SERVICE_UNAVAILABLE,
554 HTTP_STATUS_GATEWAY_TIMEOUT,
555 HTTP_STATUS_HTTP_VERSION_NOT_SUPPORTED,
559 struct libwebsocket_context;
560 /* needed even with extensions disabled for create context */
561 struct libwebsocket_extension;
564 * callback_function() - User server actions
565 * @context: Websockets context
566 * @wsi: Opaque websocket instance pointer
567 * @reason: The reason for the call
568 * @user: Pointer to per-session user data allocated by library
569 * @in: Pointer used for some callback reasons
570 * @len: Length set for some callback reasons
572 * This callback is the way the user controls what is served. All the
573 * protocol detail is hidden and handled by the library.
575 * For each connection / session there is user data allocated that is
576 * pointed to by "user". You set the size of this user data area when
577 * the library is initialized with libwebsocket_create_server.
579 * You get an opportunity to initialize user data when called back with
580 * LWS_CALLBACK_ESTABLISHED reason.
582 * LWS_CALLBACK_ESTABLISHED: after the server completes a handshake with
585 * LWS_CALLBACK_CLIENT_CONNECTION_ERROR: the request client connection has
586 * been unable to complete a handshake with the remote server
588 * LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH: this is the last chance for the
589 * client user code to examine the http headers
590 * and decide to reject the connection. If the
591 * content in the headers is interesting to the
592 * client (url, etc) it needs to copy it out at
593 * this point since it will be destroyed before
594 * the CLIENT_ESTABLISHED call
596 * LWS_CALLBACK_CLIENT_ESTABLISHED: after your client connection completed
597 * a handshake with the remote server
599 * LWS_CALLBACK_CLOSED: when the websocket session ends
601 * LWS_CALLBACK_CLOSED_HTTP: when a HTTP (non-websocket) session ends
603 * LWS_CALLBACK_RECEIVE: data has appeared for this server endpoint from a
604 * remote client, it can be found at *in and is
607 * LWS_CALLBACK_CLIENT_RECEIVE_PONG: if you elected to see PONG packets,
608 * they appear with this callback reason. PONG
609 * packets only exist in 04+ protocol
611 * LWS_CALLBACK_CLIENT_RECEIVE: data has appeared from the server for the
612 * client connection, it can be found at *in and
615 * LWS_CALLBACK_HTTP: an http request has come from a client that is not
616 * asking to upgrade the connection to a websocket
617 * one. This is a chance to serve http content,
618 * for example, to send a script to the client
619 * which will then open the websockets connection.
620 * @in points to the URI path requested and
621 * libwebsockets_serve_http_file() makes it very
622 * simple to send back a file to the client.
623 * Normally after sending the file you are done
624 * with the http connection, since the rest of the
625 * activity will come by websockets from the script
626 * that was delivered by http, so you will want to
627 * return 1; to close and free up the connection.
628 * That's important because it uses a slot in the
629 * total number of client connections allowed set
632 * LWS_CALLBACK_HTTP_BODY: the next @len bytes data from the http
633 * request body HTTP connection is now available in @in.
635 * LWS_CALLBACK_HTTP_BODY_COMPLETION: the expected amount of http request
636 * body has been delivered
638 * LWS_CALLBACK_HTTP_WRITEABLE: you can write more down the http protocol
641 * LWS_CALLBACK_HTTP_FILE_COMPLETION: a file requested to be send down
642 * http link has completed.
644 * LWS_CALLBACK_CLIENT_WRITEABLE:
645 * LWS_CALLBACK_SERVER_WRITEABLE: If you call
646 * libwebsocket_callback_on_writable() on a connection, you will
647 * get one of these callbacks coming when the connection socket
648 * is able to accept another write packet without blocking.
649 * If it already was able to take another packet without blocking,
650 * you'll get this callback at the next call to the service loop
651 * function. Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE
652 * and servers get LWS_CALLBACK_SERVER_WRITEABLE.
654 * LWS_CALLBACK_FILTER_NETWORK_CONNECTION: called when a client connects to
655 * the server at network level; the connection is accepted but then
656 * passed to this callback to decide whether to hang up immediately
657 * or not, based on the client IP. @in contains the connection
658 * socket's descriptor. Since the client connection information is
659 * not available yet, @wsi still pointing to the main server socket.
660 * Return non-zero to terminate the connection before sending or
661 * receiving anything. Because this happens immediately after the
662 * network connection from the client, there's no websocket protocol
663 * selected yet so this callback is issued only to protocol 0.
665 * LWS_CALLBACK_SERVER_NEW_CLIENT_INSTANTIATED: A new client just had
666 * been connected, accepted, and instantiated into the pool. This
667 * callback allows setting any relevant property to it. Because this
668 * happens immediately after the instantiation of a new client,
669 * there's no websocket protocol selected yet so this callback is
670 * issued only to protocol 0. Only @wsi is defined, pointing to the
671 * new client, and the return value is ignored.
673 * LWS_CALLBACK_FILTER_HTTP_CONNECTION: called when the request has
674 * been received and parsed from the client, but the response is
675 * not sent yet. Return non-zero to disallow the connection.
676 * @user is a pointer to the connection user space allocation,
677 * @in is the URI, eg, "/"
678 * In your handler you can use the public APIs
679 * lws_hdr_total_length() / lws_hdr_copy() to access all of the
680 * headers using the header enums lws_token_indexes from
681 * libwebsockets.h to check for and read the supported header
682 * presence and content before deciding to allow the http
683 * connection to proceed or to kill the connection.
685 * LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION: called when the handshake has
686 * been received and parsed from the client, but the response is
687 * not sent yet. Return non-zero to disallow the connection.
688 * @user is a pointer to the connection user space allocation,
689 * @in is the requested protocol name
690 * In your handler you can use the public APIs
691 * lws_hdr_total_length() / lws_hdr_copy() to access all of the
692 * headers using the header enums lws_token_indexes from
693 * libwebsockets.h to check for and read the supported header
694 * presence and content before deciding to allow the handshake
695 * to proceed or to kill the connection.
697 * LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS: if configured for
698 * including OpenSSL support, this callback allows your user code
699 * to perform extra SSL_CTX_load_verify_locations() or similar
700 * calls to direct OpenSSL where to find certificates the client
701 * can use to confirm the remote server identity. @user is the
704 * LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS: if configured for
705 * including OpenSSL support, this callback allows your user code
706 * to load extra certifcates into the server which allow it to
707 * verify the validity of certificates returned by clients. @user
708 * is the server's OpenSSL SSL_CTX*
710 * LWS_CALLBACK_OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY: if configured for
711 * including OpenSSL support but no private key file has been specified
712 * (ssl_private_key_filepath is NULL), this callback is called to
713 * allow the user to set the private key directly via libopenssl
714 * and perform further operations if required; this might be useful
715 * in situations where the private key is not directly accessible by
716 * the OS, for example if it is stored on a smartcard
717 * @user is the server's OpenSSL SSL_CTX*
719 * LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION: if the
720 * libwebsockets context was created with the option
721 * LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this
722 * callback is generated during OpenSSL verification of the cert
723 * sent from the client. It is sent to protocol[0] callback as
724 * no protocol has been negotiated on the connection yet.
725 * Notice that the libwebsockets context and wsi are both NULL
726 * during this callback. See
727 * http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
728 * to understand more detail about the OpenSSL callback that
729 * generates this libwebsockets callback and the meanings of the
730 * arguments passed. In this callback, @user is the x509_ctx,
731 * @in is the ssl pointer and @len is preverify_ok
732 * Notice that this callback maintains libwebsocket return
733 * conventions, return 0 to mean the cert is OK or 1 to fail it.
734 * This also means that if you don't handle this callback then
735 * the default callback action of returning 0 allows the client
738 * LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER: this callback happens
739 * when a client handshake is being compiled. @user is NULL,
740 * @in is a char **, it's pointing to a char * which holds the
741 * next location in the header buffer where you can add
742 * headers, and @len is the remaining space in the header buffer,
743 * which is typically some hundreds of bytes. So, to add a canned
744 * cookie, your handler code might look similar to:
746 * char **p = (char **)in;
751 * *p += sprintf(*p, "Cookie: a=b\x0d\x0a");
755 * Notice if you add anything, you just have to take care about
756 * the CRLF on the line you added. Obviously this callback is
757 * optional, if you don't handle it everything is fine.
759 * Notice the callback is coming to protocols[0] all the time,
760 * because there is no specific protocol handshook yet.
762 * LWS_CALLBACK_CONFIRM_EXTENSION_OKAY: When the server handshake code
763 * sees that it does support a requested extension, before
764 * accepting the extension by additing to the list sent back to
765 * the client it gives this callback just to check that it's okay
766 * to use that extension. It calls back to the requested protocol
767 * and with @in being the extension name, @len is 0 and @user is
768 * valid. Note though at this time the ESTABLISHED callback hasn't
769 * happened yet so if you initialize @user content there, @user
770 * content during this callback might not be useful for anything.
771 * Notice this callback comes to protocols[0].
773 * LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED: When a client
774 * connection is being prepared to start a handshake to a server,
775 * each supported extension is checked with protocols[0] callback
776 * with this reason, giving the user code a chance to suppress the
777 * claim to support that extension by returning non-zero. If
778 * unhandled, by default 0 will be returned and the extension
779 * support included in the header to the server. Notice this
780 * callback comes to protocols[0].
782 * LWS_CALLBACK_PROTOCOL_INIT: One-time call per protocol so it can
783 * do initial setup / allocations etc
785 * LWS_CALLBACK_PROTOCOL_DESTROY: One-time call per protocol indicating
786 * this protocol won't get used at all after this callback, the
787 * context is getting destroyed. Take the opportunity to
788 * deallocate everything that was allocated by the protocol.
790 * LWS_CALLBACK_WSI_CREATE: outermost (earliest) wsi create notification
792 * LWS_CALLBACK_WSI_DESTROY: outermost (latest) wsi destroy notification
794 * The next five reasons are optional and only need taking care of if you
795 * will be integrating libwebsockets sockets into an external polling
798 * For these calls, @in points to a struct libwebsocket_pollargs that
799 * contains @fd, @events and @prev_events members
801 * LWS_CALLBACK_ADD_POLL_FD: libwebsocket deals with its poll() loop
802 * internally, but in the case you are integrating with another
803 * server you will need to have libwebsocket sockets share a
804 * polling array with the other server. This and the other
805 * POLL_FD related callbacks let you put your specialized
806 * poll array interface code in the callback for protocol 0, the
807 * first protocol you support, usually the HTTP protocol in the
809 * This callback happens when a socket needs to be
810 * added to the polling loop: @in points to a struct
811 * libwebsocket_pollargs; the @fd member of the struct is the file
812 * descriptor, and @events contains the active events.
814 * If you are using the internal polling loop (the "service"
815 * callback), you can just ignore these callbacks.
817 * LWS_CALLBACK_DEL_POLL_FD: This callback happens when a socket descriptor
818 * needs to be removed from an external polling array. @in is
819 * again the struct libwebsocket_pollargs containing the @fd member
820 * to be removed. If you are using the internal polling
821 * loop, you can just ignore it.
823 * LWS_CALLBACK_CHANGE_MODE_POLL_FD: This callback happens when
824 * libwebsockets wants to modify the events for a connectiion.
825 * @in is the struct libwebsocket_pollargs with the @fd to change.
826 * The new event mask is in @events member and the old mask is in
827 * the @prev_events member.
828 * If you are using the internal polling loop, you can just ignore
831 * LWS_CALLBACK_LOCK_POLL:
832 * LWS_CALLBACK_UNLOCK_POLL: These allow the external poll changes driven
833 * by libwebsockets to participate in an external thread locking
834 * scheme around the changes, so the whole thing is threadsafe.
836 LWS_VISIBLE LWS_EXTERN int callback(struct libwebsocket_context *context,
837 struct libwebsocket *wsi,
838 enum libwebsocket_callback_reasons reason, void *user,
839 void *in, size_t len);
841 typedef int (callback_function)(struct libwebsocket_context *context,
842 struct libwebsocket *wsi,
843 enum libwebsocket_callback_reasons reason, void *user,
844 void *in, size_t len);
846 #ifndef LWS_NO_EXTENSIONS
848 * extension_callback_function() - Hooks to allow extensions to operate
849 * @context: Websockets context
850 * @ext: This extension
851 * @wsi: Opaque websocket instance pointer
852 * @reason: The reason for the call
853 * @user: Pointer to per-session user data allocated by library
854 * @in: Pointer used for some callback reasons
855 * @len: Length set for some callback reasons
857 * Each extension that is active on a particular connection receives
858 * callbacks during the connection lifetime to allow the extension to
859 * operate on websocket data and manage itself.
861 * Libwebsockets takes care of allocating and freeing "user" memory for
862 * each active extension on each connection. That is what is pointed to
863 * by the @user parameter.
865 * LWS_EXT_CALLBACK_CONSTRUCT: called when the server has decided to
866 * select this extension from the list provided by the client,
867 * just before the server will send back the handshake accepting
868 * the connection with this extension active. This gives the
869 * extension a chance to initialize its connection context found
872 * LWS_EXT_CALLBACK_CLIENT_CONSTRUCT: same as LWS_EXT_CALLBACK_CONSTRUCT
873 * but called when client is instantiating this extension. Some
874 * extensions will work the same on client and server side and then
875 * you can just merge handlers for both CONSTRUCTS.
877 * LWS_EXT_CALLBACK_DESTROY: called when the connection the extension was
878 * being used on is about to be closed and deallocated. It's the
879 * last chance for the extension to deallocate anything it has
880 * allocated in the user data (pointed to by @user) before the
881 * user data is deleted. This same callback is used whether you
882 * are in client or server instantiation context.
884 * LWS_EXT_CALLBACK_PACKET_RX_PREPARSE: when this extension was active on
885 * a connection, and a packet of data arrived at the connection,
886 * it is passed to this callback to give the extension a chance to
887 * change the data, eg, decompress it. @user is pointing to the
888 * extension's private connection context data, @in is pointing
889 * to an lws_tokens struct, it consists of a char * pointer called
890 * token, and an int called token_len. At entry, these are
891 * set to point to the received buffer and set to the content
892 * length. If the extension will grow the content, it should use
893 * a new buffer allocated in its private user context data and
894 * set the pointed-to lws_tokens members to point to its buffer.
896 * LWS_EXT_CALLBACK_PACKET_TX_PRESEND: this works the same way as
897 * LWS_EXT_CALLBACK_PACKET_RX_PREPARSE above, except it gives the
898 * extension a chance to change websocket data just before it will
899 * be sent out. Using the same lws_token pointer scheme in @in,
900 * the extension can change the buffer and the length to be
901 * transmitted how it likes. Again if it wants to grow the
902 * buffer safely, it should copy the data into its own buffer and
903 * set the lws_tokens token pointer to it.
905 LWS_VISIBLE LWS_EXTERN int extension_callback(struct libwebsocket_context *context,
906 struct libwebsocket_extension *ext,
907 struct libwebsocket *wsi,
908 enum libwebsocket_extension_callback_reasons reason,
909 void *user, void *in, size_t len);
911 typedef int (extension_callback_function)(struct libwebsocket_context *context,
912 struct libwebsocket_extension *ext,
913 struct libwebsocket *wsi,
914 enum libwebsocket_extension_callback_reasons reason,
915 void *user, void *in, size_t len);
919 * struct libwebsocket_protocols - List of protocols and handlers server
921 * @name: Protocol name that must match the one given in the client
922 * Javascript new WebSocket(url, 'protocol') name.
923 * @callback: The service callback used for this protocol. It allows the
924 * service action for an entire protocol to be encapsulated in
925 * the protocol-specific callback
926 * @per_session_data_size: Each new connection using this protocol gets
927 * this much memory allocated on connection establishment and
928 * freed on connection takedown. A pointer to this per-connection
929 * allocation is passed into the callback in the 'user' parameter
930 * @rx_buffer_size: if you want atomic frames delivered to the callback, you
931 * should set this to the size of the biggest legal frame that
932 * you support. If the frame size is exceeded, there is no
933 * error, but the buffer will spill to the user callback when
934 * full, which you can detect by using
935 * libwebsockets_remaining_packet_payload(). Notice that you
936 * just talk about frame size here, the LWS_SEND_BUFFER_PRE_PADDING
937 * and post-padding are automatically also allocated on top.
938 * @id: ignored by lws, but useful to contain user information bound
939 * to the selected protocol. For example if this protocol was
940 * called "myprotocol-v2", you might set id to 2, and the user
941 * code that acts differently according to the version can do so by
942 * switch (wsi->protocol->id), user code might use some bits as
943 * capability flags based on selected protocol version, etc.
944 * @user: User provided context data at the protocol level.
945 * Accessible via libwebsockets_get_protocol(wsi)->user
946 * This should not be confused with wsi->user, it is not the same.
947 * The library completely ignores any value in here.
948 * @owning_server: the server init call fills in this opaque pointer when
949 * registering this protocol with the server.
950 * @protocol_index: which protocol we are starting from zero
952 * This structure represents one protocol supported by the server. An
953 * array of these structures is passed to libwebsocket_create_server()
954 * allows as many protocols as you like to be handled by one server.
956 * The first protocol given has its callback used for user callbacks when
957 * there is no agreed protocol name, that's true during HTTP part of the
958 * connection and true if the client did not send a Protocol: header.
961 struct libwebsocket_protocols {
963 callback_function *callback;
964 size_t per_session_data_size;
965 size_t rx_buffer_size;
970 * below are filled in on server init and can be left uninitialized,
971 * no need for user to use them directly either
974 struct libwebsocket_context *owning_server;
978 #ifndef LWS_NO_EXTENSIONS
980 * struct libwebsocket_extension - An extension we know how to cope with
982 * @name: Formal extension name, eg, "deflate-stream"
983 * @callback: Service callback
984 * @per_session_data_size: Libwebsockets will auto-malloc this much
985 * memory for the use of the extension, a pointer
986 * to it comes in the @user callback parameter
987 * @per_context_private_data: Optional storage for this extension that
988 * is per-context, so it can track stuff across
989 * all sessions, etc, if it wants
992 struct libwebsocket_extension {
994 extension_callback_function *callback;
995 size_t per_session_data_size;
996 void *per_context_private_data;
1001 * struct lws_context_creation_info: parameters to create context with
1003 * @port: Port to listen on... you can use CONTEXT_PORT_NO_LISTEN to
1004 * suppress listening on any port, that's what you want if you are
1005 * not running a websocket server at all but just using it as a
1007 * @iface: NULL to bind the listen socket to all interfaces, or the
1008 * interface name, eg, "eth2"
1009 * @protocols: Array of structures listing supported protocols and a protocol-
1010 * specific callback for each one. The list is ended with an
1011 * entry that has a NULL callback pointer.
1012 * It's not const because we write the owning_server member
1013 * @extensions: NULL or array of libwebsocket_extension structs listing the
1014 * extensions this context supports. If you configured with
1015 * --without-extensions, you should give NULL here.
1016 * @token_limits: NULL or struct lws_token_limits pointer which is initialized
1017 * with a token length limit for each possible WSI_TOKEN_***
1018 * @ssl_cert_filepath: If libwebsockets was compiled to use ssl, and you want
1019 * to listen using SSL, set to the filepath to fetch the
1020 * server cert from, otherwise NULL for unencrypted
1021 * @ssl_private_key_filepath: filepath to private key if wanting SSL mode;
1022 * if this is set to NULL but sll_cert_filepath is set, the
1023 * OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY callback is called to allow
1024 * setting of the private key directly via openSSL library calls
1025 * @ssl_ca_filepath: CA certificate filepath or NULL
1026 * @ssl_cipher_list: List of valid ciphers to use (eg,
1027 * "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
1028 * or you can leave it as NULL to get "DEFAULT"
1029 * @gid: group id to change to after setting listen socket, or -1.
1030 * @uid: user id to change to after setting listen socket, or -1.
1031 * @options: 0, or LWS_SERVER_OPTION_DEFEAT_CLIENT_MASK
1032 * @user: optional user pointer that can be recovered via the context
1033 * pointer using libwebsocket_context_user
1034 * @ka_time: 0 for no keepalive, otherwise apply this keepalive timeout to
1035 * all libwebsocket sockets, client or server
1036 * @ka_probes: if ka_time was nonzero, after the timeout expires how many
1037 * times to try to get a response from the peer before giving up
1038 * and killing the connection
1039 * @ka_interval: if ka_time was nonzero, how long to wait before each ka_probes
1041 * @provided_client_ssl_ctx: If non-null, swap out libwebsockets ssl
1042 * implementation for the one provided by provided_ssl_ctx.
1043 * Libwebsockets no longer is responsible for freeing the context
1044 * if this option is selected.
1047 struct lws_context_creation_info {
1050 struct libwebsocket_protocols *protocols;
1051 struct libwebsocket_extension *extensions;
1052 struct lws_token_limits *token_limits;
1053 const char *ssl_private_key_password;
1054 const char *ssl_cert_filepath;
1055 const char *ssl_private_key_filepath;
1056 const char *ssl_ca_filepath;
1057 const char *ssl_cipher_list;
1058 const char *http_proxy_address;
1059 unsigned int http_proxy_port;
1062 unsigned int options;
1067 #ifdef LWS_OPENSSL_SUPPORT
1068 SSL_CTX *provided_client_ssl_ctx;
1069 #else /* maintain structure layout either way */
1070 void *provided_client_ssl_ctx;
1074 LWS_VISIBLE LWS_EXTERN
1075 void lws_set_log_level(int level,
1076 void (*log_emit_function)(int level, const char *line));
1078 LWS_VISIBLE LWS_EXTERN void
1079 lwsl_emit_syslog(int level, const char *line);
1081 LWS_VISIBLE LWS_EXTERN struct libwebsocket_context *
1082 libwebsocket_create_context(struct lws_context_creation_info *info);
1084 LWS_VISIBLE LWS_EXTERN int
1085 libwebsocket_set_proxy(struct libwebsocket_context *context, const char *proxy);
1087 LWS_VISIBLE LWS_EXTERN void
1088 libwebsocket_context_destroy(struct libwebsocket_context *context);
1090 LWS_VISIBLE LWS_EXTERN int
1091 libwebsocket_service(struct libwebsocket_context *context, int timeout_ms);
1093 LWS_VISIBLE LWS_EXTERN void
1094 libwebsocket_cancel_service(struct libwebsocket_context *context);
1096 LWS_VISIBLE LWS_EXTERN const unsigned char *
1097 lws_token_to_string(enum lws_token_indexes token);
1099 LWS_VISIBLE LWS_EXTERN int
1100 lws_add_http_header_by_name(struct libwebsocket_context *context,
1101 struct libwebsocket *wsi,
1102 const unsigned char *name,
1103 const unsigned char *value,
1106 unsigned char *end);
1107 LWS_VISIBLE LWS_EXTERN int
1108 lws_finalize_http_header(struct libwebsocket_context *context,
1109 struct libwebsocket *wsi,
1111 unsigned char *end);
1112 LWS_VISIBLE LWS_EXTERN int
1113 lws_add_http_header_by_token(struct libwebsocket_context *context,
1114 struct libwebsocket *wsi,
1115 enum lws_token_indexes token,
1116 const unsigned char *value,
1119 unsigned char *end);
1120 LWS_VISIBLE LWS_EXTERN int lws_add_http_header_content_length(struct libwebsocket_context *context,
1121 struct libwebsocket *wsi,
1122 unsigned long content_length,
1124 unsigned char *end);
1125 LWS_VISIBLE LWS_EXTERN int
1126 lws_add_http_header_status(struct libwebsocket_context *context,
1127 struct libwebsocket *wsi,
1130 unsigned char *end);
1132 LWS_EXTERN int lws_http_transaction_completed(struct libwebsocket *wsi);
1134 #ifdef LWS_USE_LIBEV
1135 LWS_VISIBLE LWS_EXTERN int
1136 libwebsocket_initloop(
1137 struct libwebsocket_context *context, struct ev_loop *loop);
1140 libwebsocket_sigint_cb(
1141 struct ev_loop *loop, struct ev_signal *watcher, int revents);
1142 #endif /* LWS_USE_LIBEV */
1144 LWS_VISIBLE LWS_EXTERN int
1145 libwebsocket_service_fd(struct libwebsocket_context *context,
1146 struct libwebsocket_pollfd *pollfd);
1148 LWS_VISIBLE LWS_EXTERN void *
1149 libwebsocket_context_user(struct libwebsocket_context *context);
1151 enum pending_timeout {
1152 NO_PENDING_TIMEOUT = 0,
1153 PENDING_TIMEOUT_AWAITING_PROXY_RESPONSE,
1154 PENDING_TIMEOUT_AWAITING_CONNECT_RESPONSE,
1155 PENDING_TIMEOUT_ESTABLISH_WITH_SERVER,
1156 PENDING_TIMEOUT_AWAITING_SERVER_RESPONSE,
1157 PENDING_TIMEOUT_AWAITING_PING,
1158 PENDING_TIMEOUT_CLOSE_ACK,
1159 PENDING_TIMEOUT_AWAITING_EXTENSION_CONNECT_RESPONSE,
1160 PENDING_TIMEOUT_SENT_CLIENT_HANDSHAKE,
1161 PENDING_TIMEOUT_SSL_ACCEPT,
1162 PENDING_TIMEOUT_HTTP_CONTENT,
1163 PENDING_TIMEOUT_AWAITING_CLIENT_HS_SEND,
1166 LWS_VISIBLE LWS_EXTERN void
1167 libwebsocket_set_timeout(struct libwebsocket *wsi,
1168 enum pending_timeout reason, int secs);
1173 * When sending with websocket protocol (LWS_WRITE_TEXT or LWS_WRITE_BINARY)
1174 * the send buffer has to have LWS_SEND_BUFFER_PRE_PADDING bytes valid BEFORE
1175 * buf, and LWS_SEND_BUFFER_POST_PADDING bytes valid AFTER (buf + len).
1177 * This allows us to add protocol info before and after the data, and send as
1178 * one packet on the network without payload copying, for maximum efficiency.
1180 * So for example you need this kind of code to use libwebsocket_write with a
1183 * char buf[LWS_SEND_BUFFER_PRE_PADDING + 128 + LWS_SEND_BUFFER_POST_PADDING];
1185 * // fill your part of the buffer... for example here it's all zeros
1186 * memset(&buf[LWS_SEND_BUFFER_PRE_PADDING], 0, 128);
1188 * libwebsocket_write(wsi, &buf[LWS_SEND_BUFFER_PRE_PADDING], 128,
1191 * When sending LWS_WRITE_HTTP, there is no protocol addition and you can just
1192 * use the whole buffer without taking care of the above.
1196 * this is the frame nonce plus two header plus 8 length
1197 * there's an additional two for mux extension per mux nesting level
1198 * 2 byte prepend on close will already fit because control frames cannot use
1199 * the big length style
1202 #define LWS_SEND_BUFFER_PRE_PADDING (4 + 10 + (2 * MAX_MUX_RECURSION))
1203 #define LWS_SEND_BUFFER_POST_PADDING 4
1205 LWS_VISIBLE LWS_EXTERN int
1206 libwebsocket_write(struct libwebsocket *wsi, unsigned char *buf, size_t len,
1207 enum libwebsocket_write_protocol protocol);
1209 /* helper for case where buffer may be const */
1210 #define libwebsocket_write_http(wsi, buf, len) \
1211 libwebsocket_write(wsi, (unsigned char *)(buf), len, LWS_WRITE_HTTP)
1213 LWS_VISIBLE LWS_EXTERN int
1214 libwebsockets_serve_http_file(struct libwebsocket_context *context,
1215 struct libwebsocket *wsi, const char *file,
1216 const char *content_type, const char *other_headers,
1217 int other_headers_len);
1218 LWS_VISIBLE LWS_EXTERN int
1219 libwebsockets_serve_http_file_fragment(struct libwebsocket_context *context,
1220 struct libwebsocket *wsi);
1222 LWS_VISIBLE LWS_EXTERN int libwebsockets_return_http_status(
1223 struct libwebsocket_context *context,
1224 struct libwebsocket *wsi, unsigned int code,
1225 const char *html_body);
1227 LWS_VISIBLE LWS_EXTERN const struct libwebsocket_protocols *
1228 libwebsockets_get_protocol(struct libwebsocket *wsi);
1230 LWS_VISIBLE LWS_EXTERN int
1231 libwebsocket_callback_on_writable(struct libwebsocket_context *context,
1232 struct libwebsocket *wsi);
1234 LWS_VISIBLE LWS_EXTERN int
1235 libwebsocket_callback_on_writable_all_protocol(
1236 const struct libwebsocket_protocols *protocol);
1238 LWS_VISIBLE LWS_EXTERN int
1239 libwebsocket_callback_all_protocol(
1240 const struct libwebsocket_protocols *protocol, int reason);
1242 LWS_VISIBLE LWS_EXTERN int
1243 libwebsocket_get_socket_fd(struct libwebsocket *wsi);
1245 LWS_VISIBLE LWS_EXTERN int
1246 libwebsocket_is_final_fragment(struct libwebsocket *wsi);
1248 LWS_VISIBLE LWS_EXTERN unsigned char
1249 libwebsocket_get_reserved_bits(struct libwebsocket *wsi);
1251 LWS_VISIBLE LWS_EXTERN int
1252 libwebsocket_rx_flow_control(struct libwebsocket *wsi, int enable);
1254 LWS_VISIBLE LWS_EXTERN void
1255 libwebsocket_rx_flow_allow_all_protocol(
1256 const struct libwebsocket_protocols *protocol);
1258 LWS_VISIBLE LWS_EXTERN size_t
1259 libwebsockets_remaining_packet_payload(struct libwebsocket *wsi);
1262 * if the protocol does not have any guidence, returns -1. Currently only
1263 * http2 connections get send window information from this API. But your code
1264 * should use it so it can work properly with any protocol.
1266 * If nonzero return is the amount of payload data the peer or intermediary has
1267 * reported it has buffer space for. That has NO relationship with the amount
1268 * of buffer space your OS can accept on this connection for a write action.
1270 * This number represents the maximum you could send to the peer or intermediary
1271 * on this connection right now without it complaining.
1273 * lws manages accounting for send window updates and payload writes
1274 * automatically, so this number reflects the situation at the peer or
1275 * intermediary dynamically.
1277 LWS_VISIBLE LWS_EXTERN size_t
1278 lws_get_peer_write_allowance(struct libwebsocket *wsi);
1280 LWS_VISIBLE LWS_EXTERN struct libwebsocket *
1281 libwebsocket_client_connect(struct libwebsocket_context *clients,
1282 const char *address,
1288 const char *protocol,
1289 int ietf_version_or_minus_one);
1291 LWS_VISIBLE LWS_EXTERN struct libwebsocket *
1292 libwebsocket_client_connect_extended(struct libwebsocket_context *clients,
1293 const char *address,
1299 const char *protocol,
1300 int ietf_version_or_minus_one,
1303 LWS_VISIBLE LWS_EXTERN const char *
1304 libwebsocket_canonical_hostname(struct libwebsocket_context *context);
1307 LWS_VISIBLE LWS_EXTERN void
1308 libwebsockets_get_peer_addresses(struct libwebsocket_context *context,
1309 struct libwebsocket *wsi, int fd, char *name, int name_len,
1310 char *rip, int rip_len);
1312 LWS_VISIBLE LWS_EXTERN int
1313 libwebsockets_get_random(struct libwebsocket_context *context,
1314 void *buf, int len);
1316 LWS_VISIBLE LWS_EXTERN int
1317 lws_daemonize(const char *_lock_path);
1319 LWS_VISIBLE LWS_EXTERN int
1320 lws_send_pipe_choked(struct libwebsocket *wsi);
1322 LWS_VISIBLE LWS_EXTERN int
1323 lws_partial_buffered(struct libwebsocket *wsi);
1325 LWS_VISIBLE LWS_EXTERN int
1326 lws_frame_is_binary(struct libwebsocket *wsi);
1328 LWS_VISIBLE LWS_EXTERN int
1329 lws_is_ssl(struct libwebsocket *wsi);
1331 LWS_VISIBLE LWS_EXTERN unsigned char *
1332 libwebsockets_SHA1(const unsigned char *d, size_t n, unsigned char *md);
1334 LWS_VISIBLE LWS_EXTERN int
1335 lws_b64_encode_string(const char *in, int in_len, char *out, int out_size);
1337 LWS_VISIBLE LWS_EXTERN int
1338 lws_b64_decode_string(const char *in, char *out, int out_size);
1340 LWS_VISIBLE LWS_EXTERN const char *
1341 lws_get_library_version(void);
1343 /* access to headers... only valid while headers valid */
1345 LWS_VISIBLE LWS_EXTERN int
1346 lws_hdr_total_length(struct libwebsocket *wsi, enum lws_token_indexes h);
1348 LWS_VISIBLE LWS_EXTERN int
1349 lws_hdr_copy(struct libwebsocket *wsi, char *dest, int len,
1350 enum lws_token_indexes h);
1353 * Note: this is not normally needed as a user api. It's provided in case it is
1354 * useful when integrating with other app poll loop service code.
1357 LWS_VISIBLE LWS_EXTERN int
1358 libwebsocket_read(struct libwebsocket_context *context,
1359 struct libwebsocket *wsi,
1360 unsigned char *buf, size_t len);
1362 #ifndef LWS_NO_EXTENSIONS
1363 LWS_VISIBLE LWS_EXTERN struct libwebsocket_extension *libwebsocket_get_internal_extensions();
1367 * custom allocator support
1369 LWS_VISIBLE LWS_EXTERN void
1370 lws_set_allocator(void *(*realloc)(void *ptr, size_t size));