1 /** \page reference.handlers Handler Reference
3 Handlers allow WebSocket++ programs to receive notifications about events
4 that happen in relation to their connections. Some handlers also behave as
5 hooks that give the program a chance to modify state or adjust settings before
6 the connection continues.
8 Handlers are registered by calling the appropriate `set_*_handler` method on either an
9 endpoint or connection. The * refers to the name of the handler (as
10 specified in the signature field below). For example, to set the open handler,
11 call `set_open_handler(...)`.
13 Setting handlers on an endpoint will result in them being copied as the default
14 handler to all new connections created by that endpoint. Changing an endpoint's
15 handlers will not affect connections that are already in progress. This includes
16 connections that are in the listening state. As such, it is important to set any
17 endpoint handlers before you call `endpoint::start_accept` or else the handlers
18 will not be attached to your first connection.
20 Setting handlers on a connection will result in the handler being changed for
21 that connection only, starting at the next time that handler is called. This can
22 be used to change the handler during a connection.
27 These handlers will be called at most once per connection in the order specified below.
29 ### Socket Init Handler
31 | Event | Signature | Availability |
32 | --------------------- | ----------------------------------------------------- | -------------------- |
33 | Socket initialization | `socket_init(connection_hdl, asio::ip::tcp::socket&)` | 0.3.0 Asio Transport |
35 This hook is triggered after the socket has been initialized but before a connection is established.
36 It allows setting arbitrary socket options before connections are sent/recieved.
38 ### TCP Pre-init Handler
40 | Event | Signature | Availability |
41 | ----------------------------- | ------------------------------ | -------------------- |
42 | TCP established, no data sent | `tcp_pre_init(connection_hdl)` | 0.3.0 Asio Transport |
44 This hook is triggered after the TCP connection is established, but before any pre-WebSocket-handshake
45 operations have been run. Common pre-handshake operations include TLS handshakes and proxy connections.
47 ### TCP Post-init Handler
49 | Event | Signature | Availability |
50 | ----------------------- | ------------------------------------------ | ----------------------------- |
51 | Request for TLS context | `tls_context_ptr tls_init(connection_hdl)` | 0.3.0 Asio Transport with TLS |
53 This hook is triggered before the TLS handshake to request the TLS context to use. You must
54 return a pointer to a configured TLS conext to continue. This provides the opportuinity to
55 set up the TLS settings, certificates, etc.
59 | Event | Signature | Availability |
60 | ------------------------------------- | ------------------------------- | ---------------------------- |
61 | Hook to accept or reject a connection | `bool validate(connection_hdl)` | 0.3.0 Core, Server role only |
63 This hook is triggered for servers during the opening handshake after the request has been
64 processed but before the response has been sent. It gives a program the opportunity to inspect
65 headers and other connection details and either accept or reject the connection. Validate happens
66 before the open or fail handler.
68 Return true to accept the connection, false to reject. If no validate handler is registered,
69 all connections will be accepted.
71 ### Open Connection Handler
73 | Event | Signature | Availability |
74 | ------------------------- | ---------------------- | ------------ |
75 | Successful new connection | `open(connection_hdl)` | 0.3.0 Core |
77 Either open or fail will be called for each connection. Never both. All
78 connections that begin with an open handler call will also have a matching
79 close handler call when the connection ends.
81 ### Fail Connection Handler
83 | Event | Signature | Availability |
84 | ----------------------------------- | ---------------------- | ------------ |
85 | Connection failed (before opening) | `fail(connection_hdl)` | 0.3.0 Core |
87 Either open or fail will be called for each connection. Never both. Connections
88 that fail will never have a close handler called.
90 ### Close Connection Handler
92 | Event | Signature | Availability |
93 | --------------------------------- | ----------------------- | ------------ |
94 | Connection closed (after opening) | `close(connection_hdl)` | 0.3.0 Core |
96 Close will be called exactly once for every connection that open was called for.
97 Close is not called for failed connections.
102 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.
106 | Event | Signature | Availability |
107 | --------------------- | -------------------------------------- | ------------ |
108 | Data message recieved | `message(connection_hdl, message_ptr)` | 0.3.0 Core |
110 Applies to all non-control messages, including both text and binary opcodes. The
111 `message_ptr` type and its API depends on your endpoint type and its config.
115 | Event | Signature | Availability |
116 | ------------- | ---------------------------------------- | ------------ |
117 | Ping recieved | `bool ping(connection_hdl, std::string)` | 0.3.0 Core |
119 Second (string) argument is the binary ping payload. Handler return value
120 indicates whether or not to respond to the ping with a pong. If no ping handler
121 is set, WebSocket++ will respond with a pong containing the same binary data as
122 the ping (Per requirements in RFC6455).
126 | Event | Signature | Availability |
127 | ------------- | ----------------------------------- | ------------ |
128 | Pong recieved | `pong(connection_hdl, std::string)` | 0.3.0 Core |
130 Second (string) argument is the binary pong payload.
132 ### Pong Timeout Handler
134 | Event | Signature | Availability |
135 | ---------------------------------- | ------------------------------------------- | ---------------------------------------- |
136 | Timed out while waiting for a pong | `pong_timeout(connection_hdl, std::string)` | 0.3.0 Core, transport with timer support |
138 Triggered if there is no response to a ping after the configured duration. The second
139 (string) argument is the binary payload of the unanswered ping.
143 | Event | Signature | Availability |
144 | --------------------- | --------------------- | ---------------------------- |
145 | HTTP request recieved | `http(connection_hdl` | 0.3.0 Core, Server role only |
147 Called when HTTP requests that are not WebSocket handshake upgrade requests are
148 recieved. Allows responding to regular HTTP requests. If no handler is registered
149 a 426/Upgrade Required error is returned.
151 ### Interrupt Handler
153 | Event | Signature | Availability |
154 | ----------------------------------- | --------------------------- | ------------ |
155 | Connection was manually interrupted | `interrupt(connection_hdl)` | 0.3.0 Core |
157 Interrupt events can be triggered by calling `endpoint::interrupt` or `connection::interrupt`.
158 Interrupt is similar to a timer event with duration zero but with lower overhead. It is useful
159 for single threaded programs to allow breaking up a very long handler into multiple parts and
160 for multi threaded programs as a way for worker threads to signale to the main/network thread
161 that an event is ready.
163 todo: write low and high watermark handlers