diff --git a/websocketpp/connection.hpp b/websocketpp/connection.hpp index 7a373680c2..50f89c9591 100644 --- a/websocketpp/connection.hpp +++ b/websocketpp/connection.hpp @@ -47,27 +47,125 @@ namespace websocketpp { +/// The type and function signature of an open handler +/** + * The open handler is called once for every successful WebSocket connection + * attempt. Either the fail handler or the open handler will be called for each + * WebSocket connection attempt. HTTP Connections that did not attempt to + * upgrade the connection to the WebSocket protocol will trigger the http + * handler instead of fail/open. + */ typedef lib::function open_handler; + +/// The type and function signature of a close handler +/** + * The close handler is called once for every successfully established + * connection after it is no longer capable of sending or receiving new messages + * + * The close handler will be called exactly once for every connection for which + * the open handler was called. + */ typedef lib::function close_handler; + +/// The type and function signature of a fail handler +/** + * The fail handler is called once for every unsuccessful WebSocket connection + * attempt. Either the fail handler or the open handler will be called for each + * WebSocket connection attempt. HTTP Connections that did not attempt to + * upgrade the connection to the WebSocket protocol will trigger the http + * handler instead of fail/open. + */ typedef lib::function fail_handler; +/// The type and function signature of an interrupt handler +/** + * The interrupt handler is called when a connection receives an interrupt + * request from the application. Interrupts allow the application to trigger a + * handler to be run in the absense of a WebSocket level handler trigger (like + * a new message). + * + * This is typically used by another application thread to schedule some tasks + * that can only be run from within the handler chain for thread safety reasons. + */ typedef lib::function interrupt_handler; -typedef lib::function handshake_init_handler; - +/// The type and function signature of a ping handler +/** + * The ping handler is called when the connection receives a WebSocket ping + * control frame. The string argument contains the ping payload. The payload is + * a binary string up to 126 bytes in length. The ping handler returns a bool, + * true if a pong response should be sent, false if the pong response should be + * suppressed. + */ typedef lib::function ping_handler; + +/// The type and function signature of a pong handler +/** + * The pong handler is called when the connection receives a WebSocket pong + * control frame. The string argument contains the pong payload. The payload is + * a binary string up to 126 bytes in length. + */ typedef lib::function pong_handler; + +/// The type and function signature of a pong timeout handler +/** + * The pong timeout handler is called when a ping goes unanswered by a pong for + * longer than the locally specified timeout period. + */ typedef lib::function pong_timeout_handler; +/// The type and function signature of a validate handler +/** + * The validate handler is called after a WebSocket handshake has been received + * and processed but before it has been accepted. This gives the application a + * chance to impliment connection details specific policies for accepting + * connections and the ability to negotiate extensions and subprotocols. + * + * The validate handler return value indicates whether or not the connection + * should be accepted. Additional methods may be called during the function to + * set response headers, set HTTP return/error codes, etc. + */ typedef lib::function validate_handler; + +/// The type and function signature of a http handler +/** + * The http handler is called when an HTTP connection is made that does not + * attempt to upgrade the connection to the WebSocket protocol. This allows + * WebSocket++ servers to respond to these requests with regular HTTP responses. + * + * This can be used to deliver error pages & dashboards and to deliver static + * files such as the base HTML & JavaScript for an otherwise single page + * WebSocket application. + * + * Note: WebSocket++ is designed to be a high performance WebSocket server. It + * is not tuned to provide a full featured, high performance, HTTP web server + * solution. The HTTP handler is appropriate only for low volume HTTP traffic. + * If you expect to serve high volumes of HTTP traffic a dedicated HTTP web + * server is strongly recommended. + * + * The default HTTP handler will return a 426 Upgrade Required error. Custom + * handlers may override the response status code to deliver any type of + * response. + */ typedef lib::function http_handler; // constants related to the default WebSocket protocol versions available #ifdef _WEBSOCKETPP_INITIALIZER_LISTS_ // simplified C++11 version - static const std::vector VERSIONS_SUPPORTED = {0,7,8,13}; + /// Container that stores the list of protocol versions supported + /** + * @todo Move this to configs to allow compile/runtime disabling or enabling + * of protocol versions + */ + static std::vector const versions_supported = {0,7,8,13}; #else - static const int HELPER[] = {0,7,8,13}; - static const std::vector VERSIONS_SUPPORTED(HELPER,HELPER+4); + /// Helper array to get around lack of initializer lists pre C++11 + static int const helper[] = {0,7,8,13}; + /// Container that stores the list of protocol versions supported + /** + * @todo Move this to configs to allow compile/runtime disabling or enabling + * of protocol versions + */ + static std::vector const versions_supported(helper,helper+4); #endif namespace session { diff --git a/websocketpp/endpoint.hpp b/websocketpp/endpoint.hpp index b18812b41e..522bbc4d70 100644 --- a/websocketpp/endpoint.hpp +++ b/websocketpp/endpoint.hpp @@ -88,8 +88,8 @@ public: typedef lib::shared_ptr hdl_type; explicit endpoint(bool is_server) - : m_alog(config::alog_level,&std::cout) - , m_elog(config::elog_level,&std::cerr) + : m_alog(config::alog_level, &std::cout) + , m_elog(config::elog_level, &std::cerr) , m_user_agent(::websocketpp::user_agent) , m_is_server(is_server) { @@ -106,7 +106,7 @@ public: * Returns the user agent string that this endpoint will use when creating * new connections. * - * The default value for this version is WebSocket++/0.3.0dev + * The default value for this version is stored in websocketpp::user_agent * * @return The user agent string. */ @@ -122,11 +122,11 @@ public: * * For best results set this before accepting or opening connections. * - * The default value for this version is WebSocket++/0.3.0dev + * The default value for this version is stored in websocketpp::user_agent * * @param ua The string to set the user agent to. */ - void set_user_agent(const std::string& ua) { + void set_user_agent(std::string const & ua) { scoped_lock_type guard(m_mutex); m_user_agent = ua; } @@ -189,21 +189,17 @@ public: /// Get reference to access logger /** - * TODO - * * @return A reference to the access logger */ - alog_type& get_alog() { + alog_type & get_alog() { return m_alog; } /// Get reference to error logger /** - * TODO - * * @return A reference to the error logger */ - elog_type& get_elog() { + elog_type & get_elog() { return m_elog; } diff --git a/websocketpp/impl/connection_impl.hpp b/websocketpp/impl/connection_impl.hpp index 6ebf64f5ce..12c4a80f67 100644 --- a/websocketpp/impl/connection_impl.hpp +++ b/websocketpp/impl/connection_impl.hpp @@ -962,7 +962,7 @@ bool connection::initialize_processor() { std::stringstream ss; std::string sep = ""; std::vector::const_iterator it; - for (it = VERSIONS_SUPPORTED.begin(); it != VERSIONS_SUPPORTED.end(); it++) + for (it = versions_supported.begin(); it != versions_supported.end(); it++) { ss << sep << *it; sep = ","; @@ -1625,7 +1625,7 @@ void connection::atomic_state_check(istate_type req, template const std::vector& connection::get_supported_versions() const { - return VERSIONS_SUPPORTED; + return versions_supported; } template diff --git a/websocketpp/transport/asio/security/base.hpp b/websocketpp/transport/asio/security/base.hpp index 9414accd89..073b825457 100644 --- a/websocketpp/transport/asio/security/base.hpp +++ b/websocketpp/transport/asio/security/base.hpp @@ -41,7 +41,7 @@ // Interface that sockets/security policies must implement -/** +/* * Endpoint Interface * * bool is_secure() const; @@ -55,10 +55,10 @@ */ -/// Connection -/// TODO -/// pre_init(init_handler); -/// post_init(init_handler); +// Connection +// TODO +// pre_init(init_handler); +// post_init(init_handler); namespace websocketpp { namespace transport { diff --git a/websocketpp/uri.hpp b/websocketpp/uri.hpp index aa43561cde..52aab4ac20 100644 --- a/websocketpp/uri.hpp +++ b/websocketpp/uri.hpp @@ -38,8 +38,6 @@ namespace websocketpp { -// WebSocket URI only (not http/etc) - class uri_exception : public std::exception { public: uri_exception(const std::string& msg) : m_msg(msg) {} @@ -53,10 +51,21 @@ private: }; // TODO: figure out why this fixes horrible linking errors. -static const uint16_t URI_DEFAULT_PORT = 80; -static const uint16_t uri_default_port = 80; -static const uint16_t URI_DEFAULT_SECURE_PORT = 443; -static const uint16_t uri_default_secure_port = 443; + +/// Default port for ws:// [deprecated] +/** + * @deprecated Use uri_default_port instead. Will be removed before 1.0.0 + */ +static uint16_t const URI_DEFAULT_PORT = 80; +/// Default port for ws:// +static uint16_t const uri_default_port = 80; +/// Default port for wss:// [deprecated] +/** + * @deprecated Use uri_default_secure_port instead. Will be removed before 1.0.0 + */ +static uint16_t const URI_DEFAULT_SECURE_PORT = 443; +/// Default port for wss:// +static uint16_t const uri_default_secure_port = 443; class uri { public: diff --git a/websocketpp/utilities.hpp b/websocketpp/utilities.hpp index 4bf2bfaaf5..9141adcd77 100644 --- a/websocketpp/utilities.hpp +++ b/websocketpp/utilities.hpp @@ -32,6 +32,7 @@ #include namespace websocketpp { +/// Generic non-websocket specific utility functions and data structures namespace utility { /// Helper functor for case insensitive find diff --git a/websocketpp/version.hpp b/websocketpp/version.hpp index 4ce440c570..73066ab807 100644 --- a/websocketpp/version.hpp +++ b/websocketpp/version.hpp @@ -28,6 +28,7 @@ #ifndef WEBSOCKETPP_VERSION_HPP #define WEBSOCKETPP_VERSION_HPP +/// Namespace for the WebSocket++ project namespace websocketpp { /* @@ -39,11 +40,20 @@ namespace websocketpp { - CMakeLists.txt */ +/// Library major version number static int const major_version = 0; +/// Library minor version number static int const minor_version = 3; +/// Library patch version number static int const patch_version = 0; +/// Library pre-release flag +/** + * This is a textual flag indicating the type and number for pre-release + * versions (dev, alpha, beta, rc). This will be blank for release versions. + */ static char const prerelease_flag[] = "alpha2"; +/// Default user agent string static char const user_agent[] = "WebSocket++/0.3.0-alpha2"; } // namespace websocketpp