--- /dev/null
+/** \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
+
+*/
projects / c11concurrency-benchmarks.git / blobdiff