1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
|
# SUB protocol
The {{i:*SUB* protocol}}{{hi:*SUB*}} is one half of a publisher/{{i: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
[_PUB_][pub] protocol is the publisher side.
> [!NOTE]
> 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 compared to the leading bytes of
the message body.
Applications should construct their messages accordingly.
### Socket Operations
```c
int nng_sub0_open(nng_socket *);
int nng_sub0_open_raw(nng_socket *);
int nng_sub0_socket_subscribe(nng_socket id, const void *buf, size_t sz);
int nng_sub0_socket_unsubscribe(nng_socket id, const void *buf, size_t sz);
```
The {{i:`nng_sub0_open`}} and {{i:`nng_sub0_open_raw`}} functions create a _SUB_ socket in
either [cooked] or [raw] mode.
The {{i:`nng_sub0_socket_subscribe`}} function is used to add a subscription topic to the socket.
Messages that do not match any subscription topic will be filtered out, and unavailable
for receiving.
A message is deemed to match a subscription if it has at least _sz_ bytes, and the first
_sz_ bytes are the same as _buf_.
The {{i:`nng_sub0_socket_unsubscribe`}} function removes a subscription from the socket.
> [!NOTE]
> A socket with no subscriptions cannot receive messages.
> [!TIP]
> To receive all messages, simply subscribe to a zero length topic.
### Context Operations
The _SUB_ protocol supports [contexts][context].
```c
int nng_sub0_ctx_subscribe(nng_ctx id, const void *buf, size_t sz);
int nng_sub0_ctx_unsubscribe(nng_ctx id, const void *buf, size_t sz);
```
The {{i:`nng_sub0_ctx_subscribe`}} and {{i:`nng_sub0_ctx_unsubscribe`}} functions
perform manage subscriptions for the context in precisely the same way that
[`nng_sub0_socket_subscribe`] and [`nng_sub0_socket_unsubscribe`] do.
Each context maintains its own set of subscriptions, and these are also independent
of socket level subscriptions.
### Protocol Options
| Option | Type | Description |
| ---------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| {{i:`NNG_OPT_SUB_PREF_NEW`}} | `bool` | If `true` (default), when the receive queue is full, then older unreceived messages will be discarded to make room for newer messages. If `false`, the older message is preserved and the newer message is discarded. |
### 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 Headers
The _SUB_ protocol has no protocol-specific headers.
{{#include ../xref.md}}
|
