Changes from Version 1 of devWebSQL

rakch (IP:
04/07/14 08:42:35 (10 years ago)



  • devWebSQL

    v0 v1  
     1WebSockets on C - coding:  
     5There's a helper api lws_daemonize built by default that does everything you 
     6need to daemonize well, including creating a lock file.  If you're making 
     7what's basically a daemon, just call this early in your init to fork to a 
     8headless background process and exit the starting process. 
     10Notice stdout, stderr, stdin are all redirected to /dev/null to enforce your 
     11daemon is headless, so you'll need to sort out alternative logging, by, eg, 
     15Maximum number of connections 
     18The maximum number of connections the library can deal with is decided when 
     19it starts by querying the OS to find out how many file descriptors it is 
     20allowed to open (1024 on Fedora for example).  It then allocates arrays that 
     21allow up to that many connections, minus whatever other file descriptors are 
     22in use by the user code. 
     24If you want to restrict that allocation, or increase it, you can use ulimit or 
     25similar to change the avaiable number of file descriptors, and when restarted 
     26libwebsockets will adapt accordingly. 
     29Libwebsockets is singlethreaded 
     32Directly performing websocket actions from other threads is not allowed. 
     33Aside from the internal data being inconsistent in forked() processes, 
     34the scope of a wsi (struct websocket) can end at any time during service 
     35with the socket closing and the wsi freed. 
     37Websocket write activities should only take place in the 
     38"LWS_CALLBACK_SERVER_WRITEABLE" callback as described below. 
     40Only live connections appear in the user callbacks, so this removes any 
     41possibility of trying to used closed and freed wsis. 
     43If you need to service other socket or file descriptors as well as the 
     44websocket ones, you can combine them together with the websocket ones 
     45in one poll loop, see "External Polling Loop support" below, and 
     46still do it all in one thread / process context. 
     49Only send data when socket writeable 
     52You should only send data on a websocket connection from the user callback 
     56If you want to send something, do not just send it but request a callback 
     57when the socket is writeable using 
     59 - libwebsocket_callback_on_writable(context, wsi) for a specific wsi, or 
     60 - libwebsocket_callback_on_writable_all_protocol(protocol) for all connections 
     61using that protocol to get a callback when next writeable. 
     63Usually you will get called back immediately next time around the service 
     64loop, but if your peer is slow or temporarily inactive the callback will be 
     65delayed accordingly.  Generating what to write and sending it should be done 
     66in the ...WRITEABLE callback. 
     68See the test server code for an example of how to do this. 
     71Closing connections from the user side 
     74When you want to close a connection, you do it by returning -1 from a 
     75callback for that connection. 
     77You can provoke a callback by calling libwebsocket_callback_on_writable on 
     78the wsi, then notice in the callback you want to close it and just return -1. 
     79But usually, the decision to close is made in a callback already and returning 
     80-1 is simple. 
     82If the socket knows the connection is dead, because the peer closed or there 
     83was an affirmitive network error like a FIN coming, then libwebsockets  will 
     84take care of closing the connection automatically. 
     86If you have a silently dead connection, it's possible to enter a state where 
     87the send pipe on the connection is choked but no ack will ever come, so the 
     88dead connection will never become writeable.  To cover that, you can use TCP 
     89keepalives (see later in this document) 
     92Fragmented messages 
     95To support fragmented messages you need to check for the final 
     96frame of a message with libwebsocket_is_final_fragment. This 
     97check can be combined with libwebsockets_remaining_packet_payload 
     98to gather the whole contents of a message, eg: 
     100    case LWS_CALLBACK_RECEIVE: 
     101    { 
     102        Client * const client = (Client *)user; 
     103        const size_t remaining = libwebsockets_remaining_packet_payload(wsi); 
     105        if (!remaining && libwebsocket_is_final_fragment(wsi)) { 
     106            if (client->HasFragments()) { 
     107                client->AppendMessageFragment(in, len, 0); 
     108                in = (void *)client->GetMessage(); 
     109                len = client->GetMessageLength(); 
     110            } 
     112            client->ProcessMessage((char *)in, len, wsi); 
     113            client->ResetMessage(); 
     114        } else 
     115            client->AppendMessageFragment(in, len, remaining); 
     116    } 
     117    break; 
     119The test app llibwebsockets-test-fraggle sources also show how to 
     120deal with fragmented messages. 
     123Debug Logging 
     126Also using lws_set_log_level api you may provide a custom callback to actually 
     127emit the log string.  By default, this points to an internal emit function 
     128that sends to stderr.  Setting it to NULL leaves it as it is instead. 
     130A helper function lwsl_emit_syslog() is exported from the library to simplify 
     131logging to syslog.  You still need to use setlogmask, openlog and closelog 
     132in your user code. 
     134The logging apis are made available for user code. 
     142The difference between notice and info is that notice will be logged by default 
     143whereas info is ignored by default. 
     146External Polling Loop support 
     149libwebsockets maintains an internal poll() array for all of its 
     150sockets, but you can instead integrate the sockets into an 
     151external polling array.  That's needed if libwebsockets will 
     152cooperate with an existing poll array maintained by another 
     157appear in the callback for protocol 0 and allow interface code to 
     158manage socket descriptors in other poll loops. 
     160You can pass all pollfds that need service to libwebsocket_service_fd(), even 
     161if the socket or file does not belong to libwebsockets it is safe. 
     163If libwebsocket handled it, it zeros the pollfd revents field before returning. 
     164So you can let libwebsockets try and if pollfd->revents is nonzero on return, 
     165you know it needs handling by your code. 
     168Using with in c++ apps 
     171The library is ready for use by C++ apps.  You can get started quickly by 
     172copying the test server 
     174$ cp test-server/test-server.c test.cpp 
     176and building it in C++ like this 
     178$ g++ -DINSTALL_DATADIR=\"/usr/share\" -ocpptest test.cpp -lwebsockets 
     180INSTALL_DATADIR is only needed because the test server uses it as shipped, if 
     181you remove the references to it in your app you don't need to define it on 
     182the g++ line either. 
     185Availability of header information 
     188From v1.2 of the library onwards, the HTTP header content is free()d as soon 
     189as the websocket connection is established.  For websocket servers, you can 
     190copy interesting headers by handling LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION 
     191callback, for clients there's a new callback just for this purpose 
     195TCP Keepalive 
     198It is possible for a connection which is not being used to send to die 
     199silently somewhere between the peer and the side not sending.  In this case 
     200by default TCP will just not report anything and you will never get any more 
     201incoming data or sign the link is dead until you try to send. 
     203To deal with getting a notification of that situation, you can choose to 
     204enable TCP keepalives on all libwebsockets sockets, when you create the 
     207To enable keepalive, set the ka_time member of the context creation parameter 
     208struct to a nonzero value (in seconds) at context creation time.  You should 
     209also fill ka_probes and ka_interval in that case. 
     211With keepalive enabled, the TCP layer will send control packets that should 
     212stimulate a response from the peer without affecting link traffic.  If the 
     213response is not coming, the socket will announce an error at poll() forcing 
     214a close. 
     216Note that BSDs don't support keepalive time / probes / inteveral per-socket 
     217like Linux does.  On those systems you can enable keepalive by a nonzero 
     218value in ka_time, but the systemwide kernel settings for the time / probes/ 
     219interval are used, regardless of what nonzero value is in ka_time. 
     221Optimizing SSL connections 
     224There's a member ssl_cipher_list in the lws_context_creation_info struct 
     225which allows the user code to restrict the possible cipher selection at 
     226context-creation time. 
     228You might want to look into that to stop the ssl peers selecting a ciher which 
     229is too computationally expensive.  To use it, point it to a string like 
     233if left NULL, then the "DEFAULT" set of ciphers are all possible to select. 
     236Async nature of client connections 
     239When you call libwebsocket_client_connect(..) and get a wsi back, it does not 
     240mean your connection is active.  It just mean it started trying to connect. 
     242Your client connection is actually active only when you receive 
     245There's a 5 second timeout for the connection, and it may give up or die for 
     246other reasons, if any of that happens you'll get a 
     247LWS_CALLBACK_CLIENT_CONNECTION_ERROR callback on protocol 0 instead for the 
     250After attempting the connection and getting back a non-NULL wsi you should 
     251loop calling libwebsocket_service() until one of the above callbacks occurs. 
     253As usual, see test-client.c for example code.