67
67
See the test server code for an example of how to do this.
70
Do not rely on only your own WRITEABLE requests appearing
71
---------------------------------------------------------
73
Libwebsockets may generate additional LWS_CALLBACK_CLIENT_WRITEABLE events
74
if it met network conditions where it had to buffer your send data internally.
76
So your code for LWS_CALLBACK_CLIENT_WRITEABLE needs to own the decision
77
about what to send, it can't assume that just because the writeable callback
78
came it really is time to send something.
80
It's quite possible you get an 'extra' writeable callback at any time and
81
just need to return 0 and wait for the expected callback later.
84
Closing connections from the user side
85
--------------------------------------
87
When you want to close a connection, you do it by returning -1 from a
88
callback for that connection.
90
You can provoke a callback by calling libwebsocket_callback_on_writable on
91
the wsi, then notice in the callback you want to close it and just return -1.
92
But usually, the decision to close is made in a callback already and returning
95
If the socket knows the connection is dead, because the peer closed or there
96
was an affirmitive network error like a FIN coming, then libwebsockets will
97
take care of closing the connection automatically.
99
If you have a silently dead connection, it's possible to enter a state where
100
the send pipe on the connection is choked but no ack will ever come, so the
101
dead connection will never become writeable. To cover that, you can use TCP
102
keepalives (see later in this document)
70
105
Fragmented messages
71
106
-------------------
135
170
appear in the callback for protocol 0 and allow interface code to
136
171
manage socket descriptors in other poll loops.
173
You can pass all pollfds that need service to libwebsocket_service_fd(), even
174
if the socket or file does not belong to libwebsockets it is safe.
176
If libwebsocket handled it, it zeros the pollfd revents field before returning.
177
So you can let libwebsockets try and if pollfd->revents is nonzero on return,
178
you know it needs handling by your code.
139
181
Using with in c++ apps
140
182
----------------------
188
230
like Linux does. On those systems you can enable keepalive by a nonzero
189
231
value in ka_time, but the systemwide kernel settings for the time / probes/
190
232
interval are used, regardless of what nonzero value is in ka_time.
234
Optimizing SSL connections
235
--------------------------
237
There's a member ssl_cipher_list in the lws_context_creation_info struct
238
which allows the user code to restrict the possible cipher selection at
239
context-creation time.
241
You might want to look into that to stop the ssl peers selecting a ciher which
242
is too computationally expensive. To use it, point it to a string like
244
"RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
246
if left NULL, then the "DEFAULT" set of ciphers are all possible to select.
249
Async nature of client connections
250
----------------------------------
252
When you call libwebsocket_client_connect(..) and get a wsi back, it does not
253
mean your connection is active. It just mean it started trying to connect.
255
Your client connection is actually active only when you receive
256
LWS_CALLBACK_CLIENT_ESTABLISHED for it.
258
There's a 5 second timeout for the connection, and it may give up or die for
259
other reasons, if any of that happens you'll get a
260
LWS_CALLBACK_CLIENT_CONNECTION_ERROR callback on protocol 0 instead for the
263
After attempting the connection and getting back a non-NULL wsi you should
264
loop calling libwebsocket_service() until one of the above callbacks occurs.
266
As usual, see test-client.c for example code.