Connection Handler API

The handler API defines the interface that a websocketpp session will use to communicate information about the session state and new messages to your application.

A client or server must be initialized with a default handler that will be used for all sessions. The default handler may pass a session off to another handler as necessary.

A handler must implement the following methods:

• validate(session_ptr)
• on_fail(session_ptr)
• on_open(session_ptr)
• on_close(session_ptr)
• on_message(session_ptr, const std::vector<unsigned char> &)
• on_message(session_ptr, const std::string &)

validate() will be called after a websocket handshake has been received and before it is accepted. It provides a handler the ability to refuse a connection based on application specific logic (ex: restrict domains or negotiate subprotocols). To reject the connection throw a handshake_error.
validate() is never called for client sessions. To refuse a client session (ex: if you do not like the set of extensions/subprotocols the server chose) you can close the connection immediately in the on_open() member function.

on_fail() is called whenever a session is terminated or failed before it was successfully established. This happens if there is an error during the handshake process or if the server refused the connection.
on_fail() will be the last time a session calls its handler. If your application will need information from `session` after this function you should either save the session_ptr somewhere or copy the data out.

on_open() is called after the websocket session has been successfully established and is in the OPEN state. The session is now available to send messages and will begin reading frames and calling the on_message/on_close/on_error callbacks. A client may reject the connection by closing the session at this point.

on_close() is called whenever an open session is closed for any reason. This can be due to either endpoint requesting a connection close or an error occurring. Information about why the session was closed can be extracted from the session itself.
on_close() will be the last time a session calls its handler. If your application will need information from `session` after this function you should either save the session_ptr somewhere or copy the data out.

on_message() (binary version) will be called when a binary message is received. Message data is passed as a vector of bytes (unsigned char). Data will not be available after this callback ends so the handler must either completely process the message or copy it somewhere else for processing later.

on_message() (text version). Identical to on_message except the data
parameter is a string interpreted as UTF-8. WebSocket++ guarantees that
this string is valid UTF-8.