1 <h2>lws_client_reset - retarget a connected wsi to start over with a new connection (ie, redirect) this only works if still in HTTP, ie, not upgraded yet</h2>
3 <b>lws_client_reset</b>
4 (<i>struct lws *</i> <b>wsi</b>,
6 <i>const char *</i> <b>address</b>,
7 <i>int</i> <b>port</b>,
8 <i>const char *</i> <b>path</b>,
9 <i>const char *</i> <b>host</b>)
19 network address of the new server
27 uri path to connect to on the new server
31 host header to send to the new server
34 <h2>lws_client_connect_via_info - Connect to another websocket server</h2>
36 <b>lws_client_connect_via_info</b>
37 (<i>struct lws_client_connect_info *</i> <b>i</b>)
41 <dd>pointer to lws_client_connect_info struct
45 This function creates a connection to a remote server
48 <h2>lws_client_connect_extended - Connect to another websocket server DEPRECATED use lws_client_connect_via_info</h2>
50 <b>lws_client_connect_extended</b>
51 (<i>struct lws_context *</i> <b>context</b>,
52 <i>const char *</i> <b>address</b>,
53 <i>int</i> <b>port</b>,
54 <i>int</i> <b>ssl_connection</b>,
55 <i>const char *</i> <b>path</b>,
56 <i>const char *</i> <b>host</b>,
57 <i>const char *</i> <b>origin</b>,
58 <i>const char *</i> <b>protocol</b>,
59 <i>int</i> <b>ietf_version_or_minus_one</b>,
60 <i>void *</i> <b>userdata</b>)
66 <dd>Remote server address, eg, "myserver.com"
68 <dd>Port to connect to on the remote server, eg, 80
69 <dt><b>ssl_connection</b>
70 <dd>0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self
73 <dd>Websocket path on server
75 <dd>Hostname on server
77 <dd>Socket origin name
79 <dd>Comma-separated list of protocols being asked for from
80 the server, or just one. The server will pick the one it
82 <dt><b>ietf_version_or_minus_one</b>
83 <dd>-1 to ask to connect using the default, latest
84 protocol supported, or the specific protocol ordinal
86 <dd>Pre-allocated user data
90 This function creates a connection to a remote server
93 <h2>lws_client_connect - Connect to another websocket server DEPRECATED use lws_client_connect_via_info</h2>
95 <b>lws_client_connect</b>
96 (<i>struct lws_context *</i> <b>context</b>,
97 <i>const char *</i> <b>address</b>,
98 <i>int</i> <b>port</b>,
99 <i>int</i> <b>ssl_connection</b>,
100 <i>const char *</i> <b>path</b>,
101 <i>const char *</i> <b>host</b>,
102 <i>const char *</i> <b>origin</b>,
103 <i>const char *</i> <b>protocol</b>,
104 <i>int</i> <b>ietf_version_or_minus_one</b>)
108 <dd>Websocket context
110 <dd>Remote server address, eg, "myserver.com"
112 <dd>Port to connect to on the remote server, eg, 80
113 <dt><b>ssl_connection</b>
114 <dd>0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self
117 <dd>Websocket path on server
119 <dd>Hostname on server
121 <dd>Socket origin name
123 <dd>Comma-separated list of protocols being asked for from
124 the server, or just one. The server will pick the one it
125 likes best. If you don't want to specify a protocol, which is
126 legal, use NULL here.
127 <dt><b>ietf_version_or_minus_one</b>
128 <dd>-1 to ask to connect using the default, latest
129 protocol supported, or the specific protocol ordinal
133 This function creates a connection to a remote server
136 <h2>lws_http_transaction_completed_client - wait for new http transaction or close</h2>
137 <i>int LWS_WARN_UNUSED_RESULT</i>
138 <b>lws_http_transaction_completed_client</b>
139 (<i>struct lws *</i> <b>wsi</b>)
143 <dd>websocket connection
147 Returns 1 if the HTTP connection must close now
148 Returns 0 and resets connection to wait for new HTTP header /
149 transaction if possible
152 <h2>lws_get_library_version - </h2>
154 <b>lws_get_library_version</b>
155 (<i></i> <b>void</b>)
164 returns a const char * to a string like "1.1 178d78c"
165 representing the library version followed by the git head hash it
169 <h2>lws_create_context - Create the websocket handler</h2>
170 <i>struct lws_context *</i>
171 <b>lws_create_context</b>
172 (<i>struct lws_context_creation_info *</i> <b>info</b>)
176 <dd>pointer to struct with parameters
180 This function creates the listening socket (if serving) and takes care
181 of all initialization in one step.
183 After initialization, it returns a struct lws_context * that
184 represents this server. After calling, user code needs to take care
185 of calling <b>lws_service</b> with the context pointer to get the
186 server's sockets serviced. This must be done in the same process
187 context as the initialization call.
189 The protocol callback functions are called for a handful of events
190 including http requests coming in, websocket connections becoming
191 established, and data arriving; it's also called periodically to allow
194 HTTP requests are sent always to the FIRST protocol in <tt><b>protocol</b></tt>, since
195 at that time websocket protocol has not been negotiated. Other
196 protocols after the first one never see any HTTP callack activity.
198 The server created is a simple http server by default; part of the
199 websocket standard is upgrading this http connection to a websocket one.
201 This allows the same server to provide files like scripts and favicon /
202 images or whatever over http and dynamic data over websockets all in
203 one place; they're all handled in the user callback.
206 <h2>lws_context_destroy - Destroy the websocket context</h2>
208 <b>lws_context_destroy</b>
209 (<i>struct lws_context *</i> <b>context</b>)
213 <dd>Websocket context
217 This function closes any active connections and then frees the
218 context. After calling this, any further use of the context is
222 <h2>lws_set_extension_option - </h2>
224 <b>lws_set_extension_option</b>
225 (<i>struct lws *</i> <b>wsi</b>,
226 <i>const char *</i> <b>ext_name</b>,
227 <i>const char *</i> <b>opt_name</b>,
228 <i>const char *</i> <b>opt_val</b>)
232 <dd>websocket connection
234 <dd>name of ext, like "permessage-deflate"
236 <dd>name of option, like "rx_buf_size"
238 <dd>value to set option to
241 <h2>lws_return_http_status - Return simple http status</h2>
243 <b>lws_return_http_status</b>
244 (<i>struct lws *</i> <b>wsi</b>,
245 <i>unsigned int</i> <b>code</b>,
246 <i>const char *</i> <b>html_body</b>)
250 <dd>Websocket instance (available from user callback)
252 <dd>Status index, eg, 404
254 <dd>User-readable HTML description < 1KB, or NULL
258 Helper to report HTTP errors back to the client cleanly and
262 <h2>lws_set_timeout - marks the wsi as subject to a timeout</h2>
264 <b>lws_set_timeout</b>
265 (<i>struct lws *</i> <b>wsi</b>,
266 <i>enum pending_timeout</i> <b>reason</b>,
267 <i>int</i> <b>secs</b>)
271 <dd>Websocket connection instance
280 You will not need this unless you are doing something special
283 <h2>lws_get_peer_addresses - Get client address information</h2>
285 <b>lws_get_peer_addresses</b>
286 (<i>struct lws *</i> <b>wsi</b>,
287 <i>lws_sockfd_type</i> <b>fd</b>,
288 <i>char *</i> <b>name</b>,
289 <i>int</i> <b>name_len</b>,
290 <i>char *</i> <b>rip</b>,
291 <i>int</i> <b>rip_len</b>)
295 <dd>Local struct lws associated with
297 <dd>Connection socket descriptor
299 <dd>Buffer to take client address name
301 <dd>Length of client address name buffer
303 <dd>Buffer to take client address IP dotted quad
305 <dd>Length of client address IP buffer
309 This function fills in <tt><b>name</b></tt> and <tt><b>rip</b></tt> with the name and IP of
310 the client connected with socket descriptor <tt><b>fd</b></tt>. Names may be
311 truncated if there is not enough room. If either cannot be
312 determined, they will be returned as valid zero-length strings.
315 <h2>lws_context_user - get the user data associated with the context</h2>
316 <i>LWS_EXTERN void *</i>
317 <b>lws_context_user</b>
318 (<i>struct lws_context *</i> <b>context</b>)
322 <dd>Websocket context
326 This returns the optional user allocation that can be attached to
327 the context the sockets live in at context_create time. It's a way
328 to let all sockets serviced in the same context share data without
329 using globals statics in the user code.
332 <h2>lws_callback_all_protocol - Callback all connections using the given protocol with the given reason</h2>
334 <b>lws_callback_all_protocol</b>
335 (<i>struct lws_context *</i> <b>context</b>,
336 <i>const struct lws_protocols *</i> <b>protocol</b>,
337 <i>int</i> <b>reason</b>)
341 <dd>Protocol whose connections will get callbacks
343 <dd>Callback reason index
346 <h2>lws_callback_all_protocol_vhost - Callback all connections using the given protocol with the given reason</h2>
348 <b>lws_callback_all_protocol_vhost</b>
349 (<i>struct lws_vhost *</i> <b>vh</b>,
350 <i>const struct lws_protocols *</i> <b>protocol</b>,
351 <i>int</i> <b>reason</b>)
355 <dd>Vhost whose connections will get callbacks
357 <dd>Which protocol to match
359 <dd>Callback reason index
362 <h2>lws_get_socket_fd - returns the socket file descriptor</h2>
364 <b>lws_get_socket_fd</b>
365 (<i>struct lws *</i> <b>wsi</b>)
369 <dd>Websocket connection instance
374 You will not need this unless you are doing something special
377 <h2>lws_rx_flow_control - Enable and disable socket servicing for received packets.</h2>
379 <b>lws_rx_flow_control</b>
380 (<i>struct lws *</i> <b>wsi</b>,
381 <i>int</i> <b>enable</b>)
385 <dd>Websocket connection instance to get callback for
387 <dd>0 = disable read servicing for this connection, 1 = enable
392 If the output side of a server process becomes choked, this allows flow
393 control for the input side.
396 <h2>lws_rx_flow_allow_all_protocol - Allow all connections with this protocol to receive</h2>
398 <b>lws_rx_flow_allow_all_protocol</b>
399 (<i>const struct lws_context *</i> <b>context</b>,
400 <i>const struct lws_protocols *</i> <b>protocol</b>)
404 <dd>all connections using this protocol will be allowed to receive
409 When the user server code realizes it can accept more input, it can
410 call this to have the RX flow restriction removed from all connections using
414 <h2>lws_canonical_hostname - returns this host's hostname</h2>
416 <b>lws_canonical_hostname</b>
417 (<i>struct lws_context *</i> <b>context</b>)
421 <dd>Websocket context
426 This is typically used by client code to fill in the host parameter
427 when making a client connection. You can only call it after the context
431 <h2>lws_set_proxy - Setups proxy to lws_context.</h2>
434 (<i>struct lws_vhost *</i> <b>vhost</b>,
435 <i>const char *</i> <b>proxy</b>)
439 <dd>pointer to c string containing proxy in format address:port
443 Returns 0 if proxy string was parsed and proxy was setup.
444 Returns -1 if <tt><b>proxy</b></tt> is NULL or has incorrect format.
446 This is only required if your OS does not provide the http_proxy
447 environment variable (eg, OSX)
449 IMPORTANT! You should call this function right after creation of the
450 lws_context and before call to connect. If you call this
451 function after connect behavior is undefined.
452 This function will override proxy settings made on lws_context
453 creation with <b>genenv</b> call.
456 <h2>lws_get_protocol - Returns a protocol pointer from a websocket connection.</h2>
457 <i>const struct lws_protocols *</i>
458 <b>lws_get_protocol</b>
459 (<i>struct lws *</i> <b>wsi</b>)
463 <dd>pointer to struct websocket you want to know the protocol of
468 Some apis can act on all live connections of a given protocol,
469 this is how you can get a pointer to the active protocol if needed.
472 <h2>lwsl_timestamp - </h2>
474 <b>lwsl_timestamp</b>
475 (<i>int</i> <b>level</b>,
476 <i>char *</i> <b>p</b>,
477 <i>int</i> <b>len</b>)
483 <dd>char * buffer to take timestamp
489 returns length written in p
492 <h2>lws_set_log_level - Set the logging bitfield</h2>
494 <b>lws_set_log_level</b>
495 (<i>int</i> <b>level</b>,
496 <i>void (*</i><b>func</b>) <i>(int level, const char *line)</i>)
500 <dd>OR together the LLL_ debug contexts you want output from
504 log level defaults to "err", "warn" and "notice" contexts enabled and
508 <h2>lws_is_ssl - Find out if connection is using SSL</h2>
511 (<i>struct lws *</i> <b>wsi</b>)
515 <dd>websocket connection to check
519 Returns 0 if the connection is not using SSL, 1 if using SSL and
520 using verified cert, and 2 if using SSL but the cert was not
521 checked (appears for client wsi told to skip check on connection)
524 <h2>lws_partial_buffered - find out if lws buffered the last write</h2>
526 <b>lws_partial_buffered</b>
527 (<i>struct lws *</i> <b>wsi</b>)
531 <dd>websocket connection to check
535 Returns 1 if you cannot use lws_write because the last
536 write on this connection is still buffered, and can't be cleared without
537 returning to the service loop and waiting for the connection to be
540 If you will try to do >1 lws_write call inside a single
541 WRITEABLE callback, you must check this after every write and bail if
542 set, ask for a new writeable callback and continue writing from there.
544 This is never set at the start of a writeable callback, but any write
548 <h2>lws_get_context - Allow geting lws_context from a Websocket connection instance</h2>
549 <i>LWS_EXTERN struct lws_context *</i>
550 <b>lws_get_context</b>
551 (<i>const struct lws *</i> <b>wsi</b>)
555 <dd>Websocket connection instance
560 With this function, users can access context in the callback function.
561 Otherwise users may have to declare context as a global variable.
564 <h2>lws_parse_uri - </h2>
565 <i>LWS_EXTERN int</i>
567 (<i>char *</i> <b>p</b>,
568 <i>const char **</i> <b>prot</b>,
569 <i>const char **</i> <b>ads</b>,
570 <i>int *</i> <b>port</b>,
571 <i>const char **</i> <b>path</b>)
575 <dd>incoming uri string.. will get written to
577 <dd>result pointer for protocol part (https://)
579 <dd>result pointer for address part
581 <dd>result pointer for port part
583 <dd>result pointer for path part
587 Notice it does so by dropping '\0' into input string
588 and the leading / on the path is consequently lost
591 <h2>lws_cgi - connected cgi process</h2>
592 <i>LWS_EXTERN int</i>
594 (<i>struct lws *</i> <b>wsi</b>,
595 <i>const char *const *</i> <b>exec_array</b>,
596 <i>int</i> <b>script_uri_path_len</b>,
597 <i>int</i> <b>timeout_secs</b>,
598 <i>const struct lws_protocol_vhost_options *</i> <b>mp_cgienv</b>)
602 <dd>connection to own the process
603 <dt><b>exec_array</b>
604 <dd>array of "exec-name" "arg1" ... "argn" NULL
607 <h2>lws_cgi_write_split_stdout_headers - </h2>
608 <i>LWS_EXTERN int</i>
609 <b>lws_cgi_write_split_stdout_headers</b>
610 (<i>struct lws *</i> <b>wsi</b>)
614 <dd>connection to own the process
617 <h2>lws_cgi_kill - </h2>
618 <i>LWS_EXTERN int</i>
620 (<i>struct lws *</i> <b>wsi</b>)
624 <dd>connection to own the process
627 <h2>lws_cancel_service - Cancel servicing of pending websocket activity</h2>
629 <b>lws_cancel_service</b>
630 (<i>struct lws_context *</i> <b>context</b>)
634 <dd>Websocket context
638 This function let a call to <b>lws_service</b> waiting for a timeout
641 There is no <b>poll</b> in MBED3, he will fire callbacks when he feels like
645 <h2>lws_cancel_service_pt - Cancel servicing of pending socket activity on one thread</h2>
647 <b>lws_cancel_service_pt</b>
648 (<i>struct lws *</i> <b>wsi</b>)
652 <dd>Cancel service on the thread this wsi is serviced by
656 This function let a call to <b>lws_service</b> waiting for a timeout
660 <h2>lws_cancel_service - Cancel ALL servicing of pending socket activity</h2>
662 <b>lws_cancel_service</b>
663 (<i>struct lws_context *</i> <b>context</b>)
667 <dd>Websocket context
671 This function let a call to <b>lws_service</b> waiting for a timeout
675 <h2>lws_cancel_service - Cancel servicing of pending websocket activity</h2>
677 <b>lws_cancel_service</b>
678 (<i>struct lws_context *</i> <b>context</b>)
682 <dd>Websocket context
686 This function let a call to <b>lws_service</b> waiting for a timeout
690 <h2>lws_write - Apply protocol then write data to client</h2>
693 (<i>struct lws *</i> <b>wsi</b>,
694 <i>unsigned char *</i> <b>buf</b>,
695 <i>size_t</i> <b>len</b>,
696 <i>enum lws_write_protocol</i> <b>wp</b>)
700 <dd>Websocket instance (available from user callback)
702 <dd>The data to send. For data being sent on a websocket
703 connection (ie, not default http), this buffer MUST have
704 LWS_PRE bytes valid BEFORE the pointer.
705 This is so the protocol header data can be added in-situ.
707 <dd>Count of the data bytes in the payload starting from buf
711 This function provides the way to issue data back to the client
712 for both http and websocket protocols.
714 In the case of sending using websocket protocol, be sure to allocate
715 valid storage before and after buf as explained above. This scheme
716 allows maximum efficiency of sending data and protocol in a single
717 packet while not burdening the user code with any protocol knowledge.
719 Return may be -1 for a fatal error needing connection close, or a
720 positive number reflecting the amount of bytes actually sent. This
721 can be less than the requested number of bytes due to OS memory
722 pressure at any given time.
725 <h2>lws_hdr_fragment_length - </h2>
727 <b>lws_hdr_fragment_length</b>
728 (<i>struct lws *</i> <b>wsi</b>,
729 <i>enum lws_token_indexes</i> <b>h</b>,
730 <i>int</i> <b>frag_idx</b>)
734 <dd>websocket connection
736 <dd>which header index we are interested in
738 <dd>which fragment of <tt><b>h</b></tt> we want to get the length of
742 The returned length does not include the space for a
746 <h2>lws_hdr_total_length - </h2>
748 <b>lws_hdr_total_length</b>
749 (<i>struct lws *</i> <b>wsi</b>,
750 <i>enum lws_token_indexes</i> <b>h</b>)
754 <dd>websocket connection
756 <dd>which header index we are interested in
760 The returned length does not include the space for a
764 <h2>lws_hdr_copy_fragment - </h2>
766 <b>lws_hdr_copy_fragment</b>
767 (<i>struct lws *</i> <b>wsi</b>,
768 <i>char *</i> <b>dst</b>,
769 <i>int</i> <b>len</b>,
770 <i>enum lws_token_indexes</i> <b>h</b>,
771 <i>int</i> <b>frag_idx</b>)
775 <dd>websocket connection
777 <dd>destination buffer
779 <dd>length of destination buffer
781 <dd>which header index we are interested in
785 The buffer length <tt><b>len</b></tt> must include space for an additional
786 terminating '\0', or it will fail returning -1.
787 If the requested fragment index is not present, it fails
791 <h2>lws_hdr_copy - </h2>
794 (<i>struct lws *</i> <b>wsi</b>,
795 <i>char *</i> <b>dst</b>,
796 <i>int</i> <b>len</b>,
797 <i>enum lws_token_indexes</i> <b>h</b>)
801 <dd>websocket connection
803 <dd>destination buffer
805 <dd>length of destination buffer
807 <dd>which header index we are interested in
811 The buffer length <tt><b>len</b></tt> must include space for an additional
812 terminating '\0', or it will fail returning -1.
815 <h2>lws_frame_is_binary - </h2>
817 <b>lws_frame_is_binary</b>
818 (<i>struct lws *</i> <b>wsi</b>)
822 <dd>the connection we are inquiring about
826 This is intended to be called from the LWS_CALLBACK_RECEIVE callback if
827 it's interested to see if the frame it's dealing with was sent in binary
831 <h2>lws_remaining_packet_payload - Bytes to come before "overall" rx packet is complete</h2>
833 <b>lws_remaining_packet_payload</b>
834 (<i>struct lws *</i> <b>wsi</b>)
838 <dd>Websocket instance (available from user callback)
842 This function is intended to be called from the callback if the
843 user code is interested in "complete packets" from the client.
844 libwebsockets just passes through payload as it comes and issues a buffer
845 additionally when it hits a built-in limit. The LWS_CALLBACK_RECEIVE
846 callback handler can use this API to find out if the buffer it has just
847 been given is the last piece of a "complete packet" from the client --
848 when that is the case <b>lws_remaining_packet_payload</b> will return
851 Many protocols won't care becuse their packets are always small.
854 <h2>lws_callback_on_writable - Request a callback when this socket becomes able to be written to without blocking</h2>
856 <b>lws_callback_on_writable</b>
857 (<i>struct lws *</i> <b>wsi</b>)
861 <dd>Websocket connection instance to get callback for
864 <h2>lws_callback_on_writable_all_protocol_vhost - Request a callback for all connections using the given protocol when it becomes possible to write to each socket without blocking in turn.</h2>
866 <b>lws_callback_on_writable_all_protocol_vhost</b>
867 (<i>const struct lws_vhost *</i> <b>vhost</b>,
868 <i>const struct lws_protocols *</i> <b>protocol</b>)
872 <dd>Only consider connections on this lws_vhost
874 <dd>Protocol whose connections will get callbacks
879 This calls back connections with the same protocol ON THE SAME
883 <h2>lws_callback_on_writable_all_protocol - Request a callback for all connections using the given protocol when it becomes possible to write to each socket without blocking in turn.</h2>
885 <b>lws_callback_on_writable_all_protocol</b>
886 (<i>const struct lws_context *</i> <b>context</b>,
887 <i>const struct lws_protocols *</i> <b>protocol</b>)
893 <dd>Protocol whose connections will get callbacks
898 This calls back any connection using the same protocol on ANY
902 <h2>lws_http_transaction_completed - wait for new http transaction or close</h2>
903 <i>int LWS_WARN_UNUSED_RESULT</i>
904 <b>lws_http_transaction_completed</b>
905 (<i>struct lws *</i> <b>wsi</b>)
909 <dd>websocket connection
913 Returns 1 if the HTTP connection must close now
914 Returns 0 and resets connection to wait for new HTTP header /
915 transaction if possible
918 <h2>lws_adopt_socket - adopt foreign socket as if listen socket accepted it</h2>
920 <b>lws_adopt_socket</b>
921 (<i>struct lws_context *</i> <b>context</b>,
922 <i>lws_sockfd_type</i> <b>accept_fd</b>)
928 <dd>fd of already-accepted socket to adopt
932 Either returns new wsi bound to accept_fd, or closes accept_fd and
933 returns NULL, having cleaned up any new wsi pieces.
935 LWS adopts the socket in http serving mode, it's ready to accept an upgrade
936 to ws or just serve http.
939 <h2>lws_adopt_socket_readbuf - adopt foreign socket and first rx as if listen socket accepted it</h2>
940 <i>LWS_EXTERN struct lws *</i>
941 <b>lws_adopt_socket_readbuf</b>
942 (<i>struct lws_context *</i> <b>context</b>,
943 <i>lws_sockfd_type</i> <b>accept_fd</b>,
944 <i>const char *</i> <b>readbuf</b>,
945 <i>size_t</i> <b>len</b>)
951 <dd>fd of already-accepted socket to adopt
953 <dd>NULL or pointer to data that must be drained before reading from
956 <dd>The length of the data held at <tt><b>readbuf</b></tt>
960 Either returns new wsi bound to accept_fd, or closes accept_fd and
961 returns NULL, having cleaned up any new wsi pieces.
963 LWS adopts the socket in http serving mode, it's ready to accept an upgrade
964 to ws or just serve http.
966 If your external code did not already read from the socket, you can use
967 <b>lws_adopt_socket</b> instead.
969 This api is guaranteed to use the data at <tt><b>readbuf</b></tt> first, before reading from
972 <tt><b>readbuf</b></tt> is limited to the size of the ah rx buf, currently 2048 bytes.
975 <h2>lws_serve_http_file - Send a file back to the client using http</h2>
977 <b>lws_serve_http_file</b>
978 (<i>struct lws *</i> <b>wsi</b>,
979 <i>const char *</i> <b>file</b>,
980 <i>const char *</i> <b>content_type</b>,
981 <i>const char *</i> <b>other_headers</b>,
982 <i>int</i> <b>other_headers_len</b>)
986 <dd>Websocket instance (available from user callback)
988 <dd>The file to issue over http
989 <dt><b>content_type</b>
990 <dd>The http content type, eg, text/html
991 <dt><b>other_headers</b>
992 <dd>NULL or pointer to header string
993 <dt><b>other_headers_len</b>
994 <dd>length of the other headers if non-NULL
998 This function is intended to be called from the callback in response
999 to http requests from the client. It allows the callback to issue
1000 local files down the http link in a single step.
1002 Returning <0 indicates error and the wsi should be closed. Returning
1003 >0 indicates the file was completely sent and
1004 <b>lws_http_transaction_completed</b> called on the wsi (and close if != 0)
1005 ==0 indicates the file transfer is started and needs more service later,
1006 the wsi should be left alone.
1009 <h2>lws_service_fd_tsi - Service polled socket with something waiting</h2>
1011 <b>lws_service_fd_tsi</b>
1012 (<i>struct lws_context *</i> <b>context</b>,
1013 <i>struct lws_pollfd *</i> <b>pollfd</b>,
1014 <i>int</i> <b>tsi</b>)
1018 <dd>Websocket context
1020 <dd>The pollfd entry describing the socket fd and which events
1023 <h3>Description</h3>
1025 This function takes a pollfd that has POLLIN or POLLOUT activity and
1026 services it according to the state of the associated
1029 The one call deals with all "service" that might happen on a socket
1030 including listen accepts, http files as well as websocket protocol.
1032 If a pollfd says it has something, you can just pass it to
1033 <b>lws_service_fd</b> whether it is a socket handled by lws or not.
1034 If it sees it is a lws socket, the traffic will be handled and
1035 pollfd->revents will be zeroed now.
1037 If the socket is foreign to lws, it leaves revents alone. So you can
1038 see if you should service yourself by checking the pollfd revents
1039 after letting lws try to service it.
1042 <h2>lws_service - Service any pending websocket activity</h2>
1045 (<i>struct lws_context *</i> <b>context</b>,
1046 <i>int</i> <b>timeout_ms</b>)
1050 <dd>Websocket context
1051 <dt><b>timeout_ms</b>
1052 <dd>Timeout for poll; 0 means return immediately if nothing needed
1053 service otherwise block and service immediately, returning
1054 after the timeout if nothing needed service.
1056 <h3>Description</h3>
1058 This function deals with any pending websocket traffic, for three
1059 kinds of event. It handles these events on both server and client
1060 types of connection the same.
1062 1) Accept new connections to our context's server
1064 2) Call the receive callback for incoming frame data received by
1065 server or client connections.
1067 You need to call this service function periodically to all the above
1068 functions to happen; if your application is single-threaded you can
1069 just call it in your main event loop.
1071 Alternatively you can fork a new process that asynchronously handles
1072 calling this service in a loop. In that case you are happy if this
1073 call blocks your thread until it needs to take care of something and
1074 would call it with a large nonzero timeout. Your loop then takes no
1075 CPU while there is nothing happening.
1077 If you are calling it in a single-threaded app, you don't want it to
1078 wait around blocking other things in your loop from happening, so you
1079 would call it with a timeout_ms of 0, so it returns immediately if
1080 nothing is pending, or as soon as it services whatever was pending.
1083 <h2>struct lws_plat_file_ops - Platform-specific file operations</h2>
1084 <b>struct lws_plat_file_ops</b> {<br>
1085 <i>lws_filefd_type (*</i><b>open</b>) <i>(struct lws *wsi, const char *filename,unsigned long *filelen, int flags)</i>;<br>
1086 <i>int (*</i><b>close</b>) <i>(struct lws *wsi, lws_filefd_type fd)</i>;<br>
1087 <i>unsigned long (*</i><b>seek_cur</b>) <i>(struct lws *wsi, lws_filefd_type fd,long offset_from_cur_pos)</i>;<br>
1088 <i>int (*</i><b>read</b>) <i>(struct lws *wsi, lws_filefd_type fd, unsigned long *amount,unsigned char *buf, unsigned long len)</i>;<br>
1089 <i>int (*</i><b>write</b>) <i>(struct lws *wsi, lws_filefd_type fd, unsigned long *amount,unsigned char *buf, unsigned long len)</i>;<br>
1094 <dd>Open file (always binary access if plat supports it)
1095 filelen is filled on exit to be the length of the file
1096 flags should be set to O_RDONLY or O_RDWR
1100 <dd>Seek from current position
1102 <dd>Read fron file *amount is set on exit to amount read
1104 <dd>Write to file *amount is set on exit as amount written
1106 <h3>Description</h3>
1109 These provide platform-agnostic ways to deal with filesystem access in the
1110 library and in the user code.
1113 <h2>lws_callback_function - User server actions</h2>
1115 <b>lws_callback_function</b>
1116 (<i>struct lws *</i> <b>wsi</b>,
1117 <i>enum lws_callback_reasons</i> <b>reason</b>,
1118 <i>void *</i> <b>user</b>,
1119 <i>void *</i> <b>in</b>,
1120 <i>size_t</i> <b>len</b>)
1124 <dd>Opaque websocket instance pointer
1126 <dd>The reason for the call
1128 <dd>Pointer to per-session user data allocated by library
1130 <dd>Pointer used for some callback reasons
1132 <dd>Length set for some callback reasons
1134 <h3>Description</h3>
1136 This callback is the way the user controls what is served. All the
1137 protocol detail is hidden and handled by the library.
1139 For each connection / session there is user data allocated that is
1140 pointed to by "user". You set the size of this user data area when
1141 the library is initialized with lws_create_server.
1143 You get an opportunity to initialize user data when called back with
1144 LWS_CALLBACK_ESTABLISHED reason.
1146 <h3>LWS_CALLBACK_ESTABLISHED</h3>
1148 after the server completes a handshake with
1149 an incoming client. If you built the library
1150 with ssl support, <tt><b>in</b></tt> is a pointer to the
1151 ssl struct associated with the connection or
1154 <h3>LWS_CALLBACK_CLIENT_CONNECTION_ERROR</h3>
1156 the request client connection has
1157 been unable to complete a handshake with the remote server. If
1158 in is non-NULL, you can find an error string of length len where
1161 <h3>LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH</h3>
1163 this is the last chance for the
1164 client user code to examine the http headers
1165 and decide to reject the connection. If the
1166 content in the headers is interesting to the
1167 client (url, etc) it needs to copy it out at
1168 this point since it will be destroyed before
1169 the CLIENT_ESTABLISHED call
1171 <h3>LWS_CALLBACK_CLIENT_ESTABLISHED</h3>
1173 after your client connection completed
1174 a handshake with the remote server
1176 <h3>LWS_CALLBACK_CLOSED</h3>
1178 when the websocket session ends
1180 <h3>LWS_CALLBACK_CLOSED_HTTP</h3>
1182 when a HTTP (non-websocket) session ends
1184 <h3>LWS_CALLBACK_RECEIVE</h3>
1186 data has appeared for this server endpoint from a
1187 remote client, it can be found at *in and is
1190 <h3>LWS_CALLBACK_CLIENT_RECEIVE_PONG</h3>
1192 if you elected to see PONG packets,
1193 they appear with this callback reason. PONG
1194 packets only exist in 04+ protocol
1196 <h3>LWS_CALLBACK_CLIENT_RECEIVE</h3>
1198 data has appeared from the server for the
1199 client connection, it can be found at *in and
1202 <h3>LWS_CALLBACK_HTTP</h3>
1204 an http request has come from a client that is not
1205 asking to upgrade the connection to a websocket
1206 one. This is a chance to serve http content,
1207 for example, to send a script to the client
1208 which will then open the websockets connection.
1209 <tt><b>in</b></tt> points to the URI path requested and
1210 <b>lws_serve_http_file</b> makes it very
1211 simple to send back a file to the client.
1212 Normally after sending the file you are done
1213 with the http connection, since the rest of the
1214 activity will come by websockets from the script
1215 that was delivered by http, so you will want to
1216 return 1; to close and free up the connection.
1217 That's important because it uses a slot in the
1218 total number of client connections allowed set
1221 <h3>LWS_CALLBACK_HTTP_BODY</h3>
1223 the next <tt><b>len</b></tt> bytes data from the http
1224 request body HTTP connection is now available in <tt><b>in</b></tt>.
1226 <h3>LWS_CALLBACK_HTTP_BODY_COMPLETION</h3>
1228 the expected amount of http request
1229 body has been delivered
1231 <h3>LWS_CALLBACK_HTTP_WRITEABLE</h3>
1233 you can write more down the http protocol
1236 <h3>LWS_CALLBACK_HTTP_FILE_COMPLETION</h3>
1238 a file requested to be send down
1239 http link has completed.
1241 <h3>LWS_CALLBACK_SERVER_WRITEABLE</h3>
1244 <b>lws_callback_on_writable</b> on a connection, you will
1245 get one of these callbacks coming when the connection socket
1246 is able to accept another write packet without blocking.
1247 If it already was able to take another packet without blocking,
1248 you'll get this callback at the next call to the service loop
1249 function. Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE
1250 and servers get LWS_CALLBACK_SERVER_WRITEABLE.
1252 <h3>LWS_CALLBACK_FILTER_NETWORK_CONNECTION</h3>
1254 called when a client connects to
1255 the server at network level; the connection is accepted but then
1256 passed to this callback to decide whether to hang up immediately
1257 or not, based on the client IP. <tt><b>in</b></tt> contains the connection
1258 socket's descriptor. Since the client connection information is
1259 not available yet, <tt><b>wsi</b></tt> still pointing to the main server socket.
1260 Return non-zero to terminate the connection before sending or
1261 receiving anything. Because this happens immediately after the
1262 network connection from the client, there's no websocket protocol
1263 selected yet so this callback is issued only to protocol 0.
1265 <h3>LWS_CALLBACK_SERVER_NEW_CLIENT_INSTANTIATED</h3>
1267 A new client just had
1268 been connected, accepted, and instantiated into the pool. This
1269 callback allows setting any relevant property to it. Because this
1270 happens immediately after the instantiation of a new client,
1271 there's no websocket protocol selected yet so this callback is
1272 issued only to protocol 0. Only <tt><b>wsi</b></tt> is defined, pointing to the
1273 new client, and the return value is ignored.
1275 <h3>LWS_CALLBACK_FILTER_HTTP_CONNECTION</h3>
1277 called when the request has
1278 been received and parsed from the client, but the response is
1279 not sent yet. Return non-zero to disallow the connection.
1280 <tt><b>user</b></tt> is a pointer to the connection user space allocation,
1281 <tt><b>in</b></tt> is the URI, eg, "/"
1282 In your handler you can use the public APIs
1283 <b>lws_hdr_total_length</b> / <b>lws_hdr_copy</b> to access all of the
1284 headers using the header enums lws_token_indexes from
1285 libwebsockets.h to check for and read the supported header
1286 presence and content before deciding to allow the http
1287 connection to proceed or to kill the connection.
1289 <h3>LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION</h3>
1291 called when the handshake has
1292 been received and parsed from the client, but the response is
1293 not sent yet. Return non-zero to disallow the connection.
1294 <tt><b>user</b></tt> is a pointer to the connection user space allocation,
1295 <tt><b>in</b></tt> is the requested protocol name
1296 In your handler you can use the public APIs
1297 <b>lws_hdr_total_length</b> / <b>lws_hdr_copy</b> to access all of the
1298 headers using the header enums lws_token_indexes from
1299 libwebsockets.h to check for and read the supported header
1300 presence and content before deciding to allow the handshake
1301 to proceed or to kill the connection.
1303 <h3>LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS</h3>
1306 including OpenSSL support, this callback allows your user code
1307 to perform extra <b>SSL_CTX_load_verify_locations</b> or similar
1308 calls to direct OpenSSL where to find certificates the client
1309 can use to confirm the remote server identity. <tt><b>user</b></tt> is the
1312 <h3>LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS</h3>
1315 including OpenSSL support, this callback allows your user code
1316 to load extra certifcates into the server which allow it to
1317 verify the validity of certificates returned by clients. <tt><b>user</b></tt>
1318 is the server's OpenSSL SSL_CTX*
1320 <h3>LWS_CALLBACK_OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY</h3>
1323 including OpenSSL support but no private key file has been
1324 specified (ssl_private_key_filepath is NULL), this is called to
1325 allow the user to set the private key directly via libopenssl
1326 and perform further operations if required; this might be useful
1327 in situations where the private key is not directly accessible
1328 by the OS, for example if it is stored on a smartcard
1329 <tt><b>user</b></tt> is the server's OpenSSL SSL_CTX*
1331 <h3>LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION</h3>
1334 libwebsockets context was created with the option
1335 LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this
1336 callback is generated during OpenSSL verification of the cert
1337 sent from the client. It is sent to protocol[0] callback as
1338 no protocol has been negotiated on the connection yet.
1339 Notice that the libwebsockets context and wsi are both NULL
1340 during this callback. See
1344 //www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
1345 to understand more detail about the OpenSSL callback that
1346 generates this libwebsockets callback and the meanings of the
1347 arguments passed. In this callback, <tt><b>user</b></tt> is the x509_ctx,
1348 <tt><b>in</b></tt> is the ssl pointer and <tt><b>len</b></tt> is preverify_ok
1349 Notice that this callback maintains libwebsocket return
1350 conventions, return 0 to mean the cert is OK or 1 to fail it.
1351 This also means that if you don't handle this callback then
1352 the default callback action of returning 0 allows the client
1355 <h3>LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER</h3>
1357 this callback happens
1358 when a client handshake is being compiled. <tt><b>user</b></tt> is NULL,
1359 <tt><b>in</b></tt> is a char **, it's pointing to a char * which holds the
1360 next location in the header buffer where you can add
1361 headers, and <tt><b>len</b></tt> is the remaining space in the header buffer,
1362 which is typically some hundreds of bytes. So, to add a canned
1363 cookie, your handler code might look similar to:
1365 char **p = (char **)in;
1370 *p += sprintf(*p, "Cookie: a=b\x0d\x0a");
1374 Notice if you add anything, you just have to take care about
1375 the CRLF on the line you added. Obviously this callback is
1376 optional, if you don't handle it everything is fine.
1378 Notice the callback is coming to protocols[0] all the time,
1379 because there is no specific protocol handshook yet.
1381 <h3>LWS_CALLBACK_CONFIRM_EXTENSION_OKAY</h3>
1383 When the server handshake code
1384 sees that it does support a requested extension, before
1385 accepting the extension by additing to the list sent back to
1386 the client it gives this callback just to check that it's okay
1387 to use that extension. It calls back to the requested protocol
1388 and with <tt><b>in</b></tt> being the extension name, <tt><b>len</b></tt> is 0 and <tt><b>user</b></tt> is
1389 valid. Note though at this time the ESTABLISHED callback hasn't
1390 happened yet so if you initialize <tt><b>user</b></tt> content there, <tt><b>user</b></tt>
1391 content during this callback might not be useful for anything.
1392 Notice this callback comes to protocols[0].
1394 <h3>LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED</h3>
1397 connection is being prepared to start a handshake to a server,
1398 each supported extension is checked with protocols[0] callback
1399 with this reason, giving the user code a chance to suppress the
1400 claim to support that extension by returning non-zero. If
1401 unhandled, by default 0 will be returned and the extension
1402 support included in the header to the server. Notice this
1403 callback comes to protocols[0].
1405 <h3>LWS_CALLBACK_PROTOCOL_INIT</h3>
1407 One-time call per protocol so it can
1408 do initial setup / allocations etc
1410 <h3>LWS_CALLBACK_PROTOCOL_DESTROY</h3>
1412 One-time call per protocol indicating
1413 this protocol won't get used at all after this callback, the
1414 context is getting destroyed. Take the opportunity to
1415 deallocate everything that was allocated by the protocol.
1417 <h3>LWS_CALLBACK_WSI_CREATE</h3>
1419 outermost (earliest) wsi create notification
1421 <h3>LWS_CALLBACK_WSI_DESTROY</h3>
1423 outermost (latest) wsi destroy notification
1425 The next five reasons are optional and only need taking care of if you
1426 will be integrating libwebsockets sockets into an external polling
1429 For these calls, <tt><b>in</b></tt> points to a struct lws_pollargs that
1430 contains <tt><b>fd</b></tt>, <tt><b>events</b></tt> and <tt><b>prev_events</b></tt> members
1432 <h3>LWS_CALLBACK_ADD_POLL_FD</h3>
1434 libwebsocket deals with its <b>poll</b> loop
1435 internally, but in the case you are integrating with another
1436 server you will need to have libwebsocket sockets share a
1437 polling array with the other server. This and the other
1438 POLL_FD related callbacks let you put your specialized
1439 poll array interface code in the callback for protocol 0, the
1440 first protocol you support, usually the HTTP protocol in the
1442 This callback happens when a socket needs to be
1444 <h3>added to the polling loop</h3>
1446 <tt><b>in</b></tt> points to a struct
1447 lws_pollargs; the <tt><b>fd</b></tt> member of the struct is the file
1448 descriptor, and <tt><b>events</b></tt> contains the active events.
1450 If you are using the internal polling loop (the "service"
1451 callback), you can just ignore these callbacks.
1453 <h3>LWS_CALLBACK_DEL_POLL_FD</h3>
1455 This callback happens when a socket descriptor
1456 needs to be removed from an external polling array. <tt><b>in</b></tt> is
1457 again the struct lws_pollargs containing the <tt><b>fd</b></tt> member
1458 to be removed. If you are using the internal polling
1459 loop, you can just ignore it.
1461 <h3>LWS_CALLBACK_CHANGE_MODE_POLL_FD</h3>
1463 This callback happens when
1464 libwebsockets wants to modify the events for a connectiion.
1465 <tt><b>in</b></tt> is the struct lws_pollargs with the <tt><b>fd</b></tt> to change.
1466 The new event mask is in <tt><b>events</b></tt> member and the old mask is in
1467 the <tt><b>prev_events</b></tt> member.
1468 If you are using the internal polling loop, you can just ignore
1471 <h3>LWS_CALLBACK_UNLOCK_POLL</h3>
1473 These allow the external poll changes driven
1474 by libwebsockets to participate in an external thread locking
1475 scheme around the changes, so the whole thing is threadsafe.
1476 These are called around three activities in the library,
1477 - inserting a new wsi in the wsi / fd table (len=1)
1478 - deleting a wsi from the wsi / fd table (len=1)
1479 - changing a wsi's POLLIN/OUT state (len=0)
1480 Locking and unlocking external synchronization objects when
1481 len == 1 allows external threads to be synchronized against
1482 wsi lifecycle changes if it acquires the same lock for the
1483 duration of wsi dereference from the other thread context.
1485 <h3>LWS_CALLBACK_WS_PEER_INITIATED_CLOSE</h3>
1487 The peer has sent an unsolicited Close WS packet. <tt><b>in</b></tt> and
1488 <tt><b>len</b></tt> are the optional close code (first 2 bytes, network
1489 order) and the optional additional information which is not
1490 defined in the standard, and may be a string or non-human-
1492 If you return 0 lws will echo the close and then close the
1493 connection. If you return nonzero lws will just close the
1497 <h2>lws_extension_callback_function - Hooks to allow extensions to operate</h2>
1499 <b>lws_extension_callback_function</b>
1500 (<i>struct lws_context *</i> <b>context</b>,
1501 <i>const struct lws_extension *</i> <b>ext</b>,
1502 <i>struct lws *</i> <b>wsi</b>,
1503 <i>enum lws_extension_callback_reasons</i> <b>reason</b>,
1504 <i>void *</i> <b>user</b>,
1505 <i>void *</i> <b>in</b>,
1506 <i>size_t</i> <b>len</b>)
1510 <dd>Websockets context
1514 <dd>Opaque websocket instance pointer
1516 <dd>The reason for the call
1518 <dd>Pointer to ptr to per-session user data allocated by library
1520 <dd>Pointer used for some callback reasons
1522 <dd>Length set for some callback reasons
1524 <h3>Description</h3>
1526 Each extension that is active on a particular connection receives
1527 callbacks during the connection lifetime to allow the extension to
1528 operate on websocket data and manage itself.
1530 Libwebsockets takes care of allocating and freeing "user" memory for
1531 each active extension on each connection. That is what is pointed to
1532 by the <tt><b>user</b></tt> parameter.
1534 <h3>LWS_EXT_CB_CONSTRUCT</h3>
1536 called when the server has decided to
1537 select this extension from the list provided by the client,
1538 just before the server will send back the handshake accepting
1539 the connection with this extension active. This gives the
1540 extension a chance to initialize its connection context found
1541 in <tt><b>user</b></tt>.
1543 <h3>LWS_EXT_CB_CLIENT_CONSTRUCT</h3>
1545 same as LWS_EXT_CB_CONSTRUCT
1546 but called when client is instantiating this extension. Some
1547 extensions will work the same on client and server side and then
1548 you can just merge handlers for both CONSTRUCTS.
1550 <h3>LWS_EXT_CB_DESTROY</h3>
1552 called when the connection the extension was
1553 being used on is about to be closed and deallocated. It's the
1554 last chance for the extension to deallocate anything it has
1555 allocated in the user data (pointed to by <tt><b>user</b></tt>) before the
1556 user data is deleted. This same callback is used whether you
1557 are in client or server instantiation context.
1559 <h3>LWS_EXT_CB_PACKET_RX_PREPARSE</h3>
1561 when this extension was active on
1562 a connection, and a packet of data arrived at the connection,
1563 it is passed to this callback to give the extension a chance to
1564 change the data, eg, decompress it. <tt><b>user</b></tt> is pointing to the
1565 extension's private connection context data, <tt><b>in</b></tt> is pointing
1566 to an lws_tokens struct, it consists of a char * pointer called
1567 token, and an int called token_len. At entry, these are
1568 set to point to the received buffer and set to the content
1569 length. If the extension will grow the content, it should use
1570 a new buffer allocated in its private user context data and
1571 set the pointed-to lws_tokens members to point to its buffer.
1573 <h3>LWS_EXT_CB_PACKET_TX_PRESEND</h3>
1575 this works the same way as
1576 LWS_EXT_CB_PACKET_RX_PREPARSE above, except it gives the
1577 extension a chance to change websocket data just before it will
1578 be sent out. Using the same lws_token pointer scheme in <tt><b>in</b></tt>,
1579 the extension can change the buffer and the length to be
1580 transmitted how it likes. Again if it wants to grow the
1581 buffer safely, it should copy the data into its own buffer and
1582 set the lws_tokens token pointer to it.
1585 <h2>struct lws_protocols - List of protocols and handlers server supports.</h2>
1586 <b>struct lws_protocols</b> {<br>
1587 <i>const char *</i> <b>name</b>;<br>
1588 <i>lws_callback_function *</i> <b>callback</b>;<br>
1589 <i>size_t</i> <b>per_session_data_size</b>;<br>
1590 <i>size_t</i> <b>rx_buffer_size</b>;<br>
1591 <i>unsigned int</i> <b>id</b>;<br>
1592 <i>void *</i> <b>user</b>;<br>
1597 <dd>Protocol name that must match the one given in the client
1598 Javascript new WebSocket(url, 'protocol') name.
1600 <dd>The service callback used for this protocol. It allows the
1601 service action for an entire protocol to be encapsulated in
1602 the protocol-specific callback
1603 <dt><b>per_session_data_size</b>
1604 <dd>Each new connection using this protocol gets
1605 this much memory allocated on connection establishment and
1606 freed on connection takedown. A pointer to this per-connection
1607 allocation is passed into the callback in the 'user' parameter
1608 <dt><b>rx_buffer_size</b>
1609 <dd>if you want atomic frames delivered to the callback, you
1610 should set this to the size of the biggest legal frame that
1611 you support. If the frame size is exceeded, there is no
1612 error, but the buffer will spill to the user callback when
1613 full, which you can detect by using
1614 <b>lws_remaining_packet_payload</b>. Notice that you
1615 just talk about frame size here, the LWS_PRE
1616 and post-padding are automatically also allocated on top.
1618 <dd>ignored by lws, but useful to contain user information bound
1619 to the selected protocol. For example if this protocol was
1620 called "myprotocol-v2", you might set id to 2, and the user
1621 code that acts differently according to the version can do so by
1622 switch (wsi->protocol->id), user code might use some bits as
1623 capability flags based on selected protocol version, etc.
1625 <dd>User provided context data at the protocol level.
1626 Accessible via lws_get_protocol(wsi)->user
1627 This should not be confused with wsi->user, it is not the same.
1628 The library completely ignores any value in here.
1630 <h3>Description</h3>
1632 This structure represents one protocol supported by the server. An
1633 array of these structures is passed to <b>lws_create_server</b>
1634 allows as many protocols as you like to be handled by one server.
1636 The first protocol given has its callback used for user callbacks when
1637 there is no agreed protocol name, that's true during HTTP part of the
1639 <h3>connection and true if the client did not send a Protocol</h3>
1644 <h2>struct lws_ext_options - Option arguments to the extension. These are used in the negotiation at ws upgrade time. The helper function lws_ext_parse_options() uses these to generate callbacks</h2>
1645 <b>struct lws_ext_options</b> {<br>
1646 <i>const char *</i> <b>name</b>;<br>
1647 <i>enum lws_ext_options_types</i> <b>type</b>;<br>
1652 <dd>Option name, eg, "server_no_context_takeover"
1654 <dd>What kind of args the option can take
1657 <h2>struct lws_extension - An extension we know how to cope with</h2>
1658 <b>struct lws_extension</b> {<br>
1659 <i>const char *</i> <b>name</b>;<br>
1660 <i>lws_extension_callback_function *</i> <b>callback</b>;<br>
1661 <i>const char *</i> <b>client_offer</b>;<br>
1666 <dd>Formal extension name, eg, "permessage-deflate"
1668 <dd>Service callback
1669 <dt><b>client_offer</b>
1670 <dd>String containing exts and options client offers
1673 <h2>struct lws_context_creation_info - parameters to create context with</h2>
1674 <b>struct lws_context_creation_info</b> {<br>
1675 <i>int</i> <b>port</b>;<br>
1676 <i>const char *</i> <b>iface</b>;<br>
1677 <i>const struct lws_protocols *</i> <b>protocols</b>;<br>
1678 <i>const struct lws_extension *</i> <b>extensions</b>;<br>
1679 <i>const struct lws_token_limits *</i> <b>token_limits</b>;<br>
1680 <i>const char *</i> <b>ssl_cert_filepath</b>;<br>
1681 <i>const char *</i> <b>ssl_private_key_filepath</b>;<br>
1682 <i>const char *</i> <b>ssl_ca_filepath</b>;<br>
1683 <i>const char *</i> <b>ssl_cipher_list</b>;<br>
1684 <i>const char *</i> <b>http_proxy_address</b>;<br>
1685 <i>unsigned int</i> <b>http_proxy_port</b>;<br>
1686 <i>int</i> <b>gid</b>;<br>
1687 <i>int</i> <b>uid</b>;<br>
1688 <i>unsigned int</i> <b>options</b>;<br>
1689 <i>void *</i> <b>user</b>;<br>
1690 <i>int</i> <b>ka_time</b>;<br>
1691 <i>int</i> <b>ka_probes</b>;<br>
1692 <i>int</i> <b>ka_interval</b>;<br>
1693 #ifdef LWS_OPENSSL_SUPPORT<br>
1694 <i>void *</i> <b>provided_client_ssl_ctx</b>;<br>
1696 <i>void *</i> <b>provided_client_ssl_ctx</b>;<br>
1698 <i>short</i> <b>max_http_header_data</b>;<br>
1699 <i>short</i> <b>max_http_header_pool</b>;<br>
1700 <i>unsigned int</i> <b>count_threads</b>;<br>
1701 <i>unsigned int</i> <b>fd_limit_per_thread</b>;<br>
1702 <i>unsigned int</i> <b>timeout_secs</b>;<br>
1703 <i>const char *</i> <b>ecdh_curve</b>;<br>
1704 <i>const char *</i> <b>vhost_name</b>;<br>
1705 <i>const char *const *</i> <b>plugin_dirs</b>;<br>
1706 <i>const struct lws_protocol_vhost_options *</i> <b>pvo</b>;<br>
1707 <i>int</i> <b>keepalive_timeout</b>;<br>
1708 <i>const char *</i> <b>log_filepath</b>;<br>
1709 <i>const struct lws_http_mount *</i> <b>mounts</b>;<br>
1710 <i>const char *</i> <b>server_string</b>;<br>
1715 <dd>VHOST: Port to listen on... you can use CONTEXT_PORT_NO_LISTEN to
1716 suppress listening on any port, that's what you want if you are
1717 not running a websocket server at all but just using it as a
1720 <dd>VHOST: NULL to bind the listen socket to all interfaces, or the
1721 interface name, eg, "eth2"
1722 If options specifies LWS_SERVER_OPTION_UNIX_SOCK, this member is
1723 the pathname of a UNIX domain socket. you can use the UNIX domain
1724 sockets in abstract namespace, by prepending an @ symbole to the
1726 <dt><b>protocols</b>
1727 <dd>VHOST: Array of structures listing supported protocols and a protocol-
1728 specific callback for each one. The list is ended with an
1729 entry that has a NULL callback pointer.
1730 It's not const because we write the owning_server member
1731 <dt><b>extensions</b>
1732 <dd>VHOST: NULL or array of lws_extension structs listing the
1733 extensions this context supports. If you configured with
1734 --without-extensions, you should give NULL here.
1735 <dt><b>token_limits</b>
1736 <dd>CONTEXT: NULL or struct lws_token_limits pointer which is initialized
1737 with a token length limit for each possible WSI_TOKEN_***
1738 <dt><b>ssl_cert_filepath</b>
1739 <dd>VHOST: If libwebsockets was compiled to use ssl, and you want
1740 to listen using SSL, set to the filepath to fetch the
1741 server cert from, otherwise NULL for unencrypted
1742 <dt><b>ssl_private_key_filepath</b>
1743 <dd>VHOST: filepath to private key if wanting SSL mode;
1744 if this is set to NULL but sll_cert_filepath is set, the
1745 OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY callback is called
1746 to allow setting of the private key directly via openSSL
1748 <dt><b>ssl_ca_filepath</b>
1749 <dd>VHOST: CA certificate filepath or NULL
1750 <dt><b>ssl_cipher_list</b>
1751 <dd>VHOST: List of valid ciphers to use (eg,
1752 "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
1753 or you can leave it as NULL to get "DEFAULT"
1754 <dt><b>http_proxy_address</b>
1755 <dd>VHOST: If non-NULL, attempts to proxy via the given address.
1756 If proxy auth is required, use format
1757 "username:password<tt><b>server</b></tt>:port"
1758 <dt><b>http_proxy_port</b>
1759 <dd>VHOST: If http_proxy_address was non-NULL, uses this port at
1762 <dd>CONTEXT: group id to change to after setting listen socket, or -1.
1764 <dd>CONTEXT: user id to change to after setting listen socket, or -1.
1766 <dd>VHOST + CONTEXT: 0, or LWS_SERVER_OPTION_... bitfields
1768 <dd>CONTEXT: optional user pointer that can be recovered via the context
1769 pointer using lws_context_user
1771 <dd>CONTEXT: 0 for no keepalive, otherwise apply this keepalive timeout to
1772 all libwebsocket sockets, client or server
1773 <dt><b>ka_probes</b>
1774 <dd>CONTEXT: if ka_time was nonzero, after the timeout expires how many
1775 times to try to get a response from the peer before giving up
1776 and killing the connection
1777 <dt><b>ka_interval</b>
1778 <dd>CONTEXT: if ka_time was nonzero, how long to wait before each ka_probes
1780 <dt><b>provided_client_ssl_ctx</b>
1781 <dd>CONTEXT: If non-null, swap out libwebsockets ssl
1782 implementation for the one provided by provided_ssl_ctx.
1783 Libwebsockets no longer is responsible for freeing the context
1784 if this option is selected.
1785 <dt><b>provided_client_ssl_ctx</b>
1786 <dd>CONTEXT: If non-null, swap out libwebsockets ssl
1787 implementation for the one provided by provided_ssl_ctx.
1788 Libwebsockets no longer is responsible for freeing the context
1789 if this option is selected.
1790 <dt><b>max_http_header_data</b>
1791 <dd>CONTEXT: The max amount of header payload that can be handled
1792 in an http request (unrecognized header payload is dropped)
1793 <dt><b>max_http_header_pool</b>
1794 <dd>CONTEXT: The max number of connections with http headers that
1795 can be processed simultaneously (the corresponding memory is
1796 allocated for the lifetime of the context). If the pool is
1797 busy new incoming connections must wait for accept until one
1799 <dt><b>count_threads</b>
1800 <dd>CONTEXT: how many contexts to create in an array, 0 = 1
1801 <dt><b>fd_limit_per_thread</b>
1802 <dd>CONTEXT: nonzero means restrict each service thread to this
1803 many fds, 0 means the default which is divide the process fd
1804 limit by the number of threads.
1805 <dt><b>timeout_secs</b>
1806 <dd>VHOST: various processes involving network roundtrips in the
1807 library are protected from hanging forever by timeouts. If
1808 nonzero, this member lets you set the timeout used in seconds.
1809 Otherwise a default timeout is used.
1810 <dt><b>ecdh_curve</b>
1811 <dd>VHOST: if NULL, defaults to initializing server with "prime256v1"
1812 <dt><b>vhost_name</b>
1813 <dd>VHOST: name of vhost, must match external DNS name used to
1814 access the site, like "warmcat.com" as it's used to match
1815 <dt><b>plugin_dirs</b>
1816 <dd>CONTEXT: NULL, or NULL-terminated array of directories to
1817 scan for lws protocol plugins at context creation time
1819 <dd>VHOST: pointer to optional linked list of per-vhost
1820 options made accessible to protocols
1821 <dt><b>keepalive_timeout</b>
1822 <dd>VHOST: (default = 0 = 60s) seconds to allow remote
1823 client to hold on to an idle HTTP/1.1 connection
1824 <dt><b>log_filepath</b>
1825 <dd>VHOST: filepath to append logs to... this is opened before
1826 any dropping of initial privileges
1828 <dd>VHOST: optional linked list of mounts for this vhost
1829 <dt><b>server_string</b>
1830 <dd>CONTEXT: string used in HTTP headers to identify server
1831 software, if NULL, "libwebsockets".
1833 <h3>Description</h3>
1836 This is also used to create vhosts.... if LWS_SERVER_OPTION_EXPLICIT_VHOSTS
1837 is not given, then for backwards compatibility one vhost is created at
1838 context-creation time using the info from this struct.
1840 If LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, then no vhosts are created
1841 at the same time as the context, they are expected to be created afterwards.
1845 header and / or SNI name for SSL.
1848 <h2>struct lws_client_connect_info - parameters to connect with when using lws_client_connect_via_info()</h2>
1849 <b>struct lws_client_connect_info</b> {<br>
1850 <i>struct lws_context *</i> <b>context</b>;<br>
1851 <i>const char *</i> <b>address</b>;<br>
1852 <i>int</i> <b>port</b>;<br>
1853 <i>int</i> <b>ssl_connection</b>;<br>
1854 <i>const char *</i> <b>path</b>;<br>
1855 <i>const char *</i> <b>host</b>;<br>
1856 <i>const char *</i> <b>origin</b>;<br>
1857 <i>const char *</i> <b>protocol</b>;<br>
1858 <i>int</i> <b>ietf_version_or_minus_one</b>;<br>
1859 <i>void *</i> <b>userdata</b>;<br>
1860 <i>const struct lws_extension *</i> <b>client_exts</b>;<br>
1861 <i>const char *</i> <b>method</b>;<br>
1862 <i>struct lws *</i> <b>parent_wsi</b>;<br>
1863 <i>const char *</i> <b>uri_replace_from</b>;<br>
1864 <i>const char *</i> <b>uri_replace_to</b>;<br>
1865 <i>struct lws_vhost *</i> <b>vhost</b>;<br>
1870 <dd>lws context to create connection in
1872 <dd>remote address to connect to
1874 <dd>remote port to connect to
1875 <dt><b>ssl_connection</b>
1880 <dd>content of host header
1882 <dd>content of origin header
1884 <dd>list of ws protocols
1885 <dt><b>ietf_version_or_minus_one</b>
1886 <dd>currently leave at 0 or -1
1888 <dd>if non-NULL, use this as wsi user_data instead of malloc it
1889 <dt><b>client_exts</b>
1890 <dd>array of extensions that may be used on connection
1892 <dd>if non-NULL, do this http method instead of ws[s] upgrade.
1893 use "GET" to be a simple http client connection
1894 <dt><b>parent_wsi</b>
1895 <dd>if another wsi is responsible for this connection, give it here.
1896 this is used to make sure if the parent closes so do any
1897 child connections first.
1898 <dt><b>uri_replace_from</b>
1899 <dd>if non-NULL, when this string is found in URIs in
1900 text/html content-encoding, it's replaced with <tt><b>uri_replace_to</b></tt>
1901 <dt><b>uri_replace_to</b>
1904 <dd>vhost to bind to (used to determine related SSL_CTX)
1907 <h2>lws_close_reason - Set reason and aux data to send with Close packet If you are going to return nonzero from the callback requesting the connection to close, you can optionally call this to set the reason the peer will be told if possible.</h2>
1908 <i>LWS_EXTERN void</i>
1909 <b>lws_close_reason</b>
1910 (<i>struct lws *</i> <b>wsi</b>,
1911 <i>enum lws_close_status</i> <b>status</b>,
1912 <i>unsigned char *</i> <b>buf</b>,
1913 <i>size_t</i> <b>len</b>)
1917 <dd>The websocket connection to set the close reason on
1919 <dd>A valid close status from websocket standard
1921 <dd>NULL or buffer containing up to 124 bytes of auxiliary data
1923 <dd>Length of data in <tt><b>buf</b></tt> to send
projects / platform / upstream / libwebsockets.git / blob