100 lines
3.3 KiB
Text
100 lines
3.3 KiB
Text
|
= nng_sub(7)
|
||
|
|
//
|
||
|
|
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
|
||
|
|
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
|
||
|
|
//
|
||
|
|
// This document 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_sub - subscriber protocol
|
||
|
|
|
||
|
|
== SYNOPSIS
|
||
|
|
|
||
|
|
[source,c]
|
||
|
|
----
|
||
|
|
#include <nng/nng.h>
|
||
|
|
#include <nng/protocol/pubsub0/sub.h>
|
||
|
|
----
|
||
|
|
|
||
|
|
== DESCRIPTION
|
||
|
|
|
||
|
|
(((protocol, _sub_)))
|
||
|
|
The ((_sub_ protocol)) is one half of a publisher/((subscriber)) pattern.
|
||
|
|
In this pattern, a publisher sends data, which is broadcast to all subscribers.
|
||
|
|
The subscribing applications only see the data to which they have subscribed.
|
||
|
|
|
||
|
|
The _sub_ protocol is the subscriber side, and the
|
||
|
|
xref:nng_pub.7.adoc[_pub_] protocol is the publisher side.
|
||
|
|
|
||
|
|
NOTE: In this implementation, the publisher delivers all messages to all
|
||
|
|
subscribers.
|
||
|
|
The subscribers maintain their own subscriptions, and filter them locally.
|
||
|
|
Thus, this pattern should not be used in an attempt to
|
||
|
|
reduce bandwidth consumption.
|
||
|
|
|
||
|
|
The topics that subscribers subscribe to is just the first part of
|
||
|
|
the message body.
|
||
|
|
Applications should construct their messages accordingly.
|
||
|
|
|
||
|
|
=== Socket Operations
|
||
|
|
|
||
|
|
The xref:nng_sub_open.3.adoc[`nng_sub0_open()`] functions create a subscriber socket.
|
||
|
|
This socket may be used to receive messages, but is unable to send them.
|
||
|
|
Attempts to send messages will result in `NNG_ENOTSUP`.
|
||
|
|
|
||
|
|
=== Protocol Versions
|
||
|
|
|
||
|
|
Only version 0 of this protocol is supported.
|
||
|
|
(At the time of writing, no other versions of this protocol have been defined.)
|
||
|
|
|
||
|
|
=== Protocol Options
|
||
|
|
|
||
|
|
The following protocol-specific options are available.
|
||
|
|
|
||
|
|
((`NNG_OPT_SUB_SUBSCRIBE`))(((subscribe)))::
|
||
|
|
|
||
|
|
This option registers a topic that the subscriber is interested in.
|
||
|
|
The option is write-only, and takes an array of bytes, of arbitrary size.
|
||
|
|
Each incoming message is checked against the list of subscribed topics.
|
||
|
|
If the body begins with the entire set of bytes in the topic, then the
|
||
|
|
message is accepted. If no topic matches, then the message is
|
||
|
|
discarded.
|
||
|
|
+
|
||
|
|
NOTE: This option is a byte array. Thus if you use
|
||
|
|
xref:nng_setopt.3.adoc[`nng_setopt_string()`] the `NUL` terminator byte will
|
||
|
|
be included in the topic.
|
||
|
|
If that isn't desired, consider using
|
||
|
|
xref:nng_setopt.3.adoc[`nng_setopt()`] and using `strlen()` of the topic
|
||
|
|
as the topic size.
|
||
|
|
+
|
||
|
|
TIP: To receive all messages, an empty topic (zero length) can be used.
|
||
|
|
|
||
|
|
((`NNG_OPT_SUB_UNSUBSCRIBE`))::
|
||
|
|
|
||
|
|
This option, also read-only, removes a topic from the subscription list.
|
||
|
|
Note that if the topic was not previously subscribed to with
|
||
|
|
`NNG_OPT_SUB_SUBSCRIBE` then an `NNG_ENOENT` error will result.
|
||
|
|
|
||
|
|
((`NNG_OPT_SUB_PREFNEW`))::
|
||
|
|
|
||
|
|
(`bool`)
|
||
|
|
This read/write option specifies the behavior of the subscriber when the queue is full.
|
||
|
|
When `true` (the default), the subscriber will make room in the queue by removing the oldest message.
|
||
|
|
When `false`, the subscriber will reject messages if the message queue does not have room.
|
||
|
|
|
||
|
|
=== Protocol Headers
|
||
|
|
|
||
|
|
The _sub_ protocol has no protocol-specific headers.
|
||
|
|
|
||
|
|
== SEE ALSO
|
||
|
|
|
||
|
|
[.text-left]
|
||
|
|
xref:nng_sub_open.3.adoc[nng_sub_open(3)],
|
||
|
|
xref:nng_pub.7.adoc[nng_pub(7)],
|
||
|
|
xref:nng.7.adoc[nng(7)]
|