fixes #169 document websocket transport

1 files changed, 161 insertions, 0 deletions

diff --git a/docs/nng_ws.adoc b/docs/nng_ws.adoc
new file mode 100644
index 00000000..8073e158
--- /dev/null
+++ b/docs/nng_ws.adoc
@@ -0,0 +1,161 @@
+nng_ws(7)
+=========
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:icons: font
+:source-highlighter: pygments
+:copyright: Copyright 2017 Garrett D'Amore <garrett@damore.org> \
+            Copyright 2017 Staysail Systems, Inc. <info@staysail.tech> \
+            Copyright 2017 Capitar IT Group BV <info@capitar.com> \
+            This software is supplied under the terms of the MIT License, a \
+            copy of which should be located in the distribution where this \
+            file was obtained (LICENSE.txt).  A copy of the license may also \
+            be found online at https://opensource.org/licenses/MIT.
+
+NAME
+----
+nng_ws - WebSocket transport for nng
+
+SYNOPSIS
+--------
+
+[source,c]
+----------
+#include <nng/transport/websocket/ws.h>
+
+int nng_ws_register(void);
+----------
+
+DESCRIPTION
+-----------
+
+The _nng_ws_ transport provides communication support between
+_nng_ sockets across a TCP/IP network using 
+https://tools.ietf.org/html/rfc6455[WebSockets].  Both IPv4 and IPv6
+are supported when the underlying platform also supports it.
+
+The protocol details are documented in
+http://nanomsg.org/rfcs/sp-websocket-v1.html[WebSocket Mapping for Scalability Protocols].
+
+Registration
+~~~~~~~~~~~~
+
+Depending upon how the library was built, it may be necessary to
+register the transport by calling `nng_ws_register`.  This function
+returns zero on success, or an nng error value if the transport
+cannot be initialized for any reason.
+
+URI Format
+~~~~~~~~~~
+
+This transport uses URIs using the scheme `ws://`, followed by
+an IP address or hostname, optionally followed by a colon and an
+TCP port number, optionally followed by a path.  (If no port number
+is specified then port 80 is assumed.  If no path is specified then
+a path of `/` is assumed.)
+For example, the URI `ws://localhost/app/pubsub` would use
+port 80 on localhost, with the path `/app/pubsub`.
+
+When specifying IPv6 addresses, the address must be enclosed in
+square brackets (`[]`) to avoid confusion with the final colon
+separating the port.
+
+For example, the same path and port on the IPv6 loopback address (`::1`)
+would be specified as `ws://[::1]/app/pubsub`.
+
+NOTE: When using symbolic names, the name is resolved when the
+name is first used. _nng_ won't become aware of changes in the
+name resolution until restart,
+usually.footnote:[This is a bug and will likely be fixed in the future.]
+
+NOTE: The value specified as the host, if any, will also be used
+in the `Host:` HTTP header during HTTP negotiation.
+
+The special value of 0 (`INADDR_ANY`) can be used for a listener
+to indicate that it should listen on all interfaces on the host.
+A short-hand for this form is to either omit the address, or specify
+the asterisk (`*`) character.  For example, the following three
+URIs are all equivalent, and could be used to listen to port 9999
+on the host:
+
+  1. `ws://0.0.0.0:9999`
+  2. `ws://*:9999`
+  3. `ws://:9999`
+
+Socket Address
+~~~~~~~~~~~~~~
+
+When using an `nng_sockaddr` structure, the actual structure is either
+of type `nng_sockaddr_in` (for IPv4) or `nng_sockaddr_in6` (for IPv6).
+These are `struct` types with the following definitions:
+
+[source,c]
+--------
+#define NNG_AF_INET    3 <1>
+#define NNG_AF_INET6   4
+#define NNG_MAXADDRLEN 128
+
+typedef struct {
+    // ... <2>
+    uint16_t sa_family;                 // must be NNG_AF_INET
+    uint16_t sa_port;                   // TCP port number
+    uint32_t sa_addr;
+    // ...
+} nng_sockaddr_in;
+
+typedef struct {
+    // ... <2>
+    uint16_t sa_family;                 // must be NNG_AF_INET6
+    uint16_t sa_port;                   // TCP port number
+    uint8_t  sa_addr[16];
+    // ...
+} nng_sockaddr_in6;
+--------
+<1> The values of these macros may change, so applications
+should avoid depending upon their values and instead use them symbolically.
+<2> Other members may be present, but only those listed here
+are suitable for application use.
+
+The `sa_family` member will have the value `NNG_AF_INET` or `NNG_AF_INET6`.
+The `sa_port` and `sa_addr` are the TCP port number and address, both in
+network byte order (most significant byte is first).
+
+Transport Options
+~~~~~~~~~~~~~~~~~
+
+The following transport options are available. Note that
+setting these must be done before the transport is started.
+
+`NNG_OPT_WS_REQUEST_HEADERS`::
+
+This value is a string, consisting of multiple lines terminated
+by CRLF sequences, that can be used to add further headers to the
+HTTP request sent when connecting.  This option can be set on dialers,
+and retrieved from pipes.
+
+`NNG_OPT_WS_RESPONSE_HEADERS`::
+
+This value is a string, consisting of multiple lines terminated
+by CRLF sequences, that can be used to add furthe headers to the
+HTTP response sent when connecting.  This option can be set on listeners,
+and retrieved from pipes.
+
+// We should also look at a hook mechanism for listeners. Probably this could
+// look like NNG_OPT_WS_LISTEN_HOOK_FUNC which would take a function pointer
+// along the lines of int hook(void *, char *req_headers, char **res_headers),
+// and NNG_OPT_LISTEN_HOOK_ARG that passes the void * passed in as first arg.
+// Alternatively we can uplevel the HTTP API and pass the actual HTTP objects.
+
+SEE ALSO
+--------
+<<nng.adoc#,nng(7)>>
+
+COPYRIGHT
+---------
+
+Copyright 2017 mailto:info@staysail.tech[Staysail Systems, Inc.] +
+Copyright 2017 mailto:info@capitar.com[Capitar IT Group BV]
+
+This document is supplied under the terms of the
+https://opensource.org/licenses/LICENSE.txt[MIT License].