Andy Green | 62a1293 | 2010-11-03 11:19:23 +0000 | [diff] [blame] | 1 | <h2>libwebsocket_create_server - Create the listening websockets server</h2> |
| 2 | <i>int</i> |
| 3 | <b>libwebsocket_create_server</b> |
| 4 | (<i>int</i> <b>port</b>, |
Andy Green | ce510c6 | 2010-11-11 12:48:13 +0000 | [diff] [blame] | 5 | <i>int (*</i><b>callback</b>) <i>(struct libwebsocket *, enum libwebsocket_callback_reasons, void *, void *, size_t)</i>, |
Andy Green | 3faa9c7 | 2010-11-08 17:03:03 +0000 | [diff] [blame] | 6 | <i>size_t</i> <b>user_area_size</b>, |
| 7 | <i>const char *</i> <b>ssl_cert_filepath</b>, |
| 8 | <i>const char *</i> <b>ssl_private_key_filepath</b>, |
| 9 | <i>int</i> <b>gid</b>, |
| 10 | <i>int</i> <b>uid</b>) |
Andy Green | 62a1293 | 2010-11-03 11:19:23 +0000 | [diff] [blame] | 11 | <h3>Arguments</h3> |
| 12 | <dl> |
| 13 | <dt><b>port</b> |
| 14 | <dd>Port to listen on |
| 15 | <dt><b>callback</b> |
| 16 | <dd>The callback in user code to perform actual serving |
Andy Green | 62a1293 | 2010-11-03 11:19:23 +0000 | [diff] [blame] | 17 | <dt><b>user_area_size</b> |
| 18 | <dd>How much memory to allocate per connection session |
| 19 | which will be used by the user application to store |
| 20 | per-session data. A pointer to this space is given |
| 21 | when the user callback is called. |
Andy Green | 3faa9c7 | 2010-11-08 17:03:03 +0000 | [diff] [blame] | 22 | <dt><b>ssl_cert_filepath</b> |
| 23 | <dd>If libwebsockets was compiled to use ssl, and you want |
| 24 | to listen using SSL, set to the filepath to fetch the |
| 25 | server cert from, otherwise NULL for unencrypted |
| 26 | <dt><b>ssl_private_key_filepath</b> |
| 27 | <dd>filepath to private key if wanting SSL mode, |
| 28 | else ignored |
| 29 | <dt><b>gid</b> |
| 30 | <dd>group id to change to after setting listen socket, or -1. |
| 31 | <dt><b>uid</b> |
| 32 | <dd>user id to change to after setting listen socket, or -1. |
Andy Green | 62a1293 | 2010-11-03 11:19:23 +0000 | [diff] [blame] | 33 | </dl> |
| 34 | <h3>Description</h3> |
| 35 | <blockquote> |
| 36 | This function forks to create the listening socket and takes care |
| 37 | of all initialization in one step. |
| 38 | <p> |
| 39 | The callback function is called for a handful of events including |
| 40 | http requests coming in, websocket connections becoming |
| 41 | established, and data arriving; it's also called periodically to allow |
| 42 | async transmission. |
| 43 | <p> |
| 44 | The server created is a simple http server by default; part of the |
| 45 | websocket standard is upgrading this http connection to a websocket one. |
| 46 | <p> |
| 47 | This allows the same server to provide files like scripts and favicon / |
| 48 | images or whatever over http and dynamic data over websockets all in |
| 49 | one place; they're all handled in the user callback. |
| 50 | </blockquote> |
| 51 | <hr> |
Andy Green | 62a1293 | 2010-11-03 11:19:23 +0000 | [diff] [blame] | 52 | <h2>libwebsocket_write - Apply protocol then write data to client</h2> |
| 53 | <i>int</i> |
| 54 | <b>libwebsocket_write</b> |
| 55 | (<i>struct libwebsocket *</i> <b>wsi</b>, |
| 56 | <i>unsigned char *</i> <b>buf</b>, |
| 57 | <i>size_t</i> <b>len</b>, |
| 58 | <i>enum libwebsocket_write_protocol</i> <b>protocol</b>) |
| 59 | <h3>Arguments</h3> |
| 60 | <dl> |
| 61 | <dt><b>wsi</b> |
| 62 | <dd>Websocket instance (available from user callback) |
| 63 | <dt><b>buf</b> |
| 64 | <dd>The data to send. For data being sent on a websocket |
| 65 | connection (ie, not default http), this buffer MUST have |
| 66 | LWS_SEND_BUFFER_PRE_PADDING bytes valid BEFORE the pointer |
| 67 | and an additional LWS_SEND_BUFFER_POST_PADDING bytes valid |
| 68 | in the buffer after (buf + len). This is so the protocol |
| 69 | header and trailer data can be added in-situ. |
| 70 | <dt><b>len</b> |
| 71 | <dd>Count of the data bytes in the payload starting from buf |
| 72 | <dt><b>protocol</b> |
| 73 | <dd>Use LWS_WRITE_HTTP to reply to an http connection, and one |
| 74 | of LWS_WRITE_BINARY or LWS_WRITE_TEXT to send appropriate |
| 75 | data on a websockets connection. Remember to allow the extra |
| 76 | bytes before and after buf if LWS_WRITE_BINARY or LWS_WRITE_TEXT |
| 77 | are used. |
| 78 | </dl> |
| 79 | <h3>Description</h3> |
| 80 | <blockquote> |
| 81 | This function provides the way to issue data back to the client |
| 82 | for both http and websocket protocols. |
| 83 | <p> |
| 84 | In the case of sending using websocket protocol, be sure to allocate |
| 85 | valid storage before and after buf as explained above. This scheme |
| 86 | allows maximum efficiency of sending data and protocol in a single |
| 87 | packet while not burdening the user code with any protocol knowledge. |
| 88 | </blockquote> |
| 89 | <hr> |
| 90 | <h2>libwebsockets_serve_http_file - Send a file back to the client using http</h2> |
| 91 | <i>int</i> |
| 92 | <b>libwebsockets_serve_http_file</b> |
| 93 | (<i>struct libwebsocket *</i> <b>wsi</b>, |
| 94 | <i>const char *</i> <b>file</b>, |
| 95 | <i>const char *</i> <b>content_type</b>) |
| 96 | <h3>Arguments</h3> |
| 97 | <dl> |
| 98 | <dt><b>wsi</b> |
| 99 | <dd>Websocket instance (available from user callback) |
| 100 | <dt><b>file</b> |
| 101 | <dd>The file to issue over http |
| 102 | <dt><b>content_type</b> |
| 103 | <dd>The http content type, eg, text/html |
| 104 | </dl> |
| 105 | <h3>Description</h3> |
| 106 | <blockquote> |
| 107 | This function is intended to be called from the callback in response |
| 108 | to http requests from the client. It allows the callback to issue |
| 109 | local files down the http link in a single step. |
| 110 | </blockquote> |
| 111 | <hr> |