From 74a12ffc8b37f2dae4b3002e86f33b8ca52df22d Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 29 Dec 2019 23:21:33 -0800 Subject: man page updates for 1.2 --- man/v1.2/nng_ws.7.html | 759 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 759 insertions(+) create mode 100644 man/v1.2/nng_ws.7.html (limited to 'man/v1.2/nng_ws.7.html') diff --git a/man/v1.2/nng_ws.7.html b/man/v1.2/nng_ws.7.html new file mode 100644 index 00000000..79b2d4c0 --- /dev/null +++ b/man/v1.2/nng_ws.7.html @@ -0,0 +1,759 @@ +--- +version: 1.2 +layout: refman +--- + + + + + + + +nng_ws(7) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#include <nng/transport/websocket/ws.h>
+
+int nng_ws_register(void);
+int nng_wss_register(void);
+
+
+
+
+
+

DESCRIPTION

+
+
+

+The ws transport provides communication support between +nng sockets across a TCP/IP network using +WebSockets. +Both IPv4 and IPv6 are supported when the underlying platform also supports it.

+
+
+

The protocol details are documented in +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().

+
+
+

If TLS support is enabled in the library, secure WebSockets (over TLS v1.2) +can be used as well, but the secure transport may have to be registered using +the nng_wss_register() function.

+
+
+
+

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.

+
+
+

Secure WebSockets +(if enabled) use the scheme wss://, and the default TCP port number of 443. +Otherwise the format is the same as for regular WebSockets.

+
+
+

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.

+
+
+ + + + + +
+ + +The value specified as the host, if any, will also be used +in the Host: HTTP header during HTTP negotiation. +
+
+
+

To listen to all ports on the system, the host name may be elided from +the URL on the listener. This will wind up listening to all interfaces +on the system, with possible caveats for IPv4 and IPv6 depending on what +the underlying system supports. (On most modern systems it will map to the +special IPv6 address ::, and both IPv4 and IPv6 connections will be +permitted, with IPv4 addresses mapped to IPv6 addresses.)

+
+
+
+

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).

+
+
+
+

Server Instances

+
+

This transport makes use of shared HTTP server +instances, permitting multiple +sockets or listeners to be configured with the same hostname and port. +When creating a new listener, it is registered with an existing HTTP server +instance if one can be found. +Note that the matching algorithm is somewhat simple, +using only a string based hostname or IP address and port to match. +Therefore it is recommended to use only IP addresses or the empty string as +the hostname in listener URLs.

+
+
+

Likewise, when sharing a server instance, it may not be possible to alter +TLS configuration if the server is already running, as there is only a single +TLS configuration context for the entire server instance.

+
+
+

All sharing of server instances is only typically possible within the same +process.

+
+
+

The server may also be used by other things (for example to serve static +content), in the same process.

+
+
+
+

Transport Options

+
+

The following transport options are available. Note that +setting these must be done before the transport is started.

+
+
+ + + + + +
+ + +The TLS specific options (beginning with NNG_OPT_TLS_) are +only available for wss:// endpoints. +
+
+
+
+
NNG_OPT_WS_REQUEST_HEADERS
+
+

(string) Concentation 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
+
+

(string) Concatenation of multiple lines terminated +by CRLF sequences, that can be used to add further headers to the +HTTP response sent when connecting. +This option can be set on listeners, and retrieved from pipes.

+
+
NNG_OPT_TLS_CONFIG
+
+

(nng_tls_config *) The underlying TLS +configuration object for wss:// endpoints. +A hold is placed on the underlying +configuration object before returning it. +The caller should release the object with +nng_tls_config_free() when it no +longer needs the TLS configuration.

+
+
+
+
+ + + + + +
+ + +Use this option when advanced TLS configuration is required. +
+
+
+
+
NNG_OPT_TLS_CA_FILE
+
+

(string) Write-only option naming a file containing certificates to +use for peer validation. +See nng_tls_config_ca_file() for more +information.

+
+
NNG_OPT_TLS_CERT_KEY_FILE
+
+

(string) Write-only option naming a file containing the local certificate and +associated private key. +The private key used must be unencrypted. +See nng_tls_config_own_cert() for more +information.

+
+
NNG_OPT_TLS_AUTH_MODE
+
+

(int) Write-only option used to configure the authentication mode used. +See nng_tls_config_auth_mode() for +more details.

+
+
NNG_OPT_TLS_VERIFIED
+
+

(bool) Whether the remote peer has been properly verified using TLS +authentication. +May return incorrect results if peer authentication is disabled.

+
+
+
+
+
+
+
+

SEE ALSO

+
+
+

nng_tls_config_alloc(3tls), +nng_sockaddr(5), +nng_sockaddr_in(5), +nng_sockaddr_in6(5), +nng(7)

+
+
+
+
+ + -- cgit v1.2.3-70-g09d2