1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
/** \page reference.handlers Handler Reference
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.
*/
|
