libnng - nanomsg next generation library

NAME SYNOPSIS DESCRIPTION Common Functions Socket Functions Connection Management Message Handling Functions Message Header Handling Asynchronous Operations Protocols Transports Protocol Contexts Devices, Relays Statistics URL Object Logging Support Supplemental API Byte Streams HTTP Support Common HTTP Functions HTTP Client Functions HTTP Server Functions TLS Configuration Objects SEE ALSO

NAME

libnng − nanomsg next generation library

SYNOPSIS

cc [flags] files −lnng [libraries]

DESCRIPTION

NNG provides a common messaging framework intended to solve common communication problems in distributed applications.

It provides a C language API.

Common Functions

The following common functions exist in libnng.

Socket Functions

The following functions operate on sockets.

Connection Management

The following functions are used with either listeners, or dialers. Listeners accept incoming connection requests, and dialers make them.

Message Handling Functions

Applications desiring to use the richest part of libnng will want to use the message API, where a message structure is passed between functions. This API provides the most power support for zero−copy.

Messages are divided into a header and body, where the body generally carries user−payload and the header carries protocol specific header information. Most applications will only interact with the body.

Message Header Handling

Tip

Few applications will need these functions, as message headers are only used to carry protocol−specific content. However, applications which use raw mode may need to access the header of messages.

Asynchronous Operations

Most applications will interact with NNG synchronously; that is that functions such as nng_send will block the calling thread until the operation has completed.

Note

Synchronous operations which send messages may return before the message has actually been received, or even transmitted. Instead, These functions return as soon as the message was successfully queued for delivery.

Asynchronous operations behave differently. These operations are initiated by the calling thread, but control returns immediately to the calling thread. When the operation is subsequently completed (regardless of whether this was successful or not), then a user supplied function is executed.

A context structure, an nng_aio, is allocated and associated with each asynchronous operation. Only a single asynchronous operation may be associated with an nng_aio at any time.

The following functions are used in the asynchronous model:

Protocols

The following functions are used to construct a socket with a specific protocol:

Transports

The following functions are used to register a transport for use. This is no longer necessary, and applications should not call these functions anymore.

Protocol Contexts

The following functions are useful to separate the protocol processing from a socket object, into a separate context. This can allow multiple contexts to be created on a single socket for concurrent applications.

Devices, Relays

The following function family is used to create forwarders or relayers that route messages from one socket to another.

Statistics

The following functions provide access to statistics which can be used to observe program behaviors and as an aid in troubleshooting.

URL Object

Common functionality is supplied for parsing and handling universal resource locators (URLS).

Logging Support

Common functionality for message logging.

Supplemental API

These supplemental functions are not intrinsic to building network applications with NNG, but they are made available as a convenience to aid in creating portable applications.

Byte Streams

These functions are available for use with byte streams. They are considered low−level, for uses where the higher level functions using Scalability Protocols are inappropriate.

Byte streams, represented by nng_stream objects, correspond to underlying connections such as TCP connections or named pipes. They are created by either nng_stream_dialer or nng_stream_listener objects.

HTTP Support

The library may be configured with support for HTTP, and this will be the case if WebSocket support is configured as well. In this case, it is possible to access functionality to support the creation of HTTP (and HTTP/S if TLS support is present) servers and clients.

Common HTTP Functions

The following functions are used to work with HTTP requests, responses, and connections.

HTTP Client Functions

These functions are intended for use with HTTP client applications.

HTTP Server Functions

These functions are intended for use with HTTP server applications.

TLS Configuration Objects

The following functions are used to manipulate transport layer security (TLS) configuration objects. Most of these functions will not be used even by TLS applications.

Note

These functions will only be present if the library has been built with TLS support.