mirror of
https://github.com/warmcat/libwebsockets.git
synced 2025-03-09 00:00:04 +01:00
Subject: [PATCH] Nicer readmes using markdown.
This is still readable in raw text, but much nicer for github with heading and syntax highlighting and such.
This commit is contained in:
parent
453a9b34fd
commit
4198276505
4 changed files with 216 additions and 156 deletions
|
@ -4,9 +4,9 @@ Introduction to CMake
|
|||
CMake is a multi-platform build tool that can generate build files for many
|
||||
different target platforms. See more info at http://www.cmake.org
|
||||
|
||||
CMake also allows/recommends you to do "out of source"-builds, that is,
|
||||
the build files are separated from your sources, so there is no need to
|
||||
create elaborate clean scripts to get a clean source tree, instead you
|
||||
CMake also allows/recommends you to do "out of source"-builds, that is,
|
||||
the build files are separated from your sources, so there is no need to
|
||||
create elaborate clean scripts to get a clean source tree, instead you
|
||||
simply remove your build directory.
|
||||
|
||||
Libwebsockets has been tested to build successfully on the following platforms
|
||||
|
@ -21,7 +21,7 @@ Building the library and test apps
|
|||
----------------------------------
|
||||
|
||||
The project settings used by CMake to generate the platform specific build
|
||||
files is called CMakeLists.txt. CMake then uses one of its "Generators" to
|
||||
files is called [CMakeLists.txt](CMakeLists.txt). CMake then uses one of its "Generators" to
|
||||
output a Visual Studio project or Make file for instance. To see a list of
|
||||
the available generators for your platform, simply run the "cmake" command.
|
||||
|
||||
|
@ -38,48 +38,60 @@ Building on Unix:
|
|||
|
||||
3. Generate the build files (default is Make files):
|
||||
|
||||
cd /path/to/src
|
||||
mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
```bash
|
||||
$ cd /path/to/src
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
$ cmake ..
|
||||
```
|
||||
|
||||
(NOTE: The build/ directory can have any name and be located anywhere
|
||||
on your filesystem, and that the argument ".." given to cmake is simply
|
||||
the source directory of libwebsockets containing the CMakeLists.txt
|
||||
(**NOTE**: The `build/`` directory can have any name and be located anywhere
|
||||
on your filesystem, and that the argument `..` given to cmake is simply
|
||||
the source directory of **libwebsockets** containing the [CMakeLists.txt](CMakeLists.txt)
|
||||
project file. All examples in this file assumes you use "..")
|
||||
|
||||
NOTE2
|
||||
**NOTE2**:
|
||||
A common option you may want to give is to set the install path, same
|
||||
as --prefix= with autotools. It defaults to /usr/local.
|
||||
You can do this by, eg
|
||||
|
||||
cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
|
||||
```bash
|
||||
$ cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
|
||||
```
|
||||
|
||||
NOTE3
|
||||
**NOTE3**:
|
||||
On machines that want libraries in lib64, you can also add the
|
||||
following to the cmake line
|
||||
|
||||
-DLIB_SUFFIX=64
|
||||
|
||||
NOTE4
|
||||
```bash
|
||||
-DLIB_SUFFIX=64
|
||||
```
|
||||
|
||||
**NOTE4**:
|
||||
If you are building against a non-distro OpenSSL (eg, in order to get
|
||||
access to ALPN support only in newer OpenSSL versions) the nice way to
|
||||
express that in one cmake command is eg,
|
||||
|
||||
cmake .. -DOPENSSL_ROOT_DIR=/usr/local/ssl \
|
||||
|
||||
```bash
|
||||
$ cmake .. -DOPENSSL_ROOT_DIR=/usr/local/ssl \
|
||||
-DCMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE=/usr/local/ssl \
|
||||
-DLWS_WITH_HTTP2=1
|
||||
|
||||
```
|
||||
|
||||
When you run the test apps using non-distro SSL, you have to force them
|
||||
to use your libs, not the distro ones
|
||||
|
||||
LD_LIBRARY_PATH=/usr/local/ssl/lib libwebsockets-test-server --ssl
|
||||
|
||||
```bash
|
||||
$ LD_LIBRARY_PATH=/usr/local/ssl/lib libwebsockets-test-server --ssl
|
||||
```
|
||||
|
||||
4. Finally you can build using the generated Makefile:
|
||||
|
||||
make
|
||||
```bash
|
||||
$ make
|
||||
```
|
||||
|
||||
|
||||
|
||||
Quirk of cmake
|
||||
--------------
|
||||
|
||||
|
@ -97,15 +109,17 @@ Building on Windows (Visual Studio)
|
|||
|
||||
3. Generate the Visual studio project by opening the Visual Studio cmd prompt:
|
||||
|
||||
```bash
|
||||
cd <path to src>
|
||||
md build
|
||||
cd build
|
||||
cmake -G "Visual Studio 10" ..
|
||||
```
|
||||
|
||||
(NOTE: There is also a cmake-gui available on Windows if you prefer that)
|
||||
(**NOTE**: There is also a cmake-gui available on Windows if you prefer that)
|
||||
|
||||
4. Now you should have a generated Visual Studio Solution in your
|
||||
<path to src>/build directory, which can be used to build.
|
||||
`<path to src>/build` directory, which can be used to build.
|
||||
|
||||
Setting compile options
|
||||
-----------------------
|
||||
|
@ -129,7 +143,7 @@ Unix GUI
|
|||
--------
|
||||
If you have a curses enabled build you simply type:
|
||||
(not all packages include this, my debian install does not for example).
|
||||
|
||||
|
||||
ccmake
|
||||
|
||||
Windows GUI
|
||||
|
@ -145,17 +159,19 @@ http://www.yassl.com/yaSSL/Products-cyassl.html
|
|||
It contains a OpenSSL compatability layer which makes it possible to pretty
|
||||
much link to it instead of OpenSSL, giving a much smaller footprint.
|
||||
|
||||
NOTE: cyassl needs to be compiled using the --enable-opensslextra flag for
|
||||
**NOTE**: cyassl needs to be compiled using the `--enable-opensslextra` flag for
|
||||
this to work.
|
||||
|
||||
Compiling libwebsockets with CyaSSL
|
||||
-----------------------------------
|
||||
|
||||
```bash
|
||||
cmake .. -DLWS_USE_CYASSL=1 \
|
||||
-DLWS_CYASSL_INCLUDE_DIRS=/path/to/cyassl \
|
||||
-DLWS_CYASSL_LIB=/path/to/cyassl/cyassl.a ..
|
||||
```
|
||||
|
||||
NOTE: On windows use the .lib file extension for LWS_CYASSL_LIB instead.
|
||||
**NOTE**: On windows use the .lib file extension for `LWS_CYASSL_LIB` instead.
|
||||
|
||||
|
||||
Reproducing HTTP2.0 tests
|
||||
|
@ -165,41 +181,48 @@ You must have built and be running lws against a version of openssl that has
|
|||
ALPN / NPN. Most distros still have older versions. You'll know it's right by
|
||||
seeing
|
||||
|
||||
```bash
|
||||
lwsts[4752]: Compiled with OpenSSL support
|
||||
lwsts[4752]: Using SSL mode
|
||||
lwsts[4752]: HTTP2 / ALPN enabled
|
||||
```
|
||||
|
||||
at lws startup.
|
||||
|
||||
For non-SSL HTTP2.0 upgrade
|
||||
|
||||
nghttp -nvasu http://localhost:7681/test.htm
|
||||
```bash
|
||||
$ nghttp -nvasu http://localhost:7681/test.htm
|
||||
```
|
||||
|
||||
For SSL / ALPN HTTP2.0 upgrade
|
||||
|
||||
nghttp -nvas https://localhost:7681/test.html
|
||||
|
||||
```
|
||||
$ nghttp -nvas https://localhost:7681/test.html
|
||||
```
|
||||
|
||||
Cross compiling
|
||||
---------------
|
||||
To enable cross compiling libwebsockets using CMake you need to create
|
||||
To enable cross compiling **libwebsockets** using CMake you need to create
|
||||
a "Toolchain file" that you supply to CMake when generating your build files.
|
||||
CMake will then use the cross compilers and build paths specified in this file
|
||||
to look for dependencies and such.
|
||||
|
||||
Libwebsockets includes an example toolchain file cross-arm-linux-gnueabihf.cmake
|
||||
**Libwebsockets** includes an example toolchain file [cross-arm-linux-gnueabihf.cmake](cross-arm-linux-gnueabihf.cmake)
|
||||
you can use as a starting point.
|
||||
|
||||
The commandline to configure for cross with this would look like
|
||||
|
||||
cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr \
|
||||
```bash
|
||||
$ cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr \
|
||||
-DCMAKE_TOOLCHAIN_FILE=../cross-arm-linux-gnueabihf.cmake \
|
||||
-DWITHOUT_EXTENSIONS=1 -DWITH_SSL=0
|
||||
```
|
||||
|
||||
The example shows how to build with no external cross lib dependencies, you
|
||||
need to proide the cross libraries otherwise.
|
||||
need to provide the cross libraries otherwise.
|
||||
|
||||
NOTE: start from an EMPTY build directory if you had a non-cross build in there
|
||||
**NOTE**: start from an EMPTY build directory if you had a non-cross build in there
|
||||
before the settings will be cached and your changes ignored.
|
||||
|
||||
Additional information on cross compilation with CMake:
|
||||
|
@ -215,13 +238,15 @@ server, built on ARM Cortex-A9:
|
|||
|
||||
Update at 8dac94d (2013-02-18)
|
||||
|
||||
./configure --without-client --without-extensions --disable-debug --without-daemonize
|
||||
```bash
|
||||
$ ./configure --without-client --without-extensions --disable-debug --without-daemonize
|
||||
|
||||
Context Creation, 1024 fd limit[2]: 16720 (includes 12 bytes per fd)
|
||||
Per-connection [3]: 72 bytes, +1328 during headers
|
||||
|
||||
.text .rodata .data .bss
|
||||
11512 2784 288 4
|
||||
```
|
||||
|
||||
This shows the impact of the major configuration with/without options at
|
||||
13ba5bbc633ea962d46d using Ubuntu ARM on a PandaBoard ES.
|
||||
|
@ -231,25 +256,24 @@ additional dynamic allocations via malloc. These are a bit old now but give
|
|||
the right idea for relative "expense" of features.
|
||||
|
||||
Static allocations, ARM9
|
||||
.text .rodata .data .bss
|
||||
All (no without) 35024 9940 336 4104
|
||||
without client 25684 7144 336 4104
|
||||
without client, exts 21652 6288 288 4104
|
||||
without client, exts, debug[1] 19756 3768 288 4104
|
||||
without server 30304 8160 336 4104
|
||||
without server, exts 25382 7204 288 4104
|
||||
without server, exts, debug[1] 23712 4256 288 4104
|
||||
|
||||
[1] --disable-debug only removes messages below lwsl_notice. Since that is
|
||||
the default logging level the impact is not noticable, error, warn and notice
|
||||
| | .text | .rodata | .data | .bss |
|
||||
|--------------------------------|---------|---------|-------|------|
|
||||
| All (no without) | 35024 | 9940 | 336 | 4104 |
|
||||
| without client | 25684 | 7144 | 336 | 4104 |
|
||||
| without client, exts | 21652 | 6288 | 288 | 4104 |
|
||||
| without client, exts, debug[1] | 19756 | 3768 | 288 | 4104 |
|
||||
| without server | 30304 | 8160 | 336 | 4104 |
|
||||
| without server, exts | 25382 | 7204 | 288 | 4104 |
|
||||
| without server, exts, debug[1] | 23712 | 4256 | 288 | 4104 |
|
||||
|
||||
[1] `--disable-debug` only removes messages below `lwsl_notice`. Since that is
|
||||
the default logging level the impact is not noticeable, error, warn and notice
|
||||
logs are all still there.
|
||||
|
||||
[2] 1024 fd per process is the default limit (set by ulimit) in at least Fedora
|
||||
[2] `1024` fd per process is the default limit (set by ulimit) in at least Fedora
|
||||
and Ubuntu. You can make significant savings tailoring this to actual expected
|
||||
peak fds, ie, at a limit of 20, context creation allocation reduces to 4432 +
|
||||
240 = 4672)
|
||||
peak fds, ie, at a limit of `20`, context creation allocation reduces to `4432 +
|
||||
240 = 4672`)
|
||||
|
||||
[3] known header content is freed after connection establishment
|
||||
|
||||
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
Daemonization
|
||||
-------------
|
||||
|
||||
There's a helper api lws_daemonize built by default that does everything you
|
||||
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.
|
||||
|
@ -22,19 +22,19 @@ 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.
|
||||
**libwebsockets** will adapt accordingly.
|
||||
|
||||
|
||||
Libwebsockets is singlethreaded
|
||||
-------------------------------
|
||||
|
||||
Directly performing websocket actions from other threads is not allowed.
|
||||
Aside from the internal data being inconsistent in forked() processes,
|
||||
the scope of a wsi (struct websocket) can end at any time during service
|
||||
with the socket closing and the wsi freed.
|
||||
Aside from the internal data being inconsistent in `forked()` processes,
|
||||
the scope of a `wsi` (`struct websocket`) can end at any time during service
|
||||
with the socket closing and the `wsi` freed.
|
||||
|
||||
Websocket write activities should only take place in the
|
||||
"LWS_CALLBACK_SERVER_WRITEABLE" callback as described below.
|
||||
`LWS_CALLBACK_SERVER_WRITEABLE` callback as described below.
|
||||
|
||||
Only live connections appear in the user callbacks, so this removes any
|
||||
possibility of trying to used closed and freed wsis.
|
||||
|
@ -49,14 +49,14 @@ Only send data when socket writeable
|
|||
------------------------------------
|
||||
|
||||
You should only send data on a websocket connection from the user callback
|
||||
"LWS_CALLBACK_SERVER_WRITEABLE" (or "LWS_CALLBACK_CLIENT_WRITEABLE" for
|
||||
`LWS_CALLBACK_SERVER_WRITEABLE` (or `LWS_CALLBACK_CLIENT_WRITEABLE` for
|
||||
clients).
|
||||
|
||||
If you want to send something, do not just send it but request a callback
|
||||
when the socket is writeable using
|
||||
|
||||
- libwebsocket_callback_on_writable(context, wsi) for a specific wsi, or
|
||||
- libwebsocket_callback_on_writable_all_protocol(protocol) for all connections
|
||||
- `libwebsocket_callback_on_writable(context, wsi)`` for a specific `wsi`, or
|
||||
- `libwebsocket_callback_on_writable_all_protocol(protocol)` for all connections
|
||||
using that protocol to get a callback when next writeable.
|
||||
|
||||
Usually you will get called back immediately next time around the service
|
||||
|
@ -70,30 +70,30 @@ See the test server code for an example of how to do this.
|
|||
Do not rely on only your own WRITEABLE requests appearing
|
||||
---------------------------------------------------------
|
||||
|
||||
Libwebsockets may generate additional LWS_CALLBACK_CLIENT_WRITEABLE events
|
||||
Libwebsockets may generate additional `LWS_CALLBACK_CLIENT_WRITEABLE` events
|
||||
if it met network conditions where it had to buffer your send data internally.
|
||||
|
||||
So your code for LWS_CALLBACK_CLIENT_WRITEABLE needs to own the decision
|
||||
So your code for `LWS_CALLBACK_CLIENT_WRITEABLE` needs to own the decision
|
||||
about what to send, it can't assume that just because the writeable callback
|
||||
came it really is time to send something.
|
||||
|
||||
It's quite possible you get an 'extra' writeable callback at any time and
|
||||
just need to return 0 and wait for the expected callback later.
|
||||
just need to `return 0` and wait for the expected callback later.
|
||||
|
||||
|
||||
Closing connections from the user side
|
||||
--------------------------------------
|
||||
|
||||
When you want to close a connection, you do it by returning -1 from a
|
||||
When you want to close a connection, you do it by returning `-1` from a
|
||||
callback for that connection.
|
||||
|
||||
You can provoke a callback by calling libwebsocket_callback_on_writable on
|
||||
You can provoke a callback by calling `libwebsocket_callback_on_writable` on
|
||||
the wsi, then notice in the callback you want to close it and just return -1.
|
||||
But usually, the decision to close is made in a callback already and returning
|
||||
-1 is simple.
|
||||
|
||||
If the socket knows the connection is dead, because the peer closed or there
|
||||
was an affirmitive network error like a FIN coming, then libwebsockets will
|
||||
was an affirmitive network error like a FIN coming, then **libwebsockets** will
|
||||
take care of closing the connection automatically.
|
||||
|
||||
If you have a silently dead connection, it's possible to enter a state where
|
||||
|
@ -106,10 +106,11 @@ 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
|
||||
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;
|
||||
|
@ -128,29 +129,30 @@ to gather the whole contents of a message, eg:
|
|||
client->AppendMessageFragment(in, len, remaining);
|
||||
}
|
||||
break;
|
||||
```
|
||||
|
||||
The test app llibwebsockets-test-fraggle sources also show how to
|
||||
The test app libwebsockets-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
|
||||
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.
|
||||
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
|
||||
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(...)
|
||||
- `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.
|
||||
|
@ -159,22 +161,22 @@ whereas info is ignored by default.
|
|||
External Polling Loop support
|
||||
-----------------------------
|
||||
|
||||
libwebsockets maintains an internal poll() array for all of its
|
||||
**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
|
||||
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
|
||||
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.
|
||||
|
||||
You can pass all pollfds that need service to libwebsocket_service_fd(), even
|
||||
if the socket or file does not belong to libwebsockets it is safe.
|
||||
You can pass all pollfds that need service to `libwebsocket_service_fd()`, even
|
||||
if the socket or file does not belong to **libwebsockets** it is safe.
|
||||
|
||||
If libwebsocket handled it, it zeros the pollfd revents field before returning.
|
||||
So you can let libwebsockets try and if pollfd->revents is nonzero on return,
|
||||
If **libwebsocket** handled it, it zeros the pollfd `revents` field before returning.
|
||||
So you can let **libwebsockets** try and if `pollfd->revents` is nonzero on return,
|
||||
you know it needs handling by your code.
|
||||
|
||||
|
||||
|
@ -184,13 +186,17 @@ Using with in c++ apps
|
|||
The library is ready for use by C++ apps. You can get started quickly by
|
||||
copying the test server
|
||||
|
||||
```bash
|
||||
$ cp test-server/test-server.c test.cpp
|
||||
```
|
||||
|
||||
and building it in C++ like this
|
||||
|
||||
```bash
|
||||
$ g++ -DINSTALL_DATADIR=\"/usr/share\" -ocpptest test.cpp -lwebsockets
|
||||
```
|
||||
|
||||
INSTALL_DATADIR is only needed because the test server uses it as shipped, if
|
||||
`INSTALL_DATADIR` is only needed because the test server uses it as shipped, if
|
||||
you remove the references to it in your app you don't need to define it on
|
||||
the g++ line either.
|
||||
|
||||
|
@ -198,11 +204,11 @@ the g++ line either.
|
|||
Availability of header information
|
||||
----------------------------------
|
||||
|
||||
From v1.2 of the library onwards, the HTTP header content is free()d as soon
|
||||
From v1.2 of the library onwards, the HTTP header content is `free()`d as soon
|
||||
as the websocket connection is established. For websocket servers, you can
|
||||
copy interesting headers by handling LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION
|
||||
copy interesting headers by handling `LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION`
|
||||
callback, for clients there's a new callback just for this purpose
|
||||
LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH.
|
||||
`LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH`.
|
||||
|
||||
|
||||
TCP Keepalive
|
||||
|
@ -214,7 +220,7 @@ by default TCP will just not report anything and you will never get any more
|
|||
incoming data or sign the link is dead until you try to send.
|
||||
|
||||
To deal with getting a notification of that situation, you can choose to
|
||||
enable TCP keepalives on all libwebsockets sockets, when you create the
|
||||
enable TCP keepalives on all **libwebsockets** sockets, when you create the
|
||||
context.
|
||||
|
||||
To enable keepalive, set the ka_time member of the context creation parameter
|
||||
|
@ -223,45 +229,44 @@ also fill ka_probes and ka_interval in that case.
|
|||
|
||||
With keepalive enabled, the TCP layer will send control packets that should
|
||||
stimulate a response from the peer without affecting link traffic. If the
|
||||
response is not coming, the socket will announce an error at poll() forcing
|
||||
response is not coming, the socket will announce an error at `poll()` forcing
|
||||
a close.
|
||||
|
||||
Note that BSDs don't support keepalive time / probes / inteveral per-socket
|
||||
Note that BSDs don't support keepalive time / probes / interval per-socket
|
||||
like Linux does. On those systems you can enable keepalive by a nonzero
|
||||
value in ka_time, but the systemwide kernel settings for the time / probes/
|
||||
interval are used, regardless of what nonzero value is in ka_time.
|
||||
value in `ka_time`, but the systemwide kernel settings for the time / probes/
|
||||
interval are used, regardless of what nonzero value is in `ka_time`.
|
||||
|
||||
Optimizing SSL connections
|
||||
--------------------------
|
||||
|
||||
There's a member ssl_cipher_list in the lws_context_creation_info struct
|
||||
There's a member `ssl_cipher_list` in the `lws_context_creation_info` struct
|
||||
which allows the user code to restrict the possible cipher selection at
|
||||
context-creation time.
|
||||
|
||||
You might want to look into that to stop the ssl peers selecting a ciher which
|
||||
You might want to look into that to stop the ssl peers selecting a cipher which
|
||||
is too computationally expensive. To use it, point it to a string like
|
||||
|
||||
"RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
|
||||
`"RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"`
|
||||
|
||||
if left NULL, then the "DEFAULT" set of ciphers are all possible to select.
|
||||
if left `NULL`, then the "DEFAULT" set of ciphers are all possible to select.
|
||||
|
||||
|
||||
Async nature of client connections
|
||||
----------------------------------
|
||||
|
||||
When you call libwebsocket_client_connect(..) and get a wsi back, it does not
|
||||
When you call `libwebsocket_client_connect(..)` and get a `wsi` back, it does not
|
||||
mean your connection is active. It just mean it started trying to connect.
|
||||
|
||||
Your client connection is actually active only when you receive
|
||||
LWS_CALLBACK_CLIENT_ESTABLISHED for it.
|
||||
`LWS_CALLBACK_CLIENT_ESTABLISHED` for it.
|
||||
|
||||
There's a 5 second timeout for the connection, and it may give up or die for
|
||||
other reasons, if any of that happens you'll get a
|
||||
LWS_CALLBACK_CLIENT_CONNECTION_ERROR callback on protocol 0 instead for the
|
||||
wsi.
|
||||
`LWS_CALLBACK_CLIENT_CONNECTION_ERROR` callback on protocol 0 instead for the
|
||||
`wsi`.
|
||||
|
||||
After attempting the connection and getting back a non-NULL wsi you should
|
||||
loop calling libwebsocket_service() until one of the above callbacks occurs.
|
||||
|
||||
As usual, see test-client.c for example code.
|
||||
After attempting the connection and getting back a non-`NULL` `wsi` you should
|
||||
loop calling `libwebsocket_service()` until one of the above callbacks occurs.
|
||||
|
||||
As usual, see [test-client.c](test-server/test-client.c) for example code.
|
|
@ -1,3 +1,11 @@
|
|||
[](https://travis-ci.org/warmcat/libwebsockets)
|
||||
[](https://ci.appveyor.com/project/warmcat/libwebsockets)
|
||||
[](https://scan.coverity.com/projects/2506)
|
||||
|
||||
|
||||
libwebsockets
|
||||
-------------
|
||||
|
||||
This is the libwebsockets C library for lightweight websocket clients and
|
||||
servers. For support, visit
|
||||
|
||||
|
@ -9,17 +17,18 @@ and consider joining the project mailing list at
|
|||
|
||||
You can get the latest version of the library from git
|
||||
|
||||
http://git.libwebsockets.org
|
||||
https://github.com/warmcat/libwebsockets
|
||||
- http://git.libwebsockets.org
|
||||
- https://github.com/warmcat/libwebsockets
|
||||
|
||||
for more information:
|
||||
|
||||
README.build - information on building the library
|
||||
README.coding - information for writing code using the library
|
||||
README.test-apps - information about the test apps built with the library
|
||||
- [README.build.md](README.build.md) - information on building the library
|
||||
- [README.coding.md](README.coding.md) - information for writing code using the library
|
||||
- [README.test-apps.md](README.test-apps.md) - information about the test apps built with the library
|
||||
|
||||
After 1.3, tags will be signed using a key corresponding to this public key
|
||||
After libwebsockets 1.3, tags will be signed using a key corresponding to this public key
|
||||
|
||||
```
|
||||
-----BEGIN PGP PUBLIC KEY BLOCK-----
|
||||
Version: GnuPG v1
|
||||
|
||||
|
@ -72,3 +81,4 @@ cX6tdPyGz3o0aywfJ9dcN6izleSV1gYmXmIoS0cQyezVqTUkT8C12zeRB7mtWsDa
|
|||
+AWJGq/WfB7N6pPh8S/XMW4e6ptuUodjiA==
|
||||
=HV8t
|
||||
-----END PGP PUBLIC KEY BLOCK-----
|
||||
```
|
|
@ -1,17 +1,17 @@
|
|||
Testing server with a browser
|
||||
-----------------------------
|
||||
|
||||
If you run libwebsockets-test-server and point your browser
|
||||
If you run [libwebsockets-test-server](test-server/test-server.c) 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
|
||||
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.
|
||||
what is logged using `-d <log level>`, see later.
|
||||
|
||||
|
||||
Running test server as a Daemon
|
||||
|
@ -19,21 +19,23 @@ 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.
|
||||
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
|
||||
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`
|
||||
```bash
|
||||
$ 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
|
||||
it was already running.
|
||||
|
||||
|
||||
Using SSL on the server side
|
||||
|
@ -41,7 +43,9 @@ Using SSL on the server side
|
|||
|
||||
To test it using SSL/WSS, just run the test server with
|
||||
|
||||
```bash
|
||||
$ libwebsockets-test-server --ssl
|
||||
```
|
||||
|
||||
and use the URL
|
||||
|
||||
|
@ -54,7 +58,7 @@ 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
|
||||
[test-server.c](test-server/test-server.c) is all that is needed to use libwebsockets for
|
||||
serving both the script html over http and websockets.
|
||||
|
||||
|
||||
|
@ -64,7 +68,9 @@ 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.
|
||||
|
||||
```bash
|
||||
$ 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
|
||||
|
@ -76,22 +82,28 @@ same time you will be able to see the circles being drawn.
|
|||
Testing simple echo
|
||||
-------------------
|
||||
|
||||
You can test against echo.websockets.org as a sanity test like
|
||||
this (the client connects to port 80 by default):
|
||||
You can test against `echo.websockets.org` as a sanity test like
|
||||
this (the client connects to port `80` by default):
|
||||
|
||||
```bash
|
||||
$ libwebsockets-test-echo --client echo.websocket.org
|
||||
```
|
||||
|
||||
This echo test is of limited use though because it doesn't
|
||||
negotiate any protocol. You can run the same test app as a
|
||||
local server, by default on localhost:7681
|
||||
|
||||
```bash
|
||||
$ libwebsockets-test-echo
|
||||
```
|
||||
|
||||
and do the echo test against the local echo server
|
||||
|
||||
```bash
|
||||
$ libwebsockets-test-echo --client localhost --port 7681
|
||||
```
|
||||
|
||||
If you add the --ssl switch to both the client and server, you can also test
|
||||
If you add the `--ssl` switch to both the client and server, you can also test
|
||||
with an encrypted link.
|
||||
|
||||
|
||||
|
@ -100,11 +112,13 @@ Testing SSL on the client side
|
|||
|
||||
To test SSL/WSS client action, just run the client test with
|
||||
|
||||
```bash
|
||||
$ 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
|
||||
`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.
|
||||
|
||||
|
||||
|
@ -115,7 +129,8 @@ 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
|
||||
```bash
|
||||
$ 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
|
||||
|
@ -131,20 +146,21 @@ Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
|
|||
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
|
||||
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.
|
||||
`-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
|
||||
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
|
||||
|
@ -152,7 +168,7 @@ 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
|
||||
by `--protocol=protocolname`
|
||||
|
||||
|
||||
Fraggle test app
|
||||
|
@ -160,6 +176,7 @@ Fraggle test app
|
|||
|
||||
By default it runs in server mode
|
||||
|
||||
```bash
|
||||
$ libwebsockets-test-fraggle
|
||||
libwebsockets test fraggle
|
||||
(C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
|
||||
|
@ -172,11 +189,13 @@ 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:
|
||||
give the `-c` switch and the server address at least:
|
||||
|
||||
$ libwebsockets-test-fraggle -c localhost
|
||||
```bash
|
||||
$ libwebsockets-test-fraggle -c localhost
|
||||
libwebsockets test fraggle
|
||||
(C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
|
||||
Client mode
|
||||
|
@ -189,6 +208,7 @@ 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
|
||||
|
@ -203,13 +223,15 @@ proxy support
|
|||
-------------
|
||||
|
||||
The http_proxy environment variable is respected by the client
|
||||
connection code for both ws:// and wss://. It doesn't support
|
||||
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
|
||||
```bash
|
||||
$ export http_proxy=myproxy.com:3128
|
||||
$ libwebsockets-test-client someserver.com
|
||||
```
|
||||
|
||||
|
||||
debug logging
|
||||
|
@ -217,27 +239,27 @@ 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.
|
||||
Again by default other logging is compiled 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
|
||||
`--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
|
||||
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
|
||||
512 LATENCY
|
||||
- 1 ERR
|
||||
- 2 WARN
|
||||
- 4 NOTICE
|
||||
- 8 INFO
|
||||
- 16 DEBUG
|
||||
- 32 PARSER
|
||||
- 64 HEADER
|
||||
- 128 EXTENSION
|
||||
- 256 CLIENT
|
||||
- 512 LATENCY
|
||||
|
||||
|
||||
Websocket version supported
|
||||
|
@ -250,13 +272,13 @@ version 13.
|
|||
Latency Tracking
|
||||
----------------
|
||||
|
||||
Since libwebsockets runs using poll() and a single threaded approach, any
|
||||
Since libwebsockets runs using `poll()` and a single threaded approach, any
|
||||
unexpected latency coming from system calls would be bad news. There's now
|
||||
a latency tracking scheme that can be built in with --with-latency at
|
||||
a latency tracking scheme that can be built in with `--with-latency` at
|
||||
configure-time, logging the time taken for system calls to complete and if
|
||||
the whole action did complete that time or was deferred.
|
||||
|
||||
You can see the detailed data by enabling logging level 512 (eg, -d 519 on
|
||||
You can see the detailed data by enabling logging level 512 (eg, `-d 519` on
|
||||
the test server to see that and the usual logs), however even without that
|
||||
the "worst" latency is kept and reported to the logs with NOTICE severity
|
||||
when the context is destroyed.
|
||||
|
@ -269,4 +291,3 @@ in the logging is the time taken by this particular attempt. High figures
|
|||
here may indicate a problem, or if you system is loaded with another app at
|
||||
that time, such as the browser, it may simply indicate the OS gave preferential
|
||||
treatment to the other app during that call.
|
||||
|
Loading…
Add table
Reference in a new issue