From 4f8b2bdc98e2a736bd4fafdce2eff5b0f9fd4e43 Mon Sep 17 00:00:00 2001 From: Peter Thorson Date: Sun, 23 Jun 2013 16:18:03 -0500 Subject: [PATCH] transport documentation & style --- websocketpp/transport/asio/base.hpp | 4 +- websocketpp/transport/base/connection.hpp | 101 ++++++++++++++-------- websocketpp/transport/base/endpoint.hpp | 33 ++++--- 3 files changed, 80 insertions(+), 58 deletions(-) diff --git a/websocketpp/transport/asio/base.hpp b/websocketpp/transport/asio/base.hpp index fa260b4fc7..0e46c4d8b9 100644 --- a/websocketpp/transport/asio/base.hpp +++ b/websocketpp/transport/asio/base.hpp @@ -41,7 +41,7 @@ namespace transport { /// Transport policy that uses boost::asio namespace asio { -typedef lib::function +typedef lib::function socket_shutdown_handler; /** @@ -74,7 +74,7 @@ enum value { class category : public lib::error_category { public: - const char *name() const _WEBSOCKETPP_NOEXCEPT_TOKEN_ { + char const * name() const _WEBSOCKETPP_NOEXCEPT_TOKEN_ { return "websocketpp.transport.asio"; } diff --git a/websocketpp/transport/base/connection.hpp b/websocketpp/transport/base/connection.hpp index 89464312dd..c41c899095 100644 --- a/websocketpp/transport/base/connection.hpp +++ b/websocketpp/transport/base/connection.hpp @@ -35,51 +35,76 @@ #include namespace websocketpp { +/// Transport policies provide network connectivity and timers +/** + * ### Connection Interface + * + * Transport connection components needs to provide: + * + * *Warning: This documentation section and the transport connection interface + * are not complete.* + * + * **async_read_at_least**\n + * `void async_read_at_least(size_t num_bytes, char *buf, size_t len, + * read_handler handler)`\n + * start an async read for at least num_bytes and at most len + * bytes into buf. Call handler when done with number of bytes read. + * + * WebSocket++ promises to have only one async_read_at_least in flight at a + * time. The transport must promise to only call read_handler once per async + * read + * + * **async_write**\n + * `void async_write(const char* buf, size_t len, write_handler handler)`\n + * `void async_write(std::vector & bufs, write_handler handler)`\n + * Start a write of all of the data in buf or bufs. In second case data is + * written sequentially and in place without copying anything to a temporary + * location. + * + * Websocket++ promises to have only one async_write in flight at a time. + * The transport must promise to only call the write_handler once per async + * write + * + * **remote_endpoint**\n + * `std::string remote_endpoint()`\n + * retrieve address of remote endpoint + * + * **is_secure**\n + * `void is_secure()`\n + * whether or not the connection to the remote endpoint is secure + * + * **dispatch**\n + * `lib::error_code dispatch(dispatch_handler handler)`: invoke handler within + * the transport's event system if it uses one. + */ namespace transport { -/** - * Transport needs to provide: - * - async_read_at_least(size_t num_bytes, char *buf, size_t len, read_handler handler) - * start an async read for at least num_bytes and at most len bytes into buf. Call - * handler when done with number of bytes read. - * - * WebSocket++ promises to have only one async_read_at_least in flight at a - * time. The transport must promise to only call read_handler once per async - * read - * - * - async_write(const char* buf, size_t len, write_handler handler) - * - async_write(std::vector & bufs, write_handler handler) - * start an async write of all of the data in buf or bufs. In second case data - * is written sequentially and in place without copying anything to a temporary - * location. - * - * Websocket++ promises to have only one async_write in flight at a time. - * The transport must promise to only call the write_handler once per async - * write - * - * - std::string remote_endpoint(): retrieve address of remote endpoint - * - is_secure(): whether or not the connection to the remote endpoint is secure - * - lib::error_code dispatch(dispatch_handler handler): invoke handler within - * the transport's event system if it uses one. - */ +/// The type and signature of the callback passed to the init hook +typedef lib::function init_handler; +/// The type and signature of the callback passed to the read method +typedef lib::function read_handler; +/// The type and signature of the callback passed to the write method +typedef lib::function write_handler; -// Connection callbacks -typedef lib::function init_handler; -typedef lib::function read_handler; -typedef lib::function write_handler; -typedef lib::function timer_handler; -typedef lib::function shutdown_handler; -typedef lib::function inturrupt_handler; +/// The type and signature of the callback passed to the read method +typedef lib::function timer_handler; + +/// The type and signature of the callback passed to the shutdown method +typedef lib::function shutdown_handler; + +/// The type and signature of the callback passed to the interrupt method +typedef lib::function interrupt_handler; + +/// The type and signature of the callback passed to the dispatch method typedef lib::function dispatch_handler; -typedef lib::function connection_lock; - +/// A simple utility buffer class struct buffer { - buffer(const char * b, size_t l) : buf(b),len(l) {} + buffer(char const * b, size_t l) : buf(b),len(l) {} - const char* buf; + char const * buf; size_t len; }; @@ -118,7 +143,7 @@ class category : public lib::error_category { public: category() {} - const char *name() const _WEBSOCKETPP_NOEXCEPT_TOKEN_ { + char const * name() const _WEBSOCKETPP_NOEXCEPT_TOKEN_ { return "websocketpp.transport"; } @@ -146,7 +171,7 @@ class category : public lib::error_category { } }; -inline const lib::error_category& get_category() { +inline lib::error_category const & get_category() { static category instance; return instance; } diff --git a/websocketpp/transport/base/endpoint.hpp b/websocketpp/transport/base/endpoint.hpp index 6d51680ea1..d9a78564d1 100644 --- a/websocketpp/transport/base/endpoint.hpp +++ b/websocketpp/transport/base/endpoint.hpp @@ -38,30 +38,27 @@ namespace websocketpp { /// Transport policies provide network connectivity and timers -namespace transport { - -// Endpoint callbacks -typedef lib::function accept_handler; -typedef lib::function connect_handler; - -typedef lib::function endpoint_lock; - -// Endpoint interface -// Methods a transport endpoint must implement - -/// Initialize a connection /** - * Signature: lib::error_code init(transport_con_ptr tcon); - * + * ### Endpoint Interface + * + * Transport endpoint components needs to provide: + * + * **init**\n + * `lib::error_code init(transport_con_ptr tcon)`\n * init is called by an endpoint once for each newly created connection. * It's purpose is to give the transport policy the chance to perform any * transport specific initialization that couldn't be done via the default * constructor. - * - * @param tcon A pointer to the transport portion of the connection. - * - * @return A status code indicating the success or failure of the operation */ +namespace transport { + +/// The type and signature of the callback passed to the accept method +typedef lib::function + accept_handler; + +/// The type and signature of the callback passed to the connect method +typedef lib::function + connect_handler; } // namespace transport } // namespace websocketpp