From 8ef8372af1d74809ef857ee3f21f224fa83c564e Mon Sep 17 00:00:00 2001
From: Peter Thorson <github@zaphoyd.com>
Date: Mon, 12 Aug 2013 11:16:59 -0500
Subject: [PATCH] transport policy documentation

---
 websocketpp/transport/base/connection.hpp | 45 ++++++++++++++++++++---
 websocketpp/transport/base/endpoint.hpp   | 18 +++++++++
 2 files changed, 57 insertions(+), 6 deletions(-)

diff --git a/websocketpp/transport/base/connection.hpp b/websocketpp/transport/base/connection.hpp
index cbc52a0419..1db6310d23 100644
--- a/websocketpp/transport/base/connection.hpp
+++ b/websocketpp/transport/base/connection.hpp
@@ -41,8 +41,16 @@ namespace websocketpp {
  *
  * Transport connection components needs to provide:
  *
- * *Warning: This documentation section and the transport connection interface
- * are not complete.*
+ * **init**\n
+ * `void init(init_handler handler)`\n
+ * Called once shortly after construction to give the policy the chance to
+ * perform one time initialization. When complete, the policy must call the
+ * supplied `init_handler` to continue setup. The handler takes one argument
+ * with the error code if any. If an error is returned here setup will fail and
+ * the connection will be aborted or terminated.
+ *
+ * WebSocket++ will call init only once. The transport must call `handler`
+ * exactly once.
  *
  * **async_read_at_least**\n
  * `void async_read_at_least(size_t num_bytes, char *buf, size_t len,
@@ -52,7 +60,7 @@ namespace websocketpp {
  *
  * 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
+ * read.
  *
  * **async_write**\n
  * `void async_write(const char* buf, size_t len, write_handler handler)`\n
@@ -65,8 +73,28 @@ namespace websocketpp {
  * The transport must promise to only call the write_handler once per async
  * write
  *
- * **remote_endpoint**\n
- * `std::string remote_endpoint()`\n
+ * **set_handle**\n
+ * `void set_handle(connection_hdl hdl)`\n
+ * Called by WebSocket++ to let this policy know the hdl to the connection. It
+ * may be stored for later use or ignored/discarded. This handle should be used
+ * if the policy adds any connection handlers. Connection handlers must be
+ * called with the handle as the first argument so that the handler code knows
+ * which connection generated the callback.
+ *
+ * **set_timer**\n
+ * `timer_ptr set_timer(long duration, timer_handler handler)`\n
+ * WebSocket++ uses the timers provided by the transport policy as the
+ * implementation of timers is often highly coupled with the implementation of
+ * the networking event loops.
+ *
+ * Transport timer support is an optional feature. A transport method may elect
+ * to implement a dummy timer object and have this method return an empty
+ * pointer. If so, all timer related features of WebSocket++ core will be
+ * disabled. This includes many security features designed to prevent denial of
+ * service attacks. Use timer-free transport policies with caution.
+ *
+ * **get_remote_endpoint**\n
+ * `std::string get_remote_endpoint()`\n
  * retrieve address of remote endpoint
  *
  * **is_secure**\n
@@ -75,7 +103,12 @@ namespace websocketpp {
  *
  * **dispatch**\n
  * `lib::error_code dispatch(dispatch_handler handler)`: invoke handler within
- *  the transport's event system if it uses one.
+ * the transport's event system if it uses one. Otherwise, this method should
+ * simply call `handler` immediately.
+ *
+ * **async_shutdown**\n
+ * `void async_shutdown(shutdown_handler handler)`\n
+ * Perform any cleanup necessary (if any). Call `handler` when complete.
  */
 namespace transport {
 
diff --git a/websocketpp/transport/base/endpoint.hpp b/websocketpp/transport/base/endpoint.hpp
index 118c85d00c..df1dc45a59 100644
--- a/websocketpp/transport/base/endpoint.hpp
+++ b/websocketpp/transport/base/endpoint.hpp
@@ -49,6 +49,24 @@ namespace websocketpp {
  * 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.
+ *
+ * **is_secure**\n
+ * `bool is_secure() const`\n
+ * Test whether the transport component of this endpoint is capable of secure
+ * connections.
+ *
+ * **async_connect**\n
+ * `void async_connect(transport_con_ptr tcon, uri_ptr location,
+ *  connect_handler handler)`\n
+ * Initiate a connection to `location` using the given connection `tcon`. `tcon`
+ * is a pointer to the transport connection component of the connection. When
+ * complete, `handler` should be called with the the connection's
+ * `connection_hdl` and any error that occurred.
+ *
+ * **init_logging**
+ * `void init_logging(alog_type * a, elog_type * e)`\n
+ * Called once after construction to provide pointers to the endpoint's access
+ * and error loggers. These may be stored and used to log messages or ignored.
  */
 namespace transport {