2 * libwebsockets - small server side websockets and web server implementation
4 * Copyright (C) 2010-2013 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
81 LLL_COUNT = 10 /* set to count of valid flags */
84 extern void _lws_log(int filter, const char *format, ...);
86 /* notice, warn and log are always compiled in */
87 #define lwsl_notice(...) _lws_log(LLL_NOTICE, __VA_ARGS__)
88 #define lwsl_warn(...) _lws_log(LLL_WARN, __VA_ARGS__)
89 #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
97 #define lwsl_info(...) _lws_log(LLL_INFO, __VA_ARGS__)
98 #define lwsl_debug(...) _lws_log(LLL_DEBUG, __VA_ARGS__)
99 #define lwsl_parser(...) _lws_log(LLL_PARSER, __VA_ARGS__)
100 #define lwsl_header(...) _lws_log(LLL_HEADER, __VA_ARGS__)
101 #define lwsl_ext(...) _lws_log(LLL_EXT, __VA_ARGS__)
102 #define lwsl_client(...) _lws_log(LLL_CLIENT, __VA_ARGS__)
103 #define lwsl_latency(...) _lws_log(LLL_LATENCY, __VA_ARGS__)
104 extern void lwsl_hexdump(void *buf, size_t len);
108 #define lwsl_info(...)
109 #define lwsl_debug(...)
110 #define lwsl_parser(...)
111 #define lwsl_header(...)
112 #define lwsl_ext(...)
113 #define lwsl_client(...)
114 #define lwsl_latency(...)
115 #define lwsl_hexdump(a, b)
119 enum libwebsocket_context_options {
120 LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT = 2,
121 LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME = 4,
124 enum libwebsocket_callback_reasons {
125 LWS_CALLBACK_ESTABLISHED,
126 LWS_CALLBACK_CLIENT_CONNECTION_ERROR,
127 LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH,
128 LWS_CALLBACK_CLIENT_ESTABLISHED,
130 LWS_CALLBACK_RECEIVE,
131 LWS_CALLBACK_CLIENT_RECEIVE,
132 LWS_CALLBACK_CLIENT_RECEIVE_PONG,
133 LWS_CALLBACK_CLIENT_WRITEABLE,
134 LWS_CALLBACK_SERVER_WRITEABLE,
136 LWS_CALLBACK_HTTP_FILE_COMPLETION,
137 LWS_CALLBACK_FILTER_NETWORK_CONNECTION,
138 LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION,
139 LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS,
140 LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS,
141 LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION,
142 LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER,
143 LWS_CALLBACK_CONFIRM_EXTENSION_OKAY,
144 LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED,
145 LWS_CALLBACK_PROTOCOL_INIT,
146 LWS_CALLBACK_PROTOCOL_DESTROY,
147 /* external poll() management support */
148 LWS_CALLBACK_ADD_POLL_FD,
149 LWS_CALLBACK_DEL_POLL_FD,
150 LWS_CALLBACK_SET_MODE_POLL_FD,
151 LWS_CALLBACK_CLEAR_MODE_POLL_FD,
154 #ifndef LWS_NO_EXTENSIONS
155 enum libwebsocket_extension_callback_reasons {
156 LWS_EXT_CALLBACK_SERVER_CONTEXT_CONSTRUCT,
157 LWS_EXT_CALLBACK_CLIENT_CONTEXT_CONSTRUCT,
158 LWS_EXT_CALLBACK_SERVER_CONTEXT_DESTRUCT,
159 LWS_EXT_CALLBACK_CLIENT_CONTEXT_DESTRUCT,
160 LWS_EXT_CALLBACK_CONSTRUCT,
161 LWS_EXT_CALLBACK_CLIENT_CONSTRUCT,
162 LWS_EXT_CALLBACK_CHECK_OK_TO_REALLY_CLOSE,
163 LWS_EXT_CALLBACK_CHECK_OK_TO_PROPOSE_EXTENSION,
164 LWS_EXT_CALLBACK_DESTROY,
165 LWS_EXT_CALLBACK_DESTROY_ANY_WSI_CLOSING,
166 LWS_EXT_CALLBACK_ANY_WSI_ESTABLISHED,
167 LWS_EXT_CALLBACK_PACKET_RX_PREPARSE,
168 LWS_EXT_CALLBACK_PACKET_TX_PRESEND,
169 LWS_EXT_CALLBACK_PACKET_TX_DO_SEND,
170 LWS_EXT_CALLBACK_HANDSHAKE_REPLY_TX,
171 LWS_EXT_CALLBACK_FLUSH_PENDING_TX,
172 LWS_EXT_CALLBACK_EXTENDED_PAYLOAD_RX,
173 LWS_EXT_CALLBACK_CAN_PROXY_CLIENT_CONNECTION,
174 LWS_EXT_CALLBACK_1HZ,
175 LWS_EXT_CALLBACK_REQUEST_ON_WRITEABLE,
176 LWS_EXT_CALLBACK_IS_WRITEABLE,
177 LWS_EXT_CALLBACK_PAYLOAD_TX,
178 LWS_EXT_CALLBACK_PAYLOAD_RX,
182 enum libwebsocket_write_protocol {
185 LWS_WRITE_CONTINUATION,
188 /* special 04+ opcodes */
196 LWS_WRITE_NO_FIN = 0x40,
198 * client packet payload goes out on wire unmunged
199 * only useful for security tests since normal servers cannot
200 * decode the content if used
202 LWS_WRITE_CLIENT_IGNORE_XOR_MASK = 0x80
206 * you need these to look at headers that have been parsed if using the
207 * LWS_CALLBACK_FILTER_CONNECTION callback. If a header from the enum
208 * list below is absent, .token = NULL and token_len = 0. Otherwise .token
209 * points to .token_len chars containing that header content.
217 enum lws_token_indexes {
220 WSI_TOKEN_CONNECTION,
235 WSI_TOKEN_EXTENSIONS,
237 /* client receives these */
243 /* use token storage to stash these */
245 _WSI_TOKEN_CLIENT_SENT_PROTOCOLS,
246 _WSI_TOKEN_CLIENT_PEER_ADDRESS,
247 _WSI_TOKEN_CLIENT_URI,
248 _WSI_TOKEN_CLIENT_HOST,
249 _WSI_TOKEN_CLIENT_ORIGIN,
251 /* always last real token index*/
253 /* parser state additions */
256 WSI_TOKEN_SKIPPING_SAW_CR,
257 WSI_PARSING_COMPLETE,
258 WSI_INIT_TOKEN_MUXURL,
265 1000 indicates a normal closure, meaning that the purpose for
266 which the connection was established has been fulfilled.
270 1001 indicates that an endpoint is "going away", such as a server
271 going down or a browser having navigated away from a page.
275 1002 indicates that an endpoint is terminating the connection due
280 1003 indicates that an endpoint is terminating the connection
281 because it has received a type of data it cannot accept (e.g., an
282 endpoint that understands only text data MAY send this if it
283 receives a binary message).
287 Reserved. The specific meaning might be defined in the future.
291 1005 is a reserved value and MUST NOT be set as a status code in a
292 Close control frame by an endpoint. It is designated for use in
293 applications expecting a status code to indicate that no status
294 code was actually present.
298 1006 is a reserved value and MUST NOT be set as a status code in a
299 Close control frame by an endpoint. It is designated for use in
300 applications expecting a status code to indicate that the
301 connection was closed abnormally, e.g., without sending or
302 receiving a Close control frame.
306 1007 indicates that an endpoint is terminating the connection
307 because it has received data within a message that was not
308 consistent with the type of the message (e.g., non-UTF-8 [RFC3629]
309 data within a text message).
313 1008 indicates that an endpoint is terminating the connection
314 because it has received a message that violates its policy. This
315 is a generic status code that can be returned when there is no
316 other more suitable status code (e.g., 1003 or 1009) or if there
317 is a need to hide specific details about the policy.
321 1009 indicates that an endpoint is terminating the connection
322 because it has received a message that is too big for it to
327 1010 indicates that an endpoint (client) is terminating the
328 connection because it has expected the server to negotiate one or
329 more extension, but the server didn't return them in the response
330 message of the WebSocket handshake. The list of extensions that
331 are needed SHOULD appear in the /reason/ part of the Close frame.
332 Note that this status code is not used by the server, because it
333 can fail the WebSocket handshake instead.
337 1011 indicates that a server is terminating the connection because
338 it encountered an unexpected condition that prevented it from
339 fulfilling the request.
343 1015 is a reserved value and MUST NOT be set as a status code in a
344 Close control frame by an endpoint. It is designated for use in
345 applications expecting a status code to indicate that the
346 connection was closed due to a failure to perform a TLS handshake
347 (e.g., the server certificate can't be verified).
350 enum lws_close_status {
351 LWS_CLOSE_STATUS_NOSTATUS = 0,
352 LWS_CLOSE_STATUS_NORMAL = 1000,
353 LWS_CLOSE_STATUS_GOINGAWAY = 1001,
354 LWS_CLOSE_STATUS_PROTOCOL_ERR = 1002,
355 LWS_CLOSE_STATUS_UNACCEPTABLE_OPCODE = 1003,
356 LWS_CLOSE_STATUS_RESERVED = 1004,
357 LWS_CLOSE_STATUS_NO_STATUS = 1005,
358 LWS_CLOSE_STATUS_ABNORMAL_CLOSE = 1006,
359 LWS_CLOSE_STATUS_INVALID_PAYLOAD = 1007,
360 LWS_CLOSE_STATUS_POLICY_VIOLATION = 1008,
361 LWS_CLOSE_STATUS_MESSAGE_TOO_LARGE = 1009,
362 LWS_CLOSE_STATUS_EXTENSION_REQUIRED = 1010,
363 LWS_CLOSE_STATUS_UNEXPECTED_CONDITION = 1011,
364 LWS_CLOSE_STATUS_TLS_FAILURE = 1015,
368 struct libwebsocket_context;
369 /* needed even with extensions disabled for create context */
370 struct libwebsocket_extension;
373 * callback_function() - User server actions
374 * @context: Websockets context
375 * @wsi: Opaque websocket instance pointer
376 * @reason: The reason for the call
377 * @user: Pointer to per-session user data allocated by library
378 * @in: Pointer used for some callback reasons
379 * @len: Length set for some callback reasons
381 * This callback is the way the user controls what is served. All the
382 * protocol detail is hidden and handled by the library.
384 * For each connection / session there is user data allocated that is
385 * pointed to by "user". You set the size of this user data area when
386 * the library is initialized with libwebsocket_create_server.
388 * You get an opportunity to initialize user data when called back with
389 * LWS_CALLBACK_ESTABLISHED reason.
391 * LWS_CALLBACK_ESTABLISHED: after the server completes a handshake with
394 * LWS_CALLBACK_CLIENT_CONNECTION_ERROR: the request client connection has
395 * been unable to complete a handshake with the remote server
397 * LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH: this is the last chance for the
398 * client user code to examine the http headers
399 * and decide to reject the connection. If the
400 * content in the headers is interesting to the
401 * client (url, etc) it needs to copy it out at
402 * this point since it will be destroyed before
403 * the CLIENT_ESTABLISHED call
405 * LWS_CALLBACK_CLIENT_ESTABLISHED: after your client connection completed
406 * a handshake with the remote server
408 * LWS_CALLBACK_CLOSED: when the websocket session ends
410 * LWS_CALLBACK_RECEIVE: data has appeared for this server endpoint from a
411 * remote client, it can be found at *in and is
414 * LWS_CALLBACK_CLIENT_RECEIVE_PONG: if you elected to see PONG packets,
415 * they appear with this callback reason. PONG
416 * packets only exist in 04+ protocol
418 * LWS_CALLBACK_CLIENT_RECEIVE: data has appeared from the server for the
419 * client connection, it can be found at *in and
422 * LWS_CALLBACK_HTTP: an http request has come from a client that is not
423 * asking to upgrade the connection to a websocket
424 * one. This is a chance to serve http content,
425 * for example, to send a script to the client
426 * which will then open the websockets connection.
427 * @in points to the URI path requested and
428 * libwebsockets_serve_http_file() makes it very
429 * simple to send back a file to the client.
430 * Normally after sending the file you are done
431 * with the http connection, since the rest of the
432 * activity will come by websockets from the script
433 * that was delivered by http, so you will want to
434 * return 1; to close and free up the connection.
435 * That's important because it uses a slot in the
436 * total number of client connections allowed set
439 * LWS_CALLBACK_HTTP_FILE_COMPLETION: a file requested to be send down
440 * http link has completed.
442 * LWS_CALLBACK_CLIENT_WRITEABLE:
443 * LWS_CALLBACK_SERVER_WRITEABLE: If you call
444 * libwebsocket_callback_on_writable() on a connection, you will
445 * get one of these callbacks coming when the connection socket
446 * is able to accept another write packet without blocking.
447 * If it already was able to take another packet without blocking,
448 * you'll get this callback at the next call to the service loop
449 * function. Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE
450 * and servers get LWS_CALLBACK_SERVER_WRITEABLE.
452 * LWS_CALLBACK_FILTER_NETWORK_CONNECTION: called when a client connects to
453 * the server at network level; the connection is accepted but then
454 * passed to this callback to decide whether to hang up immediately
455 * or not, based on the client IP. @user contains the connection
456 * socket's descriptor. Return non-zero to terminate
457 * the connection before sending or receiving anything.
458 * Because this happens immediately after the network connection
459 * from the client, there's no websocket protocol selected yet so
460 * this callback is issued only to protocol 0.
462 * LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION: called when the handshake has
463 * been received and parsed from the client, but the response is
464 * not sent yet. Return non-zero to disallow the connection.
465 * @user is a pointer to an array of struct lws_tokens, you can
466 * use the header enums lws_token_indexes from libwebsockets.h
467 * to check for and read the supported header presence and
468 * content before deciding to allow the handshake to proceed or
469 * to kill the connection.
471 * LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS: if configured for
472 * including OpenSSL support, this callback allows your user code
473 * to perform extra SSL_CTX_load_verify_locations() or similar
474 * calls to direct OpenSSL where to find certificates the client
475 * can use to confirm the remote server identity. @user is the
478 * LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS: if configured for
479 * including OpenSSL support, this callback allows your user code
480 * to load extra certifcates into the server which allow it to
481 * verify the validity of certificates returned by clients. @user
482 * is the server's OpenSSL SSL_CTX*
484 * LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION: if the
485 * libwebsockets context was created with the option
486 * LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this
487 * callback is generated during OpenSSL verification of the cert
488 * sent from the client. It is sent to protocol[0] callback as
489 * no protocol has been negotiated on the connection yet.
490 * Notice that the libwebsockets context and wsi are both NULL
491 * during this callback. See
492 * http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
493 * to understand more detail about the OpenSSL callback that
494 * generates this libwebsockets callback and the meanings of the
495 * arguments passed. In this callback, @user is the x509_ctx,
496 * @in is the ssl pointer and @len is preverify_ok
497 * Notice that this callback maintains libwebsocket return
498 * conventions, return 0 to mean the cert is OK or 1 to fail it.
499 * This also means that if you don't handle this callback then
500 * the default callback action of returning 0 allows the client
503 * LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER: this callback happens
504 * when a client handshake is being compiled. @user is NULL,
505 * @in is a char **, it's pointing to a char * which holds the
506 * next location in the header buffer where you can add
507 * headers, and @len is the remaining space in the header buffer,
508 * which is typically some hundreds of bytes. So, to add a canned
509 * cookie, your handler code might look similar to:
511 * char **p = (char **)in;
516 * *p += sprintf(*p, "Cookie: a=b\x0d\x0a");
520 * Notice if you add anything, you just have to take care about
521 * the CRLF on the line you added. Obviously this callback is
522 * optional, if you don't handle it everything is fine.
524 * Notice the callback is coming to protocols[0] all the time,
525 * because there is no specific protocol handshook yet.
527 * LWS_CALLBACK_CONFIRM_EXTENSION_OKAY: When the server handshake code
528 * sees that it does support a requested extension, before
529 * accepting the extension by additing to the list sent back to
530 * the client it gives this callback just to check that it's okay
531 * to use that extension. It calls back to the requested protocol
532 * and with @in being the extension name, @len is 0 and @user is
533 * valid. Note though at this time the ESTABLISHED callback hasn't
534 * happened yet so if you initialize @user content there, @user
535 * content during this callback might not be useful for anything.
536 * Notice this callback comes to protocols[0].
538 * LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED: When a client
539 * connection is being prepared to start a handshake to a server,
540 * each supported extension is checked with protocols[0] callback
541 * with this reason, giving the user code a chance to suppress the
542 * claim to support that extension by returning non-zero. If
543 * unhandled, by default 0 will be returned and the extension
544 * support included in the header to the server. Notice this
545 * callback comes to protocols[0].
547 * LWS_CALLBACK_PROTOCOL_INIT: One-time call per protocol so it can
548 * do initial setup / allocations etc
550 * LWS_CALLBACK_PROTOCOL_DESTROY: One-time call per protocol indicating
551 * this protocol won't get used at all after this callback, the
552 * context is getting destroyed. Take the opportunity to
553 * deallocate everything that was allocated by the protocol.
555 * The next four reasons are optional and only need taking care of if you
556 * will be integrating libwebsockets sockets into an external polling
559 * LWS_CALLBACK_ADD_POLL_FD: libwebsocket deals with its poll() loop
560 * internally, but in the case you are integrating with another
561 * server you will need to have libwebsocket sockets share a
562 * polling array with the other server. This and the other
563 * POLL_FD related callbacks let you put your specialized
564 * poll array interface code in the callback for protocol 0, the
565 * first protocol you support, usually the HTTP protocol in the
566 * serving case. This callback happens when a socket needs to be
567 * added to the polling loop: @user contains the fd, and
568 * @len is the events bitmap (like, POLLIN). If you are using the
569 * internal polling loop (the "service" callback), you can just
570 * ignore these callbacks.
572 * LWS_CALLBACK_DEL_POLL_FD: This callback happens when a socket descriptor
573 * needs to be removed from an external polling array. @user is
574 * the socket desricptor. If you are using the internal polling
575 * loop, you can just ignore it.
577 * LWS_CALLBACK_SET_MODE_POLL_FD: This callback happens when libwebsockets
578 * wants to modify the events for the socket descriptor in @user.
579 * The handler should OR @len on to the events member of the pollfd
580 * struct for this socket descriptor. If you are using the
581 * internal polling loop, you can just ignore it.
583 * LWS_CALLBACK_CLEAR_MODE_POLL_FD: This callback occurs when libwebsockets
584 * wants to modify the events for the socket descriptor in @user.
585 * The handler should AND ~@len on to the events member of the
586 * pollfd struct for this socket descriptor. If you are using the
587 * internal polling loop, you can just ignore it.
589 LWS_EXTERN int callback(struct libwebsocket_context *context,
590 struct libwebsocket *wsi,
591 enum libwebsocket_callback_reasons reason, void *user,
592 void *in, size_t len);
594 typedef int (callback_function)(struct libwebsocket_context *context,
595 struct libwebsocket *wsi,
596 enum libwebsocket_callback_reasons reason, void *user,
597 void *in, size_t len);
599 #ifndef LWS_NO_EXTENSIONS
601 * extension_callback_function() - Hooks to allow extensions to operate
602 * @context: Websockets context
603 * @ext: This extension
604 * @wsi: Opaque websocket instance pointer
605 * @reason: The reason for the call
606 * @user: Pointer to per-session user data allocated by library
607 * @in: Pointer used for some callback reasons
608 * @len: Length set for some callback reasons
610 * Each extension that is active on a particular connection receives
611 * callbacks during the connection lifetime to allow the extension to
612 * operate on websocket data and manage itself.
614 * Libwebsockets takes care of allocating and freeing "user" memory for
615 * each active extension on each connection. That is what is pointed to
616 * by the @user parameter.
618 * LWS_EXT_CALLBACK_CONSTRUCT: called when the server has decided to
619 * select this extension from the list provided by the client,
620 * just before the server will send back the handshake accepting
621 * the connection with this extension active. This gives the
622 * extension a chance to initialize its connection context found
625 * LWS_EXT_CALLBACK_CLIENT_CONSTRUCT: same as LWS_EXT_CALLBACK_CONSTRUCT
626 * but called when client is instantiating this extension. Some
627 * extensions will work the same on client and server side and then
628 * you can just merge handlers for both CONSTRUCTS.
630 * LWS_EXT_CALLBACK_DESTROY: called when the connection the extension was
631 * being used on is about to be closed and deallocated. It's the
632 * last chance for the extension to deallocate anything it has
633 * allocated in the user data (pointed to by @user) before the
634 * user data is deleted. This same callback is used whether you
635 * are in client or server instantiation context.
637 * LWS_EXT_CALLBACK_PACKET_RX_PREPARSE: when this extension was active on
638 * a connection, and a packet of data arrived at the connection,
639 * it is passed to this callback to give the extension a chance to
640 * change the data, eg, decompress it. @user is pointing to the
641 * extension's private connection context data, @in is pointing
642 * to an lws_tokens struct, it consists of a char * pointer called
643 * token, and an int called token_len. At entry, these are
644 * set to point to the received buffer and set to the content
645 * length. If the extension will grow the content, it should use
646 * a new buffer allocated in its private user context data and
647 * set the pointed-to lws_tokens members to point to its buffer.
649 * LWS_EXT_CALLBACK_PACKET_TX_PRESEND: this works the same way as
650 * LWS_EXT_CALLBACK_PACKET_RX_PREPARSE above, except it gives the
651 * extension a chance to change websocket data just before it will
652 * be sent out. Using the same lws_token pointer scheme in @in,
653 * the extension can change the buffer and the length to be
654 * transmitted how it likes. Again if it wants to grow the
655 * buffer safely, it should copy the data into its own buffer and
656 * set the lws_tokens token pointer to it.
658 LWS_EXTERN int extension_callback(struct libwebsocket_context *context,
659 struct libwebsocket_extension *ext,
660 struct libwebsocket *wsi,
661 enum libwebsocket_extension_callback_reasons reason,
662 void *user, void *in, size_t len);
664 typedef int (extension_callback_function)(struct libwebsocket_context *context,
665 struct libwebsocket_extension *ext,
666 struct libwebsocket *wsi,
667 enum libwebsocket_extension_callback_reasons reason,
668 void *user, void *in, size_t len);
672 * struct libwebsocket_protocols - List of protocols and handlers server
674 * @name: Protocol name that must match the one given in the client
675 * Javascript new WebSocket(url, 'protocol') name
676 * @callback: The service callback used for this protocol. It allows the
677 * service action for an entire protocol to be encapsulated in
678 * the protocol-specific callback
679 * @per_session_data_size: Each new connection using this protocol gets
680 * this much memory allocated on connection establishment and
681 * freed on connection takedown. A pointer to this per-connection
682 * allocation is passed into the callback in the 'user' parameter
683 * @rx_buffer_size: if you want atomic frames delivered to the callback, you
684 * should set this to the size of the biggest legal frame that
685 * you support. If the frame size is exceeded, there is no
686 * error, but the buffer will spill to the user callback when
687 * full, which you can detect by using
688 * libwebsockets_remaining_packet_payload(). Notice that you
689 * just talk about frame size here, the LWS_SEND_BUFFER_PRE_PADDING
690 * and post-padding are automatically also allocated on top.
691 * @owning_server: the server init call fills in this opaque pointer when
692 * registering this protocol with the server.
693 * @protocol_index: which protocol we are starting from zero
695 * This structure represents one protocol supported by the server. An
696 * array of these structures is passed to libwebsocket_create_server()
697 * allows as many protocols as you like to be handled by one server.
700 struct libwebsocket_protocols {
702 callback_function *callback;
703 size_t per_session_data_size;
704 size_t rx_buffer_size;
707 * below are filled in on server init and can be left uninitialized,
708 * no need for user to use them directly either
711 struct libwebsocket_context *owning_server;
715 #ifndef LWS_NO_EXTENSIONS
717 * struct libwebsocket_extension - An extension we know how to cope with
719 * @name: Formal extension name, eg, "deflate-stream"
720 * @callback: Service callback
721 * @per_session_data_size: Libwebsockets will auto-malloc this much
722 * memory for the use of the extension, a pointer
723 * to it comes in the @user callback parameter
724 * @per_context_private_data: Optional storage for this extension that
725 * is per-context, so it can track stuff across
726 * all sessions, etc, if it wants
729 struct libwebsocket_extension {
731 extension_callback_function *callback;
732 size_t per_session_data_size;
733 void *per_context_private_data;
738 * struct lws_context_creation_info: parameters to create context with
740 * @port: Port to listen on... you can use 0 to suppress listening on
741 * any port, that's what you want if you are not running a
742 * websocket server at all but just using it as a client
743 * @interface: NULL to bind the listen socket to all interfaces, or the
744 * interface name, eg, "eth2"
745 * @protocols: Array of structures listing supported protocols and a protocol-
746 * specific callback for each one. The list is ended with an
747 * entry that has a NULL callback pointer.
748 * It's not const because we write the owning_server member
749 * @extensions: NULL or array of libwebsocket_extension structs listing the
750 * extensions this context supports. If you configured with
751 * --without-extensions, you should give NULL here.
752 * @ssl_cert_filepath: If libwebsockets was compiled to use ssl, and you want
753 * to listen using SSL, set to the filepath to fetch the
754 * server cert from, otherwise NULL for unencrypted
755 * @ssl_private_key_filepath: filepath to private key if wanting SSL mode,
757 * @ssl_ca_filepath: CA certificate filepath or NULL
758 * @gid: group id to change to after setting listen socket, or -1.
759 * @uid: user id to change to after setting listen socket, or -1.
760 * @options: 0, or LWS_SERVER_OPTION_DEFEAT_CLIENT_MASK
761 * @user: optional user pointer that can be recovered via the context
762 * pointer using libwebsocket_context_user
763 * @ka_time: 0 for no keepalive, otherwise apply this keepalive timeout to
764 * all libwebsocket sockets, client or server
765 * @ka_probes: if ka_time was nonzero, after the timeout expires how many
766 * times to try to get a response from the peer before giving up
767 * and killing the connection
768 * @ka_interval: if ka_time was nonzero, how long to wait before each ka_probes
772 struct lws_context_creation_info {
774 const char *interface;
775 struct libwebsocket_protocols *protocols;
776 struct libwebsocket_extension *extensions;
777 const char *ssl_cert_filepath;
778 const char *ssl_private_key_filepath;
779 const char *ssl_ca_filepath;
782 unsigned int options;
791 void lws_set_log_level(int level,
792 void (*log_emit_function)(int level, const char *line));
795 lwsl_emit_syslog(int level, const char *line);
797 LWS_EXTERN struct libwebsocket_context *
798 libwebsocket_create_context(struct lws_context_creation_info *info);
801 libwebsocket_context_destroy(struct libwebsocket_context *context);
804 libwebsocket_service(struct libwebsocket_context *context, int timeout_ms);
807 libwebsocket_service_fd(struct libwebsocket_context *context,
808 struct pollfd *pollfd);
811 libwebsocket_context_user(struct libwebsocket_context *context);
816 * When sending with websocket protocol (LWS_WRITE_TEXT or LWS_WRITE_BINARY)
817 * the send buffer has to have LWS_SEND_BUFFER_PRE_PADDING bytes valid BEFORE
818 * buf, and LWS_SEND_BUFFER_POST_PADDING bytes valid AFTER (buf + len).
820 * This allows us to add protocol info before and after the data, and send as
821 * one packet on the network without payload copying, for maximum efficiency.
823 * So for example you need this kind of code to use libwebsocket_write with a
826 * char buf[LWS_SEND_BUFFER_PRE_PADDING + 128 + LWS_SEND_BUFFER_POST_PADDING];
828 * // fill your part of the buffer... for example here it's all zeros
829 * memset(&buf[LWS_SEND_BUFFER_PRE_PADDING], 0, 128);
831 * libwebsocket_write(wsi, &buf[LWS_SEND_BUFFER_PRE_PADDING], 128);
833 * When sending LWS_WRITE_HTTP, there is no protocol addition and you can just
834 * use the whole buffer without taking care of the above.
838 * this is the frame nonce plus two header plus 8 length
839 * there's an additional two for mux extension per mux nesting level
840 * 2 byte prepend on close will already fit because control frames cannot use
841 * the big length style
844 #define LWS_SEND_BUFFER_PRE_PADDING (4 + 10 + (2 * MAX_MUX_RECURSION))
845 #define LWS_SEND_BUFFER_POST_PADDING 4
848 libwebsocket_write(struct libwebsocket *wsi, unsigned char *buf, size_t len,
849 enum libwebsocket_write_protocol protocol);
852 libwebsockets_serve_http_file(struct libwebsocket_context *context,
853 struct libwebsocket *wsi, const char *file,
854 const char *content_type);
856 libwebsockets_serve_http_file_fragment(struct libwebsocket_context *context,
857 struct libwebsocket *wsi);
859 LWS_EXTERN const struct libwebsocket_protocols *
860 libwebsockets_get_protocol(struct libwebsocket *wsi);
863 libwebsocket_callback_on_writable(struct libwebsocket_context *context,
864 struct libwebsocket *wsi);
867 libwebsocket_callback_on_writable_all_protocol(
868 const struct libwebsocket_protocols *protocol);
871 libwebsocket_get_socket_fd(struct libwebsocket *wsi);
874 libwebsocket_is_final_fragment(struct libwebsocket *wsi);
876 LWS_EXTERN unsigned char
877 libwebsocket_get_reserved_bits(struct libwebsocket *wsi);
880 libwebsocket_ensure_user_space(struct libwebsocket *wsi);
883 libwebsocket_rx_flow_control(struct libwebsocket *wsi, int enable);
886 libwebsockets_remaining_packet_payload(struct libwebsocket *wsi);
888 LWS_EXTERN struct libwebsocket *
889 libwebsocket_client_connect(struct libwebsocket_context *clients,
896 const char *protocol,
897 int ietf_version_or_minus_one);
899 LWS_EXTERN struct libwebsocket *
900 libwebsocket_client_connect_extended(struct libwebsocket_context *clients,
907 const char *protocol,
908 int ietf_version_or_minus_one,
911 LWS_EXTERN const char *
912 libwebsocket_canonical_hostname(struct libwebsocket_context *context);
916 libwebsockets_get_peer_addresses(struct libwebsocket_context *context,
917 struct libwebsocket *wsi, int fd, char *name, int name_len,
918 char *rip, int rip_len);
921 libwebsockets_hangup_on_client(struct libwebsocket_context *context, int fd);
924 libwebsocket_close_and_free_session(struct libwebsocket_context *context,
925 struct libwebsocket *wsi, enum lws_close_status);
928 libwebsockets_get_random(struct libwebsocket_context *context,
932 lws_daemonize(const char *_lock_path);
935 lws_send_pipe_choked(struct libwebsocket *wsi);
938 lws_frame_is_binary(struct libwebsocket *wsi);
940 LWS_EXTERN unsigned char *
941 libwebsockets_SHA1(const unsigned char *d, size_t n, unsigned char *md);
944 lws_b64_encode_string(const char *in, int in_len, char *out, int out_size);
947 lws_b64_decode_string(const char *in, char *out, int out_size);
949 LWS_EXTERN const char *
950 lws_get_library_version(void);
952 /* access to headers... only valid while headers valid */
955 lws_hdr_total_length(struct libwebsocket *wsi, enum lws_token_indexes h);
958 lws_hdr_copy(struct libwebsocket *wsi, char *dest, int len,
959 enum lws_token_indexes h);
962 * Note: this is not normally needed as a user api. It's provided in case it is
963 * useful when integrating with other app poll loop service code.
967 libwebsocket_read(struct libwebsocket_context *context,
968 struct libwebsocket *wsi,
969 unsigned char *buf, size_t len);
971 #ifndef LWS_NO_EXTENSIONS
972 LWS_EXTERN struct libwebsocket_extension libwebsocket_internal_extensions[];