gdax-orderbook-hpp/demo/dependencies/websocketpp-0.7.0/docs/handlers.dox

   1 /** \page reference.handlers Handler Reference
   2
   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.
   7
   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(...)`.
  12
  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.
  19
  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.
  23
  24 Connection Handlers
  25 -------------------
  26
  27 These handlers will be called at most once per connection in the order specified below.
  28
  29 ### Socket Init Handler
  30
  31 | Event                 | Signature                                             | Availability         |
  32 | --------------------- | ----------------------------------------------------- | -------------------- |
  33 | Socket initialization | `socket_init(connection_hdl, asio::ip::tcp::socket&)` | 0.3.0 Asio Transport |
  34
  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.
  37
  38 ### TCP Pre-init Handler
  39
  40 | Event                         | Signature                      | Availability         |
  41 | ----------------------------- | ------------------------------ | -------------------- |
  42 | TCP established, no data sent | `tcp_pre_init(connection_hdl)` | 0.3.0 Asio Transport |
  43
  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.
  46
  47 ### TCP Post-init Handler
  48
  49 | Event                   | Signature                                  | Availability                  |
  50 | ----------------------- | ------------------------------------------ | ----------------------------- |
  51 | Request for TLS context | `tls_context_ptr tls_init(connection_hdl)` | 0.3.0 Asio Transport with TLS |
  52
  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.
  56
  57 ### Validate Handler
  58
  59 | Event                                 | Signature                       | Availability                 |
  60 | ------------------------------------- | ------------------------------- | ---------------------------- |
  61 | Hook to accept or reject a connection | `bool validate(connection_hdl)` | 0.3.0 Core, Server role only |
  62
  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.
  67
  68 Return true to accept the connection, false to reject. If no validate handler is registered,
  69 all connections will be accepted.
  70
  71 ### Open Connection Handler
  72
  73 | Event                     | Signature              | Availability |
  74 | ------------------------- | ---------------------- | ------------ |
  75 | Successful new connection | `open(connection_hdl)` | 0.3.0 Core   |
  76
  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.
  80
  81 ### Fail Connection Handler
  82
  83 | Event                               | Signature              | Availability |
  84 | ----------------------------------- | ---------------------- | ------------ |
  85 | Connection failed (before opening)  | `fail(connection_hdl)` | 0.3.0 Core   |
  86
  87 Either open or fail will be called for each connection. Never both. Connections
  88 that fail will never have a close handler called.
  89
  90 ### Close Connection Handler
  91
  92 | Event                             | Signature               | Availability |
  93 | --------------------------------- | ----------------------- | ------------ |
  94 | Connection closed (after opening) | `close(connection_hdl)` | 0.3.0 Core   |
  95
  96 Close will be called exactly once for every connection that open was called for.
  97 Close is not called for failed connections.
  98
  99 Message Handlers
 100 ----------------
 101
 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.
 103
 104 ### Message Handler
 105
 106 | Event                 | Signature                              | Availability |
 107 | --------------------- | -------------------------------------- | ------------ |
 108 | Data message recieved | `message(connection_hdl, message_ptr)` | 0.3.0 Core   |
 109
 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.
 112
 113 ### Ping Handler
 114
 115 | Event         | Signature                                | Availability |
 116 | ------------- | ---------------------------------------- | ------------ |
 117 | Ping recieved | `bool ping(connection_hdl, std::string)` | 0.3.0 Core   |
 118
 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).
 123
 124 ### Pong Handler
 125
 126 | Event         | Signature                           | Availability |
 127 | ------------- | ----------------------------------- | ------------ |
 128 | Pong recieved | `pong(connection_hdl, std::string)` | 0.3.0 Core   |
 129
 130 Second (string) argument is the binary pong payload.
 131
 132 ### Pong Timeout Handler
 133
 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 |
 137
 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.
 140
 141 ### HTTP Handler
 142
 143 | Event                 | Signature             | Availability                 |
 144 | --------------------- | --------------------- | ---------------------------- |
 145 | HTTP request recieved | `http(connection_hdl` | 0.3.0 Core, Server role only |
 146
 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.
 150
 151 ### Interrupt Handler
 152
 153 | Event                               | Signature                   | Availability |
 154 | ----------------------------------- | --------------------------- | ------------ |
 155 | Connection was manually interrupted | `interrupt(connection_hdl)` | 0.3.0 Core   |
 156
 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.
 162
 163 todo: write low and high watermark handlers
 164
 165 */