refactor README
Signed-off-by: Andy Green <andy.green@linaro.org>
diff --git a/README-test-server b/README-test-server
deleted file mode 100644
index dd4a932..0000000
--- a/README-test-server
+++ /dev/null
@@ -1,493 +0,0 @@
-Using test-server as a quickstart
----------------------------------
-
-You need to regenerate the autotools and libtoolize stuff for your system
-
-$ ./autogen.sh
-
-Then for a Fedora x86_86 box, the following config line was
-needed:
-
- ./configure --prefix=/usr --libdir=/usr/lib64 --enable-openssl
-
-For Apple systems, Christopher Baker reported that this is needed
-(and I was told separately enabling openssl makes trouble somehow)
-
-./configure CC="gcc -arch i386 -arch x86_64" CXX="g++ -arch i386 -arch
-x86_64" CPP="gcc -E" CXXCPP="g++ -E" --enable-nofork
-
-For mingw build, I did the following to get working build, ping test is
-disabled when building this way
-
-1) install mingw64_w32 compiler packages from Fedora
-2) additionally install mingw64-zlib package
-3) ./configure --prefix=/usr --enable-mingw --host=x86_64-w64-mingw32
-4) make
-
-For uClibc, you will likely need --enable-builtin-getifaddrs
-
-otherwise if /usr/local/... and /usr/local/lib are OK then...
-
-$ ./configure
-$ make clean
-$ make
-$ sudo make install
-$ libwebsockets-test-server
-
-should be enough to get a test server listening on port 7861.
-
-
-Configure script options
-------------------------
-
-There are several other possible configure options
-
---enable-nofork disables the fork into the background API
- and removes all references to fork() and
- pr_ctl() from the sources. Use it if your
- platform doesn't support forking.
-
---enable-libcrypto by default libwebsockets uses its own
- built-in md5 and sha-1 implementation for
- simplicity. However the libcrypto ones
- may be faster, and in a distro context it
- may be highly desirable to use a common
- library implementation for ease of security
- upgrades. Give this configure option
- to disable the built-in ones and force use
- of the libcrypto (part of openssl) ones.
-
---with-client-cert-dir=dir tells the client ssl support where to
- look for trust certificates to validate
- the remote certificate against.
-
---enable-noping Don't try to build the ping test app
- It needs some unixy environment that
- may choke in other build contexts, this
- lets you cleanly stop it being built
-
---enable-builtin-getifaddrs if your libc lacks getifaddrs, you can build an
- implementation into the library. By default your libc
- one is used.
-
---without-testapps Just build the library not the test apps
-
---without-client Don't build the client part of the library nor the
- test apps that need the client part. Useful to
- minimize library footprint for embedded server-only
- case
-
---without-server Don't build the server part of the library nor the
- test apps that need the server part. Useful to
- minimize library footprint for embedded client-only
- case
-
---without-daemonize Don't build daemonize.c / lws_daemonize
-
---disable-debug Remove all debug logging below lwsl_notice in severity
- from the code -- it's not just defeated from logging
- but removed from compilation
-
-
-Externally configurable important constants
--------------------------------------------
-
-You can control these from configure by just setting them as commandline
-args throgh CFLAGS, eg
-
-./configure CFLAGS="-DLWS_MAX_ZLIB_CONN_BUFFER=8192"
-
-They all have defaults so you only need to take care about them if you want
-to tune them to the amount of memory available.
-
- - LWS_MAX_HEADER_NAME_LENGTH default 64: max characters in an HTTP header
-name that libwebsockets can cope with
-
- - LWS_MAX_HEADER_LEN default 4096: largest HTTP header value string length
-libwebsockets can cope with
-
- - LWS_INITIAL_HDR_ALLOC default 256: amount of memory to allocate initially,
-tradeoff between taking too much and needless realloc
-
- - LWS_ADDITIONAL_HDR_ALLOC default 64: how much to additionally realloc if
-the header value string keeps coming
-
- - MAX_USER_RX_BUFFER default 4096: max amount of user rx data to buffer at a
-time and pass to user callback LWS_CALLBACK_RECEIVE or
-LWS_CALLBACK_CLIENT_RECEIVE. Large frames are passed to the user callback
-in chunks of this size. Tradeoff between per-connection static memory
-allocation and if you expect to deal with large frames, how much you can
-see at once which can affect efficiency.
-
- - MAX_BROADCAST_PAYLOAD default 4096: largest amount of user tx data we can
-broadcast at a time
-
- - LWS_MAX_PROTOCOLS default 10: largest amount of different protocols the
-server can serve
-
- - LWS_MAX_EXTENSIONS_ACTIVE default 10: largest amount of extensions we can
-choose to have active on one connection
-
- - SPEC_LATEST_SUPPORTED default 13: only change if you want to remove support
-for later protocol versions... unlikely
-
- - AWAITING_TIMEOUT default 5: after this many seconds without a response, the
-server will hang up on the client
-
- - CIPHERS_LIST_STRING default "DEFAULT": SSL Cipher selection. It's advisable
-to tweak the ciphers allowed to be negotiated on secure connections for
-performance reasons, otherwise a slow algorithm may be selected by the two
-endpoints and the server could expend most of its time just encrypting and
-decrypting data, severely limiting the amount of messages it will be able to
-handle per second. For example::
-
- "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
-
- - SYSTEM_RANDOM_FILEPATH default "/dev/urandom": if your random device differs
-you can set it here
-
- - LWS_MAX_ZLIB_CONN_BUFFER maximum size a compression buffer is allowed to
-grow to before closing the connection. Default is 64KBytes.
-
- - LWS_SOMAXCONN maximum number of pending connect requests the listening
-socket can cope with. Default is SOMAXCONN. If you need to use synthetic
-tests that just spam hundreds of connect requests at once without dropping
-any, you can try messing with these as well as ulimit (see later)
-(courtesy Edwin van der Oetelaar)
-
-echo "2048 64512" > /proc/sys/net/ipv4/ip_local_port_range
-echo "1" > /proc/sys/net/ipv4/tcp_tw_recycle
-echo "1" > /proc/sys/net/ipv4/tcp_tw_reuse
-echo "10" > /proc/sys/net/ipv4/tcp_fin_timeout
-echo "65536" > /proc/sys/net/core/somaxconn
-echo "65536" > /proc/sys/net/ipv4/tcp_max_syn_backlog
-echo "262144" > /proc/sys/net/netfilter/nf_conntrack_max
-
-
-Testing server with a browser
------------------------------
-
-If you point your browser (eg, Chrome) to
-
- http://127.0.0.1:7681
-
-It will fetch a script in the form of test.html, and then run the
-script in there on the browser to open a websocket connection.
-Incrementing numbers should appear in the browser display.
-
-By default the test server logs to both stderr and syslog.
-
-
-Running test server as a Daemon
--------------------------------
-
-You can use the -D option on the test server to have it fork into the
-background and return immediately. In this daemonized mode all stderr is
-disabled and logging goes only to syslog, eg, /var/log/messages or similar.
-
-The server maintains a lockfile at /tmp/.lwsts-lock that contains the pid
-of the master process, and deletes this file when the master process
-terminates.
-
-To stop the daemon, do
-
- kill `cat /tmp/.lwsts-lock`
-
-If it finds a stale lock (the pid mentioned in the file does not exist
-any more) it will delete the lock and create a new one during startup.
-
-If the lock is valid, the daemon will exit with a note on stderr that
-it was already running.s
-
-
-Using SSL on the server side
-----------------------------
-
-To test it using SSL/WSS, just run the test server with
-
-$ libwebsockets-test-server --ssl
-
-and use the URL
-
- https://127.0.0.1:7681
-
-The connection will be entirely encrypted using some generated
-certificates that your browser will not accept, since they are
-not signed by any real Certificate Authority. Just accept the
-certificates in the browser and the connection will proceed
-in first https and then websocket wss, acting exactly the
-same.
-
-test-server.c is all that is needed to use libwebsockets for
-serving both the script html over http and websockets.
-
-
-Forkless operation
-------------------
-
-If your target device does not offer fork(), you can use
-libwebsockets from your own main loop instead. Use the
-configure option --nofork and simply call libwebsocket_service()
-from your own main loop as shown in the test app sources.
-
-
-Daemonization
--------------
-
-There's a helper api lws_daemonize built by default that does everything you
-need to daemonize well, including creating a lock file. If you're making
-what's basically a daemon, just call this early in your init to fork to a
-headless background process and exit the starting process.
-
-Notice stdout, stderr, stdin are all redirected to /dev/null to enforce your
-daemon is headless, so you'll need to sort out alternative logging, by, eg,
-syslog.
-
-
-Maximum number of connections
------------------------------
-
-The maximum number of connections the library can deal with is decided when
-it starts by querying the OS to find out how many file descriptors it is
-allowed to open (1024 on Fedora for example). It then allocates arrays that
-allow up to that many connections, minus whatever other file descriptors are
-in use by the user code.
-
-If you want to restrict that allocation, or increase it, you can use ulimit or
-similar to change the avaiable number of file descriptors, and when restarted
-libwebsockets will adapt accordingly.
-
-
-Fragmented messages
--------------------
-
-To support fragmented messages you need to check for the final
-frame of a message with libwebsocket_is_final_fragment. This
-check can be combined with libwebsockets_remaining_packet_payload
-to gather the whole contents of a message, eg:
-
- case LWS_CALLBACK_RECEIVE:
- {
- Client * const client = (Client *)user;
- const size_t remaining = libwebsockets_remaining_packet_payload(wsi);
-
- if (!remaining && libwebsocket_is_final_fragment(wsi)) {
- if (client->HasFragments()) {
- client->AppendMessageFragment(in, len, 0);
- in = (void *)client->GetMessage();
- len = client->GetMessageLength();
- }
-
- client->ProcessMessage((char *)in, len, wsi);
- client->ResetMessage();
- } else
- client->AppendMessageFragment(in, len, remaining);
- }
- break;
-
-The test app llibwebsockets-test-fraggle sources also show how to
-deal with fragmented messages.
-
-
-Testing websocket client support
---------------------------------
-
-If you run the test server as described above, you can also
-connect to it using the test client as well as a browser.
-
-$ libwebsockets-test-client localhost
-
-will by default connect to the test server on localhost:7681
-and print the dumb increment number from the server at the
-same time as drawing random circles in the mirror protocol;
-if you connect to the test server using a browser at the
-same time you will be able to see the circles being drawn.
-
-
-Testing SSL on the client side
-------------------------------
-
-To test SSL/WSS client action, just run the client test with
-
-$ libwebsockets-test-client localhost --ssl
-
-By default the client test applet is set to accept selfsigned
-certificates used by the test server, this is indicated by the
-use_ssl var being set to 2. Set it to 1 to reject any server
-certificate that it doesn't have a trusted CA cert for.
-
-
-Using the websocket ping utility
---------------------------------
-
-libwebsockets-test-ping connects as a client to a remote
-websocket server using 04 protocol and pings it like the
-normal unix ping utility.
-
-$ libwebsockets-test-ping localhost
-handshake OK for protocol lws-mirror-protocol
-Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
-64 bytes from localhost: req=1 time=0.1ms
-64 bytes from localhost: req=2 time=0.1ms
-64 bytes from localhost: req=3 time=0.1ms
-64 bytes from localhost: req=4 time=0.2ms
-64 bytes from localhost: req=5 time=0.1ms
-64 bytes from localhost: req=6 time=0.2ms
-64 bytes from localhost: req=7 time=0.2ms
-64 bytes from localhost: req=8 time=0.1ms
-^C
---- localhost.localdomain websocket ping statistics ---
-8 packets transmitted, 8 received, 0% packet loss, time 7458ms
-rtt min/avg/max = 0.110/0.185/0.218 ms
-$
-
-By default it sends 64 byte payload packets using the 04
-PING packet opcode type. You can change the payload size
-using the -s= flag, up to a maximum of 125 mandated by the
-04 standard.
-
-Using the lws-mirror protocol that is provided by the test
-server, libwebsockets-test-ping can also use larger payload
-sizes up to 4096 is BINARY packets; lws-mirror will copy
-them back to the client and they appear as a PONG. Use the
--m flag to select this operation.
-
-The default interval between pings is 1s, you can use the -i=
-flag to set this, including fractions like -i=0.01 for 10ms
-interval.
-
-Before you can even use the PING opcode that is part of the
-standard, you must complete a handshake with a specified
-protocol. By default lws-mirror-protocol is used which is
-supported by the test server. But if you are using it on
-another server, you can specify the protcol to handshake with
-by --protocol=protocolname
-
-
-Fraggle test app
-----------------
-
-By default it runs in server mode
-
-$ libwebsockets-test-fraggle
-libwebsockets test fraggle
-(C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
- Compiled with SSL support, not using it
- Listening on port 7681
-server sees client connect
-accepted v06 connection
-Spamming 360 random fragments
-Spamming session over, len = 371913. sum = 0x2D3C0AE
-Spamming 895 random fragments
-Spamming session over, len = 875970. sum = 0x6A74DA1
-...
-
-You need to run a second session in client mode, you have to
-give the -c switch and the server address at least:
-
-$ libwebsockets-test-fraggle -c localhost
-libwebsockets test fraggle
-(C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
- Client mode
-Connecting to localhost:7681
-denied deflate-stream extension
-handshake OK for protocol fraggle-protocol
-client connects to server
-EOM received 371913 correctly from 360 fragments
-EOM received 875970 correctly from 895 fragments
-EOM received 247140 correctly from 258 fragments
-EOM received 695451 correctly from 692 fragments
-...
-
-The fraggle test sends a random number up to 1024 fragmented websocket frames
-each of a random size between 1 and 2001 bytes in a single message, then sends
-a checksum and starts sending a new randomly sized and fragmented message.
-
-The fraggle test client receives the same message fragments and computes the
-same checksum using websocket framing to see when the message has ended. It
-then accepts the server checksum message and compares that to its checksum.
-
-
-proxy support
--------------
-
-The http_proxy environment variable is respected by the client
-connection code for both ws:// and wss://. It doesn't support
-authentication yet.
-
-You use it like this
-
-export http_proxy=myproxy.com:3128
-libwebsockets-test-client someserver.com
-
-
-debug logging
--------------
-
-By default logging of severity "notice", "warn" or "err" is enabled to stderr.
-
-Again by default other logging is comiled in but disabled from printing.
-
-If you want to eliminate the debug logging below notice in severity, use the
---disable-debug configure option to have it removed from the code by the
-preprocesser.
-
-If you want to see more detailed debug logs, you can control a bitfield to
-select which logs types may print using the lws_set_log_level() api, in the
-test apps you can use -d <number> to control this. The types of logging
-available are (OR together the numbers to select multiple)
-
- 1 ERR
- 2 WARN
- 4 NOTICE
- 8 INFO
- 16 DEBUG
- 32 PARSER
- 64 HEADER
- 128 EXTENSION
- 256 CLIENT
-
-Also using lws_set_log_level api you may provide a custom callback to actually
-emit the log string. By default, this points to an internal emit function
-that sends to stderr. Setting it to NULL leaves it as it is instead.
-
-A helper function lwsl_emit_syslog() is exported from the library to simplify
-logging to syslog. You still need to use setlogmask, openlog and closelog
-in your user code.
-
-The logging apis are made available for user code.
-
-lwsl_err(...)
-lwsl_warn(...)
-lwsl_notice(...)
-lwsl_info(...)
-lwsl_debug(...)
-
-The difference between notice and info is that notice will be logged by default
-whereas info is ignored by default.
-
-
-Websocket version supported
----------------------------
-
-The final IETF standard is supported along with various older ones that will
-be removed at some point, -76, -04 and -05.
-
-
-External Polling Loop support
------------------------------
-
-libwebsockets maintains an internal poll() array for all of its
-sockets, but you can instead integrate the sockets into an
-external polling array. That's needed if libwebsockets will
-cooperate with an existing poll array maintained by another
-server.
-
-Four callbacks LWS_CALLBACK_ADD_POLL_FD, LWS_CALLBACK_DEL_POLL_FD,
-LWS_CALLBACK_SET_MODE_POLL_FD and LWS_CALLBACK_CLEAR_MODE_POLL_FD
-appear in the callback for protocol 0 and allow interface code to
-manage socket descriptors in other poll loops.
-
-
-2013-01-14 Andy Green <andy@warmcat.com>
-
diff --git a/README.build b/README.build
new file mode 100644
index 0000000..48167ff
--- /dev/null
+++ b/README.build
@@ -0,0 +1,169 @@
+Building the library and test apps
+----------------------------------
+
+You need to regenerate the autotools and libtoolize stuff for your system
+
+$ ./autogen.sh
+
+Then for a Fedora x86_86 box, the following config line was
+needed:
+
+ ./configure --prefix=/usr --libdir=/usr/lib64 --enable-openssl
+
+For Apple systems, Christopher Baker reported that this is needed
+(and I was told separately enabling openssl makes trouble somehow)
+
+./configure CC="gcc -arch i386 -arch x86_64" CXX="g++ -arch i386 -arch
+x86_64" CPP="gcc -E" CXXCPP="g++ -E" --enable-nofork
+
+For mingw build, I did the following to get working build, ping test is
+disabled when building this way
+
+1) install mingw64_w32 compiler packages from Fedora
+2) additionally install mingw64-zlib package
+3) ./configure --prefix=/usr --enable-mingw --host=x86_64-w64-mingw32
+4) make
+
+For uClibc, you will likely need --enable-builtin-getifaddrs
+
+
+otherwise if /usr/local/... and /usr/local/lib are OK then...
+
+$ ./configure
+$ make clean
+$ make && sudo make install
+$ libwebsockets-test-server
+
+should be enough to get a test server listening on port 7861.
+
+
+Configure script options
+------------------------
+
+There are several other possible configure options
+
+--enable-nofork disables the fork into the background API
+ and removes all references to fork() and
+ pr_ctl() from the sources. Use it if your
+ platform doesn't support forking.
+
+--enable-libcrypto by default libwebsockets uses its own
+ built-in md5 and sha-1 implementation for
+ simplicity. However the libcrypto ones
+ may be faster, and in a distro context it
+ may be highly desirable to use a common
+ library implementation for ease of security
+ upgrades. Give this configure option
+ to disable the built-in ones and force use
+ of the libcrypto (part of openssl) ones.
+
+--with-client-cert-dir=dir tells the client ssl support where to
+ look for trust certificates to validate
+ the remote certificate against.
+
+--enable-noping Don't try to build the ping test app
+ It needs some unixy environment that
+ may choke in other build contexts, this
+ lets you cleanly stop it being built
+
+--enable-builtin-getifaddrs if your libc lacks getifaddrs, you can build an
+ implementation into the library. By default your libc
+ one is used.
+
+--without-testapps Just build the library not the test apps
+
+--without-client Don't build the client part of the library nor the
+ test apps that need the client part. Useful to
+ minimize library footprint for embedded server-only
+ case
+
+--without-server Don't build the server part of the library nor the
+ test apps that need the server part. Useful to
+ minimize library footprint for embedded client-only
+ case
+
+--without-daemonize Don't build daemonize.c / lws_daemonize
+
+--disable-debug Remove all debug logging below lwsl_notice in severity
+ from the code -- it's not just defeated from logging
+ but removed from compilation
+
+
+Externally configurable important constants
+-------------------------------------------
+
+You can control these from configure by just setting them as commandline
+args throgh CFLAGS, eg
+
+./configure CFLAGS="-DLWS_MAX_ZLIB_CONN_BUFFER=8192"
+
+
+They all have reasonable defaults usable for all use-cases except resource-
+constrained, so you only need to take care about them if you want to tune them
+to the amount of memory available.
+
+ - LWS_MAX_HEADER_NAME_LENGTH default 64: max characters in an HTTP header
+name that libwebsockets can cope with
+
+ - LWS_MAX_HEADER_LEN default 4096: largest HTTP header value string length
+libwebsockets can cope with
+
+ - LWS_INITIAL_HDR_ALLOC default 256: amount of memory to allocate initially,
+tradeoff between taking too much and needless realloc
+
+ - LWS_ADDITIONAL_HDR_ALLOC default 64: how much to additionally realloc if
+the header value string keeps coming
+
+ - MAX_USER_RX_BUFFER default 4096: max amount of user rx data to buffer at a
+time and pass to user callback LWS_CALLBACK_RECEIVE or
+LWS_CALLBACK_CLIENT_RECEIVE. Large frames are passed to the user callback
+in chunks of this size. Tradeoff between per-connection static memory
+allocation and if you expect to deal with large frames, how much you can
+see at once which can affect efficiency.
+
+ - MAX_BROADCAST_PAYLOAD default 4096: largest amount of user tx data we can
+broadcast at a time
+
+ - LWS_MAX_PROTOCOLS default 10: largest amount of different protocols the
+server can serve
+
+ - LWS_MAX_EXTENSIONS_ACTIVE default 10: largest amount of extensions we can
+choose to have active on one connection
+
+ - SPEC_LATEST_SUPPORTED default 13: only change if you want to remove support
+for later protocol versions... unlikely
+
+ - AWAITING_TIMEOUT default 5: after this many seconds without a response, the
+server will hang up on the client
+
+ - CIPHERS_LIST_STRING default "DEFAULT": SSL Cipher selection. It's advisable
+to tweak the ciphers allowed to be negotiated on secure connections for
+performance reasons, otherwise a slow algorithm may be selected by the two
+endpoints and the server could expend most of its time just encrypting and
+decrypting data, severely limiting the amount of messages it will be able to
+handle per second. For example::
+
+ "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
+
+ - SYSTEM_RANDOM_FILEPATH default "/dev/urandom": if your random device differs
+you can set it here
+
+ - LWS_MAX_ZLIB_CONN_BUFFER maximum size a compression buffer is allowed to
+grow to before closing the connection. Some limit is needed or any connecton
+can exhaust all server memory by sending it 4G buffers full of zeros which the
+server is expect to expand atomically. Default is 64KBytes.
+
+ - LWS_SOMAXCONN maximum number of pending connect requests the listening
+socket can cope with. Default is SOMAXCONN. If you need to use synthetic
+tests that just spam hundreds of connect requests at once without dropping
+any, you can try messing with these as well as ulimit (see later)
+(courtesy Edwin van der Oetelaar)
+
+echo "2048 64512" > /proc/sys/net/ipv4/ip_local_port_range
+echo "1" > /proc/sys/net/ipv4/tcp_tw_recycle
+echo "1" > /proc/sys/net/ipv4/tcp_tw_reuse
+echo "10" > /proc/sys/net/ipv4/tcp_fin_timeout
+echo "65536" > /proc/sys/net/core/somaxconn
+echo "65536" > /proc/sys/net/ipv4/tcp_max_syn_backlog
+echo "262144" > /proc/sys/net/netfilter/nf_conntrack_max
+
diff --git a/README.coding b/README.coding
new file mode 100644
index 0000000..0cfb07a
--- /dev/null
+++ b/README.coding
@@ -0,0 +1,95 @@
+Daemonization
+-------------
+
+There's a helper api lws_daemonize built by default that does everything you
+need to daemonize well, including creating a lock file. If you're making
+what's basically a daemon, just call this early in your init to fork to a
+headless background process and exit the starting process.
+
+Notice stdout, stderr, stdin are all redirected to /dev/null to enforce your
+daemon is headless, so you'll need to sort out alternative logging, by, eg,
+syslog.
+
+
+Maximum number of connections
+-----------------------------
+
+The maximum number of connections the library can deal with is decided when
+it starts by querying the OS to find out how many file descriptors it is
+allowed to open (1024 on Fedora for example). It then allocates arrays that
+allow up to that many connections, minus whatever other file descriptors are
+in use by the user code.
+
+If you want to restrict that allocation, or increase it, you can use ulimit or
+similar to change the avaiable number of file descriptors, and when restarted
+libwebsockets will adapt accordingly.
+
+
+Fragmented messages
+-------------------
+
+To support fragmented messages you need to check for the final
+frame of a message with libwebsocket_is_final_fragment. This
+check can be combined with libwebsockets_remaining_packet_payload
+to gather the whole contents of a message, eg:
+
+ case LWS_CALLBACK_RECEIVE:
+ {
+ Client * const client = (Client *)user;
+ const size_t remaining = libwebsockets_remaining_packet_payload(wsi);
+
+ if (!remaining && libwebsocket_is_final_fragment(wsi)) {
+ if (client->HasFragments()) {
+ client->AppendMessageFragment(in, len, 0);
+ in = (void *)client->GetMessage();
+ len = client->GetMessageLength();
+ }
+
+ client->ProcessMessage((char *)in, len, wsi);
+ client->ResetMessage();
+ } else
+ client->AppendMessageFragment(in, len, remaining);
+ }
+ break;
+
+The test app llibwebsockets-test-fraggle sources also show how to
+deal with fragmented messages.
+
+Debug Logging
+-------------
+
+Also using lws_set_log_level api you may provide a custom callback to actually
+emit the log string. By default, this points to an internal emit function
+that sends to stderr. Setting it to NULL leaves it as it is instead.
+
+A helper function lwsl_emit_syslog() is exported from the library to simplify
+logging to syslog. You still need to use setlogmask, openlog and closelog
+in your user code.
+
+The logging apis are made available for user code.
+
+lwsl_err(...)
+lwsl_warn(...)
+lwsl_notice(...)
+lwsl_info(...)
+lwsl_debug(...)
+
+The difference between notice and info is that notice will be logged by default
+whereas info is ignored by default.
+
+
+External Polling Loop support
+-----------------------------
+
+libwebsockets maintains an internal poll() array for all of its
+sockets, but you can instead integrate the sockets into an
+external polling array. That's needed if libwebsockets will
+cooperate with an existing poll array maintained by another
+server.
+
+Four callbacks LWS_CALLBACK_ADD_POLL_FD, LWS_CALLBACK_DEL_POLL_FD,
+LWS_CALLBACK_SET_MODE_POLL_FD and LWS_CALLBACK_CLEAR_MODE_POLL_FD
+appear in the callback for protocol 0 and allow interface code to
+manage socket descriptors in other poll loops.
+
+
diff --git a/README.test-apps b/README.test-apps
new file mode 100644
index 0000000..bcc295f
--- /dev/null
+++ b/README.test-apps
@@ -0,0 +1,237 @@
+Testing server with a browser
+-----------------------------
+
+If you run libwebsockets-test-server and point your browser
+(eg, Chrome) to
+
+ http://127.0.0.1:7681
+
+It will fetch a script in the form of test.html, and then run the
+script in there on the browser to open a websocket connection.
+Incrementing numbers should appear in the browser display.
+
+By default the test server logs to both stderr and syslog, you can control
+what is logged using -d <log level>, see later.
+
+
+Running test server as a Daemon
+-------------------------------
+
+You can use the -D option on the test server to have it fork into the
+background and return immediately. In this daemonized mode all stderr is
+disabled and logging goes only to syslog, eg, /var/log/messages or similar.
+
+The server maintains a lockfile at /tmp/.lwsts-lock that contains the pid
+of the master process, and deletes this file when the master process
+terminates.
+
+To stop the daemon, do
+
+ kill `cat /tmp/.lwsts-lock`
+
+If it finds a stale lock (the pid mentioned in the file does not exist
+any more) it will delete the lock and create a new one during startup.
+
+If the lock is valid, the daemon will exit with a note on stderr that
+it was already running.s
+
+
+Using SSL on the server side
+----------------------------
+
+To test it using SSL/WSS, just run the test server with
+
+$ libwebsockets-test-server --ssl
+
+and use the URL
+
+ https://127.0.0.1:7681
+
+The connection will be entirely encrypted using some generated
+certificates that your browser will not accept, since they are
+not signed by any real Certificate Authority. Just accept the
+certificates in the browser and the connection will proceed
+in first https and then websocket wss, acting exactly the
+same.
+
+test-server.c is all that is needed to use libwebsockets for
+serving both the script html over http and websockets.
+
+
+Forkless operation
+------------------
+
+If your target device does not offer fork(), you can use
+libwebsockets from your own main loop instead. Use the
+configure option --nofork and simply call libwebsocket_service()
+from your own main loop as shown in the test app sources.
+
+
+
+
+Testing websocket client support
+--------------------------------
+
+If you run the test server as described above, you can also
+connect to it using the test client as well as a browser.
+
+$ libwebsockets-test-client localhost
+
+will by default connect to the test server on localhost:7681
+and print the dumb increment number from the server at the
+same time as drawing random circles in the mirror protocol;
+if you connect to the test server using a browser at the
+same time you will be able to see the circles being drawn.
+
+
+Testing SSL on the client side
+------------------------------
+
+To test SSL/WSS client action, just run the client test with
+
+$ libwebsockets-test-client localhost --ssl
+
+By default the client test applet is set to accept selfsigned
+certificates used by the test server, this is indicated by the
+use_ssl var being set to 2. Set it to 1 to reject any server
+certificate that it doesn't have a trusted CA cert for.
+
+
+Using the websocket ping utility
+--------------------------------
+
+libwebsockets-test-ping connects as a client to a remote
+websocket server using 04 protocol and pings it like the
+normal unix ping utility.
+
+$ libwebsockets-test-ping localhost
+handshake OK for protocol lws-mirror-protocol
+Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
+64 bytes from localhost: req=1 time=0.1ms
+64 bytes from localhost: req=2 time=0.1ms
+64 bytes from localhost: req=3 time=0.1ms
+64 bytes from localhost: req=4 time=0.2ms
+64 bytes from localhost: req=5 time=0.1ms
+64 bytes from localhost: req=6 time=0.2ms
+64 bytes from localhost: req=7 time=0.2ms
+64 bytes from localhost: req=8 time=0.1ms
+^C
+--- localhost.localdomain websocket ping statistics ---
+8 packets transmitted, 8 received, 0% packet loss, time 7458ms
+rtt min/avg/max = 0.110/0.185/0.218 ms
+$
+
+By default it sends 64 byte payload packets using the 04
+PING packet opcode type. You can change the payload size
+using the -s= flag, up to a maximum of 125 mandated by the
+04 standard.
+
+Using the lws-mirror protocol that is provided by the test
+server, libwebsockets-test-ping can also use larger payload
+sizes up to 4096 is BINARY packets; lws-mirror will copy
+them back to the client and they appear as a PONG. Use the
+-m flag to select this operation.
+
+The default interval between pings is 1s, you can use the -i=
+flag to set this, including fractions like -i=0.01 for 10ms
+interval.
+
+Before you can even use the PING opcode that is part of the
+standard, you must complete a handshake with a specified
+protocol. By default lws-mirror-protocol is used which is
+supported by the test server. But if you are using it on
+another server, you can specify the protcol to handshake with
+by --protocol=protocolname
+
+
+Fraggle test app
+----------------
+
+By default it runs in server mode
+
+$ libwebsockets-test-fraggle
+libwebsockets test fraggle
+(C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
+ Compiled with SSL support, not using it
+ Listening on port 7681
+server sees client connect
+accepted v06 connection
+Spamming 360 random fragments
+Spamming session over, len = 371913. sum = 0x2D3C0AE
+Spamming 895 random fragments
+Spamming session over, len = 875970. sum = 0x6A74DA1
+...
+
+You need to run a second session in client mode, you have to
+give the -c switch and the server address at least:
+
+$ libwebsockets-test-fraggle -c localhost
+libwebsockets test fraggle
+(C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
+ Client mode
+Connecting to localhost:7681
+denied deflate-stream extension
+handshake OK for protocol fraggle-protocol
+client connects to server
+EOM received 371913 correctly from 360 fragments
+EOM received 875970 correctly from 895 fragments
+EOM received 247140 correctly from 258 fragments
+EOM received 695451 correctly from 692 fragments
+...
+
+The fraggle test sends a random number up to 1024 fragmented websocket frames
+each of a random size between 1 and 2001 bytes in a single message, then sends
+a checksum and starts sending a new randomly sized and fragmented message.
+
+The fraggle test client receives the same message fragments and computes the
+same checksum using websocket framing to see when the message has ended. It
+then accepts the server checksum message and compares that to its checksum.
+
+
+proxy support
+-------------
+
+The http_proxy environment variable is respected by the client
+connection code for both ws:// and wss://. It doesn't support
+authentication.
+
+You use it like this
+
+export http_proxy=myproxy.com:3128
+libwebsockets-test-client someserver.com
+
+
+debug logging
+-------------
+
+By default logging of severity "notice", "warn" or "err" is enabled to stderr.
+
+Again by default other logging is comiled in but disabled from printing.
+
+If you want to eliminate the debug logging below notice in severity, use the
+--disable-debug configure option to have it removed from the code by the
+preprocesser.
+
+If you want to see more detailed debug logs, you can control a bitfield to
+select which logs types may print using the lws_set_log_level() api, in the
+test apps you can use -d <number> to control this. The types of logging
+available are (OR together the numbers to select multiple)
+
+ 1 ERR
+ 2 WARN
+ 4 NOTICE
+ 8 INFO
+ 16 DEBUG
+ 32 PARSER
+ 64 HEADER
+ 128 EXTENSION
+ 256 CLIENT
+
+
+Websocket version supported
+---------------------------
+
+The final IETF standard is supported along with various older ones that will
+be removed at some point, -76, -04 and -05.
+
+