absorb README.rst into main README and code
[profile/ivi/libwebsockets.git] / libwebsockets-api-doc.html
1 <h2>libwebsockets_hangup_on_client - Server calls to terminate client connection</h2>
2 <i>void</i>
3 <b>libwebsockets_hangup_on_client</b>
4 (<i>struct libwebsocket_context *</i> <b>context</b>,
5 <i>int</i> <b>fd</b>)
6 <h3>Arguments</h3>
7 <dl>
8 <dt><b>context</b>
9 <dd>libwebsockets context
10 <dt><b>fd</b>
11 <dd>Connection socket descriptor
12 </dl>
13 <hr>
14 <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>
37 This function fills in <tt><b>name</b></tt> and <tt><b>rip</b></tt> with the name and IP of
38 the client connected with socket descriptor <tt><b>fd</b></tt>.  Names may be
39 truncated if there is not enough room.  If either cannot be
40 determined, they will be returned as valid zero-length strings.
41 </blockquote>
42 <hr>
43 <h2>libwebsocket_service_fd - Service polled socket with something waiting</h2>
44 <i>int</i>
45 <b>libwebsocket_service_fd</b>
46 (<i>struct libwebsocket_context *</i> <b>context</b>,
47 <i>struct pollfd *</i> <b>pollfd</b>)
48 <h3>Arguments</h3>
49 <dl>
50 <dt><b>context</b>
51 <dd>Websocket context
52 <dt><b>pollfd</b>
53 <dd>The pollfd entry describing the socket fd and which events
54 happened.
55 </dl>
56 <h3>Description</h3>
57 <blockquote>
58 This function closes any active connections and then frees the
59 context.  After calling this, any further use of the context is
60 undefined.
61 </blockquote>
62 <hr>
63 <h2>libwebsocket_context_destroy - Destroy the websocket context</h2>
64 <i>void</i>
65 <b>libwebsocket_context_destroy</b>
66 (<i>struct libwebsocket_context *</i> <b>context</b>)
67 <h3>Arguments</h3>
68 <dl>
69 <dt><b>context</b>
70 <dd>Websocket context
71 </dl>
72 <h3>Description</h3>
73 <blockquote>
74 This function closes any active connections and then frees the
75 context.  After calling this, any further use of the context is
76 undefined.
77 </blockquote>
78 <hr>
79 <h2>libwebsocket_service - Service any pending websocket activity</h2>
80 <i>int</i>
81 <b>libwebsocket_service</b>
82 (<i>struct libwebsocket_context *</i> <b>context</b>,
83 <i>int</i> <b>timeout_ms</b>)
84 <h3>Arguments</h3>
85 <dl>
86 <dt><b>context</b>
87 <dd>Websocket context
88 <dt><b>timeout_ms</b>
89 <dd>Timeout for poll; 0 means return immediately if nothing needed
90 service otherwise block and service immediately, returning
91 after the timeout if nothing needed service.
92 </dl>
93 <h3>Description</h3>
94 <blockquote>
95 This function deals with any pending websocket traffic, for three
96 kinds of event.  It handles these events on both server and client
97 types of connection the same.
98 <p>
99 1) Accept new connections to our context's server
100 <p>
101 2) Perform pending broadcast writes initiated from other forked
102 processes (effectively serializing asynchronous broadcasts)
103 <p>
104 3) Call the receive callback for incoming frame data received by
105 server or client connections.
106 <p>
107 You need to call this service function periodically to all the above
108 functions to happen; if your application is single-threaded you can
109 just call it in your main event loop.
110 <p>
111 Alternatively you can fork a new process that asynchronously handles
112 calling this service in a loop.  In that case you are happy if this
113 call blocks your thread until it needs to take care of something and
114 would call it with a large nonzero timeout.  Your loop then takes no
115 CPU while there is nothing happening.
116 <p>
117 If you are calling it in a single-threaded app, you don't want it to
118 wait around blocking other things in your loop from happening, so you
119 would call it with a timeout_ms of 0, so it returns immediately if
120 nothing is pending, or as soon as it services whatever was pending.
121 </blockquote>
122 <hr>
123 <h2>libwebsocket_callback_on_writable - Request a callback when this socket becomes able to be written to without blocking</h2>
124 <i>int</i>
125 <b>libwebsocket_callback_on_writable</b>
126 (<i>struct libwebsocket_context *</i> <b>context</b>,
127 <i>struct libwebsocket *</i> <b>wsi</b>)
128 <h3>Arguments</h3>
129 <dl>
130 <dt><b>context</b>
131 <dd>libwebsockets context
132 <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>
146 <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>
164 You will not need this unless you are doing something special
165 </blockquote>
166 <hr>
167 <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>
179 You will not need this unless you are doing something special
180 </blockquote>
181 <hr>
182 <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>
197 If the output side of a server process becomes choked, this allows flow
198 control for the input side.
199 </blockquote>
200 <hr>
201 <h2>libwebsocket_canonical_hostname - returns this host's hostname</h2>
202 <i>const char *</i>
203 <b>libwebsocket_canonical_hostname</b>
204 (<i>struct libwebsocket_context *</i> <b>context</b>)
205 <h3>Arguments</h3>
206 <dl>
207 <dt><b>context</b>
208 <dd>Websocket context
209 </dl>
210 <h3>Description</h3>
211 <blockquote>
212 <p>
213 This is typically used by client code to fill in the host parameter
214 when making a client connection.  You can only call it after the context
215 has been created.
216 </blockquote>
217 <hr>
218 <h2>libwebsocket_create_context - Create the websocket handler</h2>
219 <i>struct libwebsocket_context *</i>
220 <b>libwebsocket_create_context</b>
221 (<i>int</i> <b>port</b>,
222 <i>const char *</i> <b>interf</b>,
223 <i>struct libwebsocket_protocols *</i> <b>protocols</b>,
224 <i>struct libwebsocket_extension *</i> <b>extensions</b>,
225 <i>const char *</i> <b>ssl_cert_filepath</b>,
226 <i>const char *</i> <b>ssl_private_key_filepath</b>,
227 <i>const char *</i> <b>ssl_ca_filepath</b>,
228 <i>int</i> <b>gid</b>,
229 <i>int</i> <b>uid</b>,
230 <i>unsigned int</i> <b>options</b>,
231 <i>void *</i> <b>user</b>)
232 <h3>Arguments</h3>
233 <dl>
234 <dt><b>port</b>
235 <dd>Port to listen on... you can use 0 to suppress listening on
236 any port, that's what you want if you are not running a
237 websocket server at all but just using it as a client
238 <dt><b>interf</b>
239 <dd>NULL to bind the listen socket to all interfaces, or the
240 interface name, eg, "eth2"
241 <dt><b>protocols</b>
242 <dd>Array of structures listing supported protocols and a protocol-
243 specific callback for each one.  The list is ended with an
244 entry that has a NULL callback pointer.
245 It's not const because we write the owning_server member
246 <dt><b>extensions</b>
247 <dd>NULL or array of libwebsocket_extension structs listing the
248 extensions this context supports
249 <dt><b>ssl_cert_filepath</b>
250 <dd>If libwebsockets was compiled to use ssl, and you want
251 to listen using SSL, set to the filepath to fetch the
252 server cert from, otherwise NULL for unencrypted
253 <dt><b>ssl_private_key_filepath</b>
254 <dd>filepath to private key if wanting SSL mode,
255 else ignored
256 <dt><b>ssl_ca_filepath</b>
257 <dd>CA certificate filepath or NULL
258 <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.
262 <dt><b>options</b>
263 <dd>0, or LWS_SERVER_OPTION_DEFEAT_CLIENT_MASK
264 <dt><b>user</b>
265 <dd>optional user pointer that can be recovered via the context
266 pointer using libwebsocket_context_user 
267 </dl>
268 <h3>Description</h3>
269 <blockquote>
270 This function creates the listening socket and takes care
271 of all initialization in one step.
272 <p>
273 After initialization, it returns a struct libwebsocket_context * that
274 represents this server.  After calling, user code needs to take care
275 of calling <b>libwebsocket_service</b> with the context pointer to get the
276 server's sockets serviced.  This can be done in the same process context
277 or a forked process, or another thread,
278 <p>
279 The protocol callback functions are called for a handful of events
280 including http requests coming in, websocket connections becoming
281 established, and data arriving; it's also called periodically to allow
282 async transmission.
283 <p>
284 HTTP requests are sent always to the FIRST protocol in <tt><b>protocol</b></tt>, since
285 at that time websocket protocol has not been negotiated.  Other
286 protocols after the first one never see any HTTP callack activity.
287 <p>
288 The server created is a simple http server by default; part of the
289 websocket standard is upgrading this http connection to a websocket one.
290 <p>
291 This allows the same server to provide files like scripts and favicon /
292 images or whatever over http and dynamic data over websockets all in
293 one place; they're all handled in the user callback.
294 </blockquote>
295 <hr>
296 <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>
299 (<i>struct libwebsocket_context *</i> <b>context</b>)
300 <h3>Arguments</h3>
301 <dl>
302 <dt><b>context</b>
303 <dd>server context returned by creation function
304 </dl>
305 <hr>
306 <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>
318 This is useful to get the protocol to broadcast back to from inside
319 the callback.
320 </blockquote>
321 <hr>
322 <h2>libwebsockets_broadcast - Sends a buffer to the callback for all active connections of the given protocol.</h2>
323 <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
334 allocated with LWS_SEND_BUFFER_PRE_PADDING valid bytes before
335 the pointer and LWS_SEND_BUFFER_POST_PADDING afterwards in the
336 case 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>
342 This function allows bulk sending of a packet to every connection using
343 the given protocol.  It does not send the data directly; instead it calls
344 the callback with a reason type of LWS_CALLBACK_BROADCAST.  If the callback
345 wants to actually send the data for that connection, the callback itself
346 should call <b>libwebsocket_write</b>.
347 <p>
348 <b>libwebsockets_broadcast</b> can be called from another fork context without
349 having to take any care about data visibility between the processes, it'll
350 "just work".
351 </blockquote>
352 <hr>
353 <h2>lws_set_log_level - Set the logging bitfield</h2>
354 <i>void</i>
355 <b>lws_set_log_level</b>
356 (<i>int</i> <b>level</b>,
357 <i>void (*</i><b>log_emit_function</b>) <i>(const char *line)</i>)
358 <h3>Arguments</h3>
359 <dl>
360 <dt><b>level</b>
361 <dd>OR together the LLL_ debug contexts you want output from
362 <dt><b>log_emit_function</b>
363 <dd>NULL to leave it as it is, or a user-supplied
364 function to perform log string emission instead of
365 the default stderr one.
366 </dl>
367 <h3>Description</h3>
368 <blockquote>
369 log level defaults to "err" and "warn" contexts enabled only and
370 emission on stderr.
371 </blockquote>
372 <hr>
373 <h2>libwebsocket_write - Apply protocol then write data to client</h2>
374 <i>int</i>
375 <b>libwebsocket_write</b>
376 (<i>struct libwebsocket *</i> <b>wsi</b>,
377 <i>unsigned char *</i> <b>buf</b>,
378 <i>size_t</i> <b>len</b>,
379 <i>enum libwebsocket_write_protocol</i> <b>protocol</b>)
380 <h3>Arguments</h3>
381 <dl>
382 <dt><b>wsi</b>
383 <dd>Websocket instance (available from user callback)
384 <dt><b>buf</b>
385 <dd>The data to send.  For data being sent on a websocket
386 connection (ie, not default http), this buffer MUST have
387 LWS_SEND_BUFFER_PRE_PADDING bytes valid BEFORE the pointer
388 and an additional LWS_SEND_BUFFER_POST_PADDING bytes valid
389 in the buffer after (buf + len).  This is so the protocol
390 header and trailer data can be added in-situ.
391 <dt><b>len</b>
392 <dd>Count of the data bytes in the payload starting from buf
393 <dt><b>protocol</b>
394 <dd>Use LWS_WRITE_HTTP to reply to an http connection, and one
395 of LWS_WRITE_BINARY or LWS_WRITE_TEXT to send appropriate
396 data on a websockets connection.  Remember to allow the extra
397 bytes before and after buf if LWS_WRITE_BINARY or LWS_WRITE_TEXT
398 are used.
399 </dl>
400 <h3>Description</h3>
401 <blockquote>
402 This function provides the way to issue data back to the client
403 for both http and websocket protocols.
404 <p>
405 In the case of sending using websocket protocol, be sure to allocate
406 valid storage before and after buf as explained above.  This scheme
407 allows maximum efficiency of sending data and protocol in a single
408 packet while not burdening the user code with any protocol knowledge.
409 </blockquote>
410 <hr>
411 <h2>libwebsockets_serve_http_file - Send a file back to the client using http</h2>
412 <i>int</i>
413 <b>libwebsockets_serve_http_file</b>
414 (<i>struct libwebsocket *</i> <b>wsi</b>,
415 <i>const char *</i> <b>file</b>,
416 <i>const char *</i> <b>content_type</b>)
417 <h3>Arguments</h3>
418 <dl>
419 <dt><b>wsi</b>
420 <dd>Websocket instance (available from user callback)
421 <dt><b>file</b>
422 <dd>The file to issue over http
423 <dt><b>content_type</b>
424 <dd>The http content type, eg, text/html
425 </dl>
426 <h3>Description</h3>
427 <blockquote>
428 This function is intended to be called from the callback in response
429 to http requests from the client.  It allows the callback to issue
430 local files down the http link in a single step.
431 </blockquote>
432 <hr>
433 <h2>libwebsockets_remaining_packet_payload - Bytes to come before "overall" rx packet is complete</h2>
434 <i>size_t</i>
435 <b>libwebsockets_remaining_packet_payload</b>
436 (<i>struct libwebsocket *</i> <b>wsi</b>)
437 <h3>Arguments</h3>
438 <dl>
439 <dt><b>wsi</b>
440 <dd>Websocket instance (available from user callback)
441 </dl>
442 <h3>Description</h3>
443 <blockquote>
444 This function is intended to be called from the callback if the
445 user code is interested in "complete packets" from the client.
446 libwebsockets just passes through payload as it comes and issues a buffer
447 additionally when it hits a built-in limit.  The LWS_CALLBACK_RECEIVE
448 callback handler can use this API to find out if the buffer it has just
449 been given is the last piece of a "complete packet" from the client --
450 when that is the case <b>libwebsockets_remaining_packet_payload</b> will return
451 0.
452 <p>
453 Many protocols won't care becuse their packets are always small.
454 </blockquote>
455 <hr>
456 <h2>libwebsocket_client_connect - Connect to another websocket server</h2>
457 <i>struct libwebsocket *</i>
458 <b>libwebsocket_client_connect</b>
459 (<i>struct libwebsocket_context *</i> <b>context</b>,
460 <i>const char *</i> <b>address</b>,
461 <i>int</i> <b>port</b>,
462 <i>int</i> <b>ssl_connection</b>,
463 <i>const char *</i> <b>path</b>,
464 <i>const char *</i> <b>host</b>,
465 <i>const char *</i> <b>origin</b>,
466 <i>const char *</i> <b>protocol</b>,
467 <i>int</i> <b>ietf_version_or_minus_one</b>)
468 <h3>Arguments</h3>
469 <dl>
470 <dt><b>context</b>
471 <dd>Websocket context
472 <dt><b>address</b>
473 <dd>Remote server address, eg, "myserver.com"
474 <dt><b>port</b>
475 <dd>Port to connect to on the remote server, eg, 80
476 <dt><b>ssl_connection</b>
477 <dd>0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self
478 signed certs
479 <dt><b>path</b>
480 <dd>Websocket path on server
481 <dt><b>host</b>
482 <dd>Hostname on server
483 <dt><b>origin</b>
484 <dd>Socket origin name
485 <dt><b>protocol</b>
486 <dd>Comma-separated list of protocols being asked for from
487 the server, or just one.  The server will pick the one it
488 likes best.
489 <dt><b>ietf_version_or_minus_one</b>
490 <dd>-1 to ask to connect using the default, latest
491 protocol supported, or the specific protocol ordinal
492 </dl>
493 <h3>Description</h3>
494 <blockquote>
495 This function creates a connection to a remote server
496 </blockquote>
497 <hr>
498 <h2>libwebsocket_client_connect_extended - Connect to another websocket server</h2>
499 <i>struct libwebsocket *</i>
500 <b>libwebsocket_client_connect_extended</b>
501 (<i>struct libwebsocket_context *</i> <b>context</b>,
502 <i>const char *</i> <b>address</b>,
503 <i>int</i> <b>port</b>,
504 <i>int</i> <b>ssl_connection</b>,
505 <i>const char *</i> <b>path</b>,
506 <i>const char *</i> <b>host</b>,
507 <i>const char *</i> <b>origin</b>,
508 <i>const char *</i> <b>protocol</b>,
509 <i>int</i> <b>ietf_version_or_minus_one</b>,
510 <i>void *</i> <b>userdata</b>)
511 <h3>Arguments</h3>
512 <dl>
513 <dt><b>context</b>
514 <dd>Websocket context
515 <dt><b>address</b>
516 <dd>Remote server address, eg, "myserver.com"
517 <dt><b>port</b>
518 <dd>Port to connect to on the remote server, eg, 80
519 <dt><b>ssl_connection</b>
520 <dd>0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self
521 signed certs
522 <dt><b>path</b>
523 <dd>Websocket path on server
524 <dt><b>host</b>
525 <dd>Hostname on server
526 <dt><b>origin</b>
527 <dd>Socket origin name
528 <dt><b>protocol</b>
529 <dd>Comma-separated list of protocols being asked for from
530 the server, or just one.  The server will pick the one it
531 likes best.
532 <dt><b>ietf_version_or_minus_one</b>
533 <dd>-1 to ask to connect using the default, latest
534 protocol supported, or the specific protocol ordinal
535 <dt><b>userdata</b>
536 <dd>Pre-allocated user data
537 </dl>
538 <h3>Description</h3>
539 <blockquote>
540 This function creates a connection to a remote server
541 </blockquote>
542 <hr>
543 <h2>callback - User server actions</h2>
544 <i>LWS_EXTERN int</i>
545 <b>callback</b>
546 (<i>struct libwebsocket_context *</i> <b>context</b>,
547 <i>struct libwebsocket *</i> <b>wsi</b>,
548 <i>enum libwebsocket_callback_reasons</i> <b>reason</b>,
549 <i>void *</i> <b>user</b>,
550 <i>void *</i> <b>in</b>,
551 <i>size_t</i> <b>len</b>)
552 <h3>Arguments</h3>
553 <dl>
554 <dt><b>context</b>
555 <dd>Websockets context
556 <dt><b>wsi</b>
557 <dd>Opaque websocket instance pointer
558 <dt><b>reason</b>
559 <dd>The reason for the call
560 <dt><b>user</b>
561 <dd>Pointer to per-session user data allocated by library
562 <dt><b>in</b>
563 <dd>Pointer used for some callback reasons
564 <dt><b>len</b>
565 <dd>Length set for some callback reasons
566 </dl>
567 <h3>Description</h3>
568 <blockquote>
569 This callback is the way the user controls what is served.  All the
570 protocol detail is hidden and handled by the library.
571 <p>
572 For each connection / session there is user data allocated that is
573 pointed to by "user".  You set the size of this user data area when
574 the library is initialized with libwebsocket_create_server.
575 <p>
576 You get an opportunity to initialize user data when called back with
577 LWS_CALLBACK_ESTABLISHED reason.
578 </blockquote>
579 <h3>LWS_CALLBACK_ESTABLISHED</h3>
580 <blockquote>
581 after the server completes a handshake with
582 an incoming client
583 </blockquote>
584 <h3>LWS_CALLBACK_CLIENT_CONNECTION_ERROR</h3>
585 <blockquote>
586 the request client connection has
587 been unable to complete a handshake with the remote server
588 </blockquote>
589 <h3>LWS_CALLBACK_CLIENT_ESTABLISHED</h3>
590 <blockquote>
591 after your client connection completed
592 a handshake with the remote server
593 </blockquote>
594 <h3>LWS_CALLBACK_CLOSED</h3>
595 <blockquote>
596 when the websocket session ends
597 </blockquote>
598 <h3>LWS_CALLBACK_BROADCAST</h3>
599 <blockquote>
600 signal to send to client (you would use
601 <b>libwebsocket_write</b> taking care about the
602 special buffer requirements
603 </blockquote>
604 <h3>LWS_CALLBACK_RECEIVE</h3>
605 <blockquote>
606 data has appeared for this server endpoint from a
607 remote client, it can be found at *in and is
608 len bytes long
609 </blockquote>
610 <h3>LWS_CALLBACK_CLIENT_RECEIVE_PONG</h3>
611 <blockquote>
612 if you elected to see PONG packets,
613 they appear with this callback reason.  PONG
614 packets only exist in 04+ protocol
615 </blockquote>
616 <h3>LWS_CALLBACK_CLIENT_RECEIVE</h3>
617 <blockquote>
618 data has appeared from the server for the
619 client connection, it can be found at *in and
620 is len bytes long
621 </blockquote>
622 <h3>LWS_CALLBACK_HTTP</h3>
623 <blockquote>
624 an http request has come from a client that is not
625 asking to upgrade the connection to a websocket
626 one.  This is a chance to serve http content,
627 for example, to send a script to the client
628 which will then open the websockets connection.
629 <tt><b>in</b></tt> points to the URI path requested and
630 <b>libwebsockets_serve_http_file</b> makes it very
631 simple to send back a file to the client.
632 Normally after sending the file you are done
633 with the http connection, since the rest of the
634 activity will come by websockets from the script
635 that was delivered by http, so you will want to
636 return 1; to close and free up the connection.
637 That's important because it uses a slot in the
638 total number of client connections allowed set
639 by MAX_CLIENTS.
640 </blockquote>
641 <h3>LWS_CALLBACK_SERVER_WRITEABLE</h3>
642 <blockquote>
643 If you call
644 <b>libwebsocket_callback_on_writable</b> on a connection, you will
645 get one of these callbacks coming when the connection socket
646 is able to accept another write packet without blocking.
647 If it already was able to take another packet without blocking,
648 you'll get this callback at the next call to the service loop
649 function.  Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE
650 and servers get LWS_CALLBACK_SERVER_WRITEABLE.
651 </blockquote>
652 <h3>LWS_CALLBACK_FILTER_NETWORK_CONNECTION</h3>
653 <blockquote>
654 called when a client connects to
655 the server at network level; the connection is accepted but then
656 passed to this callback to decide whether to hang up immediately
657 or not, based on the client IP.  <tt><b>user</b></tt> contains the connection
658 socket's descriptor.  Return non-zero to terminate
659 the connection before sending or receiving anything.
660 Because this happens immediately after the network connection
661 from the client, there's no websocket protocol selected yet so
662 this callback is issued only to protocol 0.
663 </blockquote>
664 <h3>LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION</h3>
665 <blockquote>
666 called when the handshake has
667 been received and parsed from the client, but the response is
668 not sent yet.  Return non-zero to disallow the connection.
669 <tt><b>user</b></tt> is a pointer to an array of struct lws_tokens, you can
670 use the header enums lws_token_indexes from libwebsockets.h
671 to check for and read the supported header presence and
672 content before deciding to allow the handshake to proceed or
673 to kill the connection.
674 </blockquote>
675 <h3>LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS</h3>
676 <blockquote>
677 if configured for
678 including OpenSSL support, this callback allows your user code
679 to perform extra <b>SSL_CTX_load_verify_locations</b> or similar
680 calls to direct OpenSSL where to find certificates the client
681 can use to confirm the remote server identity.  <tt><b>user</b></tt> is the
682 OpenSSL SSL_CTX*
683 </blockquote>
684 <h3>LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS</h3>
685 <blockquote>
686 if configured for
687 including OpenSSL support, this callback allows your user code
688 to load extra certifcates into the server which allow it to
689 verify the validity of certificates returned by clients.  <tt><b>user</b></tt>
690 is the server's OpenSSL SSL_CTX*
691 </blockquote>
692 <h3>LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION</h3>
693 <blockquote>
694 if the
695 libwebsockets context was created with the option
696 LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this
697 callback is generated during OpenSSL verification of the cert
698 sent from the client.  It is sent to protocol[0] callback as
699 no protocol has been negotiated on the connection yet.
700 Notice that the libwebsockets context and wsi are both NULL
701 during this callback.  See
702 </blockquote>
703 <h3>http</h3>
704 <blockquote>
705 //www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
706 to understand more detail about the OpenSSL callback that
707 generates this libwebsockets callback and the meanings of the
708 arguments passed.  In this callback, <tt><b>user</b></tt> is the x509_ctx,
709 <tt><b>in</b></tt> is the ssl pointer and <tt><b>len</b></tt> is preverify_ok
710 Notice that this callback maintains libwebsocket return
711 conventions, return 0 to mean the cert is OK or 1 to fail it.
712 This also means that if you don't handle this callback then
713 the default callback action of returning 0 allows the client
714 certificates.
715 </blockquote>
716 <h3>LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER</h3>
717 <blockquote>
718 this callback happens
719 when a client handshake is being compiled.  <tt><b>user</b></tt> is NULL,
720 <tt><b>in</b></tt> is a char **, it's pointing to a char * which holds the
721 next location in the header buffer where you can add
722 headers, and <tt><b>len</b></tt> is the remaining space in the header buffer,
723 which is typically some hundreds of bytes.  So, to add a canned
724 cookie, your handler code might look similar to:
725 <p>
726 char **p = (char **)in;
727 <p>
728 if (len &lt; 100)
729 return 1;
730 <p>
731 *p += sprintf(*p, "Cookie: a=b\x0d\x0a");
732 <p>
733 return 0;
734 <p>
735 Notice if you add anything, you just have to take care about
736 the CRLF on the line you added.  Obviously this callback is
737 optional, if you don't handle it everything is fine.
738 <p>
739 Notice the callback is coming to protocols[0] all the time,
740 because there is no specific protocol handshook yet.
741 </blockquote>
742 <h3>LWS_CALLBACK_CONFIRM_EXTENSION_OKAY</h3>
743 <blockquote>
744 When the server handshake code
745 sees that it does support a requested extension, before
746 accepting the extension by additing to the list sent back to
747 the client it gives this callback just to check that it's okay
748 to use that extension.  It calls back to the requested protocol
749 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
750 valid.  Note though at this time the ESTABLISHED callback hasn't
751 happened yet so if you initialize <tt><b>user</b></tt> content there, <tt><b>user</b></tt>
752 content during this callback might not be useful for anything.
753 Notice this callback comes to protocols[0].
754 </blockquote>
755 <h3>LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED</h3>
756 <blockquote>
757 When a client
758 connection is being prepared to start a handshake to a server,
759 each supported extension is checked with protocols[0] callback
760 with this reason, giving the user code a chance to suppress the
761 claim to support that extension by returning non-zero.  If
762 unhandled, by default 0 will be returned and the extension
763 support included in the header to the server.  Notice this
764 callback comes to protocols[0].
765 <p>
766 The next four reasons are optional and only need taking care of if you
767 will be integrating libwebsockets sockets into an external polling
768 array.
769 </blockquote>
770 <h3>LWS_CALLBACK_ADD_POLL_FD</h3>
771 <blockquote>
772 libwebsocket deals with its <b>poll</b> loop
773 internally, but in the case you are integrating with another
774 server you will need to have libwebsocket sockets share a
775 polling array with the other server.  This and the other
776 POLL_FD related callbacks let you put your specialized
777 poll array interface code in the callback for protocol 0, the
778 first protocol you support, usually the HTTP protocol in the
779 serving case.  This callback happens when a socket needs to be
780 </blockquote>
781 <h3>added to the polling loop</h3>
782 <blockquote>
783 <tt><b>user</b></tt> contains the fd, and
784 <tt><b>len</b></tt> is the events bitmap (like, POLLIN).  If you are using the
785 internal polling loop (the "service" callback), you can just
786 ignore these callbacks.
787 </blockquote>
788 <h3>LWS_CALLBACK_DEL_POLL_FD</h3>
789 <blockquote>
790 This callback happens when a socket descriptor
791 needs to be removed from an external polling array.  <tt><b>user</b></tt> is
792 the socket desricptor.  If you are using the internal polling
793 loop, you can just ignore it.
794 </blockquote>
795 <h3>LWS_CALLBACK_SET_MODE_POLL_FD</h3>
796 <blockquote>
797 This callback happens when libwebsockets
798 wants to modify the events for the socket descriptor in <tt><b>user</b></tt>.
799 The handler should OR <tt><b>len</b></tt> on to the events member of the pollfd
800 struct for this socket descriptor.  If you are using the
801 internal polling loop, you can just ignore it.
802 </blockquote>
803 <h3>LWS_CALLBACK_CLEAR_MODE_POLL_FD</h3>
804 <blockquote>
805 This callback occurs when libwebsockets
806 wants to modify the events for the socket descriptor in <tt><b>user</b></tt>.
807 The handler should AND ~<tt><b>len</b></tt> on to the events member of the
808 pollfd struct for this socket descriptor.  If you are using the
809 internal polling loop, you can just ignore it.
810 </blockquote>
811 <hr>
812 <h2>extension_callback - Hooks to allow extensions to operate</h2>
813 <i>LWS_EXTERN int</i>
814 <b>extension_callback</b>
815 (<i>struct libwebsocket_context *</i> <b>context</b>,
816 <i>struct libwebsocket_extension *</i> <b>ext</b>,
817 <i>struct libwebsocket *</i> <b>wsi</b>,
818 <i>enum libwebsocket_extension_callback_reasons</i> <b>reason</b>,
819 <i>void *</i> <b>user</b>,
820 <i>void *</i> <b>in</b>,
821 <i>size_t</i> <b>len</b>)
822 <h3>Arguments</h3>
823 <dl>
824 <dt><b>context</b>
825 <dd>Websockets context
826 <dt><b>ext</b>
827 <dd>This extension
828 <dt><b>wsi</b>
829 <dd>Opaque websocket instance pointer
830 <dt><b>reason</b>
831 <dd>The reason for the call
832 <dt><b>user</b>
833 <dd>Pointer to per-session user data allocated by library
834 <dt><b>in</b>
835 <dd>Pointer used for some callback reasons
836 <dt><b>len</b>
837 <dd>Length set for some callback reasons
838 </dl>
839 <h3>Description</h3>
840 <blockquote>
841 Each extension that is active on a particular connection receives
842 callbacks during the connection lifetime to allow the extension to
843 operate on websocket data and manage itself.
844 <p>
845 Libwebsockets takes care of allocating and freeing "user" memory for
846 each active extension on each connection.  That is what is pointed to
847 by the <tt><b>user</b></tt> parameter.
848 </blockquote>
849 <h3>LWS_EXT_CALLBACK_CONSTRUCT</h3>
850 <blockquote>
851 called when the server has decided to
852 select this extension from the list provided by the client,
853 just before the server will send back the handshake accepting
854 the connection with this extension active.  This gives the
855 extension a chance to initialize its connection context found
856 in <tt><b>user</b></tt>.
857 </blockquote>
858 <h3>LWS_EXT_CALLBACK_CLIENT_CONSTRUCT</h3>
859 <blockquote>
860 same as LWS_EXT_CALLBACK_CONSTRUCT
861 but called when client is instantiating this extension.  Some
862 extensions will work the same on client and server side and then
863 you can just merge handlers for both CONSTRUCTS.
864 </blockquote>
865 <h3>LWS_EXT_CALLBACK_DESTROY</h3>
866 <blockquote>
867 called when the connection the extension was
868 being used on is about to be closed and deallocated.  It's the
869 last chance for the extension to deallocate anything it has
870 allocated in the user data (pointed to by <tt><b>user</b></tt>) before the
871 user data is deleted.  This same callback is used whether you
872 are in client or server instantiation context.
873 </blockquote>
874 <h3>LWS_EXT_CALLBACK_PACKET_RX_PREPARSE</h3>
875 <blockquote>
876 when this extension was active on
877 a connection, and a packet of data arrived at the connection,
878 it is passed to this callback to give the extension a chance to
879 change the data, eg, decompress it.  <tt><b>user</b></tt> is pointing to the
880 extension's private connection context data, <tt><b>in</b></tt> is pointing
881 to an lws_tokens struct, it consists of a char * pointer called
882 token, and an int called token_len.  At entry, these are
883 set to point to the received buffer and set to the content
884 length.  If the extension will grow the content, it should use
885 a new buffer allocated in its private user context data and
886 set the pointed-to lws_tokens members to point to its buffer.
887 </blockquote>
888 <h3>LWS_EXT_CALLBACK_PACKET_TX_PRESEND</h3>
889 <blockquote>
890 this works the same way as
891 LWS_EXT_CALLBACK_PACKET_RX_PREPARSE above, except it gives the
892 extension a chance to change websocket data just before it will
893 be sent out.  Using the same lws_token pointer scheme in <tt><b>in</b></tt>,
894 the extension can change the buffer and the length to be
895 transmitted how it likes.  Again if it wants to grow the
896 buffer safely, it should copy the data into its own buffer and
897 set the lws_tokens token pointer to it.
898 </blockquote>
899 <hr>
900 <h2>struct libwebsocket_protocols - List of protocols and handlers server supports.</h2>
901 <b>struct libwebsocket_protocols</b> {<br>
902 &nbsp; &nbsp; <i>const char *</i> <b>name</b>;<br>
903 &nbsp; &nbsp; <i>callback_function *</i> <b>callback</b>;<br>
904 &nbsp; &nbsp; <i>size_t</i> <b>per_session_data_size</b>;<br>
905 &nbsp; &nbsp; <i>struct libwebsocket_context *</i> <b>owning_server</b>;<br>
906 &nbsp; &nbsp; <i>int</i> <b>broadcast_socket_port</b>;<br>
907 &nbsp; &nbsp; <i>int</i> <b>broadcast_socket_user_fd</b>;<br>
908 &nbsp; &nbsp; <i>int</i> <b>protocol_index</b>;<br>
909 };<br>
910 <h3>Members</h3>
911 <dl>
912 <dt><b>name</b>
913 <dd>Protocol name that must match the one given in the client
914 Javascript new WebSocket(url, 'protocol') name
915 <dt><b>callback</b>
916 <dd>The service callback used for this protocol.  It allows the
917 service action for an entire protocol to be encapsulated in
918 the protocol-specific callback
919 <dt><b>per_session_data_size</b>
920 <dd>Each new connection using this protocol gets
921 this much memory allocated on connection establishment and
922 freed on connection takedown.  A pointer to this per-connection
923 allocation is passed into the callback in the 'user' parameter
924 <dt><b>owning_server</b>
925 <dd>the server init call fills in this opaque pointer when
926 registering this protocol with the server.
927 <dt><b>broadcast_socket_port</b>
928 <dd>the server init call fills this in with the
929 localhost port number used to forward broadcasts for this
930 protocol
931 <dt><b>broadcast_socket_user_fd</b>
932 <dd>the server init call fills this in ... the <b>main</b>
933 process context can write to this socket to perform broadcasts
934 (use the <b>libwebsockets_broadcast</b> api to do this instead,
935 it works from any process context)
936 <dt><b>protocol_index</b>
937 <dd>which protocol we are starting from zero
938 </dl>
939 <h3>Description</h3>
940 <blockquote>
941 This structure represents one protocol supported by the server.  An
942 array of these structures is passed to <b>libwebsocket_create_server</b>
943 allows as many protocols as you like to be handled by one server.
944 </blockquote>
945 <hr>
946 <h2>struct libwebsocket_extension - An extension we know how to cope with</h2>
947 <b>struct libwebsocket_extension</b> {<br>
948 &nbsp; &nbsp; <i>const char *</i> <b>name</b>;<br>
949 &nbsp; &nbsp; <i>extension_callback_function *</i> <b>callback</b>;<br>
950 &nbsp; &nbsp; <i>size_t</i> <b>per_session_data_size</b>;<br>
951 &nbsp; &nbsp; <i>void *</i> <b>per_context_private_data</b>;<br>
952 };<br>
953 <h3>Members</h3>
954 <dl>
955 <dt><b>name</b>
956 <dd>Formal extension name, eg, "deflate-stream"
957 <dt><b>callback</b>
958 <dd>Service callback
959 <dt><b>per_session_data_size</b>
960 <dd>Libwebsockets will auto-malloc this much
961 memory for the use of the extension, a pointer
962 to it comes in the <tt><b>user</b></tt> callback parameter
963 <dt><b>per_context_private_data</b>
964 <dd>Optional storage for this externsion that
965 is per-context, so it can track stuff across
966 all sessions, etc, if it wants
967 </dl>
968 <hr>