2 * libwebsockets - small server side websockets and web server implementation
4 * Copyright (C) 2010 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__
23 #define __LIBWEBSOCKET_H__
32 #ifndef WIN32_LEAN_AND_MEAN
33 #define WIN32_LEAN_AND_MEAN
38 #include "../win32port/win32helpers/websock-w32.h"
40 #include "../win32port/win32helpers/gettimeofday.h"
42 #define strcasecmp stricmp
43 #define getdtablesize() 30000
49 #define LWS_EXTERN extern __declspec(dllexport)
51 #define LWS_EXTERN extern __declspec(dllimport)
63 #define LWS_EXTERN extern
66 #define CONTEXT_PORT_NO_LISTEN 0
67 #define MAX_MUX_RECURSION 2
80 LLL_COUNT = 9 /* set to count of valid flags */
83 extern void _lws_log(int filter, const char *format, ...);
85 /* warn and log are always compiled in */
86 #define lwsl_notice(...) _lws_log(LLL_NOTICE, __VA_ARGS__)
87 #define lwsl_warn(...) _lws_log(LLL_WARN, __VA_ARGS__)
88 #define lwsl_err(...) _lws_log(LLL_ERR, __VA_ARGS__)
91 * weaker logging can be deselected at configure time using disable_debug
92 * that gets rid of the overhead of checking while keeping _warn and _err
96 #define lwsl_info(...) _lws_log(LLL_INFO, __VA_ARGS__)
97 #define lwsl_debug(...) _lws_log(LLL_DEBUG, __VA_ARGS__)
98 #define lwsl_parser(...) _lws_log(LLL_PARSER, __VA_ARGS__)
99 #define lwsl_header(...) _lws_log(LLL_HEADER, __VA_ARGS__)
100 #define lwsl_ext(...) _lws_log(LLL_HEADER, __VA_ARGS__)
101 #define lwsl_client(...) _lws_log(LLL_CLIENT, __VA_ARGS__)
102 extern void lwsl_hexdump(void *buf, size_t len);
104 #define lwsl_info(...)
105 #define lwsl_debug(...)
106 #define lwsl_parser(...)
107 #define lwsl_header(...)
108 #define lwsl_ext(...)
109 #define lwsl_client(...)
110 #define lwsl_hexdump(a, b)
113 enum libwebsocket_context_options {
114 LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT = 2,
115 LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME = 4,
118 enum libwebsocket_callback_reasons {
119 LWS_CALLBACK_ESTABLISHED,
120 LWS_CALLBACK_CLIENT_CONNECTION_ERROR,
121 LWS_CALLBACK_CLIENT_ESTABLISHED,
123 LWS_CALLBACK_RECEIVE,
124 LWS_CALLBACK_CLIENT_RECEIVE,
125 LWS_CALLBACK_CLIENT_RECEIVE_PONG,
126 LWS_CALLBACK_CLIENT_WRITEABLE,
127 LWS_CALLBACK_SERVER_WRITEABLE,
129 LWS_CALLBACK_HTTP_FILE_COMPLETION,
130 LWS_CALLBACK_BROADCAST,
131 LWS_CALLBACK_FILTER_NETWORK_CONNECTION,
132 LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION,
133 LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS,
134 LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS,
135 LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION,
136 LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER,
137 LWS_CALLBACK_CONFIRM_EXTENSION_OKAY,
138 LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED,
139 /* external poll() management support */
140 LWS_CALLBACK_ADD_POLL_FD,
141 LWS_CALLBACK_DEL_POLL_FD,
142 LWS_CALLBACK_SET_MODE_POLL_FD,
143 LWS_CALLBACK_CLEAR_MODE_POLL_FD,
146 #ifndef LWS_NO_EXTENSIONS
147 enum libwebsocket_extension_callback_reasons {
148 LWS_EXT_CALLBACK_SERVER_CONTEXT_CONSTRUCT,
149 LWS_EXT_CALLBACK_CLIENT_CONTEXT_CONSTRUCT,
150 LWS_EXT_CALLBACK_SERVER_CONTEXT_DESTRUCT,
151 LWS_EXT_CALLBACK_CLIENT_CONTEXT_DESTRUCT,
152 LWS_EXT_CALLBACK_CONSTRUCT,
153 LWS_EXT_CALLBACK_CLIENT_CONSTRUCT,
154 LWS_EXT_CALLBACK_CHECK_OK_TO_REALLY_CLOSE,
155 LWS_EXT_CALLBACK_CHECK_OK_TO_PROPOSE_EXTENSION,
156 LWS_EXT_CALLBACK_DESTROY,
157 LWS_EXT_CALLBACK_DESTROY_ANY_WSI_CLOSING,
158 LWS_EXT_CALLBACK_ANY_WSI_ESTABLISHED,
159 LWS_EXT_CALLBACK_PACKET_RX_PREPARSE,
160 LWS_EXT_CALLBACK_PACKET_TX_PRESEND,
161 LWS_EXT_CALLBACK_PACKET_TX_DO_SEND,
162 LWS_EXT_CALLBACK_HANDSHAKE_REPLY_TX,
163 LWS_EXT_CALLBACK_FLUSH_PENDING_TX,
164 LWS_EXT_CALLBACK_EXTENDED_PAYLOAD_RX,
165 LWS_EXT_CALLBACK_CAN_PROXY_CLIENT_CONNECTION,
166 LWS_EXT_CALLBACK_1HZ,
167 LWS_EXT_CALLBACK_REQUEST_ON_WRITEABLE,
168 LWS_EXT_CALLBACK_IS_WRITEABLE,
169 LWS_EXT_CALLBACK_PAYLOAD_TX,
170 LWS_EXT_CALLBACK_PAYLOAD_RX,
174 enum libwebsocket_write_protocol {
177 LWS_WRITE_CONTINUATION,
180 /* special 04+ opcodes */
188 LWS_WRITE_NO_FIN = 0x40,
190 * client packet payload goes out on wire unmunged
191 * only useful for security tests since normal servers cannot
192 * decode the content if used
194 LWS_WRITE_CLIENT_IGNORE_XOR_MASK = 0x80
198 * you need these to look at headers that have been parsed if using the
199 * LWS_CALLBACK_FILTER_CONNECTION callback. If a header from the enum
200 * list below is absent, .token = NULL and token_len = 0. Otherwise .token
201 * points to .token_len chars containing that header content.
209 enum lws_token_indexes {
212 WSI_TOKEN_CONNECTION,
227 WSI_TOKEN_EXTENSIONS,
229 /* client receives these */
235 /* always last real token index*/
237 /* parser state additions */
240 WSI_TOKEN_SKIPPING_SAW_CR,
241 WSI_PARSING_COMPLETE,
242 WSI_INIT_TOKEN_MUXURL,
249 1000 indicates a normal closure, meaning that the purpose for
250 which the connection was established has been fulfilled.
254 1001 indicates that an endpoint is "going away", such as a server
255 going down or a browser having navigated away from a page.
259 1002 indicates that an endpoint is terminating the connection due
264 1003 indicates that an endpoint is terminating the connection
265 because it has received a type of data it cannot accept (e.g., an
266 endpoint that understands only text data MAY send this if it
267 receives a binary message).
271 Reserved. The specific meaning might be defined in the future.
275 1005 is a reserved value and MUST NOT be set as a status code in a
276 Close control frame by an endpoint. It is designated for use in
277 applications expecting a status code to indicate that no status
278 code was actually present.
282 1006 is a reserved value and MUST NOT be set as a status code in a
283 Close control frame by an endpoint. It is designated for use in
284 applications expecting a status code to indicate that the
285 connection was closed abnormally, e.g., without sending or
286 receiving a Close control frame.
290 1007 indicates that an endpoint is terminating the connection
291 because it has received data within a message that was not
292 consistent with the type of the message (e.g., non-UTF-8 [RFC3629]
293 data within a text message).
297 1008 indicates that an endpoint is terminating the connection
298 because it has received a message that violates its policy. This
299 is a generic status code that can be returned when there is no
300 other more suitable status code (e.g., 1003 or 1009) or if there
301 is a need to hide specific details about the policy.
305 1009 indicates that an endpoint is terminating the connection
306 because it has received a message that is too big for it to
311 1010 indicates that an endpoint (client) is terminating the
312 connection because it has expected the server to negotiate one or
313 more extension, but the server didn't return them in the response
314 message of the WebSocket handshake. The list of extensions that
315 are needed SHOULD appear in the /reason/ part of the Close frame.
316 Note that this status code is not used by the server, because it
317 can fail the WebSocket handshake instead.
321 1011 indicates that a server is terminating the connection because
322 it encountered an unexpected condition that prevented it from
323 fulfilling the request.
327 1015 is a reserved value and MUST NOT be set as a status code in a
328 Close control frame by an endpoint. It is designated for use in
329 applications expecting a status code to indicate that the
330 connection was closed due to a failure to perform a TLS handshake
331 (e.g., the server certificate can't be verified).
334 enum lws_close_status {
335 LWS_CLOSE_STATUS_NOSTATUS = 0,
336 LWS_CLOSE_STATUS_NORMAL = 1000,
337 LWS_CLOSE_STATUS_GOINGAWAY = 1001,
338 LWS_CLOSE_STATUS_PROTOCOL_ERR = 1002,
339 LWS_CLOSE_STATUS_UNACCEPTABLE_OPCODE = 1003,
340 LWS_CLOSE_STATUS_RESERVED = 1004,
341 LWS_CLOSE_STATUS_NO_STATUS = 1005,
342 LWS_CLOSE_STATUS_ABNORMAL_CLOSE = 1006,
343 LWS_CLOSE_STATUS_INVALID_PAYLOAD = 1007,
344 LWS_CLOSE_STATUS_POLICY_VIOLATION = 1008,
345 LWS_CLOSE_STATUS_MESSAGE_TOO_LARGE = 1009,
346 LWS_CLOSE_STATUS_EXTENSION_REQUIRED = 1010,
347 LWS_CLOSE_STATUS_UNEXPECTED_CONDITION = 1011,
348 LWS_CLOSE_STATUS_TLS_FAILURE = 1015,
352 struct libwebsocket_context;
353 /* needed even with extensions disabled for create context */
354 struct libwebsocket_extension;
357 * callback_function() - User server actions
358 * @context: Websockets context
359 * @wsi: Opaque websocket instance pointer
360 * @reason: The reason for the call
361 * @user: Pointer to per-session user data allocated by library
362 * @in: Pointer used for some callback reasons
363 * @len: Length set for some callback reasons
365 * This callback is the way the user controls what is served. All the
366 * protocol detail is hidden and handled by the library.
368 * For each connection / session there is user data allocated that is
369 * pointed to by "user". You set the size of this user data area when
370 * the library is initialized with libwebsocket_create_server.
372 * You get an opportunity to initialize user data when called back with
373 * LWS_CALLBACK_ESTABLISHED reason.
375 * LWS_CALLBACK_ESTABLISHED: after the server completes a handshake with
378 * LWS_CALLBACK_CLIENT_CONNECTION_ERROR: the request client connection has
379 * been unable to complete a handshake with the remote server
381 * LWS_CALLBACK_CLIENT_ESTABLISHED: after your client connection completed
382 * a handshake with the remote server
384 * LWS_CALLBACK_CLOSED: when the websocket session ends
386 * LWS_CALLBACK_BROADCAST: signal to send to client (you would use
387 * libwebsocket_write() taking care about the
388 * special buffer requirements
390 * LWS_CALLBACK_RECEIVE: data has appeared for this server endpoint from a
391 * remote client, it can be found at *in and is
394 * LWS_CALLBACK_CLIENT_RECEIVE_PONG: if you elected to see PONG packets,
395 * they appear with this callback reason. PONG
396 * packets only exist in 04+ protocol
398 * LWS_CALLBACK_CLIENT_RECEIVE: data has appeared from the server for the
399 * client connection, it can be found at *in and
402 * LWS_CALLBACK_HTTP: an http request has come from a client that is not
403 * asking to upgrade the connection to a websocket
404 * one. This is a chance to serve http content,
405 * for example, to send a script to the client
406 * which will then open the websockets connection.
407 * @in points to the URI path requested and
408 * libwebsockets_serve_http_file() makes it very
409 * simple to send back a file to the client.
410 * Normally after sending the file you are done
411 * with the http connection, since the rest of the
412 * activity will come by websockets from the script
413 * that was delivered by http, so you will want to
414 * return 1; to close and free up the connection.
415 * That's important because it uses a slot in the
416 * total number of client connections allowed set
419 * LWS_CALLBACK_HTTP_FILE_COMPLETION: a file requested to be send down
420 * http link has completed.
422 * LWS_CALLBACK_CLIENT_WRITEABLE:
423 * LWS_CALLBACK_SERVER_WRITEABLE: If you call
424 * libwebsocket_callback_on_writable() on a connection, you will
425 * get one of these callbacks coming when the connection socket
426 * is able to accept another write packet without blocking.
427 * If it already was able to take another packet without blocking,
428 * you'll get this callback at the next call to the service loop
429 * function. Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE
430 * and servers get LWS_CALLBACK_SERVER_WRITEABLE.
432 * LWS_CALLBACK_FILTER_NETWORK_CONNECTION: called when a client connects to
433 * the server at network level; the connection is accepted but then
434 * passed to this callback to decide whether to hang up immediately
435 * or not, based on the client IP. @user contains the connection
436 * socket's descriptor. Return non-zero to terminate
437 * the connection before sending or receiving anything.
438 * Because this happens immediately after the network connection
439 * from the client, there's no websocket protocol selected yet so
440 * this callback is issued only to protocol 0.
442 * LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION: called when the handshake has
443 * been received and parsed from the client, but the response is
444 * not sent yet. Return non-zero to disallow the connection.
445 * @user is a pointer to an array of struct lws_tokens, you can
446 * use the header enums lws_token_indexes from libwebsockets.h
447 * to check for and read the supported header presence and
448 * content before deciding to allow the handshake to proceed or
449 * to kill the connection.
451 * LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS: if configured for
452 * including OpenSSL support, this callback allows your user code
453 * to perform extra SSL_CTX_load_verify_locations() or similar
454 * calls to direct OpenSSL where to find certificates the client
455 * can use to confirm the remote server identity. @user is the
458 * LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS: if configured for
459 * including OpenSSL support, this callback allows your user code
460 * to load extra certifcates into the server which allow it to
461 * verify the validity of certificates returned by clients. @user
462 * is the server's OpenSSL SSL_CTX*
464 * LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION: if the
465 * libwebsockets context was created with the option
466 * LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this
467 * callback is generated during OpenSSL verification of the cert
468 * sent from the client. It is sent to protocol[0] callback as
469 * no protocol has been negotiated on the connection yet.
470 * Notice that the libwebsockets context and wsi are both NULL
471 * during this callback. See
472 * http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
473 * to understand more detail about the OpenSSL callback that
474 * generates this libwebsockets callback and the meanings of the
475 * arguments passed. In this callback, @user is the x509_ctx,
476 * @in is the ssl pointer and @len is preverify_ok
477 * Notice that this callback maintains libwebsocket return
478 * conventions, return 0 to mean the cert is OK or 1 to fail it.
479 * This also means that if you don't handle this callback then
480 * the default callback action of returning 0 allows the client
483 * LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER: this callback happens
484 * when a client handshake is being compiled. @user is NULL,
485 * @in is a char **, it's pointing to a char * which holds the
486 * next location in the header buffer where you can add
487 * headers, and @len is the remaining space in the header buffer,
488 * which is typically some hundreds of bytes. So, to add a canned
489 * cookie, your handler code might look similar to:
491 * char **p = (char **)in;
496 * *p += sprintf(*p, "Cookie: a=b\x0d\x0a");
500 * Notice if you add anything, you just have to take care about
501 * the CRLF on the line you added. Obviously this callback is
502 * optional, if you don't handle it everything is fine.
504 * Notice the callback is coming to protocols[0] all the time,
505 * because there is no specific protocol handshook yet.
507 * LWS_CALLBACK_CONFIRM_EXTENSION_OKAY: When the server handshake code
508 * sees that it does support a requested extension, before
509 * accepting the extension by additing to the list sent back to
510 * the client it gives this callback just to check that it's okay
511 * to use that extension. It calls back to the requested protocol
512 * and with @in being the extension name, @len is 0 and @user is
513 * valid. Note though at this time the ESTABLISHED callback hasn't
514 * happened yet so if you initialize @user content there, @user
515 * content during this callback might not be useful for anything.
516 * Notice this callback comes to protocols[0].
518 * LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED: When a client
519 * connection is being prepared to start a handshake to a server,
520 * each supported extension is checked with protocols[0] callback
521 * with this reason, giving the user code a chance to suppress the
522 * claim to support that extension by returning non-zero. If
523 * unhandled, by default 0 will be returned and the extension
524 * support included in the header to the server. Notice this
525 * callback comes to protocols[0].
527 * The next four reasons are optional and only need taking care of if you
528 * will be integrating libwebsockets sockets into an external polling
531 * LWS_CALLBACK_ADD_POLL_FD: libwebsocket deals with its poll() loop
532 * internally, but in the case you are integrating with another
533 * server you will need to have libwebsocket sockets share a
534 * polling array with the other server. This and the other
535 * POLL_FD related callbacks let you put your specialized
536 * poll array interface code in the callback for protocol 0, the
537 * first protocol you support, usually the HTTP protocol in the
538 * serving case. This callback happens when a socket needs to be
539 * added to the polling loop: @user contains the fd, and
540 * @len is the events bitmap (like, POLLIN). If you are using the
541 * internal polling loop (the "service" callback), you can just
542 * ignore these callbacks.
544 * LWS_CALLBACK_DEL_POLL_FD: This callback happens when a socket descriptor
545 * needs to be removed from an external polling array. @user is
546 * the socket desricptor. If you are using the internal polling
547 * loop, you can just ignore it.
549 * LWS_CALLBACK_SET_MODE_POLL_FD: This callback happens when libwebsockets
550 * wants to modify the events for the socket descriptor in @user.
551 * The handler should OR @len on to the events member of the pollfd
552 * struct for this socket descriptor. If you are using the
553 * internal polling loop, you can just ignore it.
555 * LWS_CALLBACK_CLEAR_MODE_POLL_FD: This callback occurs when libwebsockets
556 * wants to modify the events for the socket descriptor in @user.
557 * The handler should AND ~@len on to the events member of the
558 * pollfd struct for this socket descriptor. If you are using the
559 * internal polling loop, you can just ignore it.
561 LWS_EXTERN int callback(struct libwebsocket_context * context,
562 struct libwebsocket *wsi,
563 enum libwebsocket_callback_reasons reason, void *user,
564 void *in, size_t len);
566 typedef int (callback_function)(struct libwebsocket_context * context,
567 struct libwebsocket *wsi,
568 enum libwebsocket_callback_reasons reason, void *user,
569 void *in, size_t len);
571 #ifndef LWS_NO_EXTENSIONS
573 * extension_callback_function() - Hooks to allow extensions to operate
574 * @context: Websockets context
575 * @ext: This extension
576 * @wsi: Opaque websocket instance pointer
577 * @reason: The reason for the call
578 * @user: Pointer to per-session user data allocated by library
579 * @in: Pointer used for some callback reasons
580 * @len: Length set for some callback reasons
582 * Each extension that is active on a particular connection receives
583 * callbacks during the connection lifetime to allow the extension to
584 * operate on websocket data and manage itself.
586 * Libwebsockets takes care of allocating and freeing "user" memory for
587 * each active extension on each connection. That is what is pointed to
588 * by the @user parameter.
590 * LWS_EXT_CALLBACK_CONSTRUCT: called when the server has decided to
591 * select this extension from the list provided by the client,
592 * just before the server will send back the handshake accepting
593 * the connection with this extension active. This gives the
594 * extension a chance to initialize its connection context found
597 * LWS_EXT_CALLBACK_CLIENT_CONSTRUCT: same as LWS_EXT_CALLBACK_CONSTRUCT
598 * but called when client is instantiating this extension. Some
599 * extensions will work the same on client and server side and then
600 * you can just merge handlers for both CONSTRUCTS.
602 * LWS_EXT_CALLBACK_DESTROY: called when the connection the extension was
603 * being used on is about to be closed and deallocated. It's the
604 * last chance for the extension to deallocate anything it has
605 * allocated in the user data (pointed to by @user) before the
606 * user data is deleted. This same callback is used whether you
607 * are in client or server instantiation context.
609 * LWS_EXT_CALLBACK_PACKET_RX_PREPARSE: when this extension was active on
610 * a connection, and a packet of data arrived at the connection,
611 * it is passed to this callback to give the extension a chance to
612 * change the data, eg, decompress it. @user is pointing to the
613 * extension's private connection context data, @in is pointing
614 * to an lws_tokens struct, it consists of a char * pointer called
615 * token, and an int called token_len. At entry, these are
616 * set to point to the received buffer and set to the content
617 * length. If the extension will grow the content, it should use
618 * a new buffer allocated in its private user context data and
619 * set the pointed-to lws_tokens members to point to its buffer.
621 * LWS_EXT_CALLBACK_PACKET_TX_PRESEND: this works the same way as
622 * LWS_EXT_CALLBACK_PACKET_RX_PREPARSE above, except it gives the
623 * extension a chance to change websocket data just before it will
624 * be sent out. Using the same lws_token pointer scheme in @in,
625 * the extension can change the buffer and the length to be
626 * transmitted how it likes. Again if it wants to grow the
627 * buffer safely, it should copy the data into its own buffer and
628 * set the lws_tokens token pointer to it.
630 LWS_EXTERN int extension_callback(struct libwebsocket_context * context,
631 struct libwebsocket_extension *ext,
632 struct libwebsocket *wsi,
633 enum libwebsocket_extension_callback_reasons reason, void *user,
634 void *in, size_t len);
636 typedef int (extension_callback_function)(struct libwebsocket_context * context,
637 struct libwebsocket_extension *ext,
638 struct libwebsocket *wsi,
639 enum libwebsocket_extension_callback_reasons reason, void *user,
640 void *in, size_t len);
644 * struct libwebsocket_protocols - List of protocols and handlers server
646 * @name: Protocol name that must match the one given in the client
647 * Javascript new WebSocket(url, 'protocol') name
648 * @callback: The service callback used for this protocol. It allows the
649 * service action for an entire protocol to be encapsulated in
650 * the protocol-specific callback
651 * @per_session_data_size: Each new connection using this protocol gets
652 * this much memory allocated on connection establishment and
653 * freed on connection takedown. A pointer to this per-connection
654 * allocation is passed into the callback in the 'user' parameter
655 * @owning_server: the server init call fills in this opaque pointer when
656 * registering this protocol with the server.
657 * @broadcast_socket_port: the server init call fills this in with the
658 * localhost port number used to forward broadcasts for this
660 * @broadcast_socket_user_fd: the server init call fills this in ... the main()
661 * process context can write to this socket to perform broadcasts
662 * (use the libwebsockets_broadcast() api to do this instead,
663 * it works from any process context)
664 * @protocol_index: which protocol we are starting from zero
666 * This structure represents one protocol supported by the server. An
667 * array of these structures is passed to libwebsocket_create_server()
668 * allows as many protocols as you like to be handled by one server.
671 struct libwebsocket_protocols {
673 callback_function *callback;
674 size_t per_session_data_size;
677 * below are filled in on server init and can be left uninitialized,
678 * no need for user to use them directly either
681 struct libwebsocket_context *owning_server;
682 int broadcast_socket_port;
683 int broadcast_socket_user_fd;
687 #ifndef LWS_NO_EXTENSIONS
689 * struct libwebsocket_extension - An extension we know how to cope with
691 * @name: Formal extension name, eg, "deflate-stream"
692 * @callback: Service callback
693 * @per_session_data_size: Libwebsockets will auto-malloc this much
694 * memory for the use of the extension, a pointer
695 * to it comes in the @user callback parameter
696 * @per_context_private_data: Optional storage for this externsion that
697 * is per-context, so it can track stuff across
698 * all sessions, etc, if it wants
701 struct libwebsocket_extension {
703 extension_callback_function *callback;
704 size_t per_session_data_size;
705 void * per_context_private_data;
710 void lws_set_log_level(int level, void (*log_emit_function)(int level, const char *line));
713 lwsl_emit_syslog(int level, const char *line);
715 LWS_EXTERN struct libwebsocket_context *
716 libwebsocket_create_context(int port, const char * interf,
717 struct libwebsocket_protocols *protocols,
718 struct libwebsocket_extension *extensions,
719 const char *ssl_cert_filepath,
720 const char *ssl_private_key_filepath,
721 const char *ssl_ca_filepath,
723 unsigned int options, void *user);
726 libwebsocket_context_destroy(struct libwebsocket_context *context);
729 libwebsockets_fork_service_loop(struct libwebsocket_context *context);
732 libwebsocket_service(struct libwebsocket_context *context, int timeout_ms);
735 libwebsocket_service_fd(struct libwebsocket_context *context,
736 struct pollfd *pollfd);
739 libwebsocket_context_user(struct libwebsocket_context *context);
744 * When sending with websocket protocol (LWS_WRITE_TEXT or LWS_WRITE_BINARY)
745 * the send buffer has to have LWS_SEND_BUFFER_PRE_PADDING bytes valid BEFORE
746 * buf, and LWS_SEND_BUFFER_POST_PADDING bytes valid AFTER (buf + len).
748 * This allows us to add protocol info before and after the data, and send as
749 * one packet on the network without payload copying, for maximum efficiency.
751 * So for example you need this kind of code to use libwebsocket_write with a
754 * char buf[LWS_SEND_BUFFER_PRE_PADDING + 128 + LWS_SEND_BUFFER_POST_PADDING];
756 * // fill your part of the buffer... for example here it's all zeros
757 * memset(&buf[LWS_SEND_BUFFER_PRE_PADDING], 0, 128);
759 * libwebsocket_write(wsi, &buf[LWS_SEND_BUFFER_PRE_PADDING], 128);
761 * When sending LWS_WRITE_HTTP, there is no protocol addition and you can just
762 * use the whole buffer without taking care of the above.
766 * this is the frame nonce plus two header plus 8 length
767 * there's an additional two for mux extension per mux nesting level
768 * 2 byte prepend on close will already fit because control frames cannot use
769 * the big length style
772 #define LWS_SEND_BUFFER_PRE_PADDING (4 + 10 + (2 * MAX_MUX_RECURSION))
773 #define LWS_SEND_BUFFER_POST_PADDING 4
776 libwebsocket_write(struct libwebsocket *wsi, unsigned char *buf, size_t len,
777 enum libwebsocket_write_protocol protocol);
780 libwebsockets_serve_http_file(struct libwebsocket_context *context,
781 struct libwebsocket *wsi, const char *file,
782 const char *content_type);
784 libwebsockets_serve_http_file_fragment(struct libwebsocket_context *context,
785 struct libwebsocket *wsi);
787 /* notice - you need the pre- and post- padding allocation for buf below */
790 libwebsockets_broadcast(const struct libwebsocket_protocols *protocol,
791 unsigned char *buf, size_t len);
793 /* notice - you need the pre- and post- padding allocation for buf below */
796 libwebsockets_broadcast_foreign(struct libwebsocket_protocols *protocol,
797 unsigned char *buf, size_t len);
799 LWS_EXTERN const struct libwebsocket_protocols *
800 libwebsockets_get_protocol(struct libwebsocket *wsi);
803 libwebsocket_callback_on_writable(struct libwebsocket_context *context,
804 struct libwebsocket *wsi);
807 libwebsocket_callback_on_writable_all_protocol(
808 const struct libwebsocket_protocols *protocol);
811 libwebsocket_get_socket_fd(struct libwebsocket *wsi);
814 libwebsocket_is_final_fragment(struct libwebsocket *wsi);
816 LWS_EXTERN unsigned char
817 libwebsocket_get_reserved_bits(struct libwebsocket *wsi);
820 libwebsocket_ensure_user_space(struct libwebsocket *wsi);
823 libwebsocket_rx_flow_control(struct libwebsocket *wsi, int enable);
826 libwebsockets_remaining_packet_payload(struct libwebsocket *wsi);
828 LWS_EXTERN struct libwebsocket *
829 libwebsocket_client_connect(struct libwebsocket_context *clients,
836 const char *protocol,
837 int ietf_version_or_minus_one);
839 LWS_EXTERN struct libwebsocket *
840 libwebsocket_client_connect_extended(struct libwebsocket_context *clients,
847 const char *protocol,
848 int ietf_version_or_minus_one,
851 LWS_EXTERN const char *
852 libwebsocket_canonical_hostname(struct libwebsocket_context *context);
856 libwebsockets_get_peer_addresses(int fd, char *name, int name_len,
857 char *rip, int rip_len);
860 libwebsockets_hangup_on_client(struct libwebsocket_context *context, int fd);
863 libwebsocket_close_and_free_session(struct libwebsocket_context *context,
864 struct libwebsocket *wsi, enum lws_close_status);
867 libwebsockets_get_random(struct libwebsocket_context *context,
871 lws_daemonize(const char *_lock_path);
874 lws_send_pipe_choked(struct libwebsocket *wsi);
877 lws_frame_is_binary(struct libwebsocket *wsi);
879 LWS_EXTERN unsigned char *
880 libwebsockets_SHA1(const unsigned char *d, size_t n, unsigned char *md);
883 lws_b64_encode_string(const char *in, int in_len, char *out, int out_size);
886 lws_b64_decode_string(const char *in, char *out, int out_size);
889 * Note: this is not normally needed as a user api. It's provided in case it is
890 * useful when integrating with other app poll loop service code.
894 libwebsocket_read(struct libwebsocket_context *context,
895 struct libwebsocket *wsi,
896 unsigned char *buf, size_t len);
898 #ifndef LWS_NO_EXTENSIONS
899 LWS_EXTERN struct libwebsocket_extension libwebsocket_internal_extensions[];