<li><ahref="#http-server-api">HTTP server API</a></li>
</ul>
</div></div>
<divclass="col-md-9"role="main">
<h1id="examples">Examples</h1>
<p>The <ahref="https://github.com/machinezone/IXWebSocket/tree/master/ws"><em>ws</em></a> folder countains many interactive programs for chat, <ahref="https://github.com/machinezone/IXWebSocket/blob/master/ws/ws_send.cpp">file transfers</a>, <ahref="https://github.com/machinezone/IXWebSocket/blob/master/ws/ws_http_client.cpp">curl like</a> http clients, demonstrating client and server usage.</p>
<h2id="windows-note">Windows note</h2>
<p>To use the network system on Windows, you need to initialize it once with <em>WSAStartup()</em> and clean it up with <em>WSACleanup()</em>. We have helpers for that which you can use, see below. This init would typically take place in your main function.</p>
<p><code>websocket.send("foo")</code> will send a message.</p>
<p>If the connection was closed and sending failed, the return value will be set to false.</p>
<h3id="readystate">ReadyState</h3>
<p><code>getReadyState()</code> returns the state of the connection. There are 4 possible states.</p>
<ol>
<li>ReadyState::Connecting - The connection is not yet open.</li>
<li>ReadyState::Open - The connection is open and ready to communicate.</li>
<li>ReadyState::Closing - The connection is in the process of closing.</li>
<li>ReadyState::Closed - The connection is closed or could not be opened.</li>
</ol>
<h3id="open-and-close-notifications">Open and Close notifications</h3>
<p>The onMessage event will be fired when the connection is opened or closed. This is similar to the <ahref="https://developer.mozilla.org/en-US/docs/Web/API/WebSocket">Javascript browser API</a>, which has <code>open</code> and <code>close</code> events notification that can be registered with the browser <code>addEventListener</code>.</p>
<p>A message will be fired when there is an error with the connection. The message type will be <code>ix::WebSocketMessageType::Error</code>. Multiple fields will be available on the event to describe the error.</p>
if (msg->type == ix::WebSocketMessageType::Error)
{
std::stringstream ss;
ss <<"Error: "<< msg->errorInfo.reason << std::endl;
ss <<"#retries: "<< msg->eventInfo.retries << std::endl;
ss <<"Wait time(ms): "<< msg->eventInfo.wait_time << std::endl;
ss <<"HTTP Status: "<< msg->eventInfo.http_status << std::endl;
std::cout << ss.str() << std::endl;
}
}
);
</code></pre>
<h3id="start-stop">start, stop</h3>
<ol>
<li><code>websocket.start()</code> connect to the remote server and starts the message receiving background thread.</li>
<li><code>websocket.stop()</code> disconnect from the remote server and closes the background thread.</li>
</ol>
<h3id="configuring-the-remote-url">Configuring the remote url</h3>
<p>The url can be set and queried after a websocket object has been created. You will have to call <code>stop</code> and <code>start</code> if you want to disconnect and connect to that new url.</p>
<p>Ping/pong messages are used to implement keep-alive. 2 message types exists to identify ping and pong messages. Note that when a ping message is received, a pong is instantly send back as requested by the WebSocket spec.</p>
<p>Automatic reconnection kicks in when the connection is disconnected without the user consent. This feature is on by default and can be turned off.</p>
<pre><code>webSocket.enableAutomaticReconnection(); // turn on
webSocket.disableAutomaticReconnection(); // turn off
bool enabled = webSocket.isAutomaticReconnectionEnabled(); // query state
</code></pre>
<p>The technique to calculate wait time is called <ahref="https://docs.aws.amazon.com/general/latest/gr/api-retries.html">exponential
backoff</a>. Here
are the default waiting times between attempts (from connecting with <code>ws connect ws://foo.com</code>)</p>
<pre><code>> Connection error: Got bad status connecting to foo.com, status: 301, HTTP Status line: HTTP/1.1 301 Moved Permanently
#retries: 1
Wait time(ms): 100
#retries: 2
Wait time(ms): 200
#retries: 3
Wait time(ms): 400
#retries: 4
Wait time(ms): 800
#retries: 5
Wait time(ms): 1600
#retries: 6
Wait time(ms): 3200
#retries: 7
Wait time(ms): 6400
#retries: 8
Wait time(ms): 10000
</code></pre>
<p>The waiting time is capped by default at 10s between 2 attempts, but that value can be changed and queried.</p>
<p>Specifying <code>certFile</code> and <code>keyFile</code> configures the certificate that will be used to communicate with TLS peers.</p>
<p>On a client, this is only necessary for connecting to servers that require a client certificate.</p>
<p>On a server, this is necessary for TLS support.</p>
<p>Specifying <code>caFile</code> configures the trusted roots bundle file (in PEM format) that will be used to verify peer certificates.
- The special value of <code>SYSTEM</code> (the default) indicates that the system-configured trust bundle should be used; this is generally what you want when connecting to any publicly exposed API/server.
- The special value of <code>NONE</code> can be used to disable peer verification; this is only recommended to rule out certificate verification when testing connectivity.</p>
<p>For a client, specifying <code>caFile</code> can be used if connecting to a server that uses a self-signed cert, or when using a custom CA in an internal environment.</p>
<p>For a server, specifying <code>caFile</code> implies that:
1. You require clients to present a certificate
1. It must be signed by one of the trusted roots in the file</p>
<p>If you want to handle how requests are processed, implement the setOnConnectionCallback callback, which takes an HttpRequestPtr as input, and returns an HttpResponsePtr. You can look at HttpServer::setDefaultConnectionCallback for a slightly more advanced callback example.</p>
