NanoSDK C Client Library

The mqtt_full demo provides a single CLI binary named mqtt_client used to interact with MQTT brokers. It supports three primary subcommands:

• conn: Connects to a broker and maintains the connection (runs until interrupted by Ctrl+C).
• sub: Subscribes to topics and prints received messages.
• pub: Publishes messages to a specific topic.

Supported URL schemes depend on how the underlying nng library was compiled:

• mqtt-tcp://... (Standard TCP)
• tls+mqtt-tcp://... (MQTT over TLS)
• mqtt-quic://... (MQTT over QUIC)

mqtt_client <conn|sub|pub> [options]

The mqtt_full demo provides a command-line executable named mqtt_client used to interact with MQTT brokers. It supports three primary subcommands:

• conn: Establishes a connection and runs continuously (until interrupted by Ctrl+C).
• sub: Subscribes to topics and receives messages.
• pub: Publishes messages to a topic.

Supported URL schemes:

• mqtt-tcp://... (Standard TCP)
• tls+mqtt-tcp://... (MQTT over TLS)
• mqtt-quic://... (MQTT over QUIC)

mqtt_client <conn|sub|pub> [options]

The WebSocket transport allows using SP (Scalability Protocols) over WebSocket using either TCP or TLS.

• TCP Compatibility: When using TCP, this transport is compatible with libnanomsg legacy transport and mangos (both TCP and TLS).
• TLS Requirement: To use TLS support, the mbedTLS library must be available.
• Message Format: Each SP message is encapsulated as a standard WebSocket message (RFC 6455).

Protocol Negotiation

Protocol selection is handled via the Sec-WebSocket-Protocol field in the WebSocket handshake. The client sets this field to the server's protocol. For example, if the server is a REP endpoint, a REQ client should send rep.sp.nanomsg.org. The server then responds with its own protocol value as per WebSocket specifications.

The TCP transport provides communication support between sockets across a TCP/IP network, supporting both IPv4 and IPv6. It is generally built into the core of NNG, so no extra registration steps are typically required for standard builds.

#include <nng/transport/tcp/tcp.h>

int nng_tcp_register(void);

The nngcat utility provides a command-line interface to interact with Scalability Protocols. It allows you to write shell scripts that can send and receive messages by acting as a peer in a protocol topology.

To use nngcat, you must select at least one Protocol (e.g., --req, --pub, --sub) and at least one Peer Address (via --connect or --bind).

The ZeroTier (zt://) transport allows NNG applications to communicate over a ZeroTier network using a Virtual Layer 2 packet facility.

Important Considerations:

• Experimental: This transport is experimental.
• Dependencies: The library must be built with ZeroTier support and linked against libzerotiercore.
• Connection Latency: Initial connections can take up to a minute to establish while the network topology configures. It is recommended for long-running programs (daemons/agents) rather than short-lived ones.
• Network Requirements: Network rules must permit Ethernet type 901 to pass.
• IP Stack: This transport does not require or use an IP stack on the virtual network, mitigating IP management issues.

#include <nng/transport/zerotier/zerotier.h>

// Register the transport if necessary
int nng_zt_register(void);

An nng_aio is an opaque structure used to manage asynchronous I/O operations. Every asynchronous operation in the library requires an nng_aio handle.

Key constraints and behaviors:

• Single Use: Each handle can only be used with a single operation at a time.
• Non-blocking: Asynchronous operations are performed without blocking the calling application threads.
• Callbacks: Instead of waiting for a return value, the application registers a callback function that is executed exactly once when the operation completes (successfully or otherwise).
• Lifecycle: Handles are created using nng_aio_alloc() and must be destroyed using nng_aio_free() to prevent memory leaks.

#include <nng/nng.h>

typedef struct nng_aio nng_aio;

An NNG context is an abstraction that allows for the independent and concurrent use of stateful operations on a single socket.

When to use: Use contexts when you need to perform multiple concurrent operations on the same socket (like a rep socket handling multiple requests) without the operations interfering with each other. This allows you to write simpler concurrent logic while still benefiting from the protocol's built-in advanced processing, rather than resorting to raw mode sockets.

When not to use:

• Do not use contexts with raw mode sockets; it is unsupported and nonsensical.
• Be aware that some protocols may not support context creation at all.