Debian Codegraph @

LspCpp/third_party/ixwebsocket/docs/index.md

raw
1 ## Hello world
2
3 IXWebSocket is a C++ library for WebSocket client and server development. It has minimal dependencies (no boost), is very simple to use and support everything you'll likely need for websocket dev (SSL, deflate compression, compiles on most platforms, etc...). HTTP client and server code is also available, but it hasn't received as much testing.
4
5 It is been used on big mobile video game titles sending and receiving tons of messages since 2017 (iOS and Android). It was tested on macOS, iOS, Linux, Android, Windows and FreeBSD. Note that the MinGW compiler is not supported at this point. Two important design goals are simplicity and correctness.
6
7 A bad security bug affecting users compiling with SSL enabled and OpenSSL as the backend was just fixed in newly released version 11.0.0. Please upgrade ! (more details in the [https://github.com/machinezone/IXWebSocket/pull/250](PR).
8
9 ```cpp
10 /*
11 * main.cpp
12 * Author: Benjamin Sergeant
13 * Copyright (c) 2020 Machine Zone, Inc. All rights reserved.
14 *
15 * Super simple standalone example. See ws folder, unittest and doc/usage.md for more.
16 *
17 * On macOS
18 * $ mkdir -p build ; (cd build ; cmake -DUSE_TLS=1 .. ; make -j ; make install)
19 * $ clang++ --std=c++11 --stdlib=libc++ main.cpp -lixwebsocket -lz -framework Security -framework Foundation
20 * $ ./a.out
21 *
22 * Or use cmake -DBUILD_DEMO=ON option for other platforms
23 */
24
25 #include <ixwebsocket/IXNetSystem.h>
26 #include <ixwebsocket/IXWebSocket.h>
27 #include <ixwebsocket/IXUserAgent.h>
28 #include <iostream>
29
30 int main()
31 {
32 // Required on Windows
33 ix::initNetSystem();
34
35 // Our websocket object
36 ix::WebSocket webSocket;
37
38 // Connect to a server with encryption
39 // See https://machinezone.github.io/IXWebSocket/usage/#tls-support-and-configuration
40 std::string url("wss://echo.websocket.org");
41 webSocket.setUrl(url);
42
43 std::cout << "Connecting to " << url << "..." << std::endl;
44
45 // Setup a callback to be fired (in a background thread, watch out for race conditions !)
46 // when a message or an event (open, close, error) is received
47 webSocket.setOnMessageCallback([](const ix::WebSocketMessagePtr& msg)
48 {
49 if (msg->type == ix::WebSocketMessageType::Message)
50 {
51 std::cout << "received message: " << msg->str << std::endl;
52 std::cout << "> " << std::flush;
53 }
54 else if (msg->type == ix::WebSocketMessageType::Open)
55 {
56 std::cout << "Connection established" << std::endl;
57 std::cout << "> " << std::flush;
58 }
59 else if (msg->type == ix::WebSocketMessageType::Error)
60 {
61 // Maybe SSL is not configured properly
62 std::cout << "Connection error: " << msg->errorInfo.reason << std::endl;
63 std::cout << "> " << std::flush;
64 }
65 }
66 );
67
68 // Now that our callback is setup, we can start our background thread and receive messages
69 webSocket.start();
70
71 // Send a message to the server (default to TEXT mode)
72 webSocket.send("hello world");
73
74 // Display a prompt
75 std::cout << "> " << std::flush;
76
77 std::string text;
78 // Read text from the console and send messages in text mode.
79 // Exit with Ctrl-D on Unix or Ctrl-Z on Windows.
80 while (std::getline(std::cin, text))
81 {
82 webSocket.send(text);
83 std::cout << "> " << std::flush;
84 }
85
86 return 0;
87 }
88 ```
89
90 Interested? Go read the [docs](https://machinezone.github.io/IXWebSocket/)! If things don't work as expected, please create an issue on GitHub, or even better a pull request if you know how to fix your problem.
91
92 IXWebSocket is actively being developed, check out the [changelog](https://machinezone.github.io/IXWebSocket/CHANGELOG/) to know what's cooking. If you are looking for a real time messaging service (the chat-like 'server' your websocket code will talk to) with many features such as history, backed by Redis, look at [cobra](https://github.com/machinezone/cobra).
93
94 IXWebSocket client code is autobahn compliant beginning with the 6.0.0 version. See the current [test results](https://bsergean.github.io/autobahn/reports/clients/index.html). Some tests are still failing in the server code.
95
96 Starting with the 11.0.8 release, IXWebSocket should be fully C++11 compatible.
97
98 ## Users
99
100 If your company or project is using this library, feel free to open an issue or PR to amend this list.
101
102 - [Machine Zone](https://www.mz.com)
103 - [Tokio](https://gitlab.com/HCInk/tokio), a discord library focused on audio playback with node bindings.
104 - [libDiscordBot](https://github.com/tostc/libDiscordBot/tree/master), an easy to use Discord-bot framework.
105 - [gwebsocket](https://github.com/norrbotten/gwebsocket), a websocket (lua) module for Garry's Mod
106 - [DisCPP](https://github.com/DisCPP/DisCPP), a simple but feature rich Discord API wrapper
107 - [discord.cpp](https://github.com/luccanunes/discord.cpp), a discord library for making bots
108 - [Teleport](http://teleportconnect.com/), Teleport is your own personal remote robot avatar
109
110 ## Alternative libraries
111
112 There are plenty of great websocket libraries out there, which might work for you. Here are a couple of serious ones.
113
114 * [websocketpp](https://github.com/zaphoyd/websocketpp) - C++
115 * [beast](https://github.com/boostorg/beast) - C++
116 * [libwebsockets](https://libwebsockets.org/) - C
117 * [µWebSockets](https://github.com/uNetworking/uWebSockets) - C
118 * [wslay](https://github.com/tatsuhiro-t/wslay) - C
119
120 [uvweb](https://github.com/bsergean/uvweb) is a library written by the IXWebSocket author which is built on top of [uvw](https://github.com/skypjack/uvw), which is a C++ wrapper for [libuv](https://libuv.org/). It has more dependencies and does not support SSL at this point, but it can be used to open multiple connections within a single OS thread thanks to libuv.
121
122 To check the performance of a websocket library, you can look at the [autoroute](https://github.com/bsergean/autoroute) project.
123
124 ## Continuous Integration
125
126 | OS | TLS | Sanitizer | Status |
127 |-------------------|-------------------|-------------------|-------------------|
128 | Linux | OpenSSL | None | [![Build2][1]][0] |
129 | macOS | Secure Transport | Thread Sanitizer | [![Build2][2]][0] |
130 | macOS | OpenSSL | Thread Sanitizer | [![Build2][3]][0] |
131 | macOS | MbedTLS | Thread Sanitizer | [![Build2][4]][0] |
132 | Windows | Disabled | None | [![Build2][5]][0] |
133 | UWP | Disabled | None | [![Build2][6]][0] |
134 | Linux | OpenSSL | Address Sanitizer | [![Build2][7]][0] |
135 | Mingw | Disabled | None | [![Build2][8]][0] |
136
137 * ASAN fails on Linux because of a known problem, we need a
138 * Some tests are disabled on Windows/UWP because of a pathing problem
139 * TLS and ZLIB are disabled on Windows/UWP because enabling make the CI run takes a lot of time, for setting up vcpkg.
140
141 [0]: https://github.com/machinezone/IXWebSocket
142 [1]: https://github.com/machinezone/IXWebSocket/workflows/linux/badge.svg
143 [2]: https://github.com/machinezone/IXWebSocket/workflows/mac_tsan_sectransport/badge.svg
144 [3]: https://github.com/machinezone/IXWebSocket/workflows/mac_tsan_openssl/badge.svg
145 [4]: https://github.com/machinezone/IXWebSocket/workflows/mac_tsan_mbedtls/badge.svg
146 [5]: https://github.com/machinezone/IXWebSocket/workflows/windows/badge.svg
147 [6]: https://github.com/machinezone/IXWebSocket/workflows/uwp/badge.svg
148 [7]: https://github.com/machinezone/IXWebSocket/workflows/linux_asan/badge.svg
149 [8]: https://github.com/machinezone/IXWebSocket/workflows/unittest_windows_gcc/badge.svg