Websocket Client

Overview

This tutorial demonstrates how Mongoose Library can be used to implement a WebSocket client that does the following:

• Initiates a WebSocket connection to the WebSocket echo server
• Sends a WebSocket message to the echo server
• When a response is received, quits

Full source code for this tutorial is at https://github.com/cesanta/mongoose/tree/master/tutorials/websocket/websocket-client

Build and test

In order to test this client implementation, we need a server. We're going to use the one from the WebSocket Server tutorial.

Follow the Build Tools tutorial to setup your development environment. Then start a command prompt / terminal, clone the Mongoose repository, and build the server:

git clone https://github.com/cesanta/mongoose
cd mongoose/tutorials/websocket/websocket-server
make
...
Starting WS listener on ws://localhost:8000/websocket

Now we have a WebSocket echo server up and running on port 8000. Start another terminal, and execute:

cd mongoose/tutorials/websocket/websocket-client
make
...
GOT ECHO REPLY: [hello]
18a7e066 3 mongoose.c:3945:mg_close_con 1 4 closed
18a7e067 3 mongoose.c:4043:mg_mgr_free  All connections closed

That's it! We see that the WebSocket client got a response message and quit.

How it works

A WebSocket client is basically a regular HTTP client that sends an HTTP request with a few special headers that initiate the WebSocket negotiation:

GET /some/uri HTTP/1.1
Host: some.host.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: ....
...

When negotiation is complete, an MG_EV_WS_OPEN event is triggered. Then the connection becomes a full-duplex connection that receives MG_EV_WS_MSG events for every message from its peer.

Mongoose provides the mg_ws_connect() API function that performs WebSocket negotiation under the hood:

In the event handler function, we catch MG_EV_WS_OPEN - that's when we have established a WS connection. There, we send a message to the server:

When a response message arrives, we catch the MG_EV_WS_MSG event, and print a received message:

Mongoose handles receiving fragmented WebSocket messages for you, there is no need to check the F flag.

And this snippet in the event handler function makes our client to exit - on any error, or when any message is received:

Done!

NOTE: this example client does not implement an automatic reconnection functionality. If you require that, take a look at that section in our Error Handling tutorial

TLS support (WSS)

A Secure WebSocket client is an upgraded HTTPS client, a TLS connection is first established, then the HTTPS connection is upgraded to a WSS connection. The example code, as is, builds with our built-in TLS stack, and supports passing an URL and the CA certificate using command line arguments:

Usage: ./example OPTIONS
  -ca PATH  - Path to the CA file, default: 'ca.pem'
  -url URL  - Destination URL, default: 'ws://localhost:8000/websocket'

For more information on developing TLS clients, check the TLS tutorial. You can follow the HTTP Client tutorial for guidance