Handlers allow WebSocket++ programs to receive notifications about events that happen in relation to their connections. Some handlers also behave as hooks that give the program a chance to modify state or adjust settings before the connection continues.

Handlers are registered by calling the appropriate set_*_handler method on either an endpoint or connection. The * refers to the name of the handler (as specified in the signature field below). For example, to set the open handler, call set_open_handler(...).

Setting handlers on an endpoint will result in them being copied as the default handler to all new connections created by that endpoint. Changing an endpoint's handlers will not affect connections that are already in progress. This includes connections that are in the listening state. As such, it is important to set any endpoint handlers before you call endpoint::start_accept or else the handlers will not be attached to your first connection.

Setting handlers on a connection will result in the handler being changed for that connection only, starting at the next time that handler is called. This can be used to change the handler during a connection.

Connection Handlers

These handlers will be called at most once per connection in the order specified below.

Socket Init Handler

Event	Signature	Availability
Socket initialization	socket_init(connection_hdl, asio::ip::tcp::socket&)	0.3.0 Asio Transport

This hook is triggered after the socket has been initialized but before a connection is established. It allows setting arbitrary socket options before connections are sent/recieved.

TCP Pre-init Handler

Event	Signature	Availability
TCP established, no data sent	tcp_pre_init(connection_hdl)	0.3.0 Asio Transport

This hook is triggered after the TCP connection is established, but before any pre-WebSocket-handshake operations have been run. Common pre-handshake operations include TLS handshakes and proxy connections.

TCP Post-init Handler

Event	Signature	Availability
TCP established, pre-handshake operations complete	tcp_post_init(connection_hdl)	0.3.0 Asio Transport

This hook is triggered after all pre-WebSocket handshake operations have been run. Common pre-handshake operations include TLS handshakes and proxy connections.

TLS Initialization Handler

Event	Signature	Availability
Request for TLS context	tls_context_ptr tls_init(connection_hdl)	0.3.0 Asio Transport with TLS

This hook is triggered before the TLS handshake to request the TLS context to use. The user program must return a pointer to a configured TLS context to continue. This provides the opportuinity to set up TLS settings, certificates, etc.

Validate Handler

Event	Signature	Availability
Hook to accept or reject a connection	bool validate(connection_hdl)	0.3.0 Core, Server role only

This hook is triggered for servers during the opening handshake after the request has been processed but before the response has been sent. It gives a program the opportunity to inspect headers and other connection details and either accept or reject the connection. Validate happens before the open or fail handler.

Return true to accept the connection, false to reject. If no validate handler is registered, all connections will be accepted.

Open Connection Handler

Event	Signature	Availability
Successful new connection	open(connection_hdl)	0.3.0 Core

Either open or fail will be called for each connection. Never both. All connections that begin with an open handler call will also have a matching close handler call when the connection ends.

Fail Connection Handler

Event	Signature	Availability
Connection failed (before opening)	fail(connection_hdl)	0.3.0 Core

Either open or fail will be called for each connection. Never both. Connections that fail will never have a close handler called.

Close Connection Handler

Event	Signature	Availability
Connection closed (after opening)	close(connection_hdl)	0.3.0 Core

Close will be called exactly once for every connection that open was called for. Close is not called for failed connections.

Endpoint Handlers

TCP Listen Pre-bind handler

Event	Signature	Availability
Listen Prebind	lib::error_code tcp_pre_bind(lib::shared_ptr<lib::asio::ip::tcp::acceptor>)	0.8.0 Asio Transport

This hook is triggered during the call to endpoint::listen after the acceptor is initialized and open but before bind or listen are called. It provides an opportunity to make application specific configuation to the acceptor, most commonly setting socket options on the listening socket, such as SO_REUSEPORT or IPV6_ONLY.

The return value of the callback will be used to determine whether to proceed with listening. Return an empty/0 error code to proceed, or another error code to fail. In the fail case, the error code will be reported back to the caller of endpoint::listen.

Acceptance Loop End Handler

Event	Signature	Availability
Async Accept Loop end (after opening)	accept_loop(void(lib::error_code const &, lib::error_code const &))	0.9.0 Core, Server role only

This handler is passed to the endpoint::start_accept() function, which initiates an asyncronous loop that accepts new connections, and is invoked when that loop ends. The handler will be called exactly once for each call of start_accept no matter when or how it exits (it might exit immediately).

The handler may be called inside the call to start_accept if that function has enough information to determine that accepting connections will be impossible. Otherwise, it may be invoked at a later time from a different asyncronous handler.

The handler returns two error codes. The first from the core library and the second a more detailed code passed through from the underlying transport.

Message Handlers

These handers are called in response to incoming messages or message like events. They only will be called while the connection is in the open state.

Message Handler

Event	Signature	Availability
Data message recieved	message(connection_hdl, message_ptr)	0.3.0 Core

Applies to all non-control messages, including both text and binary opcodes. The message_ptr type and its API depends on your endpoint type and its config.

Ping Handler

Event	Signature	Availability
Ping recieved	bool ping(connection_hdl, std::string)	0.3.0 Core

Second (string) argument is the binary ping payload. Handler return value indicates whether or not to respond to the ping with a pong. If no ping handler is set, WebSocket++ will respond with a pong containing the same binary data as the ping (Per requirements in RFC6455).

Pong Handler

Event	Signature	Availability
Pong recieved	pong(connection_hdl, std::string)	0.3.0 Core

Second (string) argument is the binary pong payload.

Pong Timeout Handler

Event	Signature	Availability
Timed out while waiting for a pong	pong_timeout(connection_hdl, std::string)	0.3.0 Core, transport with timer support

Triggered if there is no response to a ping after the configured duration. The second (string) argument is the binary payload of the unanswered ping.

HTTP Handler

Event	Signature	Availability
HTTP request recieved	http(connection_hdl	0.3.0 Core, Server role only

Called when HTTP requests that are not WebSocket handshake upgrade requests are received. Allows responding to regular HTTP requests. If no handler is registered a 426/Upgrade Required error is returned.

Interrupt Handler

Event	Signature	Availability
Connection was manually interrupted	interrupt(connection_hdl)	0.3.0 Core

Interrupt events can be triggered by calling endpoint::interrupt or connection::interrupt. Interrupt is similar to a timer event with duration zero but with lower overhead. It is useful for single threaded programs to allow breaking up a very long handler into multiple parts and for multi threaded programs as a way for worker threads to signal to the main/network thread that an event is ready.