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_return_http_status - Return simple http status</h2>
224 <b>lws_return_http_status</b>
225 (<i>struct lws *</i> <b>wsi</b>,
226 <i>unsigned int</i> <b>code</b>,
227 <i>const char *</i> <b>html_body</b>)
231 <dd>Websocket instance (available from user callback)
233 <dd>Status index, eg, 404
235 <dd>User-readable HTML description < 1KB, or NULL
239 Helper to report HTTP errors back to the client cleanly and
243 <h2>lws_set_timeout - marks the wsi as subject to a timeout</h2>
245 <b>lws_set_timeout</b>
246 (<i>struct lws *</i> <b>wsi</b>,
247 <i>enum pending_timeout</i> <b>reason</b>,
248 <i>int</i> <b>secs</b>)
252 <dd>Websocket connection instance
261 You will not need this unless you are doing something special
264 <h2>lws_get_peer_addresses - Get client address information</h2>
266 <b>lws_get_peer_addresses</b>
267 (<i>struct lws *</i> <b>wsi</b>,
268 <i>lws_sockfd_type</i> <b>fd</b>,
269 <i>char *</i> <b>name</b>,
270 <i>int</i> <b>name_len</b>,
271 <i>char *</i> <b>rip</b>,
272 <i>int</i> <b>rip_len</b>)
276 <dd>Local struct lws associated with
278 <dd>Connection socket descriptor
280 <dd>Buffer to take client address name
282 <dd>Length of client address name buffer
284 <dd>Buffer to take client address IP dotted quad
286 <dd>Length of client address IP buffer
290 This function fills in <tt><b>name</b></tt> and <tt><b>rip</b></tt> with the name and IP of
291 the client connected with socket descriptor <tt><b>fd</b></tt>. Names may be
292 truncated if there is not enough room. If either cannot be
293 determined, they will be returned as valid zero-length strings.
296 <h2>lws_context_user - get the user data associated with the context</h2>
297 <i>LWS_EXTERN void *</i>
298 <b>lws_context_user</b>
299 (<i>struct lws_context *</i> <b>context</b>)
303 <dd>Websocket context
307 This returns the optional user allocation that can be attached to
308 the context the sockets live in at context_create time. It's a way
309 to let all sockets serviced in the same context share data without
310 using globals statics in the user code.
313 <h2>lws_callback_all_protocol - Callback all connections using the given protocol with the given reason</h2>
315 <b>lws_callback_all_protocol</b>
316 (<i>struct lws_context *</i> <b>context</b>,
317 <i>const struct lws_protocols *</i> <b>protocol</b>,
318 <i>int</i> <b>reason</b>)
322 <dd>Protocol whose connections will get callbacks
324 <dd>Callback reason index
327 <h2>lws_get_socket_fd - returns the socket file descriptor</h2>
329 <b>lws_get_socket_fd</b>
330 (<i>struct lws *</i> <b>wsi</b>)
334 <dd>Websocket connection instance
339 You will not need this unless you are doing something special
342 <h2>lws_rx_flow_control - Enable and disable socket servicing for received packets.</h2>
344 <b>lws_rx_flow_control</b>
345 (<i>struct lws *</i> <b>wsi</b>,
346 <i>int</i> <b>enable</b>)
350 <dd>Websocket connection instance to get callback for
352 <dd>0 = disable read servicing for this connection, 1 = enable
357 If the output side of a server process becomes choked, this allows flow
358 control for the input side.
361 <h2>lws_rx_flow_allow_all_protocol - Allow all connections with this protocol to receive</h2>
363 <b>lws_rx_flow_allow_all_protocol</b>
364 (<i>const struct lws_context *</i> <b>context</b>,
365 <i>const struct lws_protocols *</i> <b>protocol</b>)
369 <dd>all connections using this protocol will be allowed to receive
374 When the user server code realizes it can accept more input, it can
375 call this to have the RX flow restriction removed from all connections using
379 <h2>lws_canonical_hostname - returns this host's hostname</h2>
381 <b>lws_canonical_hostname</b>
382 (<i>struct lws_context *</i> <b>context</b>)
386 <dd>Websocket context
391 This is typically used by client code to fill in the host parameter
392 when making a client connection. You can only call it after the context
396 <h2>lws_set_proxy - Setups proxy to lws_context.</h2>
399 (<i>struct lws_context *</i> <b>context</b>,
400 <i>const char *</i> <b>proxy</b>)
404 <dd>pointer to struct lws_context you want set proxy to
406 <dd>pointer to c string containing proxy in format address:port
410 Returns 0 if proxy string was parsed and proxy was setup.
411 Returns -1 if <tt><b>proxy</b></tt> is NULL or has incorrect format.
413 This is only required if your OS does not provide the http_proxy
414 environment variable (eg, OSX)
416 IMPORTANT! You should call this function right after creation of the
417 lws_context and before call to connect. If you call this
418 function after connect behavior is undefined.
419 This function will override proxy settings made on lws_context
420 creation with <b>genenv</b> call.
423 <h2>lws_get_protocol - Returns a protocol pointer from a websocket connection.</h2>
424 <i>const struct lws_protocols *</i>
425 <b>lws_get_protocol</b>
426 (<i>struct lws *</i> <b>wsi</b>)
430 <dd>pointer to struct websocket you want to know the protocol of
435 Some apis can act on all live connections of a given protocol,
436 this is how you can get a pointer to the active protocol if needed.
439 <h2>lwsl_timestamp - </h2>
441 <b>lwsl_timestamp</b>
442 (<i>int</i> <b>level</b>,
443 <i>char *</i> <b>p</b>,
444 <i>int</i> <b>len</b>)
450 <dd>char * buffer to take timestamp
456 returns length written in p
459 <h2>lws_set_log_level - Set the logging bitfield</h2>
461 <b>lws_set_log_level</b>
462 (<i>int</i> <b>level</b>,
463 <i>void (*</i><b>func</b>) <i>(int level, const char *line)</i>)
467 <dd>OR together the LLL_ debug contexts you want output from
471 log level defaults to "err", "warn" and "notice" contexts enabled and
475 <h2>lws_is_ssl - Find out if connection is using SSL</h2>
478 (<i>struct lws *</i> <b>wsi</b>)
482 <dd>websocket connection to check
486 Returns 0 if the connection is not using SSL, 1 if using SSL and
487 using verified cert, and 2 if using SSL but the cert was not
488 checked (appears for client wsi told to skip check on connection)
491 <h2>lws_partial_buffered - find out if lws buffered the last write</h2>
493 <b>lws_partial_buffered</b>
494 (<i>struct lws *</i> <b>wsi</b>)
498 <dd>websocket connection to check
502 Returns 1 if you cannot use lws_write because the last
503 write on this connection is still buffered, and can't be cleared without
504 returning to the service loop and waiting for the connection to be
507 If you will try to do >1 lws_write call inside a single
508 WRITEABLE callback, you must check this after every write and bail if
509 set, ask for a new writeable callback and continue writing from there.
511 This is never set at the start of a writeable callback, but any write
515 <h2>lws_parse_uri - </h2>
516 <i>LWS_EXTERN int</i>
518 (<i>char *</i> <b>p</b>,
519 <i>const char **</i> <b>prot</b>,
520 <i>const char **</i> <b>ads</b>,
521 <i>int *</i> <b>port</b>,
522 <i>const char **</i> <b>path</b>)
526 <dd>incoming uri string.. will get written to
528 <dd>result pointer for protocol part (https://)
530 <dd>result pointer for address part
532 <dd>result pointer for port part
534 <dd>result pointer for path part
538 Notice it does so by dropping '\0' into input string
539 and the leading / on the path is consequently lost
542 <h2>lws_cgi - connected cgi process</h2>
543 <i>LWS_EXTERN int</i>
545 (<i>struct lws *</i> <b>wsi</b>,
546 <i>char *const *</i> <b>exec_array</b>,
547 <i>int</i> <b>timeout_secs</b>)
551 <dd>connection to own the process
552 <dt><b>exec_array</b>
553 <dd>array of "exec-name" "arg1" ... "argn" NULL
556 <h2>lws_cgi_kill - </h2>
557 <i>LWS_EXTERN int</i>
559 (<i>struct lws *</i> <b>wsi</b>)
563 <dd>connection to own the process
566 <h2>lws_cancel_service - Cancel servicing of pending websocket activity</h2>
568 <b>lws_cancel_service</b>
569 (<i>struct lws_context *</i> <b>context</b>)
573 <dd>Websocket context
577 This function let a call to <b>lws_service</b> waiting for a timeout
580 There is no <b>poll</b> in MBED3, he will fire callbacks when he feels like
584 <h2>lws_cancel_service_pt - Cancel servicing of pending socket activity on one thread</h2>
586 <b>lws_cancel_service_pt</b>
587 (<i>struct lws *</i> <b>wsi</b>)
591 <dd>Cancel service on the thread this wsi is serviced by
595 This function let a call to <b>lws_service</b> waiting for a timeout
599 <h2>lws_cancel_service - Cancel ALL servicing of pending socket activity</h2>
601 <b>lws_cancel_service</b>
602 (<i>struct lws_context *</i> <b>context</b>)
606 <dd>Websocket context
610 This function let a call to <b>lws_service</b> waiting for a timeout
614 <h2>lws_cancel_service - Cancel servicing of pending websocket activity</h2>
616 <b>lws_cancel_service</b>
617 (<i>struct lws_context *</i> <b>context</b>)
621 <dd>Websocket context
625 This function let a call to <b>lws_service</b> waiting for a timeout
629 <h2>lws_write - Apply protocol then write data to client</h2>
632 (<i>struct lws *</i> <b>wsi</b>,
633 <i>unsigned char *</i> <b>buf</b>,
634 <i>size_t</i> <b>len</b>,
635 <i>enum lws_write_protocol</i> <b>wp</b>)
639 <dd>Websocket instance (available from user callback)
641 <dd>The data to send. For data being sent on a websocket
642 connection (ie, not default http), this buffer MUST have
643 LWS_PRE bytes valid BEFORE the pointer.
644 This is so the protocol header data can be added in-situ.
646 <dd>Count of the data bytes in the payload starting from buf
650 This function provides the way to issue data back to the client
651 for both http and websocket protocols.
653 In the case of sending using websocket protocol, be sure to allocate
654 valid storage before and after buf as explained above. This scheme
655 allows maximum efficiency of sending data and protocol in a single
656 packet while not burdening the user code with any protocol knowledge.
658 Return may be -1 for a fatal error needing connection close, or a
659 positive number reflecting the amount of bytes actually sent. This
660 can be less than the requested number of bytes due to OS memory
661 pressure at any given time.
664 <h2>lws_hdr_fragment_length - </h2>
666 <b>lws_hdr_fragment_length</b>
667 (<i>struct lws *</i> <b>wsi</b>,
668 <i>enum lws_token_indexes</i> <b>h</b>,
669 <i>int</i> <b>frag_idx</b>)
673 <dd>websocket connection
675 <dd>which header index we are interested in
677 <dd>which fragment of <tt><b>h</b></tt> we want to get the length of
681 The returned length does not include the space for a
685 <h2>lws_hdr_total_length - </h2>
687 <b>lws_hdr_total_length</b>
688 (<i>struct lws *</i> <b>wsi</b>,
689 <i>enum lws_token_indexes</i> <b>h</b>)
693 <dd>websocket connection
695 <dd>which header index we are interested in
699 The returned length does not include the space for a
703 <h2>lws_hdr_copy_fragment - </h2>
705 <b>lws_hdr_copy_fragment</b>
706 (<i>struct lws *</i> <b>wsi</b>,
707 <i>char *</i> <b>dst</b>,
708 <i>int</i> <b>len</b>,
709 <i>enum lws_token_indexes</i> <b>h</b>,
710 <i>int</i> <b>frag_idx</b>)
714 <dd>websocket connection
716 <dd>destination buffer
718 <dd>length of destination buffer
720 <dd>which header index we are interested in
724 The buffer length <tt><b>len</b></tt> must include space for an additional
725 terminating '\0', or it will fail returning -1.
726 If the requested fragment index is not present, it fails
730 <h2>lws_hdr_copy - </h2>
733 (<i>struct lws *</i> <b>wsi</b>,
734 <i>char *</i> <b>dst</b>,
735 <i>int</i> <b>len</b>,
736 <i>enum lws_token_indexes</i> <b>h</b>)
740 <dd>websocket connection
742 <dd>destination buffer
744 <dd>length of destination buffer
746 <dd>which header index we are interested in
750 The buffer length <tt><b>len</b></tt> must include space for an additional
751 terminating '\0', or it will fail returning -1.
754 <h2>lws_frame_is_binary - </h2>
756 <b>lws_frame_is_binary</b>
757 (<i>struct lws *</i> <b>wsi</b>)
761 <dd>the connection we are inquiring about
765 This is intended to be called from the LWS_CALLBACK_RECEIVE callback if
766 it's interested to see if the frame it's dealing with was sent in binary
770 <h2>lws_remaining_packet_payload - Bytes to come before "overall" rx packet is complete</h2>
772 <b>lws_remaining_packet_payload</b>
773 (<i>struct lws *</i> <b>wsi</b>)
777 <dd>Websocket instance (available from user callback)
781 This function is intended to be called from the callback if the
782 user code is interested in "complete packets" from the client.
783 libwebsockets just passes through payload as it comes and issues a buffer
784 additionally when it hits a built-in limit. The LWS_CALLBACK_RECEIVE
785 callback handler can use this API to find out if the buffer it has just
786 been given is the last piece of a "complete packet" from the client --
787 when that is the case <b>lws_remaining_packet_payload</b> will return
790 Many protocols won't care becuse their packets are always small.
793 <h2>lws_callback_on_writable - Request a callback when this socket becomes able to be written to without blocking</h2>
795 <b>lws_callback_on_writable</b>
796 (<i>struct lws *</i> <b>wsi</b>)
800 <dd>Websocket connection instance to get callback for
803 <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>
805 <b>lws_callback_on_writable_all_protocol</b>
806 (<i>const struct lws_context *</i> <b>context</b>,
807 <i>const struct lws_protocols *</i> <b>protocol</b>)
813 <dd>Protocol whose connections will get callbacks
816 <h2>lws_http_transaction_completed - wait for new http transaction or close</h2>
817 <i>int LWS_WARN_UNUSED_RESULT</i>
818 <b>lws_http_transaction_completed</b>
819 (<i>struct lws *</i> <b>wsi</b>)
823 <dd>websocket connection
827 Returns 1 if the HTTP connection must close now
828 Returns 0 and resets connection to wait for new HTTP header /
829 transaction if possible
832 <h2>lws_adopt_socket - adopt foreign socket as if listen socket accepted it</h2>
834 <b>lws_adopt_socket</b>
835 (<i>struct lws_context *</i> <b>context</b>,
836 <i>lws_sockfd_type</i> <b>accept_fd</b>)
842 <dd>fd of already-accepted socket to adopt
846 Either returns new wsi bound to accept_fd, or closes accept_fd and
847 returns NULL, having cleaned up any new wsi pieces.
849 LWS adopts the socket in http serving mode, it's ready to accept an upgrade
850 to ws or just serve http.
853 <h2>lws_adopt_socket_readbuf - adopt foreign socket and first rx as if listen socket accepted it</h2>
854 <i>LWS_EXTERN struct lws *</i>
855 <b>lws_adopt_socket_readbuf</b>
856 (<i>struct lws_context *</i> <b>context</b>,
857 <i>lws_sockfd_type</i> <b>accept_fd</b>,
858 <i>const char *</i> <b>readbuf</b>,
859 <i>size_t</i> <b>len</b>)
865 <dd>fd of already-accepted socket to adopt
867 <dd>NULL or pointer to data that must be drained before reading from
870 <dd>The length of the data held at <tt><b>readbuf</b></tt>
874 Either returns new wsi bound to accept_fd, or closes accept_fd and
875 returns NULL, having cleaned up any new wsi pieces.
877 LWS adopts the socket in http serving mode, it's ready to accept an upgrade
878 to ws or just serve http.
880 If your external code did not already read from the socket, you can use
881 <b>lws_adopt_socket</b> instead.
883 This api is guaranteed to use the data at <tt><b>readbuf</b></tt> first, before reading from
886 <tt><b>readbuf</b></tt> is limited to the size of the ah rx buf, currently 2048 bytes.
889 <h2>lws_serve_http_file - Send a file back to the client using http</h2>
891 <b>lws_serve_http_file</b>
892 (<i>struct lws *</i> <b>wsi</b>,
893 <i>const char *</i> <b>file</b>,
894 <i>const char *</i> <b>content_type</b>,
895 <i>const char *</i> <b>other_headers</b>,
896 <i>int</i> <b>other_headers_len</b>)
900 <dd>Websocket instance (available from user callback)
902 <dd>The file to issue over http
903 <dt><b>content_type</b>
904 <dd>The http content type, eg, text/html
905 <dt><b>other_headers</b>
906 <dd>NULL or pointer to header string
907 <dt><b>other_headers_len</b>
908 <dd>length of the other headers if non-NULL
912 This function is intended to be called from the callback in response
913 to http requests from the client. It allows the callback to issue
914 local files down the http link in a single step.
916 Returning <0 indicates error and the wsi should be closed. Returning
917 >0 indicates the file was completely sent and
918 <b>lws_http_transaction_completed</b> called on the wsi (and close if != 0)
919 ==0 indicates the file transfer is started and needs more service later,
920 the wsi should be left alone.
923 <h2>lws_service_fd_tsi - Service polled socket with something waiting</h2>
925 <b>lws_service_fd_tsi</b>
926 (<i>struct lws_context *</i> <b>context</b>,
927 <i>struct lws_pollfd *</i> <b>pollfd</b>,
928 <i>int</i> <b>tsi</b>)
932 <dd>Websocket context
934 <dd>The pollfd entry describing the socket fd and which events
939 This function takes a pollfd that has POLLIN or POLLOUT activity and
940 services it according to the state of the associated
943 The one call deals with all "service" that might happen on a socket
944 including listen accepts, http files as well as websocket protocol.
946 If a pollfd says it has something, you can just pass it to
947 <b>lws_service_fd</b> whether it is a socket handled by lws or not.
948 If it sees it is a lws socket, the traffic will be handled and
949 pollfd->revents will be zeroed now.
951 If the socket is foreign to lws, it leaves revents alone. So you can
952 see if you should service yourself by checking the pollfd revents
953 after letting lws try to service it.
956 <h2>lws_service - Service any pending websocket activity</h2>
959 (<i>struct lws_context *</i> <b>context</b>,
960 <i>int</i> <b>timeout_ms</b>)
964 <dd>Websocket context
965 <dt><b>timeout_ms</b>
966 <dd>Timeout for poll; 0 means return immediately if nothing needed
967 service otherwise block and service immediately, returning
968 after the timeout if nothing needed service.
972 This function deals with any pending websocket traffic, for three
973 kinds of event. It handles these events on both server and client
974 types of connection the same.
976 1) Accept new connections to our context's server
978 2) Call the receive callback for incoming frame data received by
979 server or client connections.
981 You need to call this service function periodically to all the above
982 functions to happen; if your application is single-threaded you can
983 just call it in your main event loop.
985 Alternatively you can fork a new process that asynchronously handles
986 calling this service in a loop. In that case you are happy if this
987 call blocks your thread until it needs to take care of something and
988 would call it with a large nonzero timeout. Your loop then takes no
989 CPU while there is nothing happening.
991 If you are calling it in a single-threaded app, you don't want it to
992 wait around blocking other things in your loop from happening, so you
993 would call it with a timeout_ms of 0, so it returns immediately if
994 nothing is pending, or as soon as it services whatever was pending.
997 <h2>struct lws_plat_file_ops - Platform-specific file operations</h2>
998 <b>struct lws_plat_file_ops</b> {<br>
999 <i>lws_filefd_type (*</i><b>open</b>) <i>(struct lws *wsi, const char *filename,unsigned long *filelen, int flags)</i>;<br>
1000 <i>int (*</i><b>close</b>) <i>(struct lws *wsi, lws_filefd_type fd)</i>;<br>
1001 <i>unsigned long (*</i><b>seek_cur</b>) <i>(struct lws *wsi, lws_filefd_type fd,long offset_from_cur_pos)</i>;<br>
1002 <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>
1003 <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>
1008 <dd>Open file (always binary access if plat supports it)
1009 filelen is filled on exit to be the length of the file
1010 flags should be set to O_RDONLY or O_RDWR
1014 <dd>Seek from current position
1016 <dd>Read fron file *amount is set on exit to amount read
1018 <dd>Write to file *amount is set on exit as amount written
1020 <h3>Description</h3>
1023 These provide platform-agnostic ways to deal with filesystem access in the
1024 library and in the user code.
1027 <h2>lws_callback_function - User server actions</h2>
1029 <b>lws_callback_function</b>
1030 (<i>struct lws *</i> <b>wsi</b>,
1031 <i>enum lws_callback_reasons</i> <b>reason</b>,
1032 <i>void *</i> <b>user</b>,
1033 <i>void *</i> <b>in</b>,
1034 <i>size_t</i> <b>len</b>)
1038 <dd>Opaque websocket instance pointer
1040 <dd>The reason for the call
1042 <dd>Pointer to per-session user data allocated by library
1044 <dd>Pointer used for some callback reasons
1046 <dd>Length set for some callback reasons
1048 <h3>Description</h3>
1050 This callback is the way the user controls what is served. All the
1051 protocol detail is hidden and handled by the library.
1053 For each connection / session there is user data allocated that is
1054 pointed to by "user". You set the size of this user data area when
1055 the library is initialized with lws_create_server.
1057 You get an opportunity to initialize user data when called back with
1058 LWS_CALLBACK_ESTABLISHED reason.
1060 <h3>LWS_CALLBACK_ESTABLISHED</h3>
1062 after the server completes a handshake with
1063 an incoming client. If you built the library
1064 with ssl support, <tt><b>in</b></tt> is a pointer to the
1065 ssl struct associated with the connection or
1068 <h3>LWS_CALLBACK_CLIENT_CONNECTION_ERROR</h3>
1070 the request client connection has
1071 been unable to complete a handshake with the remote server. If
1072 in is non-NULL, you can find an error string of length len where
1075 <h3>LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH</h3>
1077 this is the last chance for the
1078 client user code to examine the http headers
1079 and decide to reject the connection. If the
1080 content in the headers is interesting to the
1081 client (url, etc) it needs to copy it out at
1082 this point since it will be destroyed before
1083 the CLIENT_ESTABLISHED call
1085 <h3>LWS_CALLBACK_CLIENT_ESTABLISHED</h3>
1087 after your client connection completed
1088 a handshake with the remote server
1090 <h3>LWS_CALLBACK_CLOSED</h3>
1092 when the websocket session ends
1094 <h3>LWS_CALLBACK_CLOSED_HTTP</h3>
1096 when a HTTP (non-websocket) session ends
1098 <h3>LWS_CALLBACK_RECEIVE</h3>
1100 data has appeared for this server endpoint from a
1101 remote client, it can be found at *in and is
1104 <h3>LWS_CALLBACK_CLIENT_RECEIVE_PONG</h3>
1106 if you elected to see PONG packets,
1107 they appear with this callback reason. PONG
1108 packets only exist in 04+ protocol
1110 <h3>LWS_CALLBACK_CLIENT_RECEIVE</h3>
1112 data has appeared from the server for the
1113 client connection, it can be found at *in and
1116 <h3>LWS_CALLBACK_HTTP</h3>
1118 an http request has come from a client that is not
1119 asking to upgrade the connection to a websocket
1120 one. This is a chance to serve http content,
1121 for example, to send a script to the client
1122 which will then open the websockets connection.
1123 <tt><b>in</b></tt> points to the URI path requested and
1124 <b>lws_serve_http_file</b> makes it very
1125 simple to send back a file to the client.
1126 Normally after sending the file you are done
1127 with the http connection, since the rest of the
1128 activity will come by websockets from the script
1129 that was delivered by http, so you will want to
1130 return 1; to close and free up the connection.
1131 That's important because it uses a slot in the
1132 total number of client connections allowed set
1135 <h3>LWS_CALLBACK_HTTP_BODY</h3>
1137 the next <tt><b>len</b></tt> bytes data from the http
1138 request body HTTP connection is now available in <tt><b>in</b></tt>.
1140 <h3>LWS_CALLBACK_HTTP_BODY_COMPLETION</h3>
1142 the expected amount of http request
1143 body has been delivered
1145 <h3>LWS_CALLBACK_HTTP_WRITEABLE</h3>
1147 you can write more down the http protocol
1150 <h3>LWS_CALLBACK_HTTP_FILE_COMPLETION</h3>
1152 a file requested to be send down
1153 http link has completed.
1155 <h3>LWS_CALLBACK_SERVER_WRITEABLE</h3>
1158 <b>lws_callback_on_writable</b> on a connection, you will
1159 get one of these callbacks coming when the connection socket
1160 is able to accept another write packet without blocking.
1161 If it already was able to take another packet without blocking,
1162 you'll get this callback at the next call to the service loop
1163 function. Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE
1164 and servers get LWS_CALLBACK_SERVER_WRITEABLE.
1166 <h3>LWS_CALLBACK_FILTER_NETWORK_CONNECTION</h3>
1168 called when a client connects to
1169 the server at network level; the connection is accepted but then
1170 passed to this callback to decide whether to hang up immediately
1171 or not, based on the client IP. <tt><b>in</b></tt> contains the connection
1172 socket's descriptor. Since the client connection information is
1173 not available yet, <tt><b>wsi</b></tt> still pointing to the main server socket.
1174 Return non-zero to terminate the connection before sending or
1175 receiving anything. Because this happens immediately after the
1176 network connection from the client, there's no websocket protocol
1177 selected yet so this callback is issued only to protocol 0.
1179 <h3>LWS_CALLBACK_SERVER_NEW_CLIENT_INSTANTIATED</h3>
1181 A new client just had
1182 been connected, accepted, and instantiated into the pool. This
1183 callback allows setting any relevant property to it. Because this
1184 happens immediately after the instantiation of a new client,
1185 there's no websocket protocol selected yet so this callback is
1186 issued only to protocol 0. Only <tt><b>wsi</b></tt> is defined, pointing to the
1187 new client, and the return value is ignored.
1189 <h3>LWS_CALLBACK_FILTER_HTTP_CONNECTION</h3>
1191 called when the request has
1192 been received and parsed from the client, but the response is
1193 not sent yet. Return non-zero to disallow the connection.
1194 <tt><b>user</b></tt> is a pointer to the connection user space allocation,
1195 <tt><b>in</b></tt> is the URI, eg, "/"
1196 In your handler you can use the public APIs
1197 <b>lws_hdr_total_length</b> / <b>lws_hdr_copy</b> to access all of the
1198 headers using the header enums lws_token_indexes from
1199 libwebsockets.h to check for and read the supported header
1200 presence and content before deciding to allow the http
1201 connection to proceed or to kill the connection.
1203 <h3>LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION</h3>
1205 called when the handshake has
1206 been received and parsed from the client, but the response is
1207 not sent yet. Return non-zero to disallow the connection.
1208 <tt><b>user</b></tt> is a pointer to the connection user space allocation,
1209 <tt><b>in</b></tt> is the requested protocol name
1210 In your handler you can use the public APIs
1211 <b>lws_hdr_total_length</b> / <b>lws_hdr_copy</b> to access all of the
1212 headers using the header enums lws_token_indexes from
1213 libwebsockets.h to check for and read the supported header
1214 presence and content before deciding to allow the handshake
1215 to proceed or to kill the connection.
1217 <h3>LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS</h3>
1220 including OpenSSL support, this callback allows your user code
1221 to perform extra <b>SSL_CTX_load_verify_locations</b> or similar
1222 calls to direct OpenSSL where to find certificates the client
1223 can use to confirm the remote server identity. <tt><b>user</b></tt> is the
1226 <h3>LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS</h3>
1229 including OpenSSL support, this callback allows your user code
1230 to load extra certifcates into the server which allow it to
1231 verify the validity of certificates returned by clients. <tt><b>user</b></tt>
1232 is the server's OpenSSL SSL_CTX*
1234 <h3>LWS_CALLBACK_OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY</h3>
1237 including OpenSSL support but no private key file has been
1238 specified (ssl_private_key_filepath is NULL), this is called to
1239 allow the user to set the private key directly via libopenssl
1240 and perform further operations if required; this might be useful
1241 in situations where the private key is not directly accessible
1242 by the OS, for example if it is stored on a smartcard
1243 <tt><b>user</b></tt> is the server's OpenSSL SSL_CTX*
1245 <h3>LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION</h3>
1248 libwebsockets context was created with the option
1249 LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this
1250 callback is generated during OpenSSL verification of the cert
1251 sent from the client. It is sent to protocol[0] callback as
1252 no protocol has been negotiated on the connection yet.
1253 Notice that the libwebsockets context and wsi are both NULL
1254 during this callback. See
1258 //www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
1259 to understand more detail about the OpenSSL callback that
1260 generates this libwebsockets callback and the meanings of the
1261 arguments passed. In this callback, <tt><b>user</b></tt> is the x509_ctx,
1262 <tt><b>in</b></tt> is the ssl pointer and <tt><b>len</b></tt> is preverify_ok
1263 Notice that this callback maintains libwebsocket return
1264 conventions, return 0 to mean the cert is OK or 1 to fail it.
1265 This also means that if you don't handle this callback then
1266 the default callback action of returning 0 allows the client
1269 <h3>LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER</h3>
1271 this callback happens
1272 when a client handshake is being compiled. <tt><b>user</b></tt> is NULL,
1273 <tt><b>in</b></tt> is a char **, it's pointing to a char * which holds the
1274 next location in the header buffer where you can add
1275 headers, and <tt><b>len</b></tt> is the remaining space in the header buffer,
1276 which is typically some hundreds of bytes. So, to add a canned
1277 cookie, your handler code might look similar to:
1279 char **p = (char **)in;
1284 *p += sprintf(*p, "Cookie: a=b\x0d\x0a");
1288 Notice if you add anything, you just have to take care about
1289 the CRLF on the line you added. Obviously this callback is
1290 optional, if you don't handle it everything is fine.
1292 Notice the callback is coming to protocols[0] all the time,
1293 because there is no specific protocol handshook yet.
1295 <h3>LWS_CALLBACK_CONFIRM_EXTENSION_OKAY</h3>
1297 When the server handshake code
1298 sees that it does support a requested extension, before
1299 accepting the extension by additing to the list sent back to
1300 the client it gives this callback just to check that it's okay
1301 to use that extension. It calls back to the requested protocol
1302 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
1303 valid. Note though at this time the ESTABLISHED callback hasn't
1304 happened yet so if you initialize <tt><b>user</b></tt> content there, <tt><b>user</b></tt>
1305 content during this callback might not be useful for anything.
1306 Notice this callback comes to protocols[0].
1308 <h3>LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED</h3>
1311 connection is being prepared to start a handshake to a server,
1312 each supported extension is checked with protocols[0] callback
1313 with this reason, giving the user code a chance to suppress the
1314 claim to support that extension by returning non-zero. If
1315 unhandled, by default 0 will be returned and the extension
1316 support included in the header to the server. Notice this
1317 callback comes to protocols[0].
1319 <h3>LWS_CALLBACK_PROTOCOL_INIT</h3>
1321 One-time call per protocol so it can
1322 do initial setup / allocations etc
1324 <h3>LWS_CALLBACK_PROTOCOL_DESTROY</h3>
1326 One-time call per protocol indicating
1327 this protocol won't get used at all after this callback, the
1328 context is getting destroyed. Take the opportunity to
1329 deallocate everything that was allocated by the protocol.
1331 <h3>LWS_CALLBACK_WSI_CREATE</h3>
1333 outermost (earliest) wsi create notification
1335 <h3>LWS_CALLBACK_WSI_DESTROY</h3>
1337 outermost (latest) wsi destroy notification
1339 The next five reasons are optional and only need taking care of if you
1340 will be integrating libwebsockets sockets into an external polling
1343 For these calls, <tt><b>in</b></tt> points to a struct lws_pollargs that
1344 contains <tt><b>fd</b></tt>, <tt><b>events</b></tt> and <tt><b>prev_events</b></tt> members
1346 <h3>LWS_CALLBACK_ADD_POLL_FD</h3>
1348 libwebsocket deals with its <b>poll</b> loop
1349 internally, but in the case you are integrating with another
1350 server you will need to have libwebsocket sockets share a
1351 polling array with the other server. This and the other
1352 POLL_FD related callbacks let you put your specialized
1353 poll array interface code in the callback for protocol 0, the
1354 first protocol you support, usually the HTTP protocol in the
1356 This callback happens when a socket needs to be
1358 <h3>added to the polling loop</h3>
1360 <tt><b>in</b></tt> points to a struct
1361 lws_pollargs; the <tt><b>fd</b></tt> member of the struct is the file
1362 descriptor, and <tt><b>events</b></tt> contains the active events.
1364 If you are using the internal polling loop (the "service"
1365 callback), you can just ignore these callbacks.
1367 <h3>LWS_CALLBACK_DEL_POLL_FD</h3>
1369 This callback happens when a socket descriptor
1370 needs to be removed from an external polling array. <tt><b>in</b></tt> is
1371 again the struct lws_pollargs containing the <tt><b>fd</b></tt> member
1372 to be removed. If you are using the internal polling
1373 loop, you can just ignore it.
1375 <h3>LWS_CALLBACK_CHANGE_MODE_POLL_FD</h3>
1377 This callback happens when
1378 libwebsockets wants to modify the events for a connectiion.
1379 <tt><b>in</b></tt> is the struct lws_pollargs with the <tt><b>fd</b></tt> to change.
1380 The new event mask is in <tt><b>events</b></tt> member and the old mask is in
1381 the <tt><b>prev_events</b></tt> member.
1382 If you are using the internal polling loop, you can just ignore
1385 <h3>LWS_CALLBACK_UNLOCK_POLL</h3>
1387 These allow the external poll changes driven
1388 by libwebsockets to participate in an external thread locking
1389 scheme around the changes, so the whole thing is threadsafe.
1390 These are called around three activities in the library,
1391 - inserting a new wsi in the wsi / fd table (len=1)
1392 - deleting a wsi from the wsi / fd table (len=1)
1393 - changing a wsi's POLLIN/OUT state (len=0)
1394 Locking and unlocking external synchronization objects when
1395 len == 1 allows external threads to be synchronized against
1396 wsi lifecycle changes if it acquires the same lock for the
1397 duration of wsi dereference from the other thread context.
1399 <h3>LWS_CALLBACK_WS_PEER_INITIATED_CLOSE</h3>
1401 The peer has sent an unsolicited Close WS packet. <tt><b>in</b></tt> and
1402 <tt><b>len</b></tt> are the optional close code (first 2 bytes, network
1403 order) and the optional additional information which is not
1404 defined in the standard, and may be a string or non-human-
1406 If you return 0 lws will echo the close and then close the
1407 connection. If you return nonzero lws will just close the
1411 <h2>lws_extension_callback_function - Hooks to allow extensions to operate</h2>
1413 <b>lws_extension_callback_function</b>
1414 (<i>struct lws_context *</i> <b>context</b>,
1415 <i>const struct lws_extension *</i> <b>ext</b>,
1416 <i>struct lws *</i> <b>wsi</b>,
1417 <i>enum lws_extension_callback_reasons</i> <b>reason</b>,
1418 <i>void *</i> <b>user</b>,
1419 <i>void *</i> <b>in</b>,
1420 <i>size_t</i> <b>len</b>)
1424 <dd>Websockets context
1428 <dd>Opaque websocket instance pointer
1430 <dd>The reason for the call
1432 <dd>Pointer to ptr to per-session user data allocated by library
1434 <dd>Pointer used for some callback reasons
1436 <dd>Length set for some callback reasons
1438 <h3>Description</h3>
1440 Each extension that is active on a particular connection receives
1441 callbacks during the connection lifetime to allow the extension to
1442 operate on websocket data and manage itself.
1444 Libwebsockets takes care of allocating and freeing "user" memory for
1445 each active extension on each connection. That is what is pointed to
1446 by the <tt><b>user</b></tt> parameter.
1448 <h3>LWS_EXT_CB_CONSTRUCT</h3>
1450 called when the server has decided to
1451 select this extension from the list provided by the client,
1452 just before the server will send back the handshake accepting
1453 the connection with this extension active. This gives the
1454 extension a chance to initialize its connection context found
1455 in <tt><b>user</b></tt>.
1457 <h3>LWS_EXT_CB_CLIENT_CONSTRUCT</h3>
1459 same as LWS_EXT_CB_CONSTRUCT
1460 but called when client is instantiating this extension. Some
1461 extensions will work the same on client and server side and then
1462 you can just merge handlers for both CONSTRUCTS.
1464 <h3>LWS_EXT_CB_DESTROY</h3>
1466 called when the connection the extension was
1467 being used on is about to be closed and deallocated. It's the
1468 last chance for the extension to deallocate anything it has
1469 allocated in the user data (pointed to by <tt><b>user</b></tt>) before the
1470 user data is deleted. This same callback is used whether you
1471 are in client or server instantiation context.
1473 <h3>LWS_EXT_CB_PACKET_RX_PREPARSE</h3>
1475 when this extension was active on
1476 a connection, and a packet of data arrived at the connection,
1477 it is passed to this callback to give the extension a chance to
1478 change the data, eg, decompress it. <tt><b>user</b></tt> is pointing to the
1479 extension's private connection context data, <tt><b>in</b></tt> is pointing
1480 to an lws_tokens struct, it consists of a char * pointer called
1481 token, and an int called token_len. At entry, these are
1482 set to point to the received buffer and set to the content
1483 length. If the extension will grow the content, it should use
1484 a new buffer allocated in its private user context data and
1485 set the pointed-to lws_tokens members to point to its buffer.
1487 <h3>LWS_EXT_CB_PACKET_TX_PRESEND</h3>
1489 this works the same way as
1490 LWS_EXT_CB_PACKET_RX_PREPARSE above, except it gives the
1491 extension a chance to change websocket data just before it will
1492 be sent out. Using the same lws_token pointer scheme in <tt><b>in</b></tt>,
1493 the extension can change the buffer and the length to be
1494 transmitted how it likes. Again if it wants to grow the
1495 buffer safely, it should copy the data into its own buffer and
1496 set the lws_tokens token pointer to it.
1499 <h2>struct lws_protocols - List of protocols and handlers server supports.</h2>
1500 <b>struct lws_protocols</b> {<br>
1501 <i>const char *</i> <b>name</b>;<br>
1502 <i>lws_callback_function *</i> <b>callback</b>;<br>
1503 <i>size_t</i> <b>per_session_data_size</b>;<br>
1504 <i>size_t</i> <b>rx_buffer_size</b>;<br>
1505 <i>unsigned int</i> <b>id</b>;<br>
1506 <i>void *</i> <b>user</b>;<br>
1511 <dd>Protocol name that must match the one given in the client
1512 Javascript new WebSocket(url, 'protocol') name.
1514 <dd>The service callback used for this protocol. It allows the
1515 service action for an entire protocol to be encapsulated in
1516 the protocol-specific callback
1517 <dt><b>per_session_data_size</b>
1518 <dd>Each new connection using this protocol gets
1519 this much memory allocated on connection establishment and
1520 freed on connection takedown. A pointer to this per-connection
1521 allocation is passed into the callback in the 'user' parameter
1522 <dt><b>rx_buffer_size</b>
1523 <dd>if you want atomic frames delivered to the callback, you
1524 should set this to the size of the biggest legal frame that
1525 you support. If the frame size is exceeded, there is no
1526 error, but the buffer will spill to the user callback when
1527 full, which you can detect by using
1528 <b>lws_remaining_packet_payload</b>. Notice that you
1529 just talk about frame size here, the LWS_PRE
1530 and post-padding are automatically also allocated on top.
1532 <dd>ignored by lws, but useful to contain user information bound
1533 to the selected protocol. For example if this protocol was
1534 called "myprotocol-v2", you might set id to 2, and the user
1535 code that acts differently according to the version can do so by
1536 switch (wsi->protocol->id), user code might use some bits as
1537 capability flags based on selected protocol version, etc.
1539 <dd>User provided context data at the protocol level.
1540 Accessible via lws_get_protocol(wsi)->user
1541 This should not be confused with wsi->user, it is not the same.
1542 The library completely ignores any value in here.
1544 <h3>Description</h3>
1546 This structure represents one protocol supported by the server. An
1547 array of these structures is passed to <b>lws_create_server</b>
1548 allows as many protocols as you like to be handled by one server.
1550 The first protocol given has its callback used for user callbacks when
1551 there is no agreed protocol name, that's true during HTTP part of the
1553 <h3>connection and true if the client did not send a Protocol</h3>
1558 <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>
1559 <b>struct lws_ext_options</b> {<br>
1560 <i>const char *</i> <b>name</b>;<br>
1561 <i>enum lws_ext_options_types</i> <b>type</b>;<br>
1566 <dd>Option name, eg, "server_no_context_takeover"
1568 <dd>What kind of args the option can take
1571 <h2>struct lws_extension - An extension we know how to cope with</h2>
1572 <b>struct lws_extension</b> {<br>
1573 <i>const char *</i> <b>name</b>;<br>
1574 <i>lws_extension_callback_function *</i> <b>callback</b>;<br>
1575 <i>const char *</i> <b>client_offer</b>;<br>
1580 <dd>Formal extension name, eg, "permessage-deflate"
1582 <dd>Service callback
1583 <dt><b>client_offer</b>
1584 <dd>String containing exts and options client offers
1587 <h2>struct lws_context_creation_info - parameters to create context with</h2>
1588 <b>struct lws_context_creation_info</b> {<br>
1589 <i>int</i> <b>port</b>;<br>
1590 <i>const char *</i> <b>iface</b>;<br>
1591 <i>const struct lws_protocols *</i> <b>protocols</b>;<br>
1592 <i>const struct lws_extension *</i> <b>extensions</b>;<br>
1593 <i>const struct lws_token_limits *</i> <b>token_limits</b>;<br>
1594 <i>const char *</i> <b>ssl_cert_filepath</b>;<br>
1595 <i>const char *</i> <b>ssl_private_key_filepath</b>;<br>
1596 <i>const char *</i> <b>ssl_ca_filepath</b>;<br>
1597 <i>const char *</i> <b>ssl_cipher_list</b>;<br>
1598 <i>const char *</i> <b>http_proxy_address</b>;<br>
1599 <i>unsigned int</i> <b>http_proxy_port</b>;<br>
1600 <i>int</i> <b>gid</b>;<br>
1601 <i>int</i> <b>uid</b>;<br>
1602 <i>unsigned int</i> <b>options</b>;<br>
1603 <i>void *</i> <b>user</b>;<br>
1604 <i>int</i> <b>ka_time</b>;<br>
1605 <i>int</i> <b>ka_probes</b>;<br>
1606 <i>int</i> <b>ka_interval</b>;<br>
1607 #ifdef LWS_OPENSSL_SUPPORT<br>
1608 <i>void *</i> <b>provided_client_ssl_ctx</b>;<br>
1610 <i>void *</i> <b>provided_client_ssl_ctx</b>;<br>
1612 <i>short</i> <b>max_http_header_data</b>;<br>
1613 <i>short</i> <b>max_http_header_pool</b>;<br>
1614 <i>unsigned int</i> <b>count_threads</b>;<br>
1615 <i>unsigned int</i> <b>fd_limit_per_thread</b>;<br>
1616 <i>unsigned int</i> <b>timeout_secs</b>;<br>
1617 <i>const char *</i> <b>ecdh_curve</b>;<br>
1622 <dd>Port to listen on... you can use CONTEXT_PORT_NO_LISTEN to
1623 suppress listening on any port, that's what you want if you are
1624 not running a websocket server at all but just using it as a
1627 <dd>NULL to bind the listen socket to all interfaces, or the
1628 interface name, eg, "eth2"
1629 <dt><b>protocols</b>
1630 <dd>Array of structures listing supported protocols and a protocol-
1631 specific callback for each one. The list is ended with an
1632 entry that has a NULL callback pointer.
1633 It's not const because we write the owning_server member
1634 <dt><b>extensions</b>
1635 <dd>NULL or array of lws_extension structs listing the
1636 extensions this context supports. If you configured with
1637 --without-extensions, you should give NULL here.
1638 <dt><b>token_limits</b>
1639 <dd>NULL or struct lws_token_limits pointer which is initialized
1640 with a token length limit for each possible WSI_TOKEN_***
1641 <dt><b>ssl_cert_filepath</b>
1642 <dd>If libwebsockets was compiled to use ssl, and you want
1643 to listen using SSL, set to the filepath to fetch the
1644 server cert from, otherwise NULL for unencrypted
1645 <dt><b>ssl_private_key_filepath</b>
1646 <dd>filepath to private key if wanting SSL mode;
1647 if this is set to NULL but sll_cert_filepath is set, the
1648 OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY callback is called
1649 to allow setting of the private key directly via openSSL
1651 <dt><b>ssl_ca_filepath</b>
1652 <dd>CA certificate filepath or NULL
1653 <dt><b>ssl_cipher_list</b>
1654 <dd>List of valid ciphers to use (eg,
1655 "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
1656 or you can leave it as NULL to get "DEFAULT"
1657 <dt><b>http_proxy_address</b>
1658 <dd>If non-NULL, attempts to proxy via the given address.
1659 If proxy auth is required, use format
1660 "username:password<tt><b>server</b></tt>:port"
1661 <dt><b>http_proxy_port</b>
1662 <dd>If http_proxy_address was non-NULL, uses this port at
1665 <dd>group id to change to after setting listen socket, or -1.
1667 <dd>user id to change to after setting listen socket, or -1.
1669 <dd>0, or LWS_SERVER_OPTION_... bitfields
1671 <dd>optional user pointer that can be recovered via the context
1672 pointer using lws_context_user
1674 <dd>0 for no keepalive, otherwise apply this keepalive timeout to
1675 all libwebsocket sockets, client or server
1676 <dt><b>ka_probes</b>
1677 <dd>if ka_time was nonzero, after the timeout expires how many
1678 times to try to get a response from the peer before giving up
1679 and killing the connection
1680 <dt><b>ka_interval</b>
1681 <dd>if ka_time was nonzero, how long to wait before each ka_probes
1683 <dt><b>provided_client_ssl_ctx</b>
1684 <dd>If non-null, swap out libwebsockets ssl
1685 implementation for the one provided by provided_ssl_ctx.
1686 Libwebsockets no longer is responsible for freeing the context
1687 if this option is selected.
1688 <dt><b>provided_client_ssl_ctx</b>
1689 <dd>If non-null, swap out libwebsockets ssl
1690 implementation for the one provided by provided_ssl_ctx.
1691 Libwebsockets no longer is responsible for freeing the context
1692 if this option is selected.
1693 <dt><b>max_http_header_data</b>
1694 <dd>The max amount of header payload that can be handled
1695 in an http request (unrecognized header payload is dropped)
1696 <dt><b>max_http_header_pool</b>
1697 <dd>The max number of connections with http headers that
1698 can be processed simultaneously (the corresponding memory is
1699 allocated for the lifetime of the context). If the pool is
1700 busy new incoming connections must wait for accept until one
1702 <dt><b>count_threads</b>
1703 <dd>how many contexts to create in an array, 0 = 1
1704 <dt><b>fd_limit_per_thread</b>
1705 <dd>nonzero means restrict each service thread to this
1706 many fds, 0 means the default which is divide the process fd
1707 limit by the number of threads.
1708 <dt><b>timeout_secs</b>
1709 <dd>various processes involving network roundtrips in the
1710 library are protected from hanging forever by timeouts. If
1711 nonzero, this member lets you set the timeout used in seconds.
1712 Otherwise a default timeout is used.
1713 <dt><b>ecdh_curve</b>
1714 <dd>if NULL, defaults to initializing server with "prime256v1"
1717 <h2>struct lws_client_connect_info - parameters to connect with when using lws_client_connect_via_info()</h2>
1718 <b>struct lws_client_connect_info</b> {<br>
1719 <i>struct lws_context *</i> <b>context</b>;<br>
1720 <i>const char *</i> <b>address</b>;<br>
1721 <i>int</i> <b>port</b>;<br>
1722 <i>int</i> <b>ssl_connection</b>;<br>
1723 <i>const char *</i> <b>path</b>;<br>
1724 <i>const char *</i> <b>host</b>;<br>
1725 <i>const char *</i> <b>origin</b>;<br>
1726 <i>const char *</i> <b>protocol</b>;<br>
1727 <i>int</i> <b>ietf_version_or_minus_one</b>;<br>
1728 <i>void *</i> <b>userdata</b>;<br>
1729 <i>const struct lws_extension *</i> <b>client_exts</b>;<br>
1730 <i>const char *</i> <b>method</b>;<br>
1735 <dd>lws context to create connection in
1737 <dd>remote address to connect to
1739 <dd>remote port to connect to
1740 <dt><b>ssl_connection</b>
1745 <dd>content of host header
1747 <dd>content of origin header
1749 <dd>list of ws protocols
1750 <dt><b>ietf_version_or_minus_one</b>
1751 <dd>currently leave at 0 or -1
1753 <dd>if non-NULL, use this as wsi user_data instead of malloc it
1754 <dt><b>client_exts</b>
1755 <dd>array of extensions that may be used on connection
1757 <dd>if non-NULL, do this http method instead of ws[s] upgrade.
1758 use "GET" to be a simple http client connection
1761 <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>
1762 <i>LWS_EXTERN void</i>
1763 <b>lws_close_reason</b>
1764 (<i>struct lws *</i> <b>wsi</b>,
1765 <i>enum lws_close_status</i> <b>status</b>,
1766 <i>unsigned char *</i> <b>buf</b>,
1767 <i>size_t</i> <b>len</b>)
1771 <dd>The websocket connection to set the close reason on
1773 <dd>A valid close status from websocket standard
1775 <dd>NULL or buffer containing up to 124 bytes of auxiliary data
1777 <dd>Length of data in <tt><b>buf</b></tt> to send
projects / platform / upstream / libwebsockets.git / blob