1|name|demonstrates| 2---|--- 3client-server|Minimal examples providing client and server connections simultaneously 4crypto|Minimal examples related to using lws crypto apis 5dbus-server|Minimal examples showing how to integrate DBUS into lws event loop 6http-client|Minimal examples providing an http client 7http-server|Minimal examples providing an http server 8raw|Minimal examples related to adopting raw file or socket descriptors into the event loop 9secure-streams|Minimal examples related to the Secure Streams client api 10ws-client|Minimal examples providing a ws client 11ws-server|Minimal examples providing a ws server (and an http server) 12 13## FAQ 14 15### Getting started 16 17Build and install lws itself first (note that after installing lws on \*nix, you need to run `ldconfig` one time so the OS can learn about the new library. Lws installs in `/usr/local` by default, Debian / Ubuntu ldconfig knows to look there already, but Fedora / CentOS need you to add the line `/usr/local/lib` to `/etc/ld.so.conf` and run ldconfig) 18 19Then start with the simplest: 20 21`http-server/minimal-http-server` 22 23### Why are most of the sources split into a main C file file and a protocol file? 24 25Lws supports three ways to implement the protocol callback code: 26 27 - you can just add it all in the same source file 28 29 - you can separate it as these examples do, and #include it 30 into the main sources 31 32 - you can build it as a standalone plugin that is discovered 33 and loaded at runtime. 34 35The way these examples are structured, you can easily also build 36the protocol callback as a plugin just with a different 37CMakeLists.txt... see https://github.com/warmcat/libwebsockets/tree/master/plugin-standalone 38for an example. 39 40### Why would we want the protocol as a plugin? 41 42You will notice a lot of the main C code is the same boilerplate 43repeated for each example. The actual interesting part is in 44the protocol callback only. 45 46Lws provides (-DLWS_WITH_LWSWS=1) a generic lightweight server app called 'lwsws' that 47can be configured by JSON. Combined with your protocol as a plugin, 48it means you don't actually have to make a special server "app" 49part, you can just use lwsws and pass per-vhost configuration 50from JSON into your protocol. (Of course in some cases you have 51an existing app you are bolting lws on to, then you don't care 52about this for that particular case). 53 54Because lwsws has no dependency on whatever your plugin does, it 55can mix and match different protocols randomly without needing any code 56changes. It reduces the size of the task to just writing the 57code you care about in your protocol handler, and nothing else to write 58or maintain. 59 60Lwsws supports advanced features like reload, where it starts a new server 61instance with changed config or different plugins, while keeping the old 62instance around until the last connection to it closes. 63 64### I get why there is a pss, but why is there a vhd? 65 66The pss is instantiated per-connection. But there are almost always 67other variables that have a lifetime longer than a single connection. 68 69You could make these variables "filescope" one-time globals, but that 70means your protocol cannot instantiate multiple times. 71 72Lws supports vhosts (virtual hosts), for example both https://warmcat.com 73and https://libwebsockets are running on the same lwsws instance on the 74same server and same IP... each of these is a separate vhost. 75 76Your protocol may be enabled on multiple vhosts, each of these vhosts 77provides a different vhd specific to the protocol instance on that 78vhost. For example many of the samples keep a linked-list head to 79a list of live pss in the vhd... that means it's cleanly a list of 80pss opened **on that vhost**. If another vhost has the protocol 81enabled, connections to that will point to a different vhd, and the 82linked-list head on that vhd will only list connections to his vhost. 83 84The example "ws-server/minimal-ws-server-threads" demonstrates how to deliver 85external configuration data to a specific vhost + protocol 86combination using code. In lwsws, this is simply a matter of setting 87the desired JSON config. 88 89 90