| <h2>libwebsocket_create_server - Create the listening websockets server</h2> |
| <i>int</i> |
| <b>libwebsocket_create_server</b> |
| (<i>int</i> <b>port</b>, |
| <i>struct libwebsocket_protocols *</i> <b>protocols</b>, |
| <i>const char *</i> <b>ssl_cert_filepath</b>, |
| <i>const char *</i> <b>ssl_private_key_filepath</b>, |
| <i>int</i> <b>gid</b>, |
| <i>int</i> <b>uid</b>) |
| <h3>Arguments</h3> |
| <dl> |
| <dt><b>port</b> |
| <dd>Port to listen on |
| <dt><b>protocols</b> |
| <dd>Array of structures listing supported protocols and a protocol- |
| specific callback for each one. The list is ended with an |
| entry that has a NULL callback pointer. |
| It's not const because we write the owning_server member |
| <dt><b>ssl_cert_filepath</b> |
| <dd>If libwebsockets was compiled to use ssl, and you want |
| to listen using SSL, set to the filepath to fetch the |
| server cert from, otherwise NULL for unencrypted |
| <dt><b>ssl_private_key_filepath</b> |
| <dd>filepath to private key if wanting SSL mode, |
| else ignored |
| <dt><b>gid</b> |
| <dd>group id to change to after setting listen socket, or -1. |
| <dt><b>uid</b> |
| <dd>user id to change to after setting listen socket, or -1. |
| </dl> |
| <h3>Description</h3> |
| <blockquote> |
| This function creates the listening socket and takes care |
| of all initialization in one step. |
| <p> |
| After initialization, it forks a thread that will sits in a service loop |
| and returns to the caller. The actual service actions are performed by |
| user code in a per-protocol callback from the appropriate one selected |
| by the client from the list in <tt><b>protocols</b></tt>. |
| <p> |
| The protocol callback functions are called for a handful of events |
| including http requests coming in, websocket connections becoming |
| established, and data arriving; it's also called periodically to allow |
| async transmission. |
| <p> |
| HTTP requests are sent always to the FIRST protocol in <tt><b>protocol</b></tt>, since |
| at that time websocket protocol has not been negotiated. Other |
| protocols after the first one never see any HTTP callack activity. |
| <p> |
| The server created is a simple http server by default; part of the |
| websocket standard is upgrading this http connection to a websocket one. |
| <p> |
| This allows the same server to provide files like scripts and favicon / |
| images or whatever over http and dynamic data over websockets all in |
| one place; they're all handled in the user callback. |
| </blockquote> |
| <hr> |
| <h2>libwebsockets_get_protocol - Returns a protocol pointer from a websocket connection.</h2> |
| <i>const struct libwebsocket_protocols *</i> |
| <b>libwebsockets_get_protocol</b> |
| (<i>struct libwebsocket *</i> <b>wsi</b>) |
| <h3>Arguments</h3> |
| <dl> |
| <dt><b>wsi</b> |
| <dd>pointer to struct websocket you want to know the protocol of |
| </dl> |
| <h3>Description</h3> |
| <blockquote> |
| <p> |
| This is useful to get the protocol to broadcast back to from inside |
| the callback. |
| </blockquote> |
| <hr> |
| <h2>libwebsockets_broadcast - Sends a buffer to rthe callback for all active connections of the given protocol.</h2> |
| <i>int</i> |
| <b>libwebsockets_broadcast</b> |
| (<i>const struct libwebsocket_protocols *</i> <b>protocol</b>, |
| <i>unsigned char *</i> <b>buf</b>, |
| <i>size_t</i> <b>len</b>) |
| <h3>Arguments</h3> |
| <dl> |
| <dt><b>protocol</b> |
| <dd>pointer to the protocol you will broadcast to all members of |
| <dt><b>buf</b> |
| <dd>buffer containing the data to be broadcase. NOTE: this has to be |
| allocated with LWS_SEND_BUFFER_PRE_PADDING valid bytes before |
| the pointer and LWS_SEND_BUFFER_POST_PADDING afterwards in the |
| case you are calling this function from callback context. |
| <dt><b>len</b> |
| <dd>length of payload data in buf, starting from buf. |
| </dl> |
| <h3>Description</h3> |
| <blockquote> |
| This function allows bulk sending of a packet to every connection using |
| the given protocol. It does not send the data directly; instead it calls |
| the callback with a reason type of LWS_CALLBACK_BROADCAST. If the callback |
| wants to actually send the data for that connection, the callback itself |
| should call <b>libwebsocket_write</b>. |
| <p> |
| <b>libwebsockets_broadcast</b> can be called from another fork context without |
| having to take any care about data visibility between the processes, it'll |
| "just work". |
| </blockquote> |
| <hr> |
| <h2>libwebsocket_write - Apply protocol then write data to client</h2> |
| <i>int</i> |
| <b>libwebsocket_write</b> |
| (<i>struct libwebsocket *</i> <b>wsi</b>, |
| <i>unsigned char *</i> <b>buf</b>, |
| <i>size_t</i> <b>len</b>, |
| <i>enum libwebsocket_write_protocol</i> <b>protocol</b>) |
| <h3>Arguments</h3> |
| <dl> |
| <dt><b>wsi</b> |
| <dd>Websocket instance (available from user callback) |
| <dt><b>buf</b> |
| <dd>The data to send. For data being sent on a websocket |
| connection (ie, not default http), this buffer MUST have |
| LWS_SEND_BUFFER_PRE_PADDING bytes valid BEFORE the pointer |
| and an additional LWS_SEND_BUFFER_POST_PADDING bytes valid |
| in the buffer after (buf + len). This is so the protocol |
| header and trailer data can be added in-situ. |
| <dt><b>len</b> |
| <dd>Count of the data bytes in the payload starting from buf |
| <dt><b>protocol</b> |
| <dd>Use LWS_WRITE_HTTP to reply to an http connection, and one |
| of LWS_WRITE_BINARY or LWS_WRITE_TEXT to send appropriate |
| data on a websockets connection. Remember to allow the extra |
| bytes before and after buf if LWS_WRITE_BINARY or LWS_WRITE_TEXT |
| are used. |
| </dl> |
| <h3>Description</h3> |
| <blockquote> |
| This function provides the way to issue data back to the client |
| for both http and websocket protocols. |
| <p> |
| In the case of sending using websocket protocol, be sure to allocate |
| valid storage before and after buf as explained above. This scheme |
| allows maximum efficiency of sending data and protocol in a single |
| packet while not burdening the user code with any protocol knowledge. |
| </blockquote> |
| <hr> |
| <h2>libwebsockets_serve_http_file - Send a file back to the client using http</h2> |
| <i>int</i> |
| <b>libwebsockets_serve_http_file</b> |
| (<i>struct libwebsocket *</i> <b>wsi</b>, |
| <i>const char *</i> <b>file</b>, |
| <i>const char *</i> <b>content_type</b>) |
| <h3>Arguments</h3> |
| <dl> |
| <dt><b>wsi</b> |
| <dd>Websocket instance (available from user callback) |
| <dt><b>file</b> |
| <dd>The file to issue over http |
| <dt><b>content_type</b> |
| <dd>The http content type, eg, text/html |
| </dl> |
| <h3>Description</h3> |
| <blockquote> |
| This function is intended to be called from the callback in response |
| to http requests from the client. It allows the callback to issue |
| local files down the http link in a single step. |
| </blockquote> |
| <hr> |
| <h2>callback - User server actions</h2> |
| <i>int</i> |
| <b>callback</b> |
| (<i>struct libwebsocket *</i> <b>wsi</b>, |
| <i>enum libwebsocket_callback_reasons</i> <b>reason</b>, |
| <i>void *</i> <b>user</b>, |
| <i>void *</i> <b>in</b>, |
| <i>size_t</i> <b>len</b>) |
| <h3>Arguments</h3> |
| <dl> |
| <dt><b>wsi</b> |
| <dd>Opaque websocket instance pointer |
| <dt><b>reason</b> |
| <dd>The reason for the call |
| <dt><b>user</b> |
| <dd>Pointer to per-session user data allocated by library |
| <dt><b>in</b> |
| <dd>Pointer used for some callback reasons |
| <dt><b>len</b> |
| <dd>Length set for some callback reasons |
| </dl> |
| <h3>Description</h3> |
| <blockquote> |
| This callback is the way the user controls what is served. All the |
| protocol detail is hidden and handled by the library. |
| <p> |
| For each connection / session there is user data allocated that is |
| pointed to by "user". You set the size of this user data area when |
| the library is initialized with libwebsocket_create_server. |
| <p> |
| You get an opportunity to initialize user data when called back with |
| LWS_CALLBACK_ESTABLISHED reason. |
| </blockquote> |
| <h3>LWS_CALLBACK_ESTABLISHED</h3> |
| <blockquote> |
| after successful websocket handshake |
| </blockquote> |
| <h3>LWS_CALLBACK_CLOSED</h3> |
| <blockquote> |
| when the websocket session ends |
| </blockquote> |
| <h3>LWS_CALLBACK_BROADCAST</h3> |
| <blockquote> |
| signal to send to client (you would use |
| <b>libwebsocket_write</b> taking care about the |
| special buffer requirements |
| </blockquote> |
| <h3>LWS_CALLBACK_RECEIVE</h3> |
| <blockquote> |
| data has appeared for the server, it can be |
| found at *in and is len bytes long |
| </blockquote> |
| <h3>LWS_CALLBACK_HTTP</h3> |
| <blockquote> |
| an http request has come from a client that is not |
| asking to upgrade the connection to a websocket |
| one. This is a chance to serve http content, |
| for example, to send a script to the client |
| which will then open the websockets connection. |
| <tt><b>in</b></tt> points to the URI path requested and |
| <b>libwebsockets_serve_http_file</b> makes it very |
| simple to send back a file to the client. |
| </blockquote> |
| <hr> |
| <h2>struct libwebsocket_protocols - List of protocols and handlers server supports.</h2> |
| <b>struct libwebsocket_protocols</b> {<br> |
| <i>const char *</i> <b>name</b>;<br> |
| <i>int (*</i><b>callback</b>) <i>(struct libwebsocket *wsi,enum libwebsocket_callback_reasons reason, void *user,void *in, size_t len)</i>;<br> |
| <i>size_t</i> <b>per_session_data_size</b>;<br> |
| <i>struct libwebsocket_context *</i> <b>owning_server</b>;<br> |
| <i>int</i> <b>broadcast_socket_port</b>;<br> |
| <i>int</i> <b>broadcast_socket_user_fd</b>;<br> |
| <i>int</i> <b>protocol_index</b>;<br> |
| };<br> |
| <h3>Members</h3> |
| <dl> |
| <dt><b>name</b> |
| <dd>Protocol name that must match the one given in the client |
| Javascript new WebSocket(url, 'protocol') name |
| <dt><b>callback</b> |
| <dd>The service callback used for this protocol. It allows the |
| service action for an entire protocol to be encapsulated in |
| the protocol-specific callback |
| <dt><b>per_session_data_size</b> |
| <dd>Each new connection using this protocol gets |
| this much memory allocated on connection establishment and |
| freed on connection takedown. A pointer to this per-connection |
| allocation is passed into the callback in the 'user' parameter |
| <dt><b>owning_server</b> |
| <dd>the server init call fills in this opaque pointer when |
| registering this protocol with the server. |
| <dt><b>broadcast_socket_port</b> |
| <dd>the server init call fills this in with the |
| localhost port number used to forward broadcasts for this |
| protocol |
| <dt><b>broadcast_socket_user_fd</b> |
| <dd>the server init call fills this in ... the <b>main</b> |
| process context can write to this socket to perform broadcasts |
| (use the <b>libwebsockets_broadcast</b> api to do this instead, |
| it works from any process context) |
| <dt><b>protocol_index</b> |
| <dd>which protocol we are starting from zero |
| </dl> |
| <h3>Description</h3> |
| <blockquote> |
| This structure represents one protocol supported by the server. An |
| array of these structures is passed to <b>libwebsocket_create_server</b> |
| allows as many protocols as you like to be handled by one server. |
| </blockquote> |
| <hr> |