Building a program with websocketpp

NOTE: this documentation refers to library release 0.3.x

As WebSocket++ is a header only library all that is necessary to include it in your program is to include the WebSocket++ repository directory in your include path or alternatively, install the websocketpp code directory somewhere already in your include path.

Required External Libraries

Your program will need to link to external libraries depending on what your build environment looks like. Below is a table of libraries that may be required along with descriptions of what triggers that requirement.

Library	Required for
boost_system	Builds that use ASIO or build environments without std::error_code
boost_regex	Build environments without std::regex
boost_random	Client role only, build environments without std::random
libcrypto	Required for TLS socket component
libssl	Required for TLS socket component
libz	Required for compression extension support
libpthread	Required on posix for thread support
librt	Required on posix for high resolution timer support (some examples)

Creating a program that uses WebSocket++

WebSocket++ provides several types of objects to use to configure and control the WebSocket functionality within your program. The most important of these is the Endpoint. An endpoint represents one of the two roles within a WebSocket connection, client and server.

WebSocket++ endpoints are created by choosing a role and a config. The role determines what sort of operations the endpoint is capable of performing. The config determines what shared components are used and what the default values are. WebSocket++ includes some default configurations you can use out of the box. Advanced users may create their own config types to tailor endpoint behavior to a specific application. More information about exactly how you can set up your own configuration types: Configuring Endpoints.

Default Roles

Role	Header	Features	Dependencies
websocketpp::server	websocketpp/server.hpp	Listen and process WebSocket connections	C++11 STL or Boost
websocketpp::client	Not included in repository yet	Create outgoing WebSocket connections	C++11 STL or Boost

Default Configs

Config	Header	Features	Dependencies
websocketpp::config::core	websocketpp/config/core.hpp	Low dependency limited feature config with transport based on STL iostreams	C++11 STL
websocketpp::config::asio	websocketpp/config/asio_no_tls.hpp or websocketpp/config/asio.hpp	Medium dependency full featured config with Boost ASIO based transport	C++11 STL or Boost, lib boost_system, pthread
websocketpp::config::asio_tls	websocketpp/config/asio.hpp	Higher dependency full featured config with Boost ASIO based transport and TLS support	C++11 STL or Boost, libboost_system, pthread, libcrypto, libssl

Each combination of role and config will create an endpoint with different interfaces and behaviors. The types described within the config can add new methods to the Endpoint object. Please refer to the documentation for the config that you are using for more details on the interface it exposes through the endpoint.

Using server < config::asio >

For an initial demonstration we will look at how the server role and config::asio combine to create a basic WebSocket server that prints out every message it receives.

First we include the config and role that we intend to use. In this case we are including asio_no_tls.hpp to avoid pulling in TLS related dependencies for this simple example. config/asio.hpp will include both plain and tls configs and the dependencies for both. Additionally, we will define a type that specifies which role and config we will be using.

#include <websocketpp/config/asio_no_tls.hpp>
#include <websocketpp/server.hpp>
typedef websocketpp::server server;

Next we will set up the program itself. Details about what each operation do are included in the comments.

int main() {
    // Create an endpoint of the type we defined earlier
    server print_server;
// Initialize the Asio transport component. This version of init_asio
// will use an internal io_service managed by the endpoint. See the asio
// transport component documentation for more information about other
// ways to initialize asio that use io_services managed directly by your
// application
print_server.init_asio();

// Listen on port 9002 of all interface and all address families
// The asio transport component provides a number of interfaces for choosing
// exactly what interface, port, and address family to listen on. This
// default listen method will listen on the specified port of any interface
// using both IPv4 and IPv6. See the asio transport component documentation
// for information on customizing this behavior
print_server.listen(9002);

// This method tells the server to post the ASIO io_service work actions for
// accepting new connections. No connections will actually be accepted until
// the io_service actually runs. If the io_service was running when
// start_accept is called connections will be accepted immediately.
print_server.start_accept();

// Start the internal asio io_service run loop. This method will block now
// running the io_service event loop until the server is killed.
print_server.run();
}