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
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
|
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Streams - NNG Reference Manual (DRAFT)</title>
<!-- Custom HTML head -->
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff">
<link rel="icon" href="../favicon.svg">
<link rel="shortcut icon" href="../favicon.png">
<link rel="stylesheet" href="../css/variables.css">
<link rel="stylesheet" href="../css/general.css">
<link rel="stylesheet" href="../css/chrome.css">
<link rel="stylesheet" href="../css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="../fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<link rel="stylesheet" href="../theme/pagetoc.css">
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "../searchindex.js";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
<div class="right-buttons">
<a href="../print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<div class="search-wrapper">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<i class="fa fa-spinner fa-spin"></i>
</div>
</div>
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<style>
.mdbook-alerts {
padding: 8px 16px;
margin-bottom: 16px;
border-left: 0.25em solid var(--mdbook-alerts-color);
}
.mdbook-alerts > *:first-child {
margin-top: 0;
}
.mdbook-alerts > *:last-child {
margin-bottom: 0;
}
.mdbook-alerts-title {
display: flex;
font-weight: 600;
align-items: center;
line-height: 1;
color: var(--mdbook-alerts-color);
text-transform: capitalize;
}
.mdbook-alerts-icon {
display: inline-block;
width: 1em;
height: 1em;
margin-right: 0.2em;
background-color: currentColor;
-webkit-mask: no-repeat center / 100%;
mask: no-repeat center / 100%;
-webkit-mask-image: var(--mdbook-alerts-icon);
mask-image: var(--mdbook-alerts-icon);
}
.mdbook-alerts-note {
--mdbook-alerts-color: rgb(9, 105, 218);
/* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
--mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
}
.mdbook-alerts-tip {
--mdbook-alerts-color: rgb(26, 127, 55);
/* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
--mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
}
.mdbook-alerts-important {
--mdbook-alerts-color: rgb(130, 80, 223);
/* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
--mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
}
.mdbook-alerts-warning {
--mdbook-alerts-color: rgb(154, 103, 0);
/* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
--mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
}
.mdbook-alerts-caution {
--mdbook-alerts-color: rgb(207, 34, 46);
/* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
--mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
}
</style>
<h1 id="streams"><a class="header" href="#streams">Streams</a></h1>
<p>NNG provides a common <a name="a001"></a>streams API for working with byte-oriented streams. In NNG, streams are bidirectional
connections for exchanging a stream of bytes.</p>
<p>Some common examples of streams are TCP connections, UNIX domain sockets, Windows named pipes, and WebSockets.</p>
<p>The API documented here is to facilitate applications that wish to work with these at a lower-level than
Scalability Protocols, in a way that is both portable and agnostic about the specific underlying transport mechanism.</p>
<div class="mdbook-alerts mdbook-alerts-tip">
<p class="mdbook-alerts-title">
<span class="mdbook-alerts-icon"></span>
tip
</p>
<p>When working with Scalability Protocols directly, it is unlikely that there will be any need for
using these Streams APIs.</p>
</div>
<h2 id="stream-type"><a class="header" href="#stream-type">Stream Type</a></h2>
<pre><code class="language-c">typedef struct nng_stream nng_stream
</code></pre>
<p>The base <a name="a002"></a><code>nng_stream</code> type represents a bidirectional, byte-oriented, reliable connection.</p>
<div class="mdbook-alerts mdbook-alerts-note">
<p class="mdbook-alerts-title">
<span class="mdbook-alerts-icon"></span>
note
</p>
<p>The <code>nng_stream</code> object is used for raw byte stream connections, and
should not be confused with a <a href="../../api/pipe.html">pipe</a> object created on a <a href="../../TODO.html">socket</a> using
the <a href="../../TODO.html"><code>nng_listen</code></a>, <a href="../../TODO.html"><code>nng_dial</code></a> or related functions.</p>
</div>
<h2 id="sending-and-receiving-data"><a class="header" href="#sending-and-receiving-data">Sending and Receiving Data</a></h2>
<pre><code class="language-c">void nng_stream_send(nng_stream *s, nng_aio *aio);
void nng_stream_recv(nng_stream *s, nng_aio *aio);
</code></pre>
<p>The <a name="a003"></a><code>nng_stream_send</code> function starts sending data asynchronously over the stream <em>s</em>.
The data is sent from the scatter/gather vector located in the <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>,
which must have been previously set using <a href="../../api/aio.html#scatter-gather-vectors"><code>nng_aio_set_iov</code></a>.</p>
<p>The <a name="a004"></a><code>nng_stream_recv</code> function starts receiving data [asynchronously over the stream <em>s</em>
into the scatter/gather vector located in the <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>,
which must have been previously set using <a href="../../api/aio.html#scatter-gather-vectors"><code>nng_aio_set_iov</code></a>.</p>
<p>These functions return immediately, with no return value.
Completion of the operation is signaled via the <em>aio</em>, and the final
result may be obtained via <a href="../../api/aio.html#result-of-operation"><code>nng_aio_result</code></a>.</p>
<p>The I/O operation may complete as soon as at least one byte has been
transferred, or an error has occurred.
Therefore, the number of bytes transferred may be less than requested.
The actual number of bytes transferred can be determined with <a href="../../api/aio.html#result-of-operation"><code>nng_aio_count</code></a>.</p>
<h2 id="closing-a-stream"><a class="header" href="#closing-a-stream">Closing a Stream</a></h2>
<pre><code class="language-c">void nng_stream_close(nng_stream *s);
void nng_stream_stop(nng_stream *s);
void nng_stream_free(nng_stream *s);
</code></pre>
<p>The <a name="a005"></a><code>nng_stream_close</code> function closes a stream, but does not destroy it.
This function returns immediately. Operations that are pending against the stream, such
as <a href="../../api/stream.html#sending-and-receiving-data"><code>nng_stream_send</code></a> or <a href="../../api/stream.html#sending-and-receiving-data"><code>nng_stream_recv</code></a> operations will be canceled asynchronously, if possible.
Those operations will result in <a href="../../api/errors.html#NNG_ECLOSED"><code>NNG_ECLOSED</code></a>.</p>
<p>The <a name="a006"></a><code>nng_stream_stop</code> function not only closes the stream, but waits for any operations
pending against it to complete, and for any underlying asynchronous registered I/O to be fully deregistered.
As some systems use separate threads for asynchronous I/O, stopping the stream is necessary before those
resources can be freed. Until the stream is stopped, there could still be I/O operations in flight,
making it unsafe to deallocate memory.</p>
<p>The <a name="a007"></a><code>nng_stream_free</code> function stops the stream like <code>nng_stream_stop</code>, but also deallocates the
stream itself.</p>
<div class="mdbook-alerts mdbook-alerts-note">
<p class="mdbook-alerts-title">
<span class="mdbook-alerts-icon"></span>
note
</p>
<p>Because <code>nng_stream_stop</code> and <code>nng_stream_free</code> both may block waiting for outstanding I/O to complete
or be aborted, these functions are unsafe to call from functions that may not block, such as the
completion function registered with an <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> when it is created.</p>
</div>
<h2 id="getting-stream-options"><a class="header" href="#getting-stream-options">Getting Stream Options</a></h2>
<pre><code class="language-c">nng_err nng_stream_get_bool(nng_stream *s, const char *opt, bool *valp);
nng_err nng_stream_get_int(nng_stream *s, const char *opt, int *valp);
nng_err nng_stream_get_ms(nng_stream *s, const char *opt, nng_duration *valp);
nng_err nng_stream_get_size(nng_stream *s, const char *opt, size_t *valp);
nng_err nng_stream_get_addr(nng_stream *s, const char *opt, nng_sockaddr *valp);
nng_err nng_stream_get_string(nng_stream *s, const char *opt, const char **valp);
</code></pre>
<p><a name="a008"></a>
<a name="a009"></a>
<a name="a010"></a>
<a name="a011"></a>
<a name="a012"></a>
<a name="a013"></a>
These functions are used to obtain value of an option named <em>opt</em> from the stream <em>s</em>, and store it in the location
referenced by <em>valp</em>.</p>
<p>These functions access an option as a specific type. The transport layer will have details about which options
are available, and which type they may be accessed using.</p>
<p>In the case of <code>nng_stream_get_string</code>, the string pointer is only guaranteed to be valid while the
stream exists. Callers should make a copy of the data if required before closing the stream.</p>
<h2 id="stream-factories"><a class="header" href="#stream-factories">Stream Factories</a></h2>
<pre><code class="language-c">typedef struct nng_stream_dialer nng_stream_dialer;
typedef struct nng_stream_listener nng_stream_listener;
</code></pre>
<p><a name="a014"></a>
The <a name="a015"></a><code>nng_stream_listener</code> object and <a name="a016"></a><code>nng_stream_listener</code> objects can be thought of as factories that
create <a href="../../api/stream.html#stream-type"><code>nng_stream</code></a> streams.</p>
<p>The <code>nng_stream_listener</code> object a handle to a listener, which creates streams by accepting incoming connection requests.
In a BSD socket implementation, this is the entity responsible for doing <a name="a017"></a><code>bind</code>, <a name="a018"></a><code>listen</code> and <a name="a019"></a><code>accept</code>.
Normally a listener may be used to accept multiple, possibly many, concurrent connections.</p>
<p>The <code>nng_stream_dialer</code> object is a handle to a dialer, which creates streams by making outgoing
connection requests. While there isn’t a specific BSD socket analogue, this can be thought of as a factory for TCP sockets
created by opening them with <a name="a020"></a><code>socket</code> and then calling <a name="a021"></a><code>connect</code> on them.</p>
<h2 id="creating-a-stream-factory"><a class="header" href="#creating-a-stream-factory">Creating a Stream Factory</a></h2>
<pre><code class="language-c">nng_err nng_stream_dialer_alloc(nng_stream_dialer **dialerp, const char *url);
nng_err nng_stream_dialer_alloc_url(nng_stream_dialer **dialerp, const nng_url *url);
nng_err nng_stream_listener_alloc(nng_stream_listener **lstenerp, const char *url);
nng_err nng_stream_listener_alloc_url(nng_stream_listener **listenerp, const nng_url *url);
</code></pre>
<p>The <a name="a022"></a><code>nng_stream_dialer_alloc</code> and <a name="a023"></a><code>nng_stream_dialer_alloc_url</code> functions create a stream dialer, associated the
<a name="a024"></a>URL specified by <em>url</em> represented as a string, or as an <a href="../../api/url.html#url-structure"><code>nng_url</code></a> object, respectively. The dialer is returned in the location
<em>dialerp</em> references.</p>
<p>The <a name="a025"></a><code>nng_stream_listener_alloc</code> and <a name="a026"></a><code>nng_stream_listener_alloc_url</code> functions create a stream listener, associated the
URL specified by <em>url</em> represented as a string, or as an <a href="../../api/url.html#url-structure"><code>nng_url</code></a> object, respectively. The listener is returned in the location
<em>listenerp</em> references.</p>
<h3 id="example-1-creating-a-tcp-listener"><a class="header" href="#example-1-creating-a-tcp-listener">Example 1: Creating a TCP Listener</a></h3>
<p>This shows creating a TCP listener that listens on <code>INADDR_ANY</code>, port 444.</p>
<pre><code class="language-c">nng_listener listener;
int rv = nng_stream_listener_alloc(&listener, "tcp://:444");
</code></pre>
<h2 id="closing-a-stream-factory"><a class="header" href="#closing-a-stream-factory">Closing a Stream Factory</a></h2>
<pre><code class="language-c">void nng_stream_dialer_close(nng_stream_listener *dialer);
void nng_stream_dialer_stop(nng_stream_listener *dialer);
void nng_stream_dialer_free(nng_stream_listener *dialer);
void nng_stream_listener_close(nng_stream_listener *listener);
void nng_stream_listener_stop(nng_stream_listener *listener);
void nng_stream_listener_free(nng_stream_listener *listener);
</code></pre>
<p>The <a name="a027"></a><code>nng_stream_dialer_close</code> and <a name="a028"></a><code>nng_stream_listener_close</code> functions close the stream <em>dialer</em> or <em>listener</em>,
preventing it from creating new connections.
This will generally include closing any underlying file used for creating such connections.
However, some requests may still be pending when this function returns, as it does not wait for the shutdown to complete.</p>
<p>The <a name="a029"></a><code>nng_stream_dialer_stop</code> and <a name="a030"></a><code>nng_stream_listener_stop</code> functions performs the same action,
but also wait until all outstanding requests are serviced, and the <em>dialer</em> or <em>listener</em> is completely stopped.
Because they blocks, these functions must not be called in contexts where blocking is not allowed.</p>
<p>The <a name="a031"></a><code>nng_stream_dialer_free</code> and <a name="a032"></a><code>nng_stream_listener_free</code> function performs the same action as
<code>nng_stream_dialer_stop</code> or <code>nng_stream_listener_stop</code>, but also deallocates the <em>dialer</em> or <em>listener</em>, and any associated resources.</p>
<div class="mdbook-alerts mdbook-alerts-tip">
<p class="mdbook-alerts-title">
<span class="mdbook-alerts-icon"></span>
tip
</p>
<p>A best practice for shutting down an application safely is to stop everything <em>before</em> deallocating. This ensures that no
callbacks are running that could reference an object after it is deallocated.</p>
</div>
<h2 id="making-outgoing-connections"><a class="header" href="#making-outgoing-connections">Making Outgoing Connections</a></h2>
<pre><code class="language-c">void nng_stream_dialer_dial(nng_stream_dialer *dialer, nng_aio *aio);
</code></pre>
<p>The <a name="a033"></a><code>nng_stream_dialer_dial</code> initiates an outgoing connection asynchronously, using the <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>.
If it successfully establishes a connection, it creates an <a href="../../api/stream.html#stream-type"><code>nng_stream</code></a>, which can be obtained as the first
output result on <em>aio</em> using the <a href="../../api/aio.html#inputs-and-outputs"><code>nng_aio_get_output</code></a> function with index zero.</p>
<div class="mdbook-alerts mdbook-alerts-tip">
<p class="mdbook-alerts-title">
<span class="mdbook-alerts-icon"></span>
tip
</p>
<p>An <a href="../../api/stream.html#stream-factories"><code>nng_stream_dialer</code></a> can be used multiple times to make multiple concurrent connection requests, but
they all must reference the same URL.</p>
</div>
<h3 id="example-3-connecting-to-google"><a class="header" href="#example-3-connecting-to-google">Example 3: Connecting to Google</a></h3>
<p>This demonstrates making an outbound connection to “google.com” on TCP port 80.
Error handling is elided for clarity.</p>
<pre><code class="language-c">nng_aio *aio;
nng_stream_dialer *dialer;
nng_stream *stream;
nng_stream_dialer_alloc(&dialer, "tcp://google.com:80");
nng_aio_alloc(&aio, NULL, NULL);
// make a single outbound connection
nng_stream_dialer_dial(dialer, aio);
nng_aio_wait(aio); // wait for the asynch operation to complete
if (nng_aio_result(aio) != 0) {
// ... handle the error
}
stream = nng_aio_get_output(aio, 0);
</code></pre>
<h2 id="accepting-incoming-connections"><a class="header" href="#accepting-incoming-connections">Accepting Incoming Connections</a></h2>
<pre><code class="language-c">nng_err nng_stream_listener_listen(nng_stream_listener *listener);
void nng_stream_listener_accept(nng_stream_listener *listener, nng_aio *aio);
</code></pre>
<p>Accepting incoming connections is performed in two steps. The first step, <a name="a034"></a><code>nng_stream_listener_listen</code> is to setup for
listening. For a TCP implementation of this, for example, this would perform the <code>bind</code> and the <code>listen</code> steps. This will bind
to the address represented by the URL that was specific when the listener was created with <a href="../../api/stream.html#creating-a-stream-factory"><code>nng_stream_listener_alloc</code></a>.</p>
<p>In the second step, <a name="a035"></a><code>nng_stream_listener_accept</code> accepts an incoming connection on <em>listener</em> asynchronously, using the <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>.
If an incoming connection is accepted, it will be represented as an <a href="../../api/stream.html#stream-type"><code>nng_stream</code></a>, which can be obtained from the <em>aio</em> as the first
output result using the <a href="../../api/aio.html#inputs-and-outputs"><code>nng_aio_get_output</code></a> function with index zero.</p>
<h3 id="example-3-accepting-an-inbound-stream"><a class="header" href="#example-3-accepting-an-inbound-stream">Example 3: Accepting an Inbound Stream</a></h3>
<p>For clarity this example uses a synchronous approach using <a href="../../api/aio.html#wait-for-completion"><code>nng_aio_wait</code></a>, but a typical server application
would most likely use a callback to accept the incoming stream, and start another instance of <code>nng_stream_listener_accept</code>.</p>
<pre><code class="language-c">nng_aio *aio;
nng_listener *listener;
nng_stream *stream;
nng_stream_listener_alloc(&listener, "tcp://:8181");
nng_aio_alloc(&aio, NULL, NULL); // normally would use a callback
// listen (binding to the URL in the process)
if (nng_stream_listener_listen(listener)) {
// ... handle the error
}
// now accept a single incoming connection as a stream object
nng_stream_listener_accept(l, aio);
nng_aio_wait(aio); // wait for the asynch operation to complete
if (nng_aio_result(aio) != 0) {
// ... handle the error
}
stream = nng_aio_get_output(aio, 0);
</code></pre>
<h2 id="stream-factory-options"><a class="header" href="#stream-factory-options">Stream Factory Options</a></h2>
<pre><code class="language-c">nng_err nng_stream_dialer_get_addr(nng_stream_dialer *dialer, const char *opt, nng_sockaddr *valp);
nng_err nng_stream_dialer_get_bool(nng_stream_dialer *dialer, const char *opt, bool *valp);
nng_err nng_stream_dialer_get_int(nng_stream_dialer *dialer, const char *opt, int *valp);
nng_err nng_stream_dialer_get_ms(nng_stream_dialer *dialer, const char *opt, nng_duration *valp);
nng_err nng_stream_dialer_get_size(nng_stream_dialer *dialer, const char *opt, size_t *valp);
nng_err nng_stream_dialer_get_string(nng_stream_dialer *dialer, const char *opt, const char **valp);
nng_err nng_stream_listener_get_addr(nng_stream_listener *listener, const char *opt, nng_sockaddr *valp);
nng_err nng_stream_listener_get_bool(nng_stream_listener *listener, const char *opt, bool *valp);
nng_err nng_stream_listener_get_int(nng_stream_listener *listener, const char *opt, int *valp);
nng_err nng_stream_listener_get_ms(nng_stream_listener *listener, const char *opt, nng_duration *valp);
nng_err nng_stream_listener_get_size(nng_stream_listener *listener, const char *opt, size_t *valp);
nng_err nng_stream_listener_get_string(nng_stream_listener *listener, const char *opt, const char **valp);
nng_err nng_stream_dialer_set_addr(nng_stream_dialer *dialer, const char *opt, const nng_sockaddr *val);
nng_err nng_stream_dialer_set_bool(nng_stream_dialer *dialer, const char *opt, bool val);
nng_err nng_stream_dialer_set_int(nng_stream_dialer *dialer, const char *opt, int val);
nng_err nng_stream_dialer_set_ms(nng_stream_dialer *dialer, const char *opt, nng_duration val);
nng_err nng_stream_dialer_set_size(nng_stream_dialer *dialer, const char *opt, size_t val);
nng_err nng_stream_dialer_set_string(nng_stream_dialer *dialer, const char *opt, const char *val);
nng_err nng_stream_listener_set_addr(nng_stream_listener *listener, const char *opt, const nng_sockaddr *val);
nng_err nng_stream_listener_set_bool(nng_stream_listener *listener, const char *opt, bool val);
nng_err nng_stream_listener_set_int(nng_stream_listener *listener, const char *opt, int val);
nng_err nng_stream_listener_set_ms(nng_stream_listener *listener, const char *opt, nng_duration val);
nng_err nng_stream_listener_set_size(nng_stream_listener *listener, const char *opt, size_t val);
nng_err nng_stream_listener_set_string(nng_stream_listener *listener, const char *opt, const char *val);
</code></pre>
<p><a name="a036"></a>
<a name="a037"></a>
<a name="a038"></a>
<a name="a039"></a>
<a name="a040"></a>
<a name="a041"></a>
<a name="a042"></a>
<a name="a043"></a>
<a name="a044"></a>
<a name="a045"></a>
<a name="a046"></a>
<a name="a047"></a>
<a name="a048"></a>
<a name="a049"></a>
<a name="a050"></a>
<a name="a051"></a>
<a name="a052"></a>
<a name="a053"></a>
<a name="a054"></a>
<a name="a055"></a>
<a name="a056"></a>
<a name="a057"></a>
<a name="a058"></a>
<a name="a059"></a>
These functions are used to retrieve or change the value of an option named <em>opt</em> from the stream <em>dialer</em> or <em>listener</em>.
The <code>nng_stream_dialer_get_</code> and <code>nng_stream_listener_get_</code> function families retrieve the value, and store it in the location <em>valp</em> references.
The <code>nng_stream_dialer_set_</code> and <code>nng_stream_listener_set_</code> function families change the value for the <em>dialer</em> or <em>listener</em>, taking it from <em>val</em>.</p>
<p>These functions access an option as a specific type. The transport layer will have details about which options
are available, and which type they may be accessed using.</p>
<p>In the case of <code>nng_stream_dialer_get_string</code> and <code>nng_stream_listener_get_string</code>, the memory holding
the string is only valid as long as the associated object remains open.</p>
<p>In the case of <code>nng_stream_dialer_set_string</code> and <code>nng_stream_listener_set_string</code>, the string contents are copied if necessary, so that the caller
need not retain the value referenced once the function returns.</p>
<p>In the case of <code>nng_stream_dialer_set_addr</code> and <code>nng_stream_listener_set_addr</code>, the contents of <em>addr</em> are copied if necessary, so that the caller
need not retain the value referenced once the function returns.</p>
<h3 id="example-4-socket-activation"><a class="header" href="#example-4-socket-activation">Example 4: Socket Activation<a name="socket-activation"></a></a></h3>
<p>Some <a href="../../api/stream.html#stream-factories"><code>nng_stream_listener</code></a> objects, depending on the underlying transport and platform, can support a technique known as “<a name="a060"></a>socket activation”,
where the file descriptor used for listening and accepting is supplied externally, such as by a system service manager.
In this case, the application supplies the file descriptor or <code>SOCKET</code> object using the <a name="a061"></a><code>NNG_OPT_LISTEN_FD</code> option,
instead of calling <a href="../../api/stream.html#accepting-incoming-connections"><code>nng_stream_listener_listen</code></a>.</p>
<div class="mdbook-alerts mdbook-alerts-tip">
<p class="mdbook-alerts-title">
<span class="mdbook-alerts-icon"></span>
tip
</p>
<p>Scalability Protocols transports based upon stream implementations that support socket activation can also benefit from this approach.</p>
</div>
<pre><code class="language-c">nng_stream_listener *listener;
int fd;
// This is a systemd API, not part of NNG.
// See systemd documentation for an explanation.
// fd at this point has already had bind() and listen() called.
fd = SD_LISTEN_FDS_START + 0;
nng_stream_listener_alloc(&listener, "tcp://");
nng_stream_listener_set_int(listener, NNG_OPT_LISTEN_FD, fd);
// can now start doing nng_stream_listener_accept...
</code></pre>
<h2 id="tls-configuration"><a class="header" href="#tls-configuration">TLS Configuration</a></h2>
<pre><code class="language-c">nng_err nng_stream_dialer_get_tls(nng_stream_listener *dialer, nng_tls_config **tlsp);
nng_err nng_stream_dialer_set_tls(nng_stream_listener *dialer, nng_tls_config *tls);
nng_err nng_stream_listener_get_tls(nng_stream_listener *listener, nng_tls_config **tlsp);
nng_err nng_stream_listener_set_tls(nng_stream_listener *listener, nng_tls_config *tls);
</code></pre>
<p>Both <a href="../../api/stream.html#stream-factories"><code>nng_stream_dialer</code></a> and <a href="../../api/stream.html#stream-factories"><code>nng_stream_listener</code></a> objects may support configuration of <a name="a062"></a>TLS parameters.
The <a name="a063"></a><code>nng_stream_dialer_set_tls</code> and <a name="a064"></a><code>nng_stream_listener_set_tls</code> functions support setting the
configuration of a <a href="../../TODO.html"><code>nng_tls_config</code></a> object supplied by <em>tls</em> on <em>dialer</em> or <em>listener</em>.
This must be performed before the <em>listener</em> starts listening with <a href="../../api/stream.html#accepting-incoming-connections"><code>nng_stream_listener_listen</code></a>, or the dialer starts an outgoing connection
as a result of <a href="../../api/stream.html#making-outgoing-connections"><code>nng_stream_dialer_dial</code></a>.</p>
<p>The configuration object that was previously established (which may be a default if one was not explicitly
configured) can be obtained with the <a name="a065"></a><code>nng_stream_dialer_get_tls</code> and <a name="a066"></a><code>nng_stream_listener_get_tls</code>.
They will return a pointer to the <a href="../../TODO.html"><code>nng_tls_config</code></a> object in question at the location referenced by <em>tlsp</em>.</p>
<div class="mdbook-alerts mdbook-alerts-note">
<p class="mdbook-alerts-title">
<span class="mdbook-alerts-icon"></span>
note
</p>
<p>TLS configuration cannot be changed once it has started being used by a listener or dialer. This applies to
both configuring a different TLS configuration object, as well as mutating the existing <a href="../../TODO.html"><code>nng_tls_config</code></a> object.</p>
</div>
<!-- NOTE: This assumes that any page referencing this is located
in a directory two levels down. Meaning ./api/somefile.md or
similar. mdbook cannot accommodate links that are called from
different levels in the hierarchy. -->
<!-- Symbol cross reference -->
<!-- HTTP -->
<!-- HTTP Status -->
<!-- TLS -->
<!-- Macros -->
<!-- Protocols -->
<!-- Transports -->
<!-- Concept index -->
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../api/errors.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../api/http.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="../api/errors.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../api/http.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script>
window.playground_copyable = true;
</script>
<script src="../elasticlunr.min.js"></script>
<script src="../mark.min.js"></script>
<script src="../searcher.js"></script>
<script src="../clipboard.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
<!-- Custom JS scripts -->
<script src="../theme/pagetoc.js"></script>
</div>
</body>
</html>
|
