blob: bd734dc1c5d3a2236161e7204f96985fb135ccbb [file] [log] [blame]
Andy Greenf7ee5492011-02-13 09:04:21 +00001<h2>libwebsockets_hangup_on_client - Server calls to terminate client connection</h2>
2<i>void</i>
3<b>libwebsockets_hangup_on_client</b>
Peter Hinz56885f32011-03-02 22:03:47 +00004(<i>struct libwebsocket_context *</i> <b>context</b>,
Andy Greenf7ee5492011-02-13 09:04:21 +00005<i>int</i> <b>fd</b>)
6<h3>Arguments</h3>
7<dl>
Peter Hinz56885f32011-03-02 22:03:47 +00008<dt><b>context</b>
Andy Greenf7ee5492011-02-13 09:04:21 +00009<dd>libwebsockets context
10<dt><b>fd</b>
11<dd>Connection socket descriptor
12</dl>
13<hr>
Andy Green07034092011-02-13 08:37:12 +000014<h2>libwebsockets_get_peer_addresses - Get client address information</h2>
15<i>void</i>
16<b>libwebsockets_get_peer_addresses</b>
17(<i>int</i> <b>fd</b>,
18<i>char *</i> <b>name</b>,
19<i>int</i> <b>name_len</b>,
20<i>char *</i> <b>rip</b>,
21<i>int</i> <b>rip_len</b>)
22<h3>Arguments</h3>
23<dl>
24<dt><b>fd</b>
25<dd>Connection socket descriptor
26<dt><b>name</b>
27<dd>Buffer to take client address name
28<dt><b>name_len</b>
29<dd>Length of client address name buffer
30<dt><b>rip</b>
31<dd>Buffer to take client address IP qotted quad
32<dt><b>rip_len</b>
33<dd>Length of client address IP buffer
34</dl>
35<h3>Description</h3>
36<blockquote>
37This function fills in <tt><b>name</b></tt> and <tt><b>rip</b></tt> with the name and IP of
38the client connected with socket descriptor <tt><b>fd</b></tt>. Names may be
39truncated if there is not enough room. If either cannot be
40determined, they will be returned as valid zero-length strings.
41</blockquote>
42<hr>
Andy Green9f990342011-02-12 11:57:45 +000043<h2>libwebsocket_service_fd - Service polled socket with something waiting</h2>
44<i>int</i>
45<b>libwebsocket_service_fd</b>
Peter Hinz56885f32011-03-02 22:03:47 +000046(<i>struct libwebsocket_context *</i> <b>context</b>,
Andy Green9f990342011-02-12 11:57:45 +000047<i>struct pollfd *</i> <b>pollfd</b>)
48<h3>Arguments</h3>
49<dl>
Peter Hinz56885f32011-03-02 22:03:47 +000050<dt><b>context</b>
Andy Green9f990342011-02-12 11:57:45 +000051<dd>Websocket context
52<dt><b>pollfd</b>
53<dd>The pollfd entry describing the socket fd and which events
54happened.
55</dl>
56<h3>Description</h3>
57<blockquote>
58This function closes any active connections and then frees the
59context. After calling this, any further use of the context is
60undefined.
61</blockquote>
62<hr>
Andy Green6964bb52011-01-23 16:50:33 +000063<h2>libwebsocket_context_destroy - Destroy the websocket context</h2>
64<i>void</i>
65<b>libwebsocket_context_destroy</b>
Peter Hinz56885f32011-03-02 22:03:47 +000066(<i>struct libwebsocket_context *</i> <b>context</b>)
Andy Green6964bb52011-01-23 16:50:33 +000067<h3>Arguments</h3>
68<dl>
Peter Hinz56885f32011-03-02 22:03:47 +000069<dt><b>context</b>
Andy Green6964bb52011-01-23 16:50:33 +000070<dd>Websocket context
71</dl>
72<h3>Description</h3>
73<blockquote>
74This function closes any active connections and then frees the
75context. After calling this, any further use of the context is
76undefined.
77</blockquote>
78<hr>
79<h2>libwebsocket_service - Service any pending websocket activity</h2>
80<i>int</i>
81<b>libwebsocket_service</b>
Peter Hinz56885f32011-03-02 22:03:47 +000082(<i>struct libwebsocket_context *</i> <b>context</b>,
Andy Green6964bb52011-01-23 16:50:33 +000083<i>int</i> <b>timeout_ms</b>)
84<h3>Arguments</h3>
85<dl>
Peter Hinz56885f32011-03-02 22:03:47 +000086<dt><b>context</b>
Andy Green6964bb52011-01-23 16:50:33 +000087<dd>Websocket context
88<dt><b>timeout_ms</b>
89<dd>Timeout for poll; 0 means return immediately if nothing needed
90service otherwise block and service immediately, returning
91after the timeout if nothing needed service.
92</dl>
93<h3>Description</h3>
94<blockquote>
95This function deals with any pending websocket traffic, for three
96kinds of event. It handles these events on both server and client
97types of connection the same.
98<p>
991) Accept new connections to our context's server
100<p>
1012) Perform pending broadcast writes initiated from other forked
102processes (effectively serializing asynchronous broadcasts)
103<p>
1043) Call the receive callback for incoming frame data received by
105server or client connections.
106<p>
107You need to call this service function periodically to all the above
108functions to happen; if your application is single-threaded you can
109just call it in your main event loop.
110<p>
111Alternatively you can fork a new process that asynchronously handles
112calling this service in a loop. In that case you are happy if this
113call blocks your thread until it needs to take care of something and
114would call it with a large nonzero timeout. Your loop then takes no
115CPU while there is nothing happening.
116<p>
117If you are calling it in a single-threaded app, you don't want it to
118wait around blocking other things in your loop from happening, so you
119would call it with a timeout_ms of 0, so it returns immediately if
120nothing is pending, or as soon as it services whatever was pending.
121</blockquote>
122<hr>
Andy Green32375b72011-02-19 08:32:53 +0000123<h2>libwebsocket_callback_on_writable - Request a callback when this socket becomes able to be written to without blocking</h2>
Andy Green90c7cbc2011-01-27 06:26:52 +0000124<i>int</i>
125<b>libwebsocket_callback_on_writable</b>
Peter Hinz56885f32011-03-02 22:03:47 +0000126(<i>struct libwebsocket_context *</i> <b>context</b>,
Andy Green62c54d22011-02-14 09:14:25 +0000127<i>struct libwebsocket *</i> <b>wsi</b>)
Andy Green90c7cbc2011-01-27 06:26:52 +0000128<h3>Arguments</h3>
129<dl>
Peter Hinz56885f32011-03-02 22:03:47 +0000130<dt><b>context</b>
Andy Green32375b72011-02-19 08:32:53 +0000131<dd>libwebsockets context
Andy Green90c7cbc2011-01-27 06:26:52 +0000132<dt><b>wsi</b>
133<dd>Websocket connection instance to get callback for
134</dl>
135<hr>
136<h2>libwebsocket_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>
137<i>int</i>
138<b>libwebsocket_callback_on_writable_all_protocol</b>
139(<i>const struct libwebsocket_protocols *</i> <b>protocol</b>)
140<h3>Arguments</h3>
141<dl>
142<dt><b>protocol</b>
143<dd>Protocol whose connections will get callbacks
144</dl>
145<hr>
Andy Greenbe93fef2011-02-14 20:25:43 +0000146<h2>libwebsocket_set_timeout - marks the wsi as subject to a timeout</h2>
147<i>void</i>
148<b>libwebsocket_set_timeout</b>
149(<i>struct libwebsocket *</i> <b>wsi</b>,
150<i>enum pending_timeout</i> <b>reason</b>,
151<i>int</i> <b>secs</b>)
152<h3>Arguments</h3>
153<dl>
154<dt><b>wsi</b>
155<dd>Websocket connection instance
156<dt><b>reason</b>
157<dd>timeout reason
158<dt><b>secs</b>
159<dd>how many seconds
160</dl>
161<h3>Description</h3>
162<blockquote>
163<p>
164You will not need this unless you are doing something special
165</blockquote>
166<hr>
Andy Greena6cbece2011-01-27 20:06:03 +0000167<h2>libwebsocket_get_socket_fd - returns the socket file descriptor</h2>
168<i>int</i>
169<b>libwebsocket_get_socket_fd</b>
170(<i>struct libwebsocket *</i> <b>wsi</b>)
171<h3>Arguments</h3>
172<dl>
173<dt><b>wsi</b>
174<dd>Websocket connection instance
175</dl>
176<h3>Description</h3>
177<blockquote>
178<p>
179You will not need this unless you are doing something special
180</blockquote>
181<hr>
Andy Green90c7cbc2011-01-27 06:26:52 +0000182<h2>libwebsocket_rx_flow_control - Enable and disable socket servicing for receieved packets.</h2>
183<i>int</i>
184<b>libwebsocket_rx_flow_control</b>
185(<i>struct libwebsocket *</i> <b>wsi</b>,
186<i>int</i> <b>enable</b>)
187<h3>Arguments</h3>
188<dl>
189<dt><b>wsi</b>
190<dd>Websocket connection instance to get callback for
191<dt><b>enable</b>
192<dd>0 = disable read servicing for this connection, 1 = enable
193</dl>
194<h3>Description</h3>
195<blockquote>
196<p>
197If the output side of a server process becomes choked, this allows flow
198control for the input side.
199</blockquote>
200<hr>
Andy Green2ac5a6f2011-01-28 10:00:18 +0000201<h2>libwebsocket_canonical_hostname - returns this host's hostname</h2>
202<i>const char *</i>
203<b>libwebsocket_canonical_hostname</b>
Peter Hinz56885f32011-03-02 22:03:47 +0000204(<i>struct libwebsocket_context *</i> <b>context</b>)
Andy Green2ac5a6f2011-01-28 10:00:18 +0000205<h3>Arguments</h3>
206<dl>
Peter Hinz56885f32011-03-02 22:03:47 +0000207<dt><b>context</b>
Andy Green2ac5a6f2011-01-28 10:00:18 +0000208<dd>Websocket context
209</dl>
210<h3>Description</h3>
211<blockquote>
212<p>
213This is typically used by client code to fill in the host parameter
214when making a client connection. You can only call it after the context
215has been created.
216</blockquote>
217<hr>
Andy Green4739e5c2011-01-22 12:51:57 +0000218<h2>libwebsocket_create_context - Create the websocket handler</h2>
Andy Greene92cd172011-01-19 13:11:55 +0000219<i>struct libwebsocket_context *</i>
Andy Green4739e5c2011-01-22 12:51:57 +0000220<b>libwebsocket_create_context</b>
Andy Green62a12932010-11-03 11:19:23 +0000221(<i>int</i> <b>port</b>,
Peter Hinz56885f32011-03-02 22:03:47 +0000222<i>const char *</i> <b>interf</b>,
Andy Greenb45993c2010-12-18 15:13:50 +0000223<i>struct libwebsocket_protocols *</i> <b>protocols</b>,
Andy Greend6e09112011-03-05 16:12:15 +0000224<i>struct libwebsocket_extension *</i> <b>extensions</b>,
Andy Green3faa9c72010-11-08 17:03:03 +0000225<i>const char *</i> <b>ssl_cert_filepath</b>,
226<i>const char *</i> <b>ssl_private_key_filepath</b>,
David Galeano2f82be82013-01-09 16:25:54 +0800227<i>const char *</i> <b>ssl_ca_filepath</b>,
Andy Green3faa9c72010-11-08 17:03:03 +0000228<i>int</i> <b>gid</b>,
Andy Green8014b292011-01-30 20:57:25 +0000229<i>int</i> <b>uid</b>,
Alon Levy0291eb32012-10-19 11:21:56 +0200230<i>unsigned int</i> <b>options</b>,
231<i>void *</i> <b>user</b>)
Andy Green62a12932010-11-03 11:19:23 +0000232<h3>Arguments</h3>
233<dl>
234<dt><b>port</b>
Andy Green4739e5c2011-01-22 12:51:57 +0000235<dd>Port to listen on... you can use 0 to suppress listening on
236any port, that's what you want if you are not running a
237websocket server at all but just using it as a client
Peter Hinz56885f32011-03-02 22:03:47 +0000238<dt><b>interf</b>
Andy Green32375b72011-02-19 08:32:53 +0000239<dd>NULL to bind the listen socket to all interfaces, or the
240interface name, eg, "eth2"
Andy Green4f3943a2010-11-12 10:44:16 +0000241<dt><b>protocols</b>
242<dd>Array of structures listing supported protocols and a protocol-
243specific callback for each one. The list is ended with an
244entry that has a NULL callback pointer.
Andy Greenb45993c2010-12-18 15:13:50 +0000245It's not const because we write the owning_server member
Andy Greenc5114822011-03-06 10:29:35 +0000246<dt><b>extensions</b>
247<dd>NULL or array of libwebsocket_extension structs listing the
248extensions this context supports
Andy Green3faa9c72010-11-08 17:03:03 +0000249<dt><b>ssl_cert_filepath</b>
250<dd>If libwebsockets was compiled to use ssl, and you want
251to listen using SSL, set to the filepath to fetch the
252server cert from, otherwise NULL for unencrypted
253<dt><b>ssl_private_key_filepath</b>
254<dd>filepath to private key if wanting SSL mode,
255else ignored
David Galeano2f82be82013-01-09 16:25:54 +0800256<dt><b>ssl_ca_filepath</b>
Andy Green988bd982013-01-10 12:26:13 +0800257<dd>CA certificate filepath or NULL
Andy Green3faa9c72010-11-08 17:03:03 +0000258<dt><b>gid</b>
259<dd>group id to change to after setting listen socket, or -1.
260<dt><b>uid</b>
261<dd>user id to change to after setting listen socket, or -1.
Andy Greenbfb051f2011-02-09 08:49:14 +0000262<dt><b>options</b>
263<dd>0, or LWS_SERVER_OPTION_DEFEAT_CLIENT_MASK
Andy Green788c4a82012-10-22 12:29:57 +0100264<dt><b>user</b>
265<dd>optional user pointer that can be recovered via the context
266pointer using libwebsocket_context_user
Andy Green62a12932010-11-03 11:19:23 +0000267</dl>
268<h3>Description</h3>
269<blockquote>
Andy Green47943ae2010-11-12 11:15:49 +0000270This function creates the listening socket and takes care
Andy Green62a12932010-11-03 11:19:23 +0000271of all initialization in one step.
272<p>
Andy Greene92cd172011-01-19 13:11:55 +0000273After initialization, it returns a struct libwebsocket_context * that
274represents this server. After calling, user code needs to take care
275of calling <b>libwebsocket_service</b> with the context pointer to get the
276server's sockets serviced. This can be done in the same process context
277or a forked process, or another thread,
Andy Green47943ae2010-11-12 11:15:49 +0000278<p>
279The protocol callback functions are called for a handful of events
280including http requests coming in, websocket connections becoming
Andy Green62a12932010-11-03 11:19:23 +0000281established, and data arriving; it's also called periodically to allow
282async transmission.
283<p>
Andy Green47943ae2010-11-12 11:15:49 +0000284HTTP requests are sent always to the FIRST protocol in <tt><b>protocol</b></tt>, since
285at that time websocket protocol has not been negotiated. Other
286protocols after the first one never see any HTTP callack activity.
287<p>
Andy Green62a12932010-11-03 11:19:23 +0000288The server created is a simple http server by default; part of the
289websocket standard is upgrading this http connection to a websocket one.
290<p>
291This allows the same server to provide files like scripts and favicon /
292images or whatever over http and dynamic data over websockets all in
293one place; they're all handled in the user callback.
294</blockquote>
295<hr>
Andy Greene92cd172011-01-19 13:11:55 +0000296<h2>libwebsockets_fork_service_loop - Optional helper function forks off a process for the websocket server loop. You don't have to use this but if not, you have to make sure you are calling libwebsocket_service periodically to service the websocket traffic</h2>
297<i>int</i>
298<b>libwebsockets_fork_service_loop</b>
Peter Hinz56885f32011-03-02 22:03:47 +0000299(<i>struct libwebsocket_context *</i> <b>context</b>)
Andy Greene92cd172011-01-19 13:11:55 +0000300<h3>Arguments</h3>
301<dl>
Peter Hinz56885f32011-03-02 22:03:47 +0000302<dt><b>context</b>
Andy Greene92cd172011-01-19 13:11:55 +0000303<dd>server context returned by creation function
304</dl>
305<hr>
Andy Greenb45993c2010-12-18 15:13:50 +0000306<h2>libwebsockets_get_protocol - Returns a protocol pointer from a websocket connection.</h2>
307<i>const struct libwebsocket_protocols *</i>
308<b>libwebsockets_get_protocol</b>
309(<i>struct libwebsocket *</i> <b>wsi</b>)
310<h3>Arguments</h3>
311<dl>
312<dt><b>wsi</b>
313<dd>pointer to struct websocket you want to know the protocol of
314</dl>
315<h3>Description</h3>
316<blockquote>
317<p>
318This is useful to get the protocol to broadcast back to from inside
319the callback.
320</blockquote>
321<hr>
Andy Greene92cd172011-01-19 13:11:55 +0000322<h2>libwebsockets_broadcast - Sends a buffer to the callback for all active connections of the given protocol.</h2>
Andy Greenb45993c2010-12-18 15:13:50 +0000323<i>int</i>
324<b>libwebsockets_broadcast</b>
325(<i>const struct libwebsocket_protocols *</i> <b>protocol</b>,
326<i>unsigned char *</i> <b>buf</b>,
327<i>size_t</i> <b>len</b>)
328<h3>Arguments</h3>
329<dl>
330<dt><b>protocol</b>
331<dd>pointer to the protocol you will broadcast to all members of
332<dt><b>buf</b>
333<dd>buffer containing the data to be broadcase. NOTE: this has to be
334allocated with LWS_SEND_BUFFER_PRE_PADDING valid bytes before
335the pointer and LWS_SEND_BUFFER_POST_PADDING afterwards in the
336case you are calling this function from callback context.
337<dt><b>len</b>
338<dd>length of payload data in buf, starting from buf.
339</dl>
340<h3>Description</h3>
341<blockquote>
342This function allows bulk sending of a packet to every connection using
343the given protocol. It does not send the data directly; instead it calls
344the callback with a reason type of LWS_CALLBACK_BROADCAST. If the callback
345wants to actually send the data for that connection, the callback itself
346should call <b>libwebsocket_write</b>.
347<p>
348<b>libwebsockets_broadcast</b> can be called from another fork context without
349having to take any care about data visibility between the processes, it'll
350"just work".
351</blockquote>
352<hr>
Andy Green43db0452013-01-10 19:50:35 +0800353<h2>lws_set_log_level - Set the logging bitfield</h2>
354<i>void</i>
355<b>lws_set_log_level</b>
Andy Greende8f27a2013-01-12 09:17:42 +0800356(<i>int</i> <b>level</b>,
357<i>void (*</i><b>log_emit_function</b>) <i>(const char *line)</i>)
Andy Green43db0452013-01-10 19:50:35 +0800358<h3>Arguments</h3>
359<dl>
360<dt><b>level</b>
361<dd>OR together the LLL_ debug contexts you want output from
Andy Greende8f27a2013-01-12 09:17:42 +0800362<dt><b>log_emit_function</b>
363<dd>NULL to leave it as it is, or a user-supplied
364function to perform log string emission instead of
365the default stderr one.
Andy Green43db0452013-01-10 19:50:35 +0800366</dl>
367<h3>Description</h3>
368<blockquote>
Andy Greende8f27a2013-01-12 09:17:42 +0800369log level defaults to "err" and "warn" contexts enabled only and
370emission on stderr.
Andy Green43db0452013-01-10 19:50:35 +0800371</blockquote>
372<hr>
Andy Green38e57bb2011-01-19 12:20:27 +0000373<h2>libwebsockets_remaining_packet_payload - Bytes to come before "overall" rx packet is complete</h2>
374<i>size_t</i>
375<b>libwebsockets_remaining_packet_payload</b>
376(<i>struct libwebsocket *</i> <b>wsi</b>)
377<h3>Arguments</h3>
378<dl>
379<dt><b>wsi</b>
380<dd>Websocket instance (available from user callback)
381</dl>
382<h3>Description</h3>
383<blockquote>
384This function is intended to be called from the callback if the
385user code is interested in "complete packets" from the client.
386libwebsockets just passes through payload as it comes and issues a buffer
387additionally when it hits a built-in limit. The LWS_CALLBACK_RECEIVE
388callback handler can use this API to find out if the buffer it has just
389been given is the last piece of a "complete packet" from the client --
390when that is the case <b>libwebsockets_remaining_packet_payload</b> will return
3910.
392<p>
393Many protocols won't care becuse their packets are always small.
394</blockquote>
395<hr>
Andy Green90c7cbc2011-01-27 06:26:52 +0000396<h2>libwebsocket_client_connect - Connect to another websocket server</h2>
397<i>struct libwebsocket *</i>
398<b>libwebsocket_client_connect</b>
Peter Hinz56885f32011-03-02 22:03:47 +0000399(<i>struct libwebsocket_context *</i> <b>context</b>,
Andy Green90c7cbc2011-01-27 06:26:52 +0000400<i>const char *</i> <b>address</b>,
401<i>int</i> <b>port</b>,
402<i>int</i> <b>ssl_connection</b>,
403<i>const char *</i> <b>path</b>,
404<i>const char *</i> <b>host</b>,
405<i>const char *</i> <b>origin</b>,
Andy Greenbfb051f2011-02-09 08:49:14 +0000406<i>const char *</i> <b>protocol</b>,
407<i>int</i> <b>ietf_version_or_minus_one</b>)
Andy Green90c7cbc2011-01-27 06:26:52 +0000408<h3>Arguments</h3>
409<dl>
Peter Hinz56885f32011-03-02 22:03:47 +0000410<dt><b>context</b>
Andy Green90c7cbc2011-01-27 06:26:52 +0000411<dd>Websocket context
412<dt><b>address</b>
413<dd>Remote server address, eg, "myserver.com"
414<dt><b>port</b>
415<dd>Port to connect to on the remote server, eg, 80
416<dt><b>ssl_connection</b>
417<dd>0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self
418signed certs
419<dt><b>path</b>
420<dd>Websocket path on server
421<dt><b>host</b>
422<dd>Hostname on server
423<dt><b>origin</b>
424<dd>Socket origin name
425<dt><b>protocol</b>
426<dd>Comma-separated list of protocols being asked for from
427the server, or just one. The server will pick the one it
428likes best.
Andy Greenbfb051f2011-02-09 08:49:14 +0000429<dt><b>ietf_version_or_minus_one</b>
430<dd>-1 to ask to connect using the default, latest
431protocol supported, or the specific protocol ordinal
Andy Green90c7cbc2011-01-27 06:26:52 +0000432</dl>
433<h3>Description</h3>
434<blockquote>
435This function creates a connection to a remote server
436</blockquote>
437<hr>
David Brooks2c60d952012-04-20 12:19:01 +0800438<h2>libwebsocket_client_connect_extended - Connect to another websocket server</h2>
439<i>struct libwebsocket *</i>
440<b>libwebsocket_client_connect_extended</b>
441(<i>struct libwebsocket_context *</i> <b>context</b>,
442<i>const char *</i> <b>address</b>,
443<i>int</i> <b>port</b>,
444<i>int</i> <b>ssl_connection</b>,
445<i>const char *</i> <b>path</b>,
446<i>const char *</i> <b>host</b>,
447<i>const char *</i> <b>origin</b>,
448<i>const char *</i> <b>protocol</b>,
449<i>int</i> <b>ietf_version_or_minus_one</b>,
450<i>void *</i> <b>userdata</b>)
451<h3>Arguments</h3>
452<dl>
453<dt><b>context</b>
454<dd>Websocket context
455<dt><b>address</b>
456<dd>Remote server address, eg, "myserver.com"
457<dt><b>port</b>
458<dd>Port to connect to on the remote server, eg, 80
459<dt><b>ssl_connection</b>
460<dd>0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self
461signed certs
462<dt><b>path</b>
463<dd>Websocket path on server
464<dt><b>host</b>
465<dd>Hostname on server
466<dt><b>origin</b>
467<dd>Socket origin name
468<dt><b>protocol</b>
469<dd>Comma-separated list of protocols being asked for from
470the server, or just one. The server will pick the one it
471likes best.
472<dt><b>ietf_version_or_minus_one</b>
473<dd>-1 to ask to connect using the default, latest
474protocol supported, or the specific protocol ordinal
475<dt><b>userdata</b>
476<dd>Pre-allocated user data
477</dl>
478<h3>Description</h3>
479<blockquote>
480This function creates a connection to a remote server
481</blockquote>
482<hr>
Andy Green8f037e42010-12-19 22:13:26 +0000483<h2>callback - User server actions</h2>
Andy Green07b56e62011-10-03 19:30:22 +0800484<i>LWS_EXTERN int</i>
Andy Green8f037e42010-12-19 22:13:26 +0000485<b>callback</b>
Darin Willitsc19456f2011-02-14 17:52:39 +0000486(<i>struct libwebsocket_context *</i> <b>context</b>,
Andy Green62c54d22011-02-14 09:14:25 +0000487<i>struct libwebsocket *</i> <b>wsi</b>,
Andy Green8f037e42010-12-19 22:13:26 +0000488<i>enum libwebsocket_callback_reasons</i> <b>reason</b>,
489<i>void *</i> <b>user</b>,
490<i>void *</i> <b>in</b>,
491<i>size_t</i> <b>len</b>)
492<h3>Arguments</h3>
493<dl>
Andy Green32375b72011-02-19 08:32:53 +0000494<dt><b>context</b>
495<dd>Websockets context
Andy Green8f037e42010-12-19 22:13:26 +0000496<dt><b>wsi</b>
497<dd>Opaque websocket instance pointer
498<dt><b>reason</b>
499<dd>The reason for the call
500<dt><b>user</b>
501<dd>Pointer to per-session user data allocated by library
502<dt><b>in</b>
503<dd>Pointer used for some callback reasons
504<dt><b>len</b>
505<dd>Length set for some callback reasons
506</dl>
507<h3>Description</h3>
508<blockquote>
509This callback is the way the user controls what is served. All the
510protocol detail is hidden and handled by the library.
511<p>
512For each connection / session there is user data allocated that is
513pointed to by "user". You set the size of this user data area when
514the library is initialized with libwebsocket_create_server.
515<p>
516You get an opportunity to initialize user data when called back with
517LWS_CALLBACK_ESTABLISHED reason.
518</blockquote>
519<h3>LWS_CALLBACK_ESTABLISHED</h3>
520<blockquote>
Andy Green90c7cbc2011-01-27 06:26:52 +0000521after the server completes a handshake with
522an incoming client
523</blockquote>
David Brooks2c60d952012-04-20 12:19:01 +0800524<h3>LWS_CALLBACK_CLIENT_CONNECTION_ERROR</h3>
525<blockquote>
526the request client connection has
527been unable to complete a handshake with the remote server
528</blockquote>
Andy Green90c7cbc2011-01-27 06:26:52 +0000529<h3>LWS_CALLBACK_CLIENT_ESTABLISHED</h3>
530<blockquote>
531after your client connection completed
532a handshake with the remote server
Andy Green8f037e42010-12-19 22:13:26 +0000533</blockquote>
534<h3>LWS_CALLBACK_CLOSED</h3>
535<blockquote>
536when the websocket session ends
537</blockquote>
538<h3>LWS_CALLBACK_BROADCAST</h3>
539<blockquote>
540signal to send to client (you would use
541<b>libwebsocket_write</b> taking care about the
542special buffer requirements
543</blockquote>
544<h3>LWS_CALLBACK_RECEIVE</h3>
545<blockquote>
Andy Green90c7cbc2011-01-27 06:26:52 +0000546data has appeared for this server endpoint from a
547remote client, it can be found at *in and is
548len bytes long
549</blockquote>
Andy Greena6cbece2011-01-27 20:06:03 +0000550<h3>LWS_CALLBACK_CLIENT_RECEIVE_PONG</h3>
551<blockquote>
552if you elected to see PONG packets,
553they appear with this callback reason. PONG
554packets only exist in 04+ protocol
555</blockquote>
Andy Green90c7cbc2011-01-27 06:26:52 +0000556<h3>LWS_CALLBACK_CLIENT_RECEIVE</h3>
557<blockquote>
558data has appeared from the server for the
559client connection, it can be found at *in and
560is len bytes long
Andy Green8f037e42010-12-19 22:13:26 +0000561</blockquote>
562<h3>LWS_CALLBACK_HTTP</h3>
563<blockquote>
564an http request has come from a client that is not
565asking to upgrade the connection to a websocket
566one. This is a chance to serve http content,
567for example, to send a script to the client
568which will then open the websockets connection.
Andy Green7619c472011-01-23 17:47:08 +0000569<tt><b>in</b></tt> points to the URI path requested and
Andy Green8f037e42010-12-19 22:13:26 +0000570<b>libwebsockets_serve_http_file</b> makes it very
571simple to send back a file to the client.
Andy Green24b588b2013-01-13 09:53:18 +0800572Normally after sending the file you are done
573with the http connection, since the rest of the
574activity will come by websockets from the script
575that was delivered by http, so you will want to
576return 1; to close and free up the connection.
577That's important because it uses a slot in the
578total number of client connections allowed set
579by MAX_CLIENTS.
Andy Green8f037e42010-12-19 22:13:26 +0000580</blockquote>
Andy Greend280b6e2013-01-15 13:40:23 +0800581<h3>LWS_CALLBACK_HTTP_FILE_COMPLETION</h3>
582<blockquote>
583a file requested to be send down
584http link has completed.
585</blockquote>
Andy Greene9739ed2011-03-07 21:40:59 +0000586<h3>LWS_CALLBACK_SERVER_WRITEABLE</h3>
Andy Green90c7cbc2011-01-27 06:26:52 +0000587<blockquote>
Andy Greene9739ed2011-03-07 21:40:59 +0000588If you call
Andy Green90c7cbc2011-01-27 06:26:52 +0000589<b>libwebsocket_callback_on_writable</b> on a connection, you will
Andy Greene9739ed2011-03-07 21:40:59 +0000590get one of these callbacks coming when the connection socket
591is able to accept another write packet without blocking.
592If it already was able to take another packet without blocking,
593you'll get this callback at the next call to the service loop
594function. Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE
595and servers get LWS_CALLBACK_SERVER_WRITEABLE.
Andy Green90c7cbc2011-01-27 06:26:52 +0000596</blockquote>
Andy Green07034092011-02-13 08:37:12 +0000597<h3>LWS_CALLBACK_FILTER_NETWORK_CONNECTION</h3>
598<blockquote>
599called when a client connects to
600the server at network level; the connection is accepted but then
601passed to this callback to decide whether to hang up immediately
602or not, based on the client IP. <tt><b>user</b></tt> contains the connection
603socket's descriptor. Return non-zero to terminate
604the connection before sending or receiving anything.
605Because this happens immediately after the network connection
606from the client, there's no websocket protocol selected yet so
607this callback is issued only to protocol 0.
608</blockquote>
Andy Greenc85619d2011-02-13 08:25:26 +0000609<h3>LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION</h3>
610<blockquote>
611called when the handshake has
612been received and parsed from the client, but the response is
613not sent yet. Return non-zero to disallow the connection.
Andy Green07034092011-02-13 08:37:12 +0000614<tt><b>user</b></tt> is a pointer to an array of struct lws_tokens, you can
615use the header enums lws_token_indexes from libwebsockets.h
616to check for and read the supported header presence and
617content before deciding to allow the handshake to proceed or
618to kill the connection.
Andy Green0894bda2011-02-19 09:09:11 +0000619</blockquote>
620<h3>LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS</h3>
621<blockquote>
Andy Green6901cb32011-02-21 08:06:47 +0000622if configured for
Andy Green0894bda2011-02-19 09:09:11 +0000623including OpenSSL support, this callback allows your user code
624to perform extra <b>SSL_CTX_load_verify_locations</b> or similar
625calls to direct OpenSSL where to find certificates the client
626can use to confirm the remote server identity. <tt><b>user</b></tt> is the
627OpenSSL SSL_CTX*
Andy Green6901cb32011-02-21 08:06:47 +0000628</blockquote>
629<h3>LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS</h3>
630<blockquote>
631if configured for
632including OpenSSL support, this callback allows your user code
633to load extra certifcates into the server which allow it to
634verify the validity of certificates returned by clients. <tt><b>user</b></tt>
635is the server's OpenSSL SSL_CTX*
636</blockquote>
637<h3>LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION</h3>
638<blockquote>
639if the
640libwebsockets context was created with the option
641LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this
642callback is generated during OpenSSL verification of the cert
643sent from the client. It is sent to protocol[0] callback as
644no protocol has been negotiated on the connection yet.
645Notice that the libwebsockets context and wsi are both NULL
646during this callback. See
647</blockquote>
648<h3>http</h3>
649<blockquote>
650//www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
651to understand more detail about the OpenSSL callback that
652generates this libwebsockets callback and the meanings of the
653arguments passed. In this callback, <tt><b>user</b></tt> is the x509_ctx,
654<tt><b>in</b></tt> is the ssl pointer and <tt><b>len</b></tt> is preverify_ok
655Notice that this callback maintains libwebsocket return
656conventions, return 0 to mean the cert is OK or 1 to fail it.
657This also means that if you don't handle this callback then
658the default callback action of returning 0 allows the client
659certificates.
Andy Green385e7ad2011-03-01 21:06:02 +0000660</blockquote>
661<h3>LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER</h3>
662<blockquote>
663this callback happens
664when a client handshake is being compiled. <tt><b>user</b></tt> is NULL,
665<tt><b>in</b></tt> is a char **, it's pointing to a char * which holds the
666next location in the header buffer where you can add
667headers, and <tt><b>len</b></tt> is the remaining space in the header buffer,
668which is typically some hundreds of bytes. So, to add a canned
669cookie, your handler code might look similar to:
670<p>
671char **p = (char **)in;
672<p>
673if (len &lt; 100)
674return 1;
675<p>
676*p += sprintf(*p, "Cookie: a=b\x0d\x0a");
677<p>
678return 0;
679<p>
680Notice if you add anything, you just have to take care about
681the CRLF on the line you added. Obviously this callback is
682optional, if you don't handle it everything is fine.
683<p>
684Notice the callback is coming to protocols[0] all the time,
685because there is no specific protocol handshook yet.
Andy Greenc5114822011-03-06 10:29:35 +0000686</blockquote>
687<h3>LWS_CALLBACK_CONFIRM_EXTENSION_OKAY</h3>
688<blockquote>
689When the server handshake code
690sees that it does support a requested extension, before
691accepting the extension by additing to the list sent back to
692the client it gives this callback just to check that it's okay
693to use that extension. It calls back to the requested protocol
694and with <tt><b>in</b></tt> being the extension name, <tt><b>len</b></tt> is 0 and <tt><b>user</b></tt> is
695valid. Note though at this time the ESTABLISHED callback hasn't
696happened yet so if you initialize <tt><b>user</b></tt> content there, <tt><b>user</b></tt>
697content during this callback might not be useful for anything.
698Notice this callback comes to protocols[0].
Andy Greenc6517fa2011-03-06 13:15:29 +0000699</blockquote>
700<h3>LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED</h3>
701<blockquote>
702When a client
703connection is being prepared to start a handshake to a server,
704each supported extension is checked with protocols[0] callback
705with this reason, giving the user code a chance to suppress the
706claim to support that extension by returning non-zero. If
707unhandled, by default 0 will be returned and the extension
708support included in the header to the server. Notice this
709callback comes to protocols[0].
Andy Greenc85619d2011-02-13 08:25:26 +0000710<p>
711The next four reasons are optional and only need taking care of if you
712will be integrating libwebsockets sockets into an external polling
713array.
714</blockquote>
715<h3>LWS_CALLBACK_ADD_POLL_FD</h3>
716<blockquote>
717libwebsocket deals with its <b>poll</b> loop
718internally, but in the case you are integrating with another
719server you will need to have libwebsocket sockets share a
720polling array with the other server. This and the other
721POLL_FD related callbacks let you put your specialized
722poll array interface code in the callback for protocol 0, the
723first protocol you support, usually the HTTP protocol in the
724serving case. This callback happens when a socket needs to be
725</blockquote>
726<h3>added to the polling loop</h3>
727<blockquote>
728<tt><b>user</b></tt> contains the fd, and
729<tt><b>len</b></tt> is the events bitmap (like, POLLIN). If you are using the
730internal polling loop (the "service" callback), you can just
731ignore these callbacks.
732</blockquote>
733<h3>LWS_CALLBACK_DEL_POLL_FD</h3>
734<blockquote>
735This callback happens when a socket descriptor
736needs to be removed from an external polling array. <tt><b>user</b></tt> is
737the socket desricptor. If you are using the internal polling
738loop, you can just ignore it.
739</blockquote>
740<h3>LWS_CALLBACK_SET_MODE_POLL_FD</h3>
741<blockquote>
742This callback happens when libwebsockets
743wants to modify the events for the socket descriptor in <tt><b>user</b></tt>.
744The handler should OR <tt><b>len</b></tt> on to the events member of the pollfd
745struct for this socket descriptor. If you are using the
746internal polling loop, you can just ignore it.
747</blockquote>
748<h3>LWS_CALLBACK_CLEAR_MODE_POLL_FD</h3>
749<blockquote>
750This callback occurs when libwebsockets
751wants to modify the events for the socket descriptor in <tt><b>user</b></tt>.
752The handler should AND ~<tt><b>len</b></tt> on to the events member of the
753pollfd struct for this socket descriptor. If you are using the
754internal polling loop, you can just ignore it.
755</blockquote>
Andy Green8f037e42010-12-19 22:13:26 +0000756<hr>
Andy Green57b4e9a2011-03-06 13:14:46 +0000757<h2>extension_callback - Hooks to allow extensions to operate</h2>
Andy Green07b56e62011-10-03 19:30:22 +0800758<i>LWS_EXTERN int</i>
Andy Green57b4e9a2011-03-06 13:14:46 +0000759<b>extension_callback</b>
760(<i>struct libwebsocket_context *</i> <b>context</b>,
Andy Green46c2ea02011-03-22 09:04:01 +0000761<i>struct libwebsocket_extension *</i> <b>ext</b>,
Andy Green57b4e9a2011-03-06 13:14:46 +0000762<i>struct libwebsocket *</i> <b>wsi</b>,
David Brooks2c60d952012-04-20 12:19:01 +0800763<i>enum libwebsocket_extension_callback_reasons</i> <b>reason</b>,
Andy Green57b4e9a2011-03-06 13:14:46 +0000764<i>void *</i> <b>user</b>,
765<i>void *</i> <b>in</b>,
766<i>size_t</i> <b>len</b>)
767<h3>Arguments</h3>
768<dl>
769<dt><b>context</b>
770<dd>Websockets context
Andy Green46c2ea02011-03-22 09:04:01 +0000771<dt><b>ext</b>
772<dd>This extension
Andy Green57b4e9a2011-03-06 13:14:46 +0000773<dt><b>wsi</b>
774<dd>Opaque websocket instance pointer
775<dt><b>reason</b>
776<dd>The reason for the call
777<dt><b>user</b>
778<dd>Pointer to per-session user data allocated by library
779<dt><b>in</b>
780<dd>Pointer used for some callback reasons
781<dt><b>len</b>
782<dd>Length set for some callback reasons
783</dl>
784<h3>Description</h3>
785<blockquote>
786Each extension that is active on a particular connection receives
787callbacks during the connection lifetime to allow the extension to
788operate on websocket data and manage itself.
789<p>
790Libwebsockets takes care of allocating and freeing "user" memory for
791each active extension on each connection. That is what is pointed to
792by the <tt><b>user</b></tt> parameter.
793</blockquote>
794<h3>LWS_EXT_CALLBACK_CONSTRUCT</h3>
795<blockquote>
796called when the server has decided to
797select this extension from the list provided by the client,
798just before the server will send back the handshake accepting
799the connection with this extension active. This gives the
800extension a chance to initialize its connection context found
801in <tt><b>user</b></tt>.
802</blockquote>
Andy Green2366b1c2011-03-06 13:15:31 +0000803<h3>LWS_EXT_CALLBACK_CLIENT_CONSTRUCT</h3>
804<blockquote>
805same as LWS_EXT_CALLBACK_CONSTRUCT
806but called when client is instantiating this extension. Some
807extensions will work the same on client and server side and then
808you can just merge handlers for both CONSTRUCTS.
809</blockquote>
Andy Green57b4e9a2011-03-06 13:14:46 +0000810<h3>LWS_EXT_CALLBACK_DESTROY</h3>
811<blockquote>
812called when the connection the extension was
813being used on is about to be closed and deallocated. It's the
814last chance for the extension to deallocate anything it has
815allocated in the user data (pointed to by <tt><b>user</b></tt>) before the
Andy Green2366b1c2011-03-06 13:15:31 +0000816user data is deleted. This same callback is used whether you
817are in client or server instantiation context.
Andy Green57b4e9a2011-03-06 13:14:46 +0000818</blockquote>
819<h3>LWS_EXT_CALLBACK_PACKET_RX_PREPARSE</h3>
820<blockquote>
821when this extension was active on
822a connection, and a packet of data arrived at the connection,
823it is passed to this callback to give the extension a chance to
824change the data, eg, decompress it. <tt><b>user</b></tt> is pointing to the
825extension's private connection context data, <tt><b>in</b></tt> is pointing
826to an lws_tokens struct, it consists of a char * pointer called
827token, and an int called token_len. At entry, these are
828set to point to the received buffer and set to the content
829length. If the extension will grow the content, it should use
830a new buffer allocated in its private user context data and
831set the pointed-to lws_tokens members to point to its buffer.
832</blockquote>
833<h3>LWS_EXT_CALLBACK_PACKET_TX_PRESEND</h3>
834<blockquote>
835this works the same way as
836LWS_EXT_CALLBACK_PACKET_RX_PREPARSE above, except it gives the
837extension a chance to change websocket data just before it will
838be sent out. Using the same lws_token pointer scheme in <tt><b>in</b></tt>,
839the extension can change the buffer and the length to be
840transmitted how it likes. Again if it wants to grow the
841buffer safely, it should copy the data into its own buffer and
842set the lws_tokens token pointer to it.
843</blockquote>
844<hr>
Andy Green4f3943a2010-11-12 10:44:16 +0000845<h2>struct libwebsocket_protocols - List of protocols and handlers server supports.</h2>
846<b>struct libwebsocket_protocols</b> {<br>
847&nbsp; &nbsp; <i>const char *</i> <b>name</b>;<br>
David Brooks2c60d952012-04-20 12:19:01 +0800848&nbsp; &nbsp; <i>callback_function *</i> <b>callback</b>;<br>
Andy Green4f3943a2010-11-12 10:44:16 +0000849&nbsp; &nbsp; <i>size_t</i> <b>per_session_data_size</b>;<br>
Andy Greenb45993c2010-12-18 15:13:50 +0000850&nbsp; &nbsp; <i>struct libwebsocket_context *</i> <b>owning_server</b>;<br>
851&nbsp; &nbsp; <i>int</i> <b>broadcast_socket_port</b>;<br>
852&nbsp; &nbsp; <i>int</i> <b>broadcast_socket_user_fd</b>;<br>
853&nbsp; &nbsp; <i>int</i> <b>protocol_index</b>;<br>
Andy Green4f3943a2010-11-12 10:44:16 +0000854};<br>
855<h3>Members</h3>
856<dl>
857<dt><b>name</b>
858<dd>Protocol name that must match the one given in the client
859Javascript new WebSocket(url, 'protocol') name
860<dt><b>callback</b>
861<dd>The service callback used for this protocol. It allows the
862service action for an entire protocol to be encapsulated in
863the protocol-specific callback
864<dt><b>per_session_data_size</b>
865<dd>Each new connection using this protocol gets
866this much memory allocated on connection establishment and
867freed on connection takedown. A pointer to this per-connection
868allocation is passed into the callback in the 'user' parameter
Andy Greenb45993c2010-12-18 15:13:50 +0000869<dt><b>owning_server</b>
870<dd>the server init call fills in this opaque pointer when
871registering this protocol with the server.
872<dt><b>broadcast_socket_port</b>
873<dd>the server init call fills this in with the
874localhost port number used to forward broadcasts for this
875protocol
876<dt><b>broadcast_socket_user_fd</b>
877<dd>the server init call fills this in ... the <b>main</b>
878process context can write to this socket to perform broadcasts
879(use the <b>libwebsockets_broadcast</b> api to do this instead,
880it works from any process context)
881<dt><b>protocol_index</b>
882<dd>which protocol we are starting from zero
Andy Green4f3943a2010-11-12 10:44:16 +0000883</dl>
884<h3>Description</h3>
885<blockquote>
886This structure represents one protocol supported by the server. An
887array of these structures is passed to <b>libwebsocket_create_server</b>
888allows as many protocols as you like to be handled by one server.
889</blockquote>
890<hr>
Andy Greend6e09112011-03-05 16:12:15 +0000891<h2>struct libwebsocket_extension - An extension we know how to cope with</h2>
892<b>struct libwebsocket_extension</b> {<br>
893&nbsp; &nbsp; <i>const char *</i> <b>name</b>;<br>
David Brooks2c60d952012-04-20 12:19:01 +0800894&nbsp; &nbsp; <i>extension_callback_function *</i> <b>callback</b>;<br>
Andy Greend6e09112011-03-05 16:12:15 +0000895&nbsp; &nbsp; <i>size_t</i> <b>per_session_data_size</b>;<br>
Andy Greenaa6fc442012-04-12 13:26:49 +0800896&nbsp; &nbsp; <i>void *</i> <b>per_context_private_data</b>;<br>
Andy Greend6e09112011-03-05 16:12:15 +0000897};<br>
898<h3>Members</h3>
899<dl>
900<dt><b>name</b>
901<dd>Formal extension name, eg, "deflate-stream"
902<dt><b>callback</b>
903<dd>Service callback
904<dt><b>per_session_data_size</b>
905<dd>Libwebsockets will auto-malloc this much
906memory for the use of the extension, a pointer
907to it comes in the <tt><b>user</b></tt> callback parameter
Andy Greenaa6fc442012-04-12 13:26:49 +0800908<dt><b>per_context_private_data</b>
909<dd>Optional storage for this externsion that
910is per-context, so it can track stuff across
911all sessions, etc, if it wants
Andy Greend6e09112011-03-05 16:12:15 +0000912</dl>
913<hr>