forked from zaphoyd/websocketpp
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathhandlers.dox
165 lines (115 loc) · 7.98 KB
/
handlers.dox
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
/** \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 |
| ----------------------- | ------------------------------------------ | ----------------------------- |
| 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. You must
return a pointer to a configured TLS conext to continue. This provides the opportuinity to
set up the 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.
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
recieved. 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 signale to the main/network thread
that an event is ready.
todo: write low and high watermark handlers
*/