Conditionally accepting connections

By default, WebSocket++ based servers accept any WebSocket connection. This behavior can be tailored to suit your application via a number of techniques. Most of this control comes by registering a validate handler. The validate handler is called after a connection handshake has been received and parsed, but before the response has been sent. The validate handler allows you to negotiate some aspects of the connection (such as which subprotocol or extensions to use) as well as rejecting or accepting the connection.

The signature of the validate handler is bool validate_handler(connection_hdl hdl). It can be registered with an endpoint or connection via the set_validate_handler(validate_handler h) method.

Accepting or Rejecting the Connection

The most basic function of the validate handler is to decide whether or not to accept the connection. This is done via the function's return value. Return true to accept the connection, false to reject it. If you are rejecting a connection, you can use set_status(http::status_code::value code) to specify the HTTP error code to return. set_body(string) also works here.

Accessing connection details

The validate handler may make its decisions about whether or not to accept connections by any means. Limits could be set based on global information, such as server resources in use, number of current connections, etc. Decisions can also be made using connection specific information. The validate handler is passed a connection_hdl as a parameter. Like with other handlers, this can be upgraded to a connection_ptr using server::get_con_from_hdl(connection_hdl hdl). With the connection_ptr, you can retrieve various information about the connection itself:

Method Value
get_secure() Whether or not the connection is secure.
get_host() The host component of the connection URI (
get_resource() The resource component of the connection URI (/foo).
get_port() The port component of the connection URI.
get_request_header(key) Value of header `key` from the handshake HTTP request.
get_origin() Value of origin header set by browser clients to indicate the origin of the original requesting script.
get_requested_subprotocols() A list of subprotocols the client is capable of speaking in order of preference.

Negotiating Origin

Browser clients will set an origin header indicating the origin of the original request. The const std::string & get_origin() method can be used to retrieve this value. This header can be used to implement a policy whereby only scripts running on whitelisted domains may connect to the server. Please note, like the origin header used for this purpose in regular HTTP servers, nothing prevents non-browser clients from spoofing this value.

Negotiating Subprotocols

WebSocket clients may include a list of supported subprotocols with their request. This list can be retrieved using std::vector<:string> & get_requested_subprotocols(). The list is ordered by client priority. As a server you may optionally choose one of these subprotocols to use. To select a subprotocol, use void select_subprotocol(const std::string & value) during the validate handler. The handshake return will include this value to let the client know which one has been chosen. The WebSocket protocol does not define the meaning or interpretation of the subprotocol, this is left up to the individual endpoints.

On the client side, WebSocket++ based clients can build the outgoing subprotocol request list by calling void add_subprotocol(string) before calling connect() for each protocol they want to request, in order of preference. The server's response can be read via get_subprotocol().

Negotiating Extensions


Add new comment

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.
By submitting this form, you accept the Mollom privacy policy.