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
|
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>NORM Developer's Guide (version 1.5b5)</title><link rel="stylesheet" type="text/css" href="html.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><meta name="description" content="This document describes an application programming interface (API) for the Nack-Oriented Reliable Multicast (NORM) protocol implementation developed by the Protocol Engineering and Advance Networking (PROTEAN) Research Group of the United States Naval Research Laboratory (NRL). The NORM protocol provides general purpose reliable data transport for applications wishing to use Internet Protocol (IP) Multicast services for group data delivery. NORM can also support unicast (point-to-point) data communication and may be used for such when deemed appropriate. The current NORM protocol specification is given in the Internet Engineering Task Force (IETF) RFC 3940. This document is currently a reference guide to the NORM API of the NRL reference implementation. More tutorial material may be include in a future version of this document or a separate developer's tutorial may be created at a later date."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" title="NORM Developer's Guide (version 1.5b5)"><div class="titlepage"><div><div><h2 class="title"><a name="d0e1"></a><span class="inlinemediaobject"><img src="resources/NormLogo.gif" align="middle" width="270"></span> NORM Developer's Guide (version 1.5b5)</h2></div><div><div class="abstract" title="Abstract"><p class="title"><b>Abstract</b></p><p>This document describes an application programming interface (API) for the <a class="ulink" href="http://norm.pf.itd.nrl.navy.mil/" target="_top">Nack-Oriented Reliable Multicast (NORM)</a> protocol implementation developed by the Protocol Engineering and Advance Networking (<a class="ulink" href="http://cs.itd.nrl.navy.mil/" target="_top">PROTEAN</a>) Research Group of the United States <a class="ulink" href="http://www.nrl.navy.mil/" target="_top">Naval Research Laboratory</a> (NRL). The NORM protocol provides general purpose reliable data transport for applications wishing to use Internet Protocol (IP) Multicast services for group data delivery. NORM can also support unicast (point-to-point) data communication and may be used for such when deemed appropriate. The current NORM protocol specification is given in the <a class="ulink" href="http://www.ietf.org/" target="_top">Internet Engineering Task Force</a> (IETF) <a class="ulink" href="http://norm.pf.itd.nrl.navy.mil/rfc3940.pdf" target="_top">RFC 3940</a>. This document is currently a reference guide to the NORM API of the NRL reference implementation. More tutorial material may be include in a future version of this document or a separate developer's tutorial may be created at a later date.</p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#d0e28">1. Background</a></span></dt><dt><span class="sect1"><a href="#d0e52">2. Overview</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d0e88">2.1. API Initialization</a></span></dt><dt><span class="sect2"><a href="#d0e125">2.2. Session Creation and Control</a></span></dt><dt><span class="sect2"><a href="#d0e132">2.3. Data Transport</a></span></dt><dd><dl><dt><span class="sect3"><a href="#d0e152">2.3.1. Data Transmission</a></span></dt><dt><span class="sect3"><a href="#d0e310">2.3.2. Data Reception</a></span></dt></dl></dd><dt><span class="sect2"><a href="#d0e360">2.4. API Event Notification</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d0e405">3. Build Notes</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d0e424">3.1. Unix Platforms</a></span></dt><dt><span class="sect2"><a href="#d0e451">3.2. Win32/WiNCE Platforms</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d0e480">4. API Reference</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d0e485">4.1. API Variable Types and Constants</a></span></dt><dd><dl><dt><span class="sect3"><a href="#NormInstanceHandle">4.1.1. NormInstanceHandle</a></span></dt><dt><span class="sect3"><a href="#NormSessionHandle">4.1.2. NormSessionHandle</a></span></dt><dt><span class="sect3"><a href="#NormSessionId">4.1.3. NormSessionId</a></span></dt><dt><span class="sect3"><a href="#NormNodeHandle">4.1.4. NormNodeHandle</a></span></dt><dt><span class="sect3"><a href="#NormNodeId">4.1.5. NormNodeId</a></span></dt><dt><span class="sect3"><a href="#NormObjectHandle">4.1.6. NormObjectHandle</a></span></dt><dt><span class="sect3"><a href="#NormObjectType">4.1.7. NormObjectType</a></span></dt><dt><span class="sect3"><a href="#NormSize">4.1.8. NormSize</a></span></dt><dt><span class="sect3"><a href="#NormObjectTransportId">4.1.9. NormObjectTransportId</a></span></dt><dt><span class="sect3"><a href="#NormEventType">4.1.10. NormEventType</a></span></dt><dt><span class="sect3"><a href="#NormEvent">4.1.11. NormEvent</a></span></dt><dt><span class="sect3"><a href="#NormDescriptor">4.1.12. NormDescriptor</a></span></dt><dt><span class="sect3"><a href="#NormFlushMode">4.1.13. NormFlushMode</a></span></dt><dt><span class="sect3"><a href="#NormProbingMode">4.1.14. NormProbingMode</a></span></dt><dt><span class="sect3"><a href="#NormSyncPolicy">4.1.15. NormSyncPolicy</a></span></dt><dt><span class="sect3"><a href="#NormNackingMode">4.1.16. NormNackingMode</a></span></dt><dt><span class="sect3"><a href="#NormRepairBoundary">4.1.17. NormRepairBoundary</a></span></dt><dt><span class="sect3"><a href="#NormAckingStatus">4.1.18. NormAckingStatus</a></span></dt></dl></dd><dt><span class="sect2"><a href="#d0e1055">4.2. API Initialization and Operation</a></span></dt><dd><dl><dt><span class="sect3"><a href="#NormCreateInstance">4.2.1. NormCreateInstance()</a></span></dt><dt><span class="sect3"><a href="#NormDestroyInstance">4.2.2. NormDestroyInstance()</a></span></dt><dt><span class="sect3"><a href="#NormStopInstance">4.2.3. NormStopInstance()</a></span></dt><dt><span class="sect3"><a href="#NormRestartInstance">4.2.4. NormRestartInstance()</a></span></dt><dt><span class="sect3"><a href="#NormSetCacheDirectory">4.2.5. NormSetCacheDirectory()</a></span></dt><dt><span class="sect3"><a href="#NormGetNextEvent">4.2.6. NormGetNextEvent()</a></span></dt><dt><span class="sect3"><a href="#NormGetDescriptor">4.2.7. NormGetDescriptor()</a></span></dt></dl></dd><dt><span class="sect2"><a href="#d0e1841">4.3. Session Creation and Control Functions</a></span></dt><dd><dl><dt><span class="sect3"><a href="#NormCreateSession">4.3.1. NormCreateSession()</a></span></dt><dt><span class="sect3"><a href="#NormDestroySession">4.3.2. NormDestroySession()</a></span></dt><dt><span class="sect3"><a href="#NormSetUserData">4.3.3. NormSetUserData()</a></span></dt><dt><span class="sect3"><a href="#NormGetUserData">4.3.4. NormGetUserData()</a></span></dt><dt><span class="sect3"><a href="#NormGetLocalNodeId">4.3.5. NormGetLocalNodeId()</a></span></dt><dt><span class="sect3"><a href="#NormSetTxPort">4.3.6. NormSetTxPort()</a></span></dt><dt><span class="sect3"><a href="#NormSetTxOnly">4.3.7. NormSetTxOnly()</a></span></dt><dt><span class="sect3"><a href="#NormSetRxPortReuse">4.3.8. NormSetRxPortReuse()</a></span></dt><dt><span class="sect3"><a href="#NormSetMulticastInterface">4.3.9. NormSetMulticastInterface()</a></span></dt><dt><span class="sect3"><a href="#NormSetMulticastInterface">4.3.10. NormSetSSM()</a></span></dt><dt><span class="sect3"><a href="#NormSetTTL">4.3.11. NormSetTTL()</a></span></dt><dt><span class="sect3"><a href="#NormSetTOS">4.3.12. NormSetTOS()</a></span></dt><dt><span class="sect3"><a href="#NormSetLoopback">4.3.13. NormSetLoopback()</a></span></dt><dt><span class="sect3"><a href="#NormSetFragmentation">4.3.14. NormSetFragmentation()</a></span></dt></dl></dd><dt><span class="sect2"><a href="#d0e2759">4.4. NORM Sender Functions</a></span></dt><dd><dl><dt><span class="sect3"><a href="#NormStartSender">4.4.1. NormStartSender()</a></span></dt><dt><span class="sect3"><a href="#NormStopSender">4.4.2. NormStopSender()</a></span></dt><dt><span class="sect3"><a href="#NormSetTxRate">4.4.3. NormSetTxRate()</a></span></dt><dt><span class="sect3"><a href="#NormGetTxRate">4.4.4. NormGetTxRate()</a></span></dt><dt><span class="sect3"><a href="#NormSetTxSocketBuffer">4.4.5. NormSetTxSocketBuffer()</a></span></dt><dt><span class="sect3"><a href="#NormSetFlowControl">4.4.6. NormSetFlowControl()</a></span></dt><dt><span class="sect3"><a href="#NormSetCongestionControl">4.4.7. NormSetCongestionControl()</a></span></dt><dt><span class="sect3"><a href="#NormSetTxRateBounds">4.4.8. NormSetTxRateBounds()</a></span></dt><dt><span class="sect3"><a href="#NormSetTxCacheBounds">4.4.9. NormSetTxCacheBounds()</a></span></dt><dt><span class="sect3"><a href="#NormSetAutoParity">4.4.10. NormSetAutoParity()</a></span></dt><dt><span class="sect3"><a href="#NormGetGrttEstimate">4.4.11. NormGetGrttEstimate()</a></span></dt><dt><span class="sect3"><a href="#NormSetGrttEstimate">4.4.12. NormSetGrttEstimate()</a></span></dt><dt><span class="sect3"><a href="#NormSetGrttMax">4.4.13. NormSetGrttMax()</a></span></dt><dt><span class="sect3"><a href="#NormSetGrttProbingMode">4.4.14. NormSetGrttProbingMode()</a></span></dt><dt><span class="sect3"><a href="#NormSetGrttProbingInterval">4.4.15. NormSetGrttProbingInterval()</a></span></dt><dt><span class="sect3"><a href="#NormSetBackoffFactor">4.4.16. NormSetBackoffFactor()</a></span></dt><dt><span class="sect3"><a href="#NormSetGroupSize">4.4.17. NormSetGroupSize()</a></span></dt><dt><span class="sect3"><a href="#NormSetTxRobustFactor">4.4.18. NormSetTxRobustFactor()</a></span></dt><dt><span class="sect3"><a href="#NormFileEnqueue">4.4.19. NormFileEnqueue()</a></span></dt><dt><span class="sect3"><a href="#NormDataEnqueue">4.4.20. NormDataEnqueue()</a></span></dt><dt><span class="sect3"><a href="#NormRequeueObject">4.4.21. NormRequeueObject()</a></span></dt><dt><span class="sect3"><a href="#NormStreamOpen">4.4.22. NormStreamOpen()</a></span></dt><dt><span class="sect3"><a href="#NormStreamClose">4.4.23. NormStreamClose()</a></span></dt><dt><span class="sect3"><a href="#NormStreamWrite">4.4.24. NormStreamWrite()</a></span></dt><dt><span class="sect3"><a href="#NormStreamFlush">4.4.25. NormStreamFlush()</a></span></dt><dt><span class="sect3"><a href="#NormStreamSetAutoFlush">4.4.26. NormStreamSetAutoFlush()</a></span></dt><dt><span class="sect3"><a href="#NormStreamSetPushEnable">4.4.27. NormStreamSetPushEnable()</a></span></dt><dt><span class="sect3"><a href="#NormStreamHasVacancy">4.4.28. NormStreamHasVacancy()</a></span></dt><dt><span class="sect3"><a href="#NormStreamMarkEom">4.4.29. NormStreamMarkEom()</a></span></dt><dt><span class="sect3"><a href="#NormSetWatermark">4.4.30. NormSetWatermark()</a></span></dt><dt><span class="sect3"><a href="#NormCancelWatermark">4.4.31. NormCancelWatermark()</a></span></dt><dt><span class="sect3"><a href="#NormAddAckingNode">4.4.32. NormAddAckingNode()</a></span></dt><dt><span class="sect3"><a href="#NormRemoveAckingNode">4.4.33. NormRemoveAckingNode()</a></span></dt><dt><span class="sect3"><a href="#NormGetNextAckingNode">4.4.34. NormGetNextAckingNode()</a></span></dt><dt><span class="sect3"><a href="#NormGetAckingStatus">4.4.35. NormGetAckingStatus()</a></span></dt><dt><span class="sect3"><a href="#NormSendCommand">4.4.36. NormSendCommand()</a></span></dt><dt><span class="sect3"><a href="#NormCancelCommand">4.4.37. NormCancelCommand()</a></span></dt></dl></dd><dt><span class="sect2"><a href="#d0e5766">4.5. NORM Receiver Functions</a></span></dt><dd><dl><dt><span class="sect3"><a href="#NormStartReceiver">4.5.1. NormStartReceiver()</a></span></dt><dt><span class="sect3"><a href="#NormStopReceiver">4.5.2. NormStopReceiver()</a></span></dt><dt><span class="sect3"><a href="#NormSetRxCacheLimit">4.5.3. NormSetRxCacheLimit()</a></span></dt><dt><span class="sect3"><a href="#NormSetRxSocketBuffer">4.5.4. NormSetRxSocketBuffer()</a></span></dt><dt><span class="sect3"><a href="#NormSetSilentReceiver">4.5.5. NormSetSilentReceiver()</a></span></dt><dt><span class="sect3"><a href="#NormSetDefaultUnicastNack">4.5.6. NormSetDefaultUnicastNack()</a></span></dt><dt><span class="sect3"><a href="#NormNodeSetUnicastNack">4.5.7. NormNodeSetUnicastNack()</a></span></dt><dt><span class="sect3"><a href="#NormSetDefaultSyncPolicy">4.5.8. NormSetDefaultSyncPolicy()</a></span></dt><dt><span class="sect3"><a href="#NormSetDefaultNackingMode">4.5.9. NormSetDefaultNackingMode()</a></span></dt><dt><span class="sect3"><a href="#NormNodeSetNackingMode">4.5.10. NormNodeSetNackingMode()</a></span></dt><dt><span class="sect3"><a href="#NormObjectSetNackingMode">4.5.11. NormObjectSetNackingMode()</a></span></dt><dt><span class="sect3"><a href="#NormSetDefaultRepairBoundary">4.5.12. NormSetDefaultRepairBoundary()</a></span></dt><dt><span class="sect3"><a href="#NormNodeSetRepairBoundary">4.5.13. NormNodeSetRepairBoundary()</a></span></dt><dt><span class="sect3"><a href="#NormSetDefaultRxRobustFactor">4.5.14. NormSetDefaultRxRobustFactor()</a></span></dt><dt><span class="sect3"><a href="#NormNodeSetRxRobustFactor">4.5.15. NormNodeSetRxRobustFactor()</a></span></dt><dt><span class="sect3"><a href="#NormStreamRead">4.5.16. NormStreamRead()</a></span></dt><dt><span class="sect3"><a href="#NormStreamSeekMsgStart">4.5.17. NormStreamSeekMsgStart()</a></span></dt><dt><span class="sect3"><a href="#NormStreamGetReadOffset">4.5.18. NormStreamGetReadOffset()</a></span></dt></dl></dd><dt><span class="sect2"><a href="#d0e6850">4.6. NORM Object Functions</a></span></dt><dd><dl><dt><span class="sect3"><a href="#NormObjectGetType">4.6.1. NormObjectGetType()</a></span></dt><dt><span class="sect3"><a href="#NormObjectHasInfo">4.6.2. NormObjectHasInfo()</a></span></dt><dt><span class="sect3"><a href="#NormObjectGetInfoLength">4.6.3. NormObjectGetInfoLength()</a></span></dt><dt><span class="sect3"><a href="#NormObjectGetInfo">4.6.4. NormObjectGetInfo()</a></span></dt><dt><span class="sect3"><a href="#NormObjectGetSize">4.6.5. NormObjectGetSize()</a></span></dt><dt><span class="sect3"><a href="#NormObjectGetBytesPending">4.6.6. NormObjectGetBytesPending()</a></span></dt><dt><span class="sect3"><a href="#NormObjectCancel">4.6.7. NormObjectCancel()</a></span></dt><dt><span class="sect3"><a href="#NormObjectRetain">4.6.8. NormObjectRetain()</a></span></dt><dt><span class="sect3"><a href="#NormObjectRelease">4.6.9. NormObjectRelease()</a></span></dt><dt><span class="sect3"><a href="#NormFileGetName">4.6.10. NormFileGetName()</a></span></dt><dt><span class="sect3"><a href="#NormFileRename">4.6.11. NormFileRename()</a></span></dt><dt><span class="sect3"><a href="#NormDataAccessData">4.6.12. NormDataAccessData()</a></span></dt><dt><span class="sect3"><a href="#NormDataDetachData">4.6.13. NormDataDetachData()</a></span></dt><dt><span class="sect3"><a href="#NormObjectGetSender">4.6.14. NormObjectGetSender()</a></span></dt></dl></dd><dt><span class="sect2"><a href="#d0e7692">4.7. NORM Node Functions</a></span></dt><dd><dl><dt><span class="sect3"><a href="#NormNodeGetId">4.7.1. NormNodeGetId()</a></span></dt><dt><span class="sect3"><a href="#NormNodeGetAddress">4.7.2. NormNodeGetAddress()</a></span></dt><dt><span class="sect3"><a href="#NormNodeGetGrtt">4.7.3. NormNodeGetGrtt()</a></span></dt><dt><span class="sect3"><a href="#NormNodeGetCommand">4.7.4. NormNodeGetCommand()</a></span></dt><dt><span class="sect3"><a href="#NormNodeFreeBuffers">4.7.5. NormNodeFreeBuffers()</a></span></dt><dt><span class="sect3"><a href="#NormNodeDelete">4.7.6. NormNodeDelete()</a></span></dt><dt><span class="sect3"><a href="#NormNodeRetain">4.7.7. NormNodeRetain()</a></span></dt><dt><span class="sect3"><a href="#NormNodeRelease">4.7.8. NormNodeRelease()</a></span></dt></dl></dd><dt><span class="sect2"><a href="#d0e8179">4.8. NORM Debugging Functions</a></span></dt><dd><dl><dt><span class="sect3"><a href="#NormSetDebugLevel">4.8.1. NormSetDebugLevel()</a></span></dt><dt><span class="sect3"><a href="#NormOpenDebugLog">4.8.2. NormOpenDebugLog()</a></span></dt><dt><span class="sect3"><a href="#NormCloseDebugLog">4.8.3. NormCloseDebugLog()</a></span></dt><dt><span class="sect3"><a href="#NormOpenDebugPipe">4.8.4. NormOpenDebugPipe()</a></span></dt><dt><span class="sect3"><a href="#NormCloseDebugPipe">4.8.5. NormCloseDebugPipe()</a></span></dt></dl></dd></dl></dd></dl></div><div class="sect1" title="1. Background"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e28"></a>1. Background</h2></div></div></div><p>This document describes an application programming interface (API) for the <a class="ulink" href="http://norm.pf.itd.nrl.navy.mil/" target="_top">Nack-Oriented Reliable Multicast (NORM)</a> protocol implementation developed by the Protocol Engineering and Advance Networking (<a class="ulink" href="http://cs.itd.nrl.navy.mil/" target="_top">PROTEAN</a>) Research Group of the United States <a class="ulink" href="http://www.nrl.navy.mil/" target="_top">Naval Research Laboratory</a> (NRL). The NORM protocol provides general purpose reliable data transport for applications wishing to use Internet Protocol (IP) Multicast services for group data delivery. NORM can also support unicast (point-to-point) data communication and may be used for such when deemed appropriate. The current NORM protocol specification is given in the <a class="ulink" href="http://www.ietf.org/" target="_top">Internet Engineering Task Force</a> (IETF) <a class="ulink" href="http://norm.pf.itd.nrl.navy.mil/rfc5740.pdf" target="_top">RFC 5740</a>.</p><p>The NORM protocol is designed to provide end-to-end reliable transport of bulk data objects or streams over generic IP multicast routing and forwarding services. NORM uses a selective, negative acknowledgement (NACK) mechanism for transport reliability and offers additional protocol mechanisms to conduct reliable multicast sessions with limited "a priori" coordination among senders and receivers. A congestion control scheme is specified to allow the NORM protocol to fairly share available network bandwidth with other transport protocols such as Transmission Control Protocol (TCP). It is capable of operating with both reciprocal multicast routing among senders and receivers and with asymmetric connectivity (possibly a unicast return path) from the senders to receivers. The protocol offers a number of features to allow different types of applications or possibly other higher-level transport protocols to utilize its service in different ways. The protocol leverages the use of FEC-based repair and other proven reliable multicast transport techniques in its design.</p><p>The NRL NORM library attempts to provide a general useful capability for development of reliable multicast applications for bulk file or other data delivery as well as support of stream-based transport with possible real-time delivery requirements. The API allows access to many NORM protocol parameters and control functions to tailor performance for specific applications. While default parameters, where provided, can be useful to a potential wide range of requirements, the many different possible group communication paradigms dictate different needs for different applications. Even with NORM, the developer should have a thorough understanding of the specific application's group communication needs.</p></div><div class="sect1" title="2. Overview"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e52"></a>2. Overview</h2></div></div></div><p>The NORM API has been designed to provide simple, straightforward access to and control of NORM protocol state and functions. Functions are provided to create and initialize instances of the NORM API and associated transport sessions (<span class="emphasis"><em>NormSessions</em></span>). Subsequently, NORM data transmission (<span class="emphasis"><em>NormSender</em></span>) operation can be activated and the application can queue various types of data (<span class="emphasis"><em>NormObjects</em></span>) for reliable transport. Additionally or alternatively, NORM reception (<span class="emphasis"><em>NormReceiver</em></span>) operation can also be enabled on a per-session basis and the protocol implementation alerts the application of receive events.</p><p>By default, the NORM API will create an operating system thread in which the NORM protocol engine runs. This allows user application code and the underlying NORM code to execute somewhat independently of one another. The NORM protocol thread notifies the application of various protocol events through a thread-safe event dispatching mechanism and API calls are provided to allow the application to control NORM operation. (Note: API mechanisms for lower-level, non-threaded control and execution of the NORM protocol engine code may also be provided in the future.)</p><p>The NORM API operation can be roughly summarized with the following categories of functions:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>API Initialization</p></li><li class="listitem"><p>Session Creation and Control</p></li><li class="listitem"><p>Data Transport</p></li><li class="listitem"><p>API Event Notification</p></li></ol></div><p>Note the order of these categories roughly reflects the order of function calls required to use NORM in an application. The first step is to create and initialize, as needed, at least one instance of the NORM API. Then one or more NORM transport sessions (where a "session" corresponds to data exchanges on a given multicast group (or unicast address) and host port number) may be created and controlled. Applications may participate as senders and/or receivers within a NORM session. NORM senders transmit data to the session destination address (usually an IP multicast group) while receivers are notified of incoming data. The NORM API provides and event notification scheme to notify the application of significant sender and receiver events. There are also a number support functions provided for the application to control and monitor its participation within a NORM transport session.</p><div class="sect2" title="2.1. API Initialization"><div class="titlepage"><div><div><h3 class="title"><a name="d0e88"></a>2.1. API Initialization</h3></div></div></div><p>The NORM API requires that an application explicitly create at least one instance of the NORM protocol engine that is subsequently used as a conduit for further NORM API calls. By default, the NORM protocol engine runs in its own operating system thread and interacts with the application in a thread-safe manner through the API calls and event dispatching mechanism.</p><p>In general, only a single thread should access the <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a> API call for a given <span class="emphasis"><em>NormInstance</em></span>. This function serves as the conduit for delivering NORM protocol engine events to the application. A NORM application can be designed to be single-threaded, even with multiple active NormSessions, but also multiple API instances can be created (see <a class="link" href="#NormCreateInstance" title="4.2.1. NormCreateInstance()"><code class="literal">NormCreateInstance()</code></a>) as needed for applications with specific requirements for accessing and controlling participation in multiple <span class="emphasis"><em>NormSessions</em></span> from separate operating system multiple threads. Or, alternatively, a single <span class="emphasis"><em>NormInstance</em></span> could be used, with a "master thread" serving as an intermediary between the <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a> function, demultiplexing and dispatching events as appropriate to other "child threads" that are created to handle "per-<span class="emphasis"><em>NormSession</em></span>" input/output. The advantage of this alternative approach is that the end result would be one NORM protocol engine thread plus one "master thread" plus one "child thread" per <span class="emphasis"><em>NormSession</em></span> instead of two threads (protocol engine plus application thread) per <span class="emphasis"><em>NormSession</em></span> if such multi-threaded operation is needed by the application.</p></div><div class="sect2" title="2.2. Session Creation and Control"><div class="titlepage"><div><div><h3 class="title"><a name="d0e125"></a>2.2. Session Creation and Control</h3></div></div></div><p>Once an API instance has been successfully created, the application may then create NORM transport session instances as needed. The application can participate in each session as a sender and/or receiver of data. If an application is participating as a sender, it may enqueue data transport objects for transmission. The control of transmission is largely left to the senders and API calls are provided to control transmission rate, FEC parameters, etc. Applications participating as receivers will be notified via the NORM API's event dispatching mechanism of pending and completed reliable reception of data along with other significant events. Additionally, API controls for some optional NORM protocol mechanisms, such as positive acknowledgment collection, are also provided.</p><p>Note when multiple senders are involved, receivers allocate system resources (buffer space) for each active sender. With a very large number of concurrently active senders, this may translate to significant memory allocation on receiver nodes. Currently, the API allows the application to control how much buffer space is allocated for each active sender (NOTE: In the future, API functions may be provided limit the number of active senders monitored and/or provide the application with finer control over receive buffer allocation, perhaps on a per sender basis).</p></div><div class="sect2" title="2.3. Data Transport"><div class="titlepage"><div><div><h3 class="title"><a name="d0e132"></a>2.3. Data Transport</h3></div></div></div><p>The NORM protocol supports transport of three basic types of data content. These include the types <code class="literal">NORM_OBJECT_FILE</code> and <code class="literal">NORM_OBJECT_DATA</code> which represent predetermined, fixed-size application data content. The only differentiation with respect to these two types is the implicit "hint" to the receiver to use non-volatile (i.e. file system) storage or memory. This "hint" lets the receiver allocate appropriate storage space with no other information on the incoming data. The NORM implementation reads/writes data for the <code class="literal">NORM_OBJECT_FILE</code> type directly from/to file storage, while application memory space is accessed for the <code class="literal">NORM_OBJECT_DATA</code> type. The third data content type, <code class="literal">NORM_OBJECT_STREAM</code>, represents unbounded, possibly persistent, streams of data content. Using this transport paradigm, traditional, byte-oriented streaming transport service (e.g. similar to that provided by a TCP socket) can be provided. Additionally, NORM has provisions for application-defined message-oriented transport where receivers can recover message boundaries without any "handshake" with the sender. Stream content is buffered by the NORM implementation for transmission/retransmission and as it is received.</p><div class="sect3" title="2.3.1. Data Transmission"><div class="titlepage"><div><div><h4 class="title"><a name="d0e152"></a>2.3.1. Data Transmission</h4></div></div></div><p>The behavior of data transport operation is largely placed in the control of the NORM sender(s). NORM senders controls their data transmission rate, forward error correction (FEC) encoding settings, and parameters controlling feedback from the receiver group. Multiple senders may operate in a session, each with independent transmission parameters. NORM receivers learn needed parameter values from fields in NORM message headers.</p><p>NORM transport "objects" (file, data, or stream) are queued for transmission by NORM senders. NORM senders may also cancel transmission of objects at any time. The NORM sender controls the transmission rate either manually (fixed transmission rate) or automatically when NORM congestion control operation is enabled. The NORM congestion control mechanism is designed to be "friendly" to other data flows on the network, fairly sharing available bandwidth.<a class="link" href="#NormSetAutoParity" title="4.4.10. NormSetAutoParity()"><code class="literal">NormSetAutoParity()</code></a>) to achieve reliable transfer) receive object transmission before any extensive repair process that may be required to satisfy other receivers with poor network connectivity. The repair boundary can also be set for individual remote senders using the <a class="link" href="#NormNodeSetRepairBoundary" title="4.5.13. NormNodeSetRepairBoundary()"><code class="literal">NormNodeSetRepairBoundary()</code></a> function.<code class="literal">NORM_OBJECT_FILE</code> objects. This function must be called before any file objects may be received and thus should be called before any calls to <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a> are made. However, note that the cache directory may be changed even during active NORM reception. In this case, the new specified directory path will be used for subsequently-received files. Any files received before a directory path change will remain in the previous cache location. Note that the <a class="link" href="#NormFileRename" title="4.6.11. NormFileRename()"><code class="literal">NormFileRename()</code></a> function may be used to rename, and thus potentially move, received files after reception has begun.</p><p>By default, the NORM sender transmits application-enqueued data content, providing repair transmissions (usually in the form of FEC messages) only when requested by NACKs from the receivers. However, the application may also configure NORM to proactively send some amount of FEC content along with the original data content to create a "robust" transmission that, in some cases, may be reliably received without any NACKing activity. This can allow for some degree of reliable protocol operation even without receiver feedback available. NORM senders may also requeue (within the limits of "transmit cache" settings) objects for repeat transmission, and receivers may combine together multiple transmissions to reliably receive content. Additionally, hybrid proactive/reactive FEC repair operation is possible with the receiver NACK process as a "backup" for when network packet loss exceeds the repair capability of the proactive FEC settings.</p><p>The NRL NORM implementation also supports optional collection of positive acknowledgment from a subset of the receiver group at application-determined positions during data transmission. The NORM API allows the application to specify the receiver subset ("acking node list") and set "watermark" points for which positive acknowledgement is collected. This process can provide the application with explicit flow control for an application-determined critical set of receivers in the group.</p><p>For a NORM application to perform data transmission, it must first create a session using <a class="link" href="#NormCreateSession" title="4.3.1. NormCreateSession()"><code class="literal">NormCreateSession()</code></a> and make a call to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> before sending actual user data. The functions <a class="link" href="#NormFileEnqueue" title="4.4.19. NormFileEnqueue()"><code class="literal">NormFileEnqueue()</code></a>, <a class="link" href="#NormDataEnqueue" title="4.4.20. NormDataEnqueue()"><code class="literal">NormDataEnqueue()</code></a>, and <a class="link" href="#NormStreamWrite" title="4.4.24. NormStreamWrite()"><code class="literal">NormStreamWrite()</code></a> are available for the application to pass data to the NORM protocol engine for transmission. Note that to use <a class="link" href="#NormStreamWrite" title="4.4.24. NormStreamWrite()"><code class="literal">NormStreamWrite()</code></a>, a "sender stream" must first be created using <a class="link" href="#NormStreamOpen" title="4.4.22. NormStreamOpen()"><code class="literal">NormStreamOpen()</code></a>. In the case of <a class="link" href="#NormFileEnqueue" title="4.4.19. NormFileEnqueue()"><code class="literal">NormFileEnqueue()</code></a> and <a class="link" href="#NormDataEnqueue" title="4.4.20. NormDataEnqueue()"><code class="literal">NormDataEnqueue()</code></a>, the NORM protocol engine directly accesses the application file or memory space to refer to the transmitted content and does not make its own copy of this data.</p><p>The calls to enqueue transport objects or write to a stream may be called at any time, but the <code class="literal">NORM_TX_QUEUE_EMPTY</code> and <code class="literal">NORM_TX_QUEUE_VACANCY</code> notification events (see <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a>) provide useful cues for when these functions may be successfully called. Typically, an application might catch both <code class="literal">NORM_TX_QUEUE_EMPTY</code> and <code class="literal">NORM_TX_QUEUE_VACANCY</code> event types as cues for enqueuing additional transport objects or writing to a stream. However, an application may choose to cue off of <code class="literal">NORM_TX_QUEUE_EMPTY</code> only if it wishes to provide the "freshest" data to NORM for transmission. The advantage of additionally using <code class="literal">NORM_TX_QUEUE_VACANCY</code> is that if the application uses this cue to fill up NORM transport object or stream buffers, it can keep the NORM stream busy sending data and realize the highest possible transmission rate when attempting very high speed communication (Otherwise, the NORM protocol engine may experience some "dead air time" waiting for the application thread to respond to a <code class="literal">NORM_TX_QUEUE_EMPTY</code> event). Note the sender application can control buffer depths as needed with the <a class="link" href="#NormSetTxCacheBounds" title="4.4.9. NormSetTxCacheBounds()"><code class="literal">NormSetTxCacheBounds()</code></a> and <a class="link" href="#NormStreamOpen" title="4.4.22. NormStreamOpen()"><code class="literal">NormStreamOpen()</code></a> calls. Additionally, it is possible for applications to configure the transmit object "cache" (see <a class="link" href="#NormSetTxCacheBounds" title="4.4.9. NormSetTxCacheBounds()"><code class="literal">NormSetTxCacheBounds()</code></a>) and use the <a class="link" href="#NormRequeueObject" title="4.4.21. NormRequeueObject()"><code class="literal">NormRequeueObject()</code></a> call (for objects that have not yet received a <em class="parameter"><code>NORM_TX_OBJECT_PURGED</code></em> notification) to effect a sort of "data carousel" operation with repeated transmission of the cached objects. The <em class="parameter"><code>NORM_TX_OBJECT_SENT</code></em> notification can be used a cue to properly control the "requeue" cycle(s).</p><p>The NORM implementation provides a form of timer-based flow control that limits how quickly sender applications may enqueue new objects or stream data for transmission. The <a class="link" href="#NormSetFlowControl" title="4.4.6. NormSetFlowControl()"><code class="literal">NormSetFlowControl()</code></a> call is provided to control this behavior, including the option to disable it. This timer-based mechanism is a type of "soft" flow control by allowing receivers "sufficient" time to request repair of pending data the sender has enqueued. A more explicit form of flow control using the optional "watermark flushing" mechanism is described below.</p><p>Another cue that can be leveraged by the sender application to determine when it is appropriate to enqueue (or write) additional data for transmission is the <code class="literal">NORM_TX_WATERMARK_COMPLETED</code> event. This event is posted when the flushing or explicit positive acknowledgment collection process has completed for a "watermark" point in transmission that was set by the sender (see <a class="link" href="#NormSetWatermark" title="4.4.30. NormSetWatermark()"><code class="literal">NormSetWatermark()</code></a> and <a class="link" href="#NormAddAckingNode" title="4.4.32. NormAddAckingNode()"><code class="literal">NormAddAckingNode()</code></a>). A list of <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> values can be supplied from which explicit acknowledgement is expected and/or the <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> <code class="literal">NORM_NODE_NONE</code> can be set (using <a class="link" href="#NormAddAckingNode" title="4.4.32. NormAddAckingNode()"><code class="literal">NormAddAckingNode()</code></a>) for completion of a NACK-based version of the watermark flushing procedure. This flushing process can be used as a flow control mechanism for NORM applications. Note this is distinct from NORM's congestion control mechanism that, while it provides network-friendly transmission rate control, does guarantee flow control to receiving nodes.<code class="literal">NORM_NODE_NONE</code> can be set (using <a class="link" href="#NormAddAckingNode" title="4.4.32. NormAddAckingNode()"><code class="literal">NormAddAckingNode()</code></a>) for completion of a NACK-based version of the watermark flushing procedure. This flushing process can be used as a flow control mechanism for NORM applications. Note this is distinct from NORM's congestion control mechanism that, while it provides network-friendly transmission rate control, does guarantee flow control to receiving nodes.</p></div><div class="sect3" title="2.3.2. Data Reception"><div class="titlepage"><div><div><h4 class="title"><a name="d0e310"></a>2.3.2. Data Reception</h4></div></div></div><p>NORM receiver applications learn of active senders and their corresponding pending and completed data transfers, etc via the API event dispatching mechanism. By default, NORM receivers use NACK messages to request repair of transmitted content from the originating sender as needed to achieve reliable transfer. Some API functions are available to provide some additional control over the NACKing behavior, such as initially NACKing for <code class="literal">NORM_INFO</code> content only or even to the extent of disabling receiver feedback (silent receiver or emission-controlled (EMCON) operation) entirely. Otherwise, the parameters and operation of reliable data transmission are left to sender applications and receivers learn of sender parameters in NORM protocol message headers and are instructed by <code class="literal">NORM_CMD</code> messages from the sender(s).</p><p>With respect to the NORM API, the receiver application is informed of new senders and receive data objects via the the <em class="parameter"><code>NORM_REMOTE_SENDER_NEW</code></em> and <em class="parameter"><code>NORM_RX_OBJECT_NEW</code></em> notifications, respectfully. Additionally, object reception progress is indicated with the <em class="parameter"><code>NORM_RX_OBJECT_UPDATED</code></em> notification and this also serves as an indicator for the <em class="parameter"><code>NORM_OBJECT_STREAM</code></em> type that the receive application should make calls to <a class="link" href="#NormStreamRead" title="4.5.16. NormStreamRead()"><code class="literal">NormStreamRead()</code></a> to read newly received stream content. NORM sender status is also conveyed via the <em class="parameter"><code>NORM_REMOTE_SENDER_ACTIVE</code></em> and NORM_REMOTE_SENDER_INACTIVE notifications. For example, the receiver application may use the <em class="parameter"><code>NORM_REMOTE_SENDER_INACTIVE</code></em> as a cue to make calls to <a class="link" href="#NormNodeFreeBuffers" title="4.7.5. NormNodeFreeBuffers()"><code class="literal">NormNodeFreeBuffers()</code></a> and/or <a class="link" href="#NormNodeDelete" title="4.7.6. NormNodeDelete()"><code class="literal">NormNodeDelete()</code></a> to free memory resources allocated for buffering received content for the given sender. The amount of memory allocated <span class="emphasis"><em>per sender</em></span> is set in the <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a> call.</p></div></div><div class="sect2" title="2.4. API Event Notification"><div class="titlepage"><div><div><h3 class="title"><a name="d0e360"></a>2.4. API Event Notification</h3></div></div></div><p>An asynchronous event dispatching mechanism is provided to notify the application of significant NORM protocol events. The centerpiece of this is the <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a> function that can be used to retrieve the next NORM protocol engine event in the form of a <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> structure. This function will typically block until a <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> occurs. However, non-blocking operation may be achieved by using the <a class="link" href="#NormGetDescriptor" title="4.2.7. NormGetDescriptor()"><code class="literal">NormGetDescriptor()</code></a> call to get a <a class="link" href="#NormDescriptor" title="4.1.12. NormDescriptor"><span class="type">NormDescriptor</span></a> (file descriptor) value (Unix <span class="type">int</span> or Win32 <span class="type">HANDLE</span>) suitable for use in a asynchronous I/O monitoring functions such as the Unix <code class="function">select()</code> or Win32 <code class="function">MsgWaitForMultipleObjects()</code> system calls. The a <a class="link" href="#NormDescriptor" title="4.1.12. NormDescriptor"><span class="type">NormDescriptor</span></a> will be signaled when a <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> is available. For Win32 platforms, dispatching of a user-defined Windows message for NORM event notification is also planned for a future update to the NORM API.</p></div></div><div class="sect1" title="3. Build Notes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e405"></a>3. Build Notes</h2></div></div></div><p>To build applications that use the NORM library, a path to the "normApi.h" header file must be provided and the linker step needs to reference the NORM library file ("<code class="filename">libnorm.a</code>" for Unix platforms and "<code class="filename">Norm.lib</code>" for Win32 platforms). NORM also depends upon the NRL Protean Protocol Prototyping toolkit "Protokit" library (a.k.a "Protolib") (static library files "<code class="filename">libProtokit.a</code>" for Unix and "<code class="filename">Protokit.lib</code>" for Win32). Shared or dynamically-linked versions of these libraries may also be built from the NORM source code or provided. Depending upon the platform, some additional library dependencies may be required to support the needs of NORM and/or Protokit. These are described below.</p><p>The "makefiles" directory contains Unix Makefiles for various platforms the "win32" and "wince" sub-directories there contain Microsoft Visual C++ (VC++) and Embedded VC++ project files for building the NORM implementation. Additionally, a "waf" (Python-based build tool) build option is supported that can be used to build and install the NORM library code on the supported platforms. Finally, Python and Java bindings to the NORM API are included and "src/python" and "src/java" directories contain the code for these and the "makefiles/java" directory contains Makefiles to build the NORM Java JNI bindings. Note the "waf" tool can also be used to build the Java and Python bindings.</p><div class="sect2" title="3.1. Unix Platforms"><div class="titlepage"><div><div><h3 class="title"><a name="d0e424"></a>3.1. Unix Platforms</h3></div></div></div><p>NORM has been built and tested on Linux (various architectures), MacOS (BSD), Solaris, and IRIX (SGI) platforms. The code should be readily portable to other Unix platforms.</p><p>To support IPv6 operation, the NORM and the Protokit library must be compiled with the "<code class="constant">HAVE_IPV6</code>" macro defined. This is default in the NORM and Protokit Makefiles for platforms that support IPv6. It is important that NORM and Protokit be built with this macro defined the same. With NORM, it is recommended that "large file support" options be enabled when possible.</p><p>The NORM API uses threading so that the NORM protocol engine may run independent of the application. Thus the "POSIX Threads" library must be included ("-pthread") in the linking step. MacOS/BSD also requires the addition of the "-lresolv" (resolver) library and Solaris requires the dynamic loader, network/socket, and resolver libraries ("-lnsl -lsocket -lresolv") to achieve successful compilation. The Makefiles in the NORM source code distribution are a reference for these requirements. Note that MacOS 9 and earlier are not supported.</p><p>Additionally, it is critical that the _<code class="constant">FILE_OFFSET_BITS</code> macro be consistently defined for the NORM library build and the application build using the library. The distributed NORM Makefiles have <code class="constant">-D_FILE_OFFSET_BITS=64</code> set in the compilation to enable "large file support". Applications built using NORM should have the same compilation option set to operate correctly (The definition of the <a class="link" href="#NormSize" title="4.1.8. NormSize"><code class="literal">NormSize</code></a> type in "<code class="filename">normApi.h</code>" depends upon this compilation flag).</p></div><div class="sect2" title="3.2. Win32/WiNCE Platforms"><div class="titlepage"><div><div><h3 class="title"><a name="d0e451"></a>3.2. Win32/WiNCE Platforms</h3></div></div></div><p>NORM has been built using Microsoft's Visual C++ (6.0 and .NET) and Embedded VC++ 4.2 environments. In addition to proper macro definitions (e.g., HAVE_IPV6, etc) that are included in the respective "Protokit" and "NORM" project files, it is important that common code generation settings be used when building the NORM application. The NORM and Protokit projects are built with the "Multi-threading DLL" library usage set. The NORM API requires multi-threading support. This is a critical setting and numerous compiler and linker errors will result if this is not properly set for your application project.</p><p>NORM and Protokit also depend on the Winsock 2.0 ("<code class="filename">ws2_32.lib</code>" (or "<code class="filename">ws2.lib</code>" (WinCE)) and the IP Helper API ("<code class="filename">iphlpapi.lib</code>") libraries and these must be included in the project "Link" attributes.</p><p>An additional note is that a bug in VC++ 6.0 and earlier compilers (includes embedded VC++ 4.x compilers) prevent compilation of Protokit-based code with debugging capabilities enabled. However, this has been resolved in VC++ .NET and is hoped to be resolved in the future for the WinCE build tools.</p><p>Operation on Windows NT4 (and perhaps other older Windows operating systems) requires that the compile time macro <code class="constant">WINVER=0x0400</code> defined. This is because the version of the IP Helper API library (<code class="filename">iphlpapi.lib</code>) used by <span class="emphasis"><em>Protolib</em></span> (and hence NORM) for this system doesn't support some of the functions defined for this library. This may be related to IPv6 support issues so it may be possible that the Protolib build could be tweaked to provide a single binary executable suitable for IPv4 operation only across a large range of Windows platforms.</p></div></div><div class="sect1" title="4. API Reference"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e480"></a>4. API Reference</h2></div></div></div><p>This section provides a reference to the NORM API variable types, constants and functions.</p><div class="sect2" title="4.1. API Variable Types and Constants"><div class="titlepage"><div><div><h3 class="title"><a name="d0e485"></a>4.1. API Variable Types and Constants</h3></div></div></div><p>The NORM API defines and enumerates a number of supporting variable types and values which are used in different function calls. The variable types are described here.</p><div class="sect3" title="4.1.1. NormInstanceHandle"><div class="titlepage"><div><div><h4 class="title"><a name="NormInstanceHandle"></a>4.1.1. NormInstanceHandle</h4></div></div></div><p>The <a class="link" href="#NormInstanceHandle" title="4.1.1. NormInstanceHandle"><code class="literal">NormInstanceHandle</code></a> type is returned when a NORM API instance is created (see <a class="link" href="#NormCreateInstance" title="4.2.1. NormCreateInstance()"><code class="literal">NormCreateInstance()</code></a>). This handle can be subsequently used for API calls which require reference to a specific NORM API instance. By default, each NORM API instance instantiated creates an operating system thread for protocol operation. Note that multiple NORM transport sessions may be created for a single API instance. In general, it is expected that applications will create a single NORM API instance, but some multi-threaded application designs may prefer multiple corresponding NORM API instances. The value <code class="literal">NORM_INSTANCE_INVALID</code> corresponds to an invalid API instance.</p></div><div class="sect3" title="4.1.2. NormSessionHandle"><div class="titlepage"><div><div><h4 class="title"><a name="NormSessionHandle"></a>4.1.2. NormSessionHandle</h4></div></div></div><p>The <a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> type is used to reference NORM transport sessions which have been created using the <a class="link" href="#NormCreateSession" title="4.3.1. NormCreateSession()"><code class="literal">NormCreateSession()</code></a> API call. Multiple <a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> values may be associated with a given <a class="link" href="#NormInstanceHandle" title="4.1.1. NormInstanceHandle"><code class="literal">NormInstanceHandle</code></a>. The special value <code class="literal">NORM_SESSION_INVALID</code> is used to refer to invalid session references.</p></div><div class="sect3" title="4.1.3. NormSessionId"><div class="titlepage"><div><div><h4 class="title"><a name="NormSessionId"></a>4.1.3. NormSessionId</h4></div></div></div><p>The <a class="link" href="#NormSessionId" title="4.1.3. NormSessionId"><code class="literal">NormSessionId</code></a> type is used by applications to uniquely identify their instance of participation as a sender within a <span class="emphasis"><em>NormSession</em></span>. This type is a parameter to the <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> function. Robust applications can use different <a class="link" href="#NormSessionId" title="4.1.3. NormSessionId"><code class="literal">NormSessionId</code></a> values when initiating sender operation so that receivers can discriminate when a sender has terminated and restarted (whether intentional or due to system failure). For example, an application could cache its prior <a class="link" href="#NormSessionId" title="4.1.3. NormSessionId"><code class="literal">NormSessionId</code></a> value in non-volatile storage which could then be recovered and incremented (for example) upon system restart to produce a new value. The <a class="link" href="#NormSessionId" title="4.1.3. NormSessionId"><code class="literal">NormSessionId</code></a> value is used for the value of the instance_id field in NORM protocol sender messages (see the NORM protocol specification) and receivers use this field to detect sender restart within a <span class="emphasis"><em>NormSession</em></span>.</p></div><div class="sect3" title="4.1.4. NormNodeHandle"><div class="titlepage"><div><div><h4 class="title"><a name="NormNodeHandle"></a>4.1.4. NormNodeHandle</h4></div></div></div><p>The <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> type is used to reference state kept by the NORM implementation with respect to other participants within a <span class="emphasis"><em>NormSession</em></span>. Most typically, the <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> is used by receiver applications to dereference information about remote senders of data as needed. The special value <code class="literal">NORM_NODE_INVALID</code> corresponds to an invalid reference.</p></div><div class="sect3" title="4.1.5. NormNodeId"><div class="titlepage"><div><div><h4 class="title"><a name="NormNodeId"></a>4.1.5. NormNodeId</h4></div></div></div><p>The <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> type corresponds to a 32-bit numeric value which should uniquely identify a participant (node) in a given <span class="emphasis"><em>NormSession</em></span>. The <a class="link" href="#NormNodeGetId" title="4.7.1. NormNodeGetId()"><code class="literal">NormNodeGetId()</code></a> function can be used to retrieve this value given a valid <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a>. The special value <code class="literal">NORM_NODE_NONE</code> corresponds to an invalid (or null) node while the value <code class="literal">NORM_NODE_ANY</code> serves as a wild card value for some functions.</p></div><div class="sect3" title="4.1.6. NormObjectHandle"><div class="titlepage"><div><div><h4 class="title"><a name="NormObjectHandle"></a>4.1.6. NormObjectHandle</h4></div></div></div><p>The <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> type is used to reference state kept for data transport objects being actively transmitted or received. The state kept for NORM transport objects is temporary, but the NORM API provides a function to persistently retain state associated with a sender or receiver <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> (see <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a>) if needed. For sender objects, unless explicitly retained, the <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> can be considered valid until the referenced object is explicitly canceled (see <a class="link" href="#NormObjectCancel" title="4.6.7. NormObjectCancel()"><code class="literal">NormObjectCancel()</code></a>) or purged from the sender transmission queue (see the event <code class="literal">NORM_TX_OBJECT_PURGED</code>). For receiver objects, these handles should be treated as valid only until a subsequent call to <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a> unless, again, specifically retained. The special value <code class="literal">NORM_OBJECT_INVALID</code> corresponds to an invalid transport object reference.</p></div><div class="sect3" title="4.1.7. NormObjectType"><div class="titlepage"><div><div><h4 class="title"><a name="NormObjectType"></a>4.1.7. NormObjectType</h4></div></div></div><p>The <a class="link" href="#NormObjectType" title="4.1.7. NormObjectType"><code class="literal">NormObjectType</code></a> type is an enumeration of possible NORM data transport object types. As previously mentioned, valid types include:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><code class="literal">NORM_OBJECT_FILE</code></p></li><li class="listitem"><p><code class="literal">NORM_OBJECT_DATA</code>, and</p></li><li class="listitem"><p><code class="literal">NORM_OBJECT_STREAM</code></p></li></ol></div><p>Given a <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a>, the application may determine an object's type using the <a class="link" href="#NormObjectGetType" title="4.6.1. NormObjectGetType()"><code class="literal">NormObjectGetType()</code></a> function call. A special <a class="link" href="#NormObjectType" title="4.1.7. NormObjectType"><code class="literal">NormObjectType</code></a> value, <code class="literal">NORM_OBJECT_NONE</code>, indicates an invalid object type.</p></div><div class="sect3" title="4.1.8. NormSize"><div class="titlepage"><div><div><h4 class="title"><a name="NormSize"></a>4.1.8. NormSize</h4></div></div></div><p>The <a class="link" href="#NormSize" title="4.1.8. NormSize"><code class="literal">NormSize</code></a> is the type used for <span class="emphasis"><em>NormObject</em></span> size information. For example, the <a class="link" href="#NormObjectGetSize" title="4.6.5. NormObjectGetSize()"><code class="literal">NormObjectGetSize()</code></a> function returns a value of type <a class="link" href="#NormSize" title="4.1.8. NormSize"><code class="literal">NormSize</code></a>. The range of <a class="link" href="#NormSize" title="4.1.8. NormSize"><code class="literal">NormSize</code></a> values depends upon the operating system and NORM library compilation settings. With "large file support" enabled, as is the case with distributed NORM library "Makefiles", the <a class="link" href="#NormSize" title="4.1.8. NormSize"><code class="literal">NormSize</code></a> type is a 64-bit integer. However, some platforms may support only 32-bit object sizes.</p></div><div class="sect3" title="4.1.9. NormObjectTransportId"><div class="titlepage"><div><div><h4 class="title"><a name="NormObjectTransportId"></a>4.1.9. NormObjectTransportId</h4></div></div></div><p>The <a class="link" href="#NormObjectTransportId" title="4.1.9. NormObjectTransportId"><code class="literal">NormObjectTransportId</code></a> type is a 16-bit numerical value assigned to <span class="emphasis"><em>NormObjects</em></span> by senders during active transport. These values are temporarily unique with respect to a given sender within a <span class="emphasis"><em>NormSession</em></span> and may be "recycled" for use for future transport objects. NORM sender nodes assign these values in a monotonically increasing fashion during the course of a session as part of protocol operation. Typically, the application should not need access to these values, but an API call such as <code class="function">NormObjectGetTransportId()</code> (<span class="emphasis"><em>TBD</em></span>) may be provided to retrieve these values if needed. (Note this type may be deprecated; i.e., it may not be needed at since the <a class="link" href="#NormRequeueObject" title="4.4.21. NormRequeueObject()"><code class="function">NormRequeueObject()</code></a> function is implemented using handles only, but _some_ applications requiring persistence even after a system reboot may need the ability to recall previous transport ids?)</p></div><div class="sect3" title="4.1.10. NormEventType"><div class="titlepage"><div><div><h4 class="title"><a name="NormEventType"></a>4.1.10. NormEventType</h4></div></div></div><p>The <a class="link" href="#NormEventType" title="4.1.10. NormEventType"><code class="literal">NormEventType</code></a> is an enumeration of NORM API events. "Events" are used by the NORM API to signal the application of significant NORM protocol operation events (e.g., receipt of a new receive object, etc). A description of possible <a class="link" href="#NormEventType" title="4.1.10. NormEventType"><code class="literal">NormEventType</code></a> values and their interpretation is given below. The function call <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a> is used to retrieve events from the NORM protocol engine.</p></div><div class="sect3" title="4.1.11. NormEvent"><div class="titlepage"><div><div><h4 class="title"><a name="NormEvent"></a>4.1.11. NormEvent</h4></div></div></div><p>The <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> type is a structure used to describe significant NORM protocol events. This structure is defined as follows:</p><pre class="programlisting">typedef struct
{
NormEventType type;
<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> session;
<a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> node;
<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> object;
} <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a>;</pre><p>The <em class="parameter"><code>type</code></em> field indicates the <a class="link" href="#NormEventType" title="4.1.10. NormEventType"><code class="literal">NormEventType</code></a> and determines how the other fields should be interpreted. Note that not all <a class="link" href="#NormEventType" title="4.1.10. NormEventType"><code class="literal">NormEventType</code></a> fields are relevant to all events. The <em class="parameter"><code>session</code></em>, <em class="parameter"><code>node</code></em>, and <em class="parameter"><code>object</code></em> fields indicate the applicable <a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a>, <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a>, and <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a>, respectively, to which the event applies. NORM protocol events are made available to the application via the <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a> function call.</p></div><div class="sect3" title="4.1.12. NormDescriptor"><div class="titlepage"><div><div><h4 class="title"><a name="NormDescriptor"></a>4.1.12. NormDescriptor</h4></div></div></div><p>The <a class="link" href="#NormDescriptor" title="4.1.12. NormDescriptor"><code class="literal">NormDescriptor</code></a> type can provide a reference to a corresponding file descriptor (Unix <span class="type">int</span> or Win32 <span class="type">HANDLE</span>) for the <span class="emphasis"><em>NormInstance</em></span>. For a given <a class="link" href="#NormInstanceHandle" title="4.1.1. NormInstanceHandle"><code class="literal">NormInstanceHandle</code></a>, the <a class="link" href="#NormGetDescriptor" title="4.2.7. NormGetDescriptor()"><code class="literal">NormGetDescriptor()</code></a> function can be used to retrieve a <a class="link" href="#NormDescriptor" title="4.1.12. NormDescriptor"><code class="literal">NormDescriptor</code></a> value that may, in turn, used in appropriate system calls (e.g. <code class="function">select()</code> or <code class="function">MsgWaitForMultipleObjects()</code>) to asynchronously monitor the NORM protocol engine for notification events (see <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> description).</p></div><div class="sect3" title="4.1.13. NormFlushMode"><div class="titlepage"><div><div><h4 class="title"><a name="NormFlushMode"></a>4.1.13. NormFlushMode</h4></div></div></div><p>The <a class="link" href="#NormFlushMode" title="4.1.13. NormFlushMode"><code class="literal">NormFlushMode</code></a> type consists of the following enumeration:</p><pre class="programlisting">enum <a class="link" href="#NormFlushMode" title="4.1.13. NormFlushMode"><code class="literal">NormFlushMode</code></a>
<code class="literal">{
NORM_FLUSH_NON</code>E<code class="literal">,
NORM_FLUSH_PASSIV</code>E<code class="literal">,
NORM_FLUSH_ACTIV</code>E
};</pre><p>The use and interpretation of these values is given in the descriptions of <a class="link" href="#NormStreamFlush" title="4.4.25. NormStreamFlush()"><code class="literal">NormStreamFlush()</code></a> and <a class="link" href="#NormStreamSetAutoFlush" title="4.4.26. NormStreamSetAutoFlush()"><code class="literal">NormStreamSetAutoFlush()</code></a> functions.</p></div><div class="sect3" title="4.1.14. NormProbingMode"><div class="titlepage"><div><div><h4 class="title"><a name="NormProbingMode"></a>4.1.14. NormProbingMode</h4></div></div></div><p>The <a class="link" href="#NormProbingMode" title="4.1.14. NormProbingMode"><code class="literal">NormProbingMode</code></a> type consists of the following enumeration:</p><pre class="programlisting">enum <a class="link" href="#NormProbingMode" title="4.1.14. NormProbingMode"><code class="literal">NormProbingMode</code></a>
{
<code class="literal">NORM_PROBE_NON</code>E<code class="literal">,
NORM_PROBE_PASSIV</code>E<code class="literal">,
NORM_PROBE_ACTIV</code>E
};</pre><p>The use and interpretation of these values is given in the description of <a class="link" href="#NormSetGrttProbingMode" title="4.4.14. NormSetGrttProbingMode()"><code class="literal">NormSetGrttProbingMode()</code></a> function.</p></div><div class="sect3" title="4.1.15. NormSyncPolicy"><div class="titlepage"><div><div><h4 class="title"><a name="NormSyncPolicy"></a>4.1.15. NormSyncPolicy</h4></div></div></div><p>The <a class="link" href="#NormSyncPolicy" title="4.1.15. NormSyncPolicy"><code class="literal">NormSyncPolicy</code></a> type consists of the following enumeration:</p><pre class="programlisting">enum <a class="link" href="#NormSyncPolicy" title="4.1.15. NormSyncPolicy"><code class="literal">NormSyncPolicy</code></a>
{
<code class="literal">NORM_SYNC_CURRENT</code><code class="literal">,
NORM_</code>SYNC_ALL<code class="literal">
};</code></pre><p>The use and interpretation of these values is given in the descriptions of the <a class="link" href="#NormSetDefaultSyncPolicy" title="4.5.8. NormSetDefaultSyncPolicy()"><code class="literal">NormSetDefaultSyncPolicy()</code></a> function.</p></div><div class="sect3" title="4.1.16. NormNackingMode"><div class="titlepage"><div><div><h4 class="title"><a name="NormNackingMode"></a>4.1.16. NormNackingMode</h4></div></div></div><p>The <a class="link" href="#NormNackingMode" title="4.1.16. NormNackingMode"><code class="literal">NormNackingMode</code></a> type consists of the following enumeration:</p><pre class="programlisting">enum <a class="link" href="#NormNackingMode" title="4.1.16. NormNackingMode"><code class="literal">NormNackingMode</code></a>
{
<code class="literal">NORM_NACK_NON</code>E<code class="literal">,
NORM_NACK_INFO_ONL</code>Y,
<code class="literal">NORM_NACK_NORMAL
};</code></pre><p>The use and interpretation of these values is given in the descriptions of the <a class="link" href="#NormSetDefaultNackingMode" title="4.5.9. NormSetDefaultNackingMode()"><code class="literal">NormSetDefaultNackingMode()</code></a>, <a class="link" href="#NormNodeSetNackingMode" title="4.5.10. NormNodeSetNackingMode()"><code class="literal">NormNodeSetNackingMode()</code></a> and <a class="link" href="#NormObjectSetNackingMode" title="4.5.11. NormObjectSetNackingMode()"><code class="literal">NormObjectSetNackingMode()</code></a> functions.</p></div><div class="sect3" title="4.1.17. NormRepairBoundary"><div class="titlepage"><div><div><h4 class="title"><a name="NormRepairBoundary"></a>4.1.17. NormRepairBoundary</h4></div></div></div><p>The <a class="link" href="#NormRepairBoundary" title="4.1.17. NormRepairBoundary"><code class="literal">NormRepairBoundary</code></a> types consists of the following enumeration:</p><pre class="programlisting">enum <a class="link" href="#NormRepairBoundary" title="4.1.17. NormRepairBoundary"><code class="literal">NormRepairBoundary</code></a>
{<code class="literal">
NORM_BOUNDARY_BLOC</code>K,
N<code class="literal">ORM_BOUNDARY_OBJECT
};</code></pre><p>The interpretation of these values is given in the descriptions of the <a class="link" href="#NormSetDefaultRepairBoundary" title="4.5.12. NormSetDefaultRepairBoundary()"><code class="literal">NormSetDefaultRepairBoundary()</code></a> and <a class="link" href="#NormNodeSetRepairBoundary" title="4.5.13. NormNodeSetRepairBoundary()"><code class="literal">NormNodeSetRepairBoundary()</code></a> functions.</p></div><div class="sect3" title="4.1.18. NormAckingStatus"><div class="titlepage"><div><div><h4 class="title"><a name="NormAckingStatus"></a>4.1.18. NormAckingStatus</h4></div></div></div><p>The <a class="link" href="#NormAckingStatus" title="4.1.18. NormAckingStatus"><code class="literal">NormAckingStatus</code></a> consist of the following enumeration:</p><pre class="programlisting">enum <a class="link" href="#NormAckingStatus" title="4.1.18. NormAckingStatus"><code class="literal">NormAckingStatus</code></a>
{
<code class="literal">NORM_ACK_INVALID</code>,<code class="literal">
NORM_ACK_FAILUR</code>E<code class="literal">,
NORM_ACK_PENDIN</code>G,
<code class="literal">NORM_ACK_SUCCES</code>S
};</pre><p>The interpretation of these values is given in the descriptions of the <a class="link" href="#NormGetAckingStatus" title="4.4.35. NormGetAckingStatus()"><code class="literal">NormGetAckingStatus()</code></a> function.</p></div></div><div class="sect2" title="4.2. API Initialization and Operation"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1055"></a>4.2. API Initialization and Operation</h3></div></div></div><p>The first step in using the NORM API is to create an "instance" of the NORM protocol engine. Note that multiple instances may be created by the application if necessary, but generally only a single instance is required since multiple <span class="emphasis"><em>NormSessions</em></span> may be managed under a single NORM API instance.</p><div class="sect3" title="4.2.1. NormCreateInstance()"><div class="titlepage"><div><div><h4 class="title"><a name="NormCreateInstance"></a>4.2.1. NormCreateInstance()</h4></div></div></div><div class="sect4" title="4.2.1.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1066"></a>4.2.1.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
<a class="link" href="#NormInstanceHandle" title="4.1.1. NormInstanceHandle"><code class="literal">NormInstanceHandle</code></a> <a class="link" href="#NormCreateInstance" title="4.2.1. NormCreateInstance()"><code class="literal">NormCreateInstance</code></a>(bool <em class="parameter"><code>priorityBoost</code></em> = false);</pre></div><div class="sect4" title="4.2.1.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1082"></a>4.2.1.2. Description</h5></div></div></div><p>This function creates an instance of a NORM protocol engine and is the necessary first step before any other API functions may be used. With the instantiation of the NORM protocol engine, an operating system thread is created for protocol execution. The returned <a class="link" href="#NormInstanceHandle" title="4.1.1. NormInstanceHandle"><code class="literal">NormInstanceHandle</code></a> value may be used in subsequent API calls as needed, such <a class="link" href="#NormCreateSession" title="4.3.1. NormCreateSession()"><code class="literal">NormCreateSession()</code></a>, etc. The optional <em class="parameter"><code>priorityBoost</code></em> parameter, when set to a value of true, specifies that the NORM protocol engine thread be run with higher priority scheduling. On Win32 platforms, this corresponds to <code class="constant">THREAD_PRIORITY_TIME_CRITICAL</code> and on Unix systems with the <code class="function">sched_setscheduler()</code> API, an attempt to get the maximum allowed <code class="constant">SCHED_FIFO</code> priority is made. The use of this option should be carefully evaluated since, depending upon the application's scheduling priority and NORM API usage, this may have adverse effects instead of a guaranteed performance increase!</p></div><div class="sect4" title="4.2.1.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1107"></a>4.2.1.3. Return Values</h5></div></div></div><p>A value of <code class="literal">NORM_INSTANCE_INVALID</code> is returned upon failure. The function will only fail if system resources are unavailable to allocate the instance and/or create the corresponding thread.</p></div></div><div class="sect3" title="4.2.2. NormDestroyInstance()"><div class="titlepage"><div><div><h4 class="title"><a name="NormDestroyInstance"></a>4.2.2. NormDestroyInstance()</h4></div></div></div><div class="sect4" title="4.2.2.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1118"></a>4.2.2.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormDestroyInstance" title="4.2.2. NormDestroyInstance()"><code class="literal">NormDestroyInstance</code></a>(<a class="link" href="#NormInstanceHandle" title="4.1.1. NormInstanceHandle"><code class="literal">NormInstanceHandle</code></a> instanceHandle);</pre></div><div class="sect4" title="4.2.2.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1131"></a>4.2.2.2. Description</h5></div></div></div><p>The <a class="link" href="#NormDestroyInstance" title="4.2.2. NormDestroyInstance()"><code class="literal">NormDestroyInstance()</code></a> function immediately shuts down and destroys the NORM protocol engine instance referred to by the <em class="parameter"><code>instanceHandle</code></em> parameter. The application should make no subsequent references to the indicated <a class="link" href="#NormInstanceHandle" title="4.1.1. NormInstanceHandle"><code class="literal">NormInstanceHandle</code></a> or any other API handles or objects associated with it. However, the application is still responsible for releasing any object handles it has retained (see <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a> and <a class="link" href="#NormObjectRelease" title="4.6.9. NormObjectRelease()"><code class="literal">NormObjectRelease()</code></a>).</p></div><div class="sect4" title="4.2.2.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1155"></a>4.2.2.3. Return Values</h5></div></div></div><p>The function has no return value.</p></div></div><div class="sect3" title="4.2.3. NormStopInstance()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStopInstance"></a>4.2.3. NormStopInstance()</h4></div></div></div><div class="sect4" title="4.2.3.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1163"></a>4.2.3.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormStopInstance" title="4.2.3. NormStopInstance()"><code class="literal">NormStopInstance</code></a>(<a class="link" href="#NormInstanceHandle" title="4.1.1. NormInstanceHandle"><code class="literal">NormInstanceHandle</code></a> instanceHandle);</pre></div><div class="sect4" title="4.2.3.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1176"></a>4.2.3.2. Description</h5></div></div></div><p>This function immediately stops the NORM protocol engine thread corresponding to the given <em class="parameter"><code>instanceHandle</code></em> parameter. It also posts a "dummy" notification event so that if another thread is blocked on a call to <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a>, that thread will be released. Hence, for some multi-threaded uses of the NORM API, this function may be useful as a preliminary step to safely coordinate thread shutdown before a call is made to <a class="link" href="#NormDestroyInstance" title="4.2.2. NormDestroyInstance()"><code class="literal">NormDestroyInstance()</code></a>. After <a class="link" href="#NormStopInstance" title="4.2.3. NormStopInstance()"><code class="literal">NormStopInstance()</code></a> is called and any pending events posted prior to its call have been retrieved, <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a> will return a value of <code class="constant">false</code>.</p><p>When this function is invoked, state for any <span class="emphasis"><em>NormSessions</em></span> associated with the given instance is "frozen". The complementary function, <a class="link" href="#NormRestartInstance" title="4.2.4. NormRestartInstance()"><code class="literal">NormRestartInstance()</code></a> can be subsequently used to "unfreeze" and resume NORM protocol operation (a new thread is created and started).</p></div><div class="sect4" title="4.2.3.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1212"></a>4.2.3.3. Return Values</h5></div></div></div><p>The function has no return value.</p></div></div><div class="sect3" title="4.2.4. NormRestartInstance()"><div class="titlepage"><div><div><h4 class="title"><a name="NormRestartInstance"></a>4.2.4. NormRestartInstance()</h4></div></div></div><div class="sect4" title="4.2.4.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1220"></a>4.2.4.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormRestartInstance" title="4.2.4. NormRestartInstance()"><code class="literal">NormRestartInstance</code></a>(<a class="link" href="#NormInstanceHandle" title="4.1.1. NormInstanceHandle"><code class="literal">NormInstanceHandle</code></a> instanceHandle);</pre></div><div class="sect4" title="4.2.4.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1233"></a>4.2.4.2. Description</h5></div></div></div><p>This function creates and starts an operating system thread to resume NORM protocol engine operation for the given <em class="parameter"><code>instanceHandle</code></em> that was previously stopped by a call to <a class="link" href="#NormStopInstance" title="4.2.3. NormStopInstance()"><code class="literal">NormStopInstance()</code></a>. It is not expected that this function will be used often, but there may be special application cases where "freezing" and later resuming NORM protocol operation may be useful.</p></div><div class="sect4" title="4.2.4.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1245"></a>4.2.4.3. Return Values</h5></div></div></div><p>The function returns <code class="constant">true</code> when the NORM protocol engine thread is successfully restarted, and <code class="constant">false</code> otherwise.</p></div></div><div class="sect3" title="4.2.5. NormSetCacheDirectory()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetCacheDirectory"></a>4.2.5. NormSetCacheDirectory()</h4></div></div></div><div class="sect4" title="4.2.5.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1259"></a>4.2.5.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormSetCacheDirectory" title="4.2.5. NormSetCacheDirectory()"><code class="literal">NormSetCacheDirectory</code></a>(<a class="link" href="#NormInstanceHandle" title="4.1.1. NormInstanceHandle"><code class="literal">NormInstanceHandle</code></a> instanceHandle,
const char* cachePath);</pre></div><div class="sect4" title="4.2.5.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1272"></a>4.2.5.2. Description</h5></div></div></div><p>This function sets the directory path used by receivers to cache newly-received <code class="constant">NORM_OBJECT_FILE</code> content. The <em class="parameter"><code>instanceHandle</code></em> parameter specifies the NORM protocol engine instance (all <span class="emphasis"><em>NormSessions</em></span> associated with that <em class="parameter"><code>instanceHandle</code></em> share the same cache path) and the <em class="parameter"><code>cachePath</code></em> is a string specifying a valid (and writable) directory path.</p></div><div class="sect4" title="4.2.5.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1292"></a>4.2.5.3. Return Values</h5></div></div></div><p>The function returns <code class="constant">true</code> on success and <code class="constant">false</code> on failure. The failure conditions are that the indicated directory does not exist or the process does not have permissions to write.</p></div></div><div class="sect3" title="4.2.6. NormGetNextEvent()"><div class="titlepage"><div><div><h4 class="title"><a name="NormGetNextEvent"></a>4.2.6. NormGetNextEvent()</h4></div></div></div><div class="sect4" title="4.2.6.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1306"></a>4.2.6.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent</code></a>(<a class="link" href="#NormInstanceHandle" title="4.1.1. NormInstanceHandle"><code class="literal">NormInstanceHandle</code></a> instanceHandle,
<a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a>* theEvent);</pre></div><div class="sect4" title="4.2.6.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1323"></a>4.2.6.2. Description</h5></div></div></div><p>This function retrieves the next available NORM protocol event from the protocol engine. The <em class="parameter"><code>instanceHandle</code></em> parameter specifies the applicable NORM protocol engine, and the <em class="parameter"><code>theEvent</code></em> parameter must be a valid pointer to a <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> structure capable of receiving the NORM event information. For expected reliable protocol operation, the application should make every attempt to retrieve and process NORM notification events in a timely manner.</p><p>Note that this is currently the only blocking call in the NORM API. But non-blocking operation may be achieved by using the <a class="link" href="#NormGetDescriptor" title="4.2.7. NormGetDescriptor()"><code class="literal">NormGetDescriptor()</code></a> function to obtain a descriptor (<span class="type">int</span> for Unix or <span class="type">HANDLE</span> for WIN32) suitable for asynchronous input/output (I/O) notification using such system calls the Unix <code class="function">select()</code> or Win32 <code class="function">WaitForMultipleObjects()</code> calls. The descriptor is signaled when a notification event is pending and a call to <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a> will not block.<a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent</code></a></p></div><div class="sect4" title="4.2.6.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1363"></a>4.2.6.3. Return Values</h5></div></div></div><p>The function returns <code class="constant">true</code> when a <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><span class="type">NormEvent</span></a> is successfully retrieved, and <code class="constant">false</code> otherwise. Note that a return value of <code class="constant">false</code> does <span class="emphasis"><em>not</em></span> indicate an error or signify end of NORM operation.</p></div><div class="sect4" title="4.2.6.4. NORM Notification Event Types"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1384"></a>4.2.6.4. NORM Notification Event Types</h5></div></div></div><p>The following table enumerates the possible <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> values and describes how these notifications should be interpreted as they are retrieved by the application via the <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a> function call.</p><div class="informaltable"><table border="1"><colgroup><col width="28%"><col width="72%"></colgroup><tbody><tr><td><p><span class="bold"><strong>Sender Notifications:</strong></span></p></td><td class="auto-generated"> </td></tr><tr><td><p><code class="literal">NORM_TX_QUEUE_VACANCY</code></p></td><td><p>This event indicates that there is room for additional transmit objects to be enqueued, or, if the handle of <code class="literal">NORM_OBJECT_STREAM</code> is given in the corresponding event "object" field, the application may successfully write to the indicated stream object. Note this event is not dispatched until a call to <a class="link" href="#NormFileEnqueue" title="4.4.19. NormFileEnqueue()"><code class="literal">NormFileEnqueue()</code></a>, <a class="link" href="#NormDataEnqueue" title="4.4.20. NormDataEnqueue()"><code class="literal">NormDataEnqueue()</code></a>, or <a class="link" href="#NormStreamWrite" title="4.4.24. NormStreamWrite()"><code class="literal">NormStreamWrite()</code></a> fails because of a filled transmit cache or stream buffer.</p></td></tr><tr><td><p><code class="literal">NORM_TX_QUEUE_EMPTY</code></p></td><td><p>This event indicates the NORM protocol engine has no new data pending transmission and the application may enqueue additional objects for transmission. If the handle of a sender <code class="literal">NORM_OBJECT_STREAM</code> is given in the corresponding event "object" field, this indicates the stream transmit buffer has been emptied and the sender application may write to the stream (Use of <code class="literal">NORM_TX_QUEUE_VACANCY</code> may be preferred for this purpose since it allows the application to keep the NORM protocol engine busier sending data, resulting in higher throughput when attempting very high transfer rates).</p></td></tr><tr><td><p><code class="literal">NORM_TX_FLUSH_COMPLETED</code></p></td><td><p>This event indicates that the flushing process the NORM sender observes when it no longer has data ready for transmission has completed. The completion of the flushing process is a reasonable indicator (with a sufficient NORM "robust factor" value) that the receiver set no longer has any pending repair requests. Note the use of NORM's optional positive acknowledgement feature is more deterministic in this regards, but this notification is useful when there are non-acking (NACK-only) receivers. The default NORM robust factor of 20 (20 flush messages are sent at end-of-transmission) provides a high assurance of reliable transmission, even with packet loss rates of 50%.</p></td></tr><tr><td><p><code class="literal">NORM_TX_WATERMARK_COMPLETED</code></p></td><td><p>This event indicates that the flushing process initiated by a prior application call to <a class="link" href="#NormSetWatermark" title="4.4.30. NormSetWatermark()"><code class="literal">NormSetWatermark()</code></a> has completed The posting of this event indicates the appropriate time for the application to make a call <a class="link" href="#NormGetAckingStatus" title="4.4.35. NormGetAckingStatus()"><code class="literal">NormGetAckingStatus()</code></a> to determine the results of the watermark flushing process.</p></td></tr><tr><td><p><code class="literal">NORM_TX_OBJECT_SENT</code></p></td><td><p>This event indicates that the transport object referenced by the event's "object" field has completed at least one pass of total transmission. Note that this does not guarantee that reliable transmission has yet completed; only that the entire object content has been transmitted. Depending upon network behavior, several rounds of NACKing and repair transmissions may be required to complete reliable transfer.</p></td></tr><tr><td><p><code class="literal">NORM_TX_OBJECT_PURGED</code></p></td><td><p>This event indicates that the NORM protocol engine will no longer refer to the transport object identified by the event's "object' field. Typically, this will occur when the application has enqueued more objects than space available within the set sender transmit cache bounds (see <a class="link" href="#NormSetTxCacheBounds" title="4.4.9. NormSetTxCacheBounds()"><code class="literal">NormSetTxCacheBounds()</code></a>). Posting of this notification means the application is free to free any resources (memory, files, etc) associated with the indicated "object". After this event, the given "object" handle (<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a>) is no longer valid unless it is specifically retained by the application.<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a></p></td></tr><tr><td><code class="literal">NORM_TX_CMD_SENT</code></td><td>This event indicates that an application-defined command previously enqueued with a call to <a class="link" href="#NormSendCommand" title="4.4.36. NormSendCommand()"><code class="literal">NormSendCommand()</code></a> has been transmitted, including any repetition.</td></tr><tr><td><code class="literal">NORM_TX_RATE_CHANGED</code></td><td>This event indicates that NORM Congestion Control operation has adjusted the transmission rate. The <a class="link" href="#NormGetTxRate" title="4.4.4. NormGetTxRate()"><code class="literal">NormGetTxRate()</code></a> call may be used to retrieve the new corresponding transmission rate. Note that if <a class="link" href="#NormSetCongestionControl" title="4.4.7. NormSetCongestionControl()"><code class="literal">NormSetCongestionControl()</code></a> was called with its <em class="parameter"><code>adjustRate</code></em> parameter set to <code class="constant">false</code>, then no actual rate change has occurred and the rate value returned by <a class="link" href="#NormGetTxRate" title="4.4.4. NormGetTxRate()"><code class="literal">NormGetTxRate()</code></a> reflects a "suggested" rate and not the actual transmission rate.</td></tr><tr><td><p><code class="literal">NORM_LOCAL_SENDER_CLOSED</code></p></td><td><p>This event is posted when the NORM protocol engine completes the "graceful shutdown" of its participation as a sender in the indicated "session" (see <a class="link" href="#NormStopSender" title="4.4.2. NormStopSender()"><code class="literal">NormStopSender()</code></a>).</p></td></tr><tr><td><p><code class="literal">NORM_CC_ACTIVE</code></p></td><td><p>This event indicates that congestion control feedback from receivers has begun to be received (This also implies that receivers in the group are actually present and can be used as a cue to begin data transmission.). Note that congestion control must be enabled (see <a class="link" href="#NormSetCongestionControl" title="4.4.7. NormSetCongestionControl()"><code class="literal">NormSetCongestionControl()</code></a>) for this event to be posted. Congestion control feedback can be assumed to be received until a <code class="literal">NORM_CC_INACTIVE</code> event is posted.</p></td></tr><tr><td><p><code class="literal">NORM_CC_INACTIVE</code></p></td><td><p>This event indicates there has been no recent congestion control feedback received from the receiver set and that the local NORM sender has reached its minimum transmit rate. Applications may wish to refrain from new data transmission until a <code class="literal">NORM_CC_ACTIVE</code> event is posted. This notification is only posted when congestion control operation is enabled (see <a class="link" href="#NormSetCongestionControl" title="4.4.7. NormSetCongestionControl()"><code class="literal">NormSetCongestionControl()</code></a>) and a previous <code class="literal">NORM_CC_ACTIVE</code> event has occurred.</p></td></tr><tr><td><p><span class="bold"><strong>Receiver Notifications:</strong></span></p></td><td class="auto-generated"> </td></tr><tr><td><p><code class="literal">NORM_REMOTE_SENDER_NEW</code></p></td><td><p>This event is posted when a receiver first receives messages from a specific remote NORM sender. This marks the beginning of the interval during which the application may reference the provided "node" handle (<a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a>).</p></td></tr><tr><td><p><code class="literal">NORM_REMOTE_SENDER_ACTIVE</code></p></td><td><p>This event is posted when a previously inactive (or new) remote <a name="OLE_LINK5"></a> <a name="OLE_LINK4"></a>sender is detected operating as an active sender within the session.</p></td></tr><tr><td><p><code class="literal">NORM_REMOTE_SENDER_INACTIVE</code></p></td><td><p>This event is posted after a significant period of inactivity (no sender messages received) of a specific NORM sender within the session. The NORM protocol engine frees buffering resources allocated for this sender when it becomes inactive.</p></td></tr><tr><td><p><code class="literal">NORM_REMOTE_SENDER_PURGED</code></p></td><td><p>This event is posted when the NORM protocol engine frees resources for, and thus invalidates the indicated "node" handle.</p></td></tr><tr><td><p><code class="literal">NORM_RX_OBJECT_NEW</code></p></td><td><p>This event is posted when reception of a new transport object begins and marks the beginning of the interval during which the specified "object" (<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a>) is valid.</p></td></tr><tr><td><p><code class="literal">NORM_RX_OBJECT_INFO</code></p></td><td><p>This notification is posted when the <code class="literal">NORM_INFO</code> content for the indicated "object" is received.</p></td></tr><tr><td><p><code class="literal">NORM_RX_OBJECT_UPDATED</code></p></td><td><p>This event indicates that the identified receive "object" has newly received data content.</p></td></tr><tr><td><p><code class="literal">NORM_RX_OBJECT_COMPLETED</code></p></td><td><p>This event is posted when a receive object is completely received, including available <code class="literal">NORM_INFO</code> content. Unless the application specifically retains the "object" handle, the indicated <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> becomes invalid and must no longer be referenced.</p></td></tr><tr><td><p><code class="literal">NORM_RX_OBJECT_ABORTED</code></p></td><td><p>This notification is posted when a pending receive object's transmission is aborted by the remote sender. Unless the application specifically retains the "object" handle, the indicated <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> becomes invalid and must no longer be referenced.</p></td></tr><tr><td><code class="constant">NORM_RX_CMD_NEW</code></td><td>This event indicates that an application-defined command has been received from a remote sender. The <span class="type">NormEvent</span> node element indicates the <span class="type">NormNodeHandle</span> value associated with the given sender. The <a class="link" href="#NormNodeGetCommand" title="4.7.4. NormNodeGetCommand()"><code class="literal">NormNodeGetCommand()</code></a> call can be used to retrieve the received command content.</td></tr><tr><td><p><span class="bold"><strong>Miscellaneous Notifications:</strong></span></p></td><td class="auto-generated"> </td></tr><tr><td><p><code class="literal">NORM_GRTT_UPDATED</code></p></td><td><p>This notification indicates that either the local sender estimate of GRTT has changed, or that a remote sender's estimate of GRTT has changed. The "sender" member of the <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> is set to <code class="literal">NORM_NODE_INVALID</code> if the local sender's GRTT estimate has changed or to the <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> of the remote sender that has updated its estimate of GRTT.</p></td></tr><tr><td><p><code class="literal">NORM_EVENT_INVALID</code></p></td><td><p>This <a class="link" href="#NormEventType" title="4.1.10. NormEventType"><code class="literal">NormEventType</code></a> indicates an invalid or "null" notification which should be ignored.</p></td></tr></tbody></table></div></div><div class="sect4" title="4.2.6.5. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1729"></a>4.2.6.5. Return Values</h5></div></div></div><p>This function generally blocks the thread of application execution until a <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> is available and returns <code class="constant">true</code> when a <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> is available. However, there are some exceptional cases when the function may immediately return even when no event is pending. In these cases, the return value is <code class="constant">false</code> indicating the <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> should be ignored.</p><p><span class="emphasis"><em>Win32 Note: A future version of this API will provide an option to have a user-defined Window message posted when a NORM API event is pending. (Also some event filtering calls may be provided (e.g. avoid the potentially numerous <code class="literal">NORM_RX_OBJECT_UPDATED</code> events if not needed by the application)).</em></span></p></div></div><div class="sect3" title="4.2.7. NormGetDescriptor()"><div class="titlepage"><div><div><h4 class="title"><a name="NormGetDescriptor"></a>4.2.7. NormGetDescriptor()</h4></div></div></div><div class="sect4" title="4.2.7.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1761"></a>4.2.7.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
<a class="link" href="#NormDescriptor" title="4.1.12. NormDescriptor"><code class="literal">NormDescriptor</code></a> <a class="link" href="#NormGetDescriptor" title="4.2.7. NormGetDescriptor()"><code class="literal">NormGetDescriptor</code></a>(<a class="link" href="#NormInstanceHandle" title="4.1.1. NormInstanceHandle"><code class="literal">NormInstanceHandle</code></a> instance);</pre></div><div class="sect4" title="4.2.7.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1778"></a>4.2.7.2. Description</h5></div></div></div><p>This function is used to retrieve a <a class="link" href="#NormDescriptor" title="4.1.12. NormDescriptor"><code class="literal">NormDescriptor</code></a> (Unix <span class="type">int</span> file descriptor or Win32 <span class="type">HANDLE</span>) suitable for asynchronous I/O notification to avoid blocking calls to <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a>. A <a class="link" href="#NormDescriptor" title="4.1.12. NormDescriptor"><code class="literal">NormDescriptor</code></a> is available for each protocol engine instance created using <a class="link" href="#NormCreateInstance" title="4.2.1. NormCreateInstance()">NormCreateInstance()</a>. The descriptor returned is suitable for use as an input (or "read") descriptor which is signaled when a NORM protocol event is ready for retrieval via <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a>. Hence, a call to <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a> will not block when the descriptor has been signaled. The Unix <code class="function">select()</code> or Win32 <code class="function">WaitForMultipleObjects()</code> system calls can be used to detect when the <a class="link" href="#NormDescriptor" title="4.1.12. NormDescriptor"><code class="literal">NormDescriptor</code></a> is signaled. Note that for Unix <code class="function">select()</code> call usage, the NORM descriptor should be treated as a "read" descriptor.</p></div><div class="sect4" title="4.2.7.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1825"></a>4.2.7.3. Return Values</h5></div></div></div><p>A <a class="link" href="#NormDescriptor" title="4.1.12. NormDescriptor"><span class="type">NormDescriptor</span></a> value is returned which is valid until a call to <a class="link" href="#NormDestroyInstance" title="4.2.2. NormDestroyInstance()"><code class="literal">NormDestroyInstance()</code></a> is made. Upon error, a value of <code class="literal">NORM_DESCRIPTOR_INVALID</code> is returned.</p></div></div></div><div class="sect2" title="4.3. Session Creation and Control Functions"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1841"></a>4.3. Session Creation and Control Functions</h3></div></div></div><p>Whether participating in a NORM protocol session as a sender, receiver, or both, there are some common API calls used to instantiate a <span class="emphasis"><em>NormSession</em></span> and set some common session parameters. Functions are provided to control network socket and multicast parameters. Additionally, a "user data" value may be associated with a <a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> for programming convenience when dealing with multiple sessions.</p><div class="sect3" title="4.3.1. NormCreateSession()"><div class="titlepage"><div><div><h4 class="title"><a name="NormCreateSession"></a>4.3.1. NormCreateSession()</h4></div></div></div><div class="sect4" title="4.3.1.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1856"></a>4.3.1.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">
NormSessionHandle</code></a> <a class="link" href="#NormCreateSession" title="4.3.1. NormCreateSession()"><code class="literal">NormCreateSession</code></a>(<a class="link" href="#NormInstanceHandle" title="4.1.1. NormInstanceHandle"><code class="literal">NormInstanceHandle</code></a> instance,
const char* address,
unsigned short port,
<a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> localId);</pre></div><div class="sect4" title="4.3.1.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1877"></a>4.3.1.2. Description</h5></div></div></div><p>This function creates a NORM protocol session (<span class="emphasis"><em>NormSession</em></span>) using the <em class="parameter"><code>address</code></em> (multicast or unicast) and <em class="parameter"><code>port</code></em> parameters provided. While session state is allocated and initialized, active session participation does not begin until a call is made to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> and/or <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a> to join the specified multicast group (if applicable) and start protocol operation. The following parameters are required in this function call:</p><div class="informaltable"><table border="1"><colgroup><col width="16%"><col width="84%"></colgroup><tbody><tr><td><p><code class="literal">instance</code></p></td><td><p>This must be a valid <a class="link" href="#NormInstanceHandle" title="4.1.1. NormInstanceHandle"><code class="literal">NormInstanceHandle</code></a> previously obtained with a call to <a class="link" href="#NormCreateInstance" title="4.2.1. NormCreateInstance()"><code class="literal">NormCreateInstance()</code></a>.</p></td></tr><tr><td><p><code class="literal">address</code></p></td><td><p>This points to a string containing an IP address (e.g. dotted decimal IPv4 address (or IPv6 address) or name resolvable to a valid IP address. The specified address (along with the port number) determines the destination of NORM messages sent. For multicast sessions, NORM senders and receivers must use a common multicast address and port number. For unicast sessions, the sender and receiver must use a common port number, but specify the other node's IP address as the session address (Although note that receiver-only unicast nodes who are providing unicast feedback to senders will not generate any messages to the session IP address and the address parameter value is thus inconsequential for this special case).</p></td></tr><tr><td><p><code class="literal">port</code></p></td><td><p>This must be a valid, unused port number corresponding to the desired NORM session address. See the address parameter description for more details.</p></td></tr><tr><td><p><code class="literal">localId</code></p></td><td><p>The <em class="parameter"><code>localId</code></em> parameter specifies the <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> that should be used to identify the application's presence in the <span class="emphasis"><em>NormSession</em></span>. All participant's in a <span class="emphasis"><em>NormSession</em></span> should use unique <em class="parameter"><code>localId</code></em> values. The application may specify a value of <code class="literal">NORM_NODE_ANY</code> or <code class="literal">NORM_NODE_ANY</code> for the <em class="parameter"><code>localId</code></em> parameter. In this case, the NORM implementation will attempt to pick an identifier based on the host computer's "default" IP address (based on the computer's default host name). Note there is a chance that this approach may not provide unique node identifiers in some situations and the NORM protocol does not currently provide a mechanism to detect or resolve <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> collisions. Thus, the application should explicitly specify the <em class="parameter"><code>localId</code></em> unless there is a high degree of confidence that the default IP address will provide a unique identifier.</p></td></tr></tbody></table></div></div><div class="sect4" title="4.3.1.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1976"></a>4.3.1.3. Return Values</h5></div></div></div><p>The returned <a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> value is valid until a call to <a class="link" href="#NormDestroySession" title="4.3.2. NormDestroySession()"><code class="literal">NormDestroySession()</code></a> is made. A value of <code class="literal">NORM_SESSION_INVALID</code> is returned upon error.</p></div></div><div class="sect3" title="4.3.2. NormDestroySession()"><div class="titlepage"><div><div><h4 class="title"><a name="NormDestroySession"></a>4.3.2. NormDestroySession()</h4></div></div></div><div class="sect4" title="4.3.2.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e1995"></a>4.3.2.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormDestroySession" title="4.3.2. NormDestroySession()"><code class="literal">NormDestroySession</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle);</pre></div><div class="sect4" title="4.3.2.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2008"></a>4.3.2.2. Description</h5></div></div></div><p>This function immediately terminates the application's participation in the <span class="emphasis"><em>NormSession</em></span> identified by the <em class="parameter"><code>sessionHandle</code></em> parameter and frees any resources used by that session. An exception to this is that the application is responsible for releasing any explicitly retained <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> values (See <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a> and <a class="link" href="#NormObjectRelease" title="4.6.9. NormObjectRelease()"><code class="literal">NormObjectRelease()</code></a>).</p></div><div class="sect4" title="4.3.2.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2031"></a>4.3.2.3. Return Values</h5></div></div></div><p>This function has no returned values.</p></div></div><div class="sect3" title="4.3.3. NormSetUserData()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetUserData"></a>4.3.3. NormSetUserData()</h4></div></div></div><div class="sect4" title="4.3.3.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2039"></a>4.3.3.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetUserData" title="4.3.3. NormSetUserData()"><code class="literal">NormSetUserData</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
const void* userData);</pre></div><div class="sect4" title="4.3.3.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2052"></a>4.3.3.2. Description</h5></div></div></div><p>This function allows the application to attach a value to the previously-created <span class="emphasis"><em>NormSession</em></span> instance specified by the <em class="parameter"><code>sessionHandle</code></em> parameter. This value is not used or interpreted by NORM, but is available to the application for use at the programmer's discretion. The set <em class="parameter"><code>userData</code></em> value can be later retrieved using the <a class="link" href="#NormGetUserData" title="4.3.4. NormGetUserData()"><code class="literal">NormGetUserData()</code></a> function call.</p></div><div class="sect4" title="4.3.3.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2070"></a>4.3.3.3. Return Values</h5></div></div></div><p>This function has no returned values.</p></div></div><div class="sect3" title="4.3.4. NormGetUserData()"><div class="titlepage"><div><div><h4 class="title"><a name="NormGetUserData"></a>4.3.4. NormGetUserData()</h4></div></div></div><div class="sect4" title="4.3.4.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2078"></a>4.3.4.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
const void* <a class="link" href="#NormGetUserData" title="4.3.4. NormGetUserData()"><code class="literal">NormGetUserData</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle);</pre></div><div class="sect4" title="4.3.4.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2091"></a>4.3.4.2. Description</h5></div></div></div><p>This function retrieves the "user data" value set for the specified <em class="parameter"><code>sessionHandle</code></em> with a prior call to <a class="link" href="#NormSetUserData" title="4.3.3. NormSetUserData()"><code class="literal">NormSetUserData()</code></a>.</p></div><div class="sect4" title="4.3.4.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2103"></a>4.3.4.3. Return Values</h5></div></div></div><p>This function returns the user data value set for the specified session. If no user data value has been previously set, a NULL (i.e., <code class="literal">(<span class="type">const void*</span>)0)</code> value is returned.</p></div></div><div class="sect3" title="4.3.5. NormGetLocalNodeId()"><div class="titlepage"><div><div><h4 class="title"><a name="NormGetLocalNodeId"></a>4.3.5. NormGetLocalNodeId()</h4></div></div></div><div class="sect4" title="4.3.5.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2117"></a>4.3.5.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
<a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> <a class="link" href="#NormGetLocalNodeId" title="4.3.5. NormGetLocalNodeId()"><code class="literal">NormGetLocalNodeId</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle);</pre></div><div class="sect4" title="4.3.5.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2134"></a>4.3.5.2. Description</h5></div></div></div><p>This function retrieves the <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> value used for the application's participation in the <span class="emphasis"><em>NormSession</em></span> identified by the <em class="parameter"><code>sessionHandle</code></em> parameter. The value may have been explicitly set during the <a class="link" href="#NormCreateSession" title="4.3.1. NormCreateSession()"><code class="literal">NormCreateSession()</code></a> call or may have been automatically derived using the host computer's "default" IP network address.</p></div><div class="sect4" title="4.3.5.3. Return Valuess"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2153"></a>4.3.5.3. Return Valuess</h5></div></div></div><p>The returned value indicates the <span class="emphasis"><em>NormNode</em></span> identifier used by the NORM protocol engine for the local application's participation in the specified <span class="emphasis"><em>NormSession</em></span>.</p></div></div><div class="sect3" title="4.3.6. NormSetTxPort()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetTxPort"></a>4.3.6. NormSetTxPort()</h4></div></div></div><div class="sect4" title="4.3.6.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2167"></a>4.3.6.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormSetTxPort" title="4.3.6. NormSetTxPort()"><code class="literal">NormSetTxPort</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
unsigned short txPort,
bool enableReuse = false,
const char* txBindAddress = (const char*)0);</pre></div><div class="sect4" title="4.3.6.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2180"></a>4.3.6.2. Description</h5></div></div></div><p>This function is used to force NORM to use a specific port number for UDP packets sent for the specified <em class="parameter"><code>sessionHandle</code></em>. Additionally, it can optionally enable reuse of the specified port number and/or specify a specific source address binding that is used for packet transmission. By default, NORM uses separate port numbers for packet transmission and session packet reception (the receive port is specified as part of the <a class="link" href="#NormCreateSession" title="4.3.1. NormCreateSession()"><code class="literal">NormCreateSession()</code></a> call), allowing the operating system to pick a freely available port for transmission. This call allows the application to pick a specific port number for transmission, and furthermore allows the application to even specify the same port number for transmission as is used for reception. However, the use of separate transmit/receive ports allows NORM to discriminate when unicast feedback is occurring and thus it is not generally recommended that the transmit port be set to the same value as the session receive port.</p><p>The <em class="parameter"><code>enableReuse</code></em> parameter, when set to <code class="constant">true</code>, allows that the specified port may be reused for multiple sessions, but care must be taken when enabling this option. The <em class="parameter"><code>txBindAddress</code></em> parameter allows specification of a specific source address binding for packet transmission. The specified address MUST be a valid unicast IP address assigned and configured for the host system. Additionally, the address specified must be compatible with multicast routing and/or the interfaces specified in any calls to <a class="link" href="#NormSetMulticastInterface" title="4.3.9. NormSetMulticastInterface()"><code class="literal">NormSetMulticastInterface()</code></a> for the given session when IP multicast is used.</p><p>When the <em class="parameter"><code>txPort</code></em> is set equal to the session port number and a <em class="parameter"><code>txBindAddress</code></em> is not specified or set equal to the session address, a single socket is used for both transmission and reception. If the same port number is desired for both packet transmission and reception, <span class="emphasis"><em>and</em></span> a specific source address binding is set, then the <em class="parameter"><code>enableReuse</code></em> parameter MUST be (and is automatically) set to <code class="constant">true</code> for successful operation. In this case, the receive socket is bound to session address if it is multicast and the transmit socket is bound to the specified <em class="parameter"><code>txAddress</code></em> although both are bound to the same port number.</p><p>Note this call MUST be made <span class="emphasis"><em>before</em></span> any calls to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> or <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a> for the given session to work as described.</p></div><div class="sect4" title="4.3.6.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2240"></a>4.3.6.3. Return Values</h5></div></div></div><p>This function returns <code class="constant">true</code> upon success and <code class="constant">false</code> upon failure. Failure will occur if a <em class="parameter"><code>txBindAddress</code></em> is provided that does not correspond to a valid, configured IP address for the local host system.</p></div></div><div class="sect3" title="4.3.7. NormSetTxOnly()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetTxOnly"></a>4.3.7. NormSetTxOnly()</h4></div></div></div><div class="sect4" title="4.3.7.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2257"></a>4.3.7.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormStopSender" title="4.4.2. NormStopSender()"><code class="literal">NormSetTxOnly</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
bool txOnly,
bool connectToSessionAddress = false);</pre></div><div class="sect4" title="4.3.7.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2270"></a>4.3.7.2. Description</h5></div></div></div><p>This function limits the <span class="emphasis"><em>NormSession</em></span> to perform NORM sender functions only. It also limits the underlying NORM UDP socket usage to open only a single transmit socket (tx_socket) and does <span class="emphasis"><em>not</em></span> open or bind a receive socket for the given session address or port number. Thus, if this property is set, any NORM receivers MUST enable unicast feedback via a call to the <a class="link" href="#NormSetDefaultUnicastNack" title="4.5.6. NormSetDefaultUnicastNack()">NormSetDefaultUnicastNack()</a> or appropriate <a class="link" href="#NormNodeSetUnicastNack" title="4.5.7. NormNodeSetUnicastNack()">NormNodeSetUnicastNack()</a> function in order for their feedback messages (NACKs and ACKs) to be received by this sender. The purpose of this function is to allow NORM sender sessions to be created as separate process from a corresponding NORM receiver session for the same session address and port number. By default (when this call is not made), a <span class="emphasis"><em>NormSession</em></span>, even when acting as only a sender (see<a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"> NormStartSender()</a>) opens two separate UDP sockets including a "receive" socket bound to the session port number and a "transmit" socket used for message transmission and reception of unicast feedback messages when receivers are so configured.</p><p>The optional <em class="parameter"><code>connectToSessionAddress</code></em> parameter, when set to <code class="constant">true</code>, causes the underlying NORM code to "<code class="function">connect()</code>" the UDP socket to the session (remote receiver) address and port number. If the corresponding NORM remote receiver instance uses <a class="link" href="#NormSetTxPort" title="4.3.6. NormSetTxPort()">NormSetTxPort()</a> to set its transmit port to the same as the session port number, the result is a unique binding between this "tx only" sender instance and the remote NORM receiver instance. With proper use of <a class="link" href="#NormSetRxPortReuse" title="4.3.8. NormSetRxPortReuse()">NormSetRxPortReuse()</a>, this allows multiple senders to be properly associated (i.e., binded with respect to UDP socket packet demultiplexing) with multiple receivers on a single host (all using the same session port number). Note the NORM receiver MUST also use the <a class="link" href="#NormSetDefaultUnicastNack" title="4.5.6. NormSetDefaultUnicastNack()">NormSetDefaultUnicastNack()</a> call so that its feedback messages are directed to the "tx only" sender address/port. The motivation for this API call is to allow systems have NORM sender and receiver instances in separate processes supporting a set (e.g. a mesh) of unicast connections to other hosts. The only constraint is that the senders uses a "tx port" number that is different from the "rx port" number. This enables firewall configurations that only open a pair of UDP ports and allow for connection among an arbitrary number of hosts. This option is really only relevant for unicast NORM sessions.</p></div><div class="sect4" title="4.3.7.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2313"></a>4.3.7.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.3.8. NormSetRxPortReuse()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetRxPortReuse"></a>4.3.8. NormSetRxPortReuse()</h4></div></div></div><div class="sect4" title="4.3.8.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2321"></a>4.3.8.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetRxPortReuse" title="4.3.8. NormSetRxPortReuse()"><code class="literal">NormSetRxPortReuse</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> session,
bool enableReuse,
const char* rxBindAddress = (const char*)0,
const char* senderAddress = (const char*)0,
UINT16 senderPort = 0);</pre></div><div class="sect4" title="4.3.8.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2334"></a>4.3.8.2. Description</h5></div></div></div><p>This function allows the user to control the port reuse and binding behavior for the receive socket used for the given NORM <em class="parameter"><code>sessionHandle</code></em>. When the <em class="parameter"><code>enablReuse</code></em> parameter is set to <code class="constant">true</code>, reuse of the <span class="emphasis"><em>NormSession</em></span> port number by multiple NORM instances or sessions is enabled.</p><p>If the optional <em class="parameter"><code>rxBindAddress</code></em> is supplied (an IP address or host name in string form), the socket will bind() to the given address when it is opened in a call to NormStartReceiver() or NormStartSender(). The <em class="parameter"><code>rxBindAddress</code></em> MUST be the session multicast address (if it is a multicast session) or a valid local unicast address in the case of NORM unicast operation. This binding limits the socket to receive only packets destined for the specified <em class="parameter"><code>rxBindAddress</code></em>. This allows multiple NORM sessions to reuse the same port number, but use different multicast addresses (or allow for multiple NORM sessions for multiple local unicast addresses).</p><p>The optional <em class="parameter"><code>senderAddress</code></em> and <em class="parameter"><code>senderPort</code></em> parameters can be used to connect() the underlying NORM receive socket to specific address/port. This limits the socket to receiving only packets from the specified <em class="parameter"><code>senderAddress</code></em>/<em class="parameter"><code>senderPort</code></em>. This, with receive port reuse enabled, allows for multiple NORM receiver instances to be listening to different NORM senders and have proper UDP socket demultiplexing occur. Note that it is also possible to have single NORM receiver receive transmissions from multiple senders, but in some cases it may be desirable for separate NORM processes or threads to be used to handle reception from separate senders. Thus, this socket binding option is provided.</p><p>When this call is not made in any form, the default socket binding to IP address INADDR_ANY (equivalent to when this call is made and <em class="parameter"><code>rxBindAddress</code></em> is set to <code class="constant">NULL</code>) allows the <span class="emphasis"><em>NormSession</em></span> receive socket to receive any multicast or unicast transmissions to the session port number provided in the call to <a class="link" href="#NormCreateSession" title="4.3.1. NormCreateSession()"><code class="literal">NormCreateSession()</code></a>. This allows a NORM receiver to receive from senders sending to a multicast session address or the receiver's unicast address. As mentioned, enabling port reuse and binding the session destination address allows multiple NORM sessions on the same port number, but participating in different multicast groups.</p><p>Note this call MUST be made <span class="emphasis"><em>before</em></span> any calls to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> or <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a> for the given <em class="parameter"><code>sessionHandle</code></em> to succeed.</p><p>This call could also be used in conjunction with <a class="link" href="#NormSetMulticastInterface" title="4.3.9. NormSetMulticastInterface()"><code class="literal">NormSetMulticastInterface()</code></a> so that multiple <span class="emphasis"><em>NormSessions</em></span>, using the same port and multicast address, could separately cover multiple network interfaces (and some sort of application-layer bridging of reliable multicast could be realized if desired).</p></div><div class="sect4" title="4.3.8.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2416"></a>4.3.8.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.3.9. NormSetMulticastInterface()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetMulticastInterface"></a>4.3.9. NormSetMulticastInterface()</h4></div></div></div><div class="sect4" title="4.3.9.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2424"></a>4.3.9.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormSetMulticastInterface" title="4.3.9. NormSetMulticastInterface()"><code class="literal">NormSetMulticastInterface</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> session,
const char* interfaceName);</pre></div><div class="sect4" title="4.3.9.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2437"></a>4.3.9.2. Description</h5></div></div></div><p>This function specifies which host network interface is used for IP Multicast transmissions and group membership. This should be called <span class="emphasis"><em>before</em></span> any call to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> or <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a> is made so that the IP multicast group is joined on the proper host interface. However, if a call to <a class="link" href="#NormSetMulticastInterface" title="4.3.9. NormSetMulticastInterface()"><code class="literal">NormSetMulticastInterface()</code></a> is made after either of these function calls, the call will not affect the group membership interface, but only dictate that a possibly different network interface is used for transmitted NORM messages. Thus, the code:</p><pre class="programlisting"><a class="link" href="#NormSetMulticastInterface" title="4.3.9. NormSetMulticastInterface()"><code class="literal">NormSetMulticastInterface</code></a>(session, "interface1");
<a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver</code></a>(session, ...);<a class="link" href="#NormSetMulticastInterface" title="4.3.9. NormSetMulticastInterface()"><code class="literal">
NormSetMulticastInterface</code></a>(session, "interface2");</pre><p>will result in NORM group membership (i.e. multicast reception) being managed on "<code class="literal">interface1</code>" while NORM multicast transmissions are made via "<code class="literal">interface2</code>".</p></div><div class="sect4" title="4.3.9.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2479"></a>4.3.9.3. Return Values</h5></div></div></div><p>A return value of <code class="constant">true</code> indicates success while a return value of <code class="constant">false</code> indicates that the specified interface was invalid. This function will always return <code class="constant">true</code> if made before calls to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> or <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a>. However, those calls may fail if an invalid interface was specified with the call described here.</p></div></div><div class="sect3" title="4.3.10. NormSetSSM()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetMulticastInterface"></a>4.3.10. NormSetSSM()</h4></div></div></div><div class="sect4" title="4.3.10.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2504"></a>4.3.10.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormSetMulticastInterface" title="4.3.9. NormSetMulticastInterface()"><code class="literal">NormSetSSM</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> session,
const char* sourceAddress);</pre></div><div class="sect4" title="4.3.10.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2517"></a>4.3.10.2. Description</h5></div></div></div><p>This function sets the source address for Source-Specific Multicast (SSM) operation. This should be called <span class="emphasis"><em>before</em></span> any call to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> or <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a> is made so that the proper group join is done. The receiver application MUST also use the <a class="link" href="#NormSetDefaultUnicastNack" title="4.5.6. NormSetDefaultUnicastNack()"><code class="literal">NormSetDefaultUnicastNack()</code></a> call so that feedback traffic is directed back to appropriate sender.</p></div><div class="sect4" title="4.3.10.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2537"></a>4.3.10.3. Return Values</h5></div></div></div><p>A return value of <code class="constant">true</code> indicates success while a return value of <code class="constant">false</code> indicates that the specified source address was invalid. Note that if a valid IP address is specified but is improper for SSM (e.g., an IP multicast address) the later calls to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> or <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a> may fail.</p></div></div><div class="sect3" title="4.3.11. NormSetTTL()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetTTL"></a>4.3.11. NormSetTTL()</h4></div></div></div><div class="sect4" title="4.3.11.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2559"></a>4.3.11.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormSetTTL" title="4.3.11. NormSetTTL()"><code class="literal">NormSetTTL</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> session,
unsigned char ttl);</pre></div><div class="sect4" title="4.3.11.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2572"></a>4.3.11.2. Description</h5></div></div></div><p>This function specifies the time-to-live (<em class="parameter"><code>ttl</code></em>) for IP Multicast datagrams generated by NORM for the specified <em class="parameter"><code>sessionHandle</code></em>. The IP TTL field limits the number of router "hops" that a generated multicast packet may traverse before being dropped. For example, if TTL is equal to one, the transmissions will be limited to the local area network (LAN) of the host computers network interface. Larger TTL values should be specified to span large networks. Also note that some multicast router configurations use artificial "TTL threshold" values to constrain some multicast traffic to an administrative boundary. In these cases, the NORM TTL setting must also exceed the router "TTL threshold" in order for the NORM traffic to be allowed to exit the administrative area.</p></div><div class="sect4" title="4.3.11.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2583"></a>4.3.11.3. Return Values</h5></div></div></div><p>A return value of <code class="constant">true</code> indicates success while a return value of <code class="constant">false</code> indicates that the specified <em class="parameter"><code>ttl</code></em> could not be set. This function will always return <code class="constant">true</code> if made before calls to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> or <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a>. However, those calls may fail if the desired <em class="parameter"><code>ttl</code></em> value cannot be set.</p></div></div><div class="sect3" title="4.3.12. NormSetTOS()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetTOS"></a>4.3.12. NormSetTOS()</h4></div></div></div><div class="sect4" title="4.3.12.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2614"></a>4.3.12.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormSetTOS" title="4.3.12. NormSetTOS()"><code class="literal">NormSetTOS</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
unsigned char tos);</pre></div><div class="sect4" title="4.3.12.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2627"></a>4.3.12.2. Description</h5></div></div></div><p>This function specifies the type-of-service (<em class="parameter"><code>tos</code></em>) field value used in IP Multicast datagrams generated by NORM for the specified <em class="parameter"><code>sessionHandle</code></em>. The IP TOS field value can be used as an indicator that a "flow" of packets may merit special Quality-of-Service (QoS) treatment by network devices. Users should refer to applicable QoS information for their network to determine the expected interpretation and treatment (if any) of packets with explicit TOS marking.</p></div><div class="sect4" title="4.3.12.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2638"></a>4.3.12.3. Return Values</h5></div></div></div><p>A return value of <code class="constant">true</code> indicates success while a return value of <code class="constant">false</code> indicates that the specified <em class="parameter"><code>tos</code></em> could not be set. This function will always return <code class="constant">true</code> if made before calls to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> or <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a>. However, those calls may fail if the desired <em class="parameter"><code>tos</code></em> value cannot be set.</p></div></div><div class="sect3" title="4.3.13. NormSetLoopback()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetLoopback"></a>4.3.13. NormSetLoopback()</h4></div></div></div><div class="sect4" title="4.3.13.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2669"></a>4.3.13.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetLoopback" title="4.3.13. NormSetLoopback()"><code class="literal">NormSetLoopback</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
bool loopbackEnable);</pre></div><div class="sect4" title="4.3.13.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2682"></a>4.3.13.2. Description</h5></div></div></div><p>This function enables or disables loopback operation for the indicated NORM <em class="parameter"><code>sessionHandle</code></em>. If <em class="parameter"><code>loopbackEnable</code></em> is set to <code class="constant">true</code>, loopback operation is enabled which allows the application to receive its own message traffic. Thus, an application which is both actively receiving and sending may receive its own transmissions. Note it is expected that this option would be principally be used for test purposes and that applications would generally not need to transfer data to themselves. If <em class="parameter"><code>loopbackEnable</code></em> is false, the application is prevented from receiving its own NORM message transmissions. By default, loopback operation is disabled when a <span class="emphasis"><em>NormSession</em></span> is created.</p></div><div class="sect4" title="4.3.13.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2702"></a>4.3.13.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.3.14. NormSetFragmentation()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetFragmentation"></a>4.3.14. NormSetFragmentation()</h4></div></div></div><div class="sect4" title="4.3.14.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2710"></a>4.3.14.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormSetFragmentation" title="4.3.14. NormSetFragmentation()"><code class="literal">NormSetFragmentation</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
bool fragmentation);</pre></div><div class="sect4" title="4.3.14.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2723"></a>4.3.14.2. Description</h5></div></div></div><p>This function sets an underlying socket option that enables or disables IP datagram fragmentation by network intermediate systems according to whether the <em class="parameter"><code>fragmentation</code></em> parameter is set to a value of <code class="constant">true</code> or <code class="constant">false</code>, respectively. If set to <code class="constant">true</code> to enable fragmentation, the DF (don't fragment) bit of the headers of NORM UDP/IP packets sent will be cleared. Otherwise the DF bit is set and packets will not be fragmented by network devices if they exceed a link Maximum Transmission Unit (MTU) and will instead be dropped. For IP Multicast destinations, some operating systems may always set the DF bit of transmitted packets, regardless of the setting here and the underlying socket option status. Typically, the DF bit is set (i.e., fragmentation disabled) by default on most operating systems.</p><p>This call is not currently functional on the Mac OSX system that does not support the needed <code class="constant">IP_MTU_DISCOVER</code> or <code class="constant">IP_DONTFRAG</code> socket options.</p></div><div class="sect4" title="4.3.14.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2748"></a>4.3.14.3. Return Values</h5></div></div></div><p>This function returns <code class="constant">true</code> upon success and <code class="constant">false</code> upon failure.</p></div></div></div><div class="sect2" title="4.4. NORM Sender Functions"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2759"></a>4.4. <a name="_NORM_Sender_Functions"></a>NORM Sender Functions</h3></div></div></div><p>The functions described in this section apply only to NORM sender operation. Applications may participate strictly as senders or as receivers, or may act as both in the context of a NORM protocol session. The NORM sender is responsible for most parameters pertaining to its transmission of data. This includes transmission rate, data segmentation sizes, FEC coding parameters, stream buffer sizes, etc.</p><div class="sect3" title="4.4.1. NormStartSender()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStartSender"></a>4.4.1. NormStartSender()</h4></div></div></div><div class="sect4" title="4.4.1.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2768"></a>4.4.1.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
<a class="link" href="#NormSessionId" title="4.1.3. NormSessionId"><code class="literal">NormSessionId</code></a> instanceId,
unsigned long bufferSpace,
unsigned short segmentSize,
unsigned char blockSize,
unsigned char numParity);</pre></div><div class="sect4" title="4.4.1.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2785"></a>4.4.1.2. Description</h5></div></div></div><p>The application's participation as a sender within a specified <span class="emphasis"><em>NormSession</em></span> begins when this function is called. This includes protocol activity such as congestion control and/or group round-trip timing (GRTT) feedback collection and application API activity such as posting of sender-related <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> notifications. The parameters required for this function call include:</p><div class="informaltable"><table border="1"><colgroup><col width="16%"><col width="84%"></colgroup><tbody><tr><td><p><em class="parameter"><code>sessionHandle</code></em></p></td><td><p>This must be a valid <a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> previously obtained with a call to <a class="link" href="#NormCreateSession" title="4.3.1. NormCreateSession()"><code class="literal">NormCreateSession()</code></a>.</p></td></tr><tr><td><p><em class="parameter"><code>instanceId</code></em></p></td><td><p>Application-defined value used as the <code class="constant">instance_id</code> field of NORM sender messages for the application's participation within a session. Receivers can detect when a sender has terminated and restarted if the application uses different <em class="parameter"><code>instanceId</code></em> values when initiating sender operation. For example, a robust application could cache previous <em class="parameter"><code>instanceId</code></em> values in non-volatile storage and gracefully recover (without confusing receivers) from a total system shutdown and reboot by using a new <em class="parameter"><code>instanceId</code></em> value upon restart.</p></td></tr><tr><td><p><em class="parameter"><code>bufferSpace</code></em></p></td><td><p>This specifies the maximum memory space (in bytes) the NORM protocol engine is allowed to use to buffer any sender calculated FEC segments and repair state for the session. The optimum <em class="parameter"><code>bufferSpace</code></em> value is function of the network topology bandwidth*delay product and packet loss characteristics. If the <em class="parameter"><code>bufferSpace</code></em> limit is too small, the protocol may operate less efficiently as the sender is required to possibly recalculate FEC parity segments and/or provide less efficient repair transmission strategies (resort to explicit repair) when state is dropped due to constrained buffering resources. However, note the protocol will still provide reliable transfer. A large <em class="parameter"><code>bufferSpace</code></em> allocation is safer at the expense of possibly committing more memory resources.</p></td></tr><tr><td><p><em class="parameter"><code>segmentSize</code></em></p></td><td><p>This parameter sets the maximum payload size (in bytes) of NORM sender messages (not including any NORM message header fields). A sender's <em class="parameter"><code>segmentSize</code></em> value is also used by receivers to limit the payload content of some feedback messages (e.g. <code class="literal">NORM_NACK</code> message content, etc.) generated in response to that sender. Note different senders within a <span class="emphasis"><em>NormSession</em></span> may use different segmentSize values. Generally, the appropriate segment size to use is dependent upon the types of networks forming the multicast topology, but applications may choose different values for other purposes. Note that application designers MUST account for the size of NORM message headers when selecting a <em class="parameter"><code>segmentSize</code></em>. For example, the <code class="literal">NORM_DATA</code> message header for a <code class="literal">NORM_OBJECT_STREAM</code> with full header extensions is 48 bytes in length. In this case, the UDP payload size of these messages generated by NORM would be up to (48 + <em class="parameter"><code>segmentSize</code></em>) bytes.</p></td></tr><tr><td><p><em class="parameter"><code>blockSize</code></em></p></td><td><p>This parameter sets the number of source symbol segments (packets) per coding block, for the systematic Reed-Solomon FEC code used in the current NORM implementation. For traditional systematic block code "(n,k)" nomenclature, the <em class="parameter"><code>blockSize</code></em> value corresponds to "k". NORM logically segments transport object data content into coding blocks and the <em class="parameter"><code>blockSize</code></em> parameter determines the number of source symbol segments (packets) comprising a single coding block where each source symbol segment is up to <em class="parameter"><code>segmentSize</code></em> bytes in length.. A given block's parity symbol segments are calculated using the corresponding set of source symbol segments. The maximum <em class="parameter"><code>blockSize</code></em> allowed by the 8-bit Reed-Solomon codes in NORM is <code class="constant">255</code>, with the further limitation that (<em class="parameter"><code>blockSize</code></em> + <em class="parameter"><code>numParity</code></em>) <= <code class="constant">255</code>.</p></td></tr><tr><td><p><em class="parameter"><code>numParity</code></em></p></td><td><p>This parameter sets the maximum number of parity symbol segments (packets) the sender is willing to calculate per FEC coding block. The parity symbol segments for a block are calculated from the corresponding <em class="parameter"><code>blockSize</code></em> source symbol segments. In the "<code class="literal">(n,k)</code>" nomenclature mention above, the <em class="parameter"><code>numParity</code></em> value corresponds to "<code class="literal">n - k</code>". A property of the Reed-Solomon FEC codes used in the current NORM implementation is that one parity segment can fill any one erasure (missing segment (packet)) for a coding block. For a given <em class="parameter"><code>blockSize</code></em>, the maximum numParity value is (<code class="constant">255</code> - <em class="parameter"><code>blockSize</code></em>). However, note that computational complexity increases significantly with increasing <em class="parameter"><code>numParity</code></em> values and applications may wish to be conservative with respect to <em class="parameter"><code>numParity</code></em> selection, given anticipated network packet loss conditions and group size scalability concerns. Additional FEC code options may be provided for this NORM implementation in the future with different parameters, capabilities, trade-offs, and computational requirements.</p></td></tr></tbody></table></div><p>These parameters are currently immutable with respect to a sender's participation within a <span class="emphasis"><em>NormSession</em></span>. Sender operation must be stopped (see <a class="link" href="#NormStopSender" title="4.4.2. NormStopSender()"><code class="literal">NormStopSender()</code></a>) and restarted with another call to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> if these parameters require alteration. The API may be extended in the future to support additional flexibility here, if required. For example, the NORM protocol "<em class="parameter"><code>intance_id</code></em>" field may possibly be leveraged to permit a node to establish multiple virtual presences as a sender within a <span class="emphasis"><em>NormSession</em></span> in the future. This would allow the sender to provide multiple concurrent streams of transport, with possibly different FEC and other parameters if appropriate within the context of a single <span class="emphasis"><em>NormSession</em></span>. Again, this extended functionality is not yet supported in this implementation.</p></div><div class="sect4" title="4.4.1.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e2973"></a>4.4.1.3. Return Values</h5></div></div></div><p>A value of <code class="constant">true</code> is returned upon success and <code class="constant">false</code> upon failure. The reasons failure may occur include limited system resources or that the network sockets required for communication failed to open or properly configure. (<span class="emphasis"><em>TBD - Provide a <code class="function">NormGetError</code>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> <em class="parameter"><code>sessionHandle</code></em>) function to retrieve a more specific error indication for this and other functions.</em></span>)</p></div></div><div class="sect3" title="4.4.2. NormStopSender()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStopSender"></a>4.4.2. NormStopSender()</h4></div></div></div><div class="sect4" title="4.4.2.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3000"></a>4.4.2.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormStopSender" title="4.4.2. NormStopSender()"><code class="literal">NormStopSender</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
bool graceful = false);</pre></div><div class="sect4" title="4.4.2.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3013"></a>4.4.2.2. Description</h5></div></div></div><p>This function terminates the application's participation in a <span class="emphasis"><em>NormSession</em></span> as a sender. By default, the sender will immediately exit the session identified by the <em class="parameter"><code>sessionHandle</code></em> parameter without notifying the receiver set of its intention. However a "graceful shutdown" option, enabled by setting the <em class="parameter"><code>graceful</code></em> parameter to true, is provided to terminate sender operation gracefully, notifying the receiver set its pending exit with appropriate protocol messaging. A <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a>, <code class="literal">NORM_LOCAL_SENDER_CLOSED</code>, is dispatched when the graceful shutdown process has completed.</p></div><div class="sect4" title="4.4.2.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3034"></a>4.4.2.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.3. NormSetTxRate()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetTxRate"></a>4.4.3. NormSetTxRate()</h4></div></div></div><div class="sect4" title="4.4.3.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3042"></a>4.4.3.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetTxRate" title="4.4.3. NormSetTxRate()"><code class="literal">NormSetTxRate</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
double rate);</pre></div><div class="sect4" title="4.4.3.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3055"></a>4.4.3.2. Description</h5></div></div></div><p>This function sets the transmission <em class="parameter"><code>rate</code></em> (in bits per second (bps)) limit used for <span class="emphasis"><em>NormSender</em></span> transmissions for the given <em class="parameter"><code>sessionHandle</code></em>. For fixed-rate transmission of <code class="literal">NORM_OBJECT_FILE</code> or <code class="literal">NORM_OBJECT_DATA</code>, this limit determines the data rate at which NORM protocol messages and data content are sent. For <code class="literal">NORM_OBJECT_STREAM</code> transmissions, this is the maximum rate allowed for transmission (i.e. if the application writes to the stream at a lower rate, a lower average NORM transmission rate will occur). Note that the application will need to consider the overhead of NORM protocol headers when determining an appropriate transmission rate for its purposes. When NORM congestion control is enabled (see <a class="link" href="#NormSetCongestionControl" title="4.4.7. NormSetCongestionControl()"><code class="literal">NormSetCongestionControl()</code></a>), the <em class="parameter"><code>rate</code></em> set here will be set, but congestion control operation, if enabled, may quickly readjust the transmission rate.</p></div><div class="sect4" title="4.4.3.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3085"></a>4.4.3.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.4. NormGetTxRate()"><div class="titlepage"><div><div><h4 class="title"><a name="NormGetTxRate"></a>4.4.4. NormGetTxRate()</h4></div></div></div><div class="sect4" title="4.4.4.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3093"></a>4.4.4.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
double <a class="link" href="#NormGetTxRate" title="4.4.4. NormGetTxRate()"><code class="literal">NormGetTxRate</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle);</pre></div><div class="sect4" title="4.4.4.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3106"></a>4.4.4.2. Description</h5></div></div></div><p>This function retrieves the current sender transmission rate in units of bits per second (bps) for the given <em class="parameter"><code>sessionHandle</code></em>. When NORM congestion control is enabled (see <a class="link" href="#NormSetCongestionControl" title="4.4.7. NormSetCongestionControl()"><code class="literal">NormSetCongestionControl()</code></a>), this reflects the current rate set (or suggested) by NORM congestion control operation. Otherwise, this returns the rate that was set with the <code class="literal"><a class="link" href="#NormSetTxRate" title="4.4.3. NormSetTxRate()">NormSetTxRate()</a></code> call.</p></div><div class="sect4" title="4.4.4.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3122"></a>4.4.4.3. Return Values</h5></div></div></div><p>This function returns the sender transmission rate in units of bits per second (bps).</p></div></div><div class="sect3" title="4.4.5. NormSetTxSocketBuffer()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetTxSocketBuffer"></a>4.4.5. NormSetTxSocketBuffer()</h4></div></div></div><div class="sect4" title="4.4.5.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3130"></a>4.4.5.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormSetTxSocketBuffer" title="4.4.5. NormSetTxSocketBuffer()"><code class="literal">NormSetTxSocketBuffer</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
unsigned int bufferSize);</pre></div><div class="sect4" title="4.4.5.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3143"></a>4.4.5.2. Description</h5></div></div></div><p>This function can be used to set a non-default socket buffer size for the UDP socket used by the specified NORM <em class="parameter"><code>sessionHandle</code></em> for data transmission. The <em class="parameter"><code>bufferSize</code></em> parameter specifies the desired socket buffer size in bytes. Large transmit socket buffer sizes may be necessary to achieve high transmission rates when NORM, as a user-space process, is unable to precisely time its packet transmissions. Similarly, NORM receivers may need to set large receive socket buffer sizes to achieve successful, sustained high data rate reception (see <a class="link" href="#NormSetRxSocketBuffer" title="4.5.4. NormSetRxSocketBuffer()"><code class="literal">NormSetRxSocketBuffer()</code></a>). Typically, it is more important to set the receive socket buffer size (see <a class="link" href="#NormSetRxSocketBuffer" title="4.5.4. NormSetRxSocketBuffer()"><code class="literal">NormSetRxSocketBuffer()</code></a>) as this maintains reliability (i.e. by avoiding receive socket buffer overflow) at high data rates while setting a larger transmit socket buffer size allows higher average transmission rates to be achieved.</p></div><div class="sect4" title="4.4.5.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3162"></a>4.4.5.3. Return Values</h5></div></div></div><p>This function returns <code class="constant">true</code> upon success and <code class="constant">false</code> upon failure. Possible failure modes include an invalid <em class="parameter"><code>sessionHandle</code></em> parameter, a call to <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a> or <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> has not yet been made for the session, or an invalid <em class="parameter"><code>bufferSize</code></em> was given. Note some operating systems may require additional system configuration to use non-standard socket buffer sizes.</p></div></div><div class="sect3" title="4.4.6. NormSetFlowControl()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetFlowControl"></a>4.4.6. NormSetFlowControl()</h4></div></div></div><div class="sect4" title="4.4.6.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3190"></a>4.4.6.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetFlowControl" title="4.4.6. NormSetFlowControl()"><code class="literal">NormSetFlowControl</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
double flowControlFactor);</pre></div><div class="sect4" title="4.4.6.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3203"></a>4.4.6.2. Description</h5></div></div></div><p>This function controls a scaling factor that is used for sender timer-based flow control for the the specified NORM <em class="parameter"><code>sessionHandle</code></em>. Timer-based flow control works by preventing the NORM sender application from enqueueing new transmit objects or stream data that would purge "old" objects or stream data when there has been recent NACK activity for those old objects or data. If the <em class="parameter"><code>flowControlFactor</code></em> is set to <code class="constant">ZERO</code>, then the flow control mechanism is effectively disabled. Larger <em class="parameter"><code>flowControlFactor</code></em> values enforce more robust flow control by forcing the sender to maintain state longer, but then larger transmit buffer, stream buffer, transmit cache bounds and receive cache limits (see <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a>, <a class="link" href="#NormStreamOpen" title="4.4.22. NormStreamOpen()"><code class="literal">NormStreamOpen()</code></a>, <a class="link" href="#NormSetTxCacheBounds" title="4.4.9. NormSetTxCacheBounds()"><code class="literal">NormSetTxCacheBounds()</code></a>, and <a class="link" href="#NormSetRxCacheLimit" title="4.5.3. NormSetRxCacheLimit()"><code class="literal">NormSetRxCacheLimit()</code></a>, respectively) may be needed to maintain throughput in larger <delay*bandwidth, loss> conditions. Effectively, a larger <em class="parameter"><code>flowControlFactor</code></em> can favor reliability over throughput when buffer-constrained.</p><p>The <em class="parameter"><code>flowControlFactor</code></em> is used to compute a delay time for when a sender buffered object (or block of stream data) may be released (i.e. purged) after transmission or applicable NACKs reception. The delay time function is:</p><pre class="programlisting">flowControlDelay = flowControlFactor * GRTT * (backoffFactor + 1)</pre><p>where the "<code class="literal">GRTT</code>" is the sender's advertised GRTT estimate and the <code class="literal">backoffFactor</code> is the sender's configured timer-based feedback scaling factor.</p><p>The default value (when this function is not called) of the <em class="parameter"><code>flowControlFactor</code></em> is <code class="constant">2.0</code>. Note that a NORM application can also implement more explicit, deterministic flow control through use of the <a class="link" href="#NormSetWatermark" title="4.4.30. NormSetWatermark()"><code class="literal">NormSetWatermark()</code></a> API call, potentially even requiring positive acknowledgement of older data before enqueueing new data. Note that using the <a class="link" href="#NormSetWatermark" title="4.4.30. NormSetWatermark()"><code class="literal">NormSetWatermark()</code></a> API call with a <code class="constant">NORM_NODE_NONE</code> member in acking node list to force a "full" watermark flush is somewhat equivalent to timer-based flow control with a <em class="parameter"><code>flowControlFactor</code></em> equal to <code class="literal">2.0 * txRobustFactor</code>.</p><p>If such explicit flow control is implemented by the application, then a reduced <em class="parameter"><code>flowControlFactor</code></em> (or even <code class="constant">ZERO</code>) may be used. If "push mode" is enabled for a <code class="constant">NORM_OBJECT_STREAM</code> (see <a class="link" href="#NormStreamSetPushEnable" title="4.4.27. NormStreamSetPushEnable()"><code class="literal">NormStreamSetPushEnable()</code></a>), then flow control has no effect for the stream.</p></div><div class="sect4" title="4.4.6.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3295"></a>4.4.6.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.7. NormSetCongestionControl()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetCongestionControl"></a>4.4.7. NormSetCongestionControl()</h4></div></div></div><div class="sect4" title="4.4.7.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3303"></a>4.4.7.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetCongestionControl" title="4.4.7. NormSetCongestionControl()"><code class="literal">NormSetCongestionControl</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
bool enable,
bool adjustRate = true);</pre></div><div class="sect4" title="4.4.7.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3316"></a>4.4.7.2. Description</h5></div></div></div><p>This function enables (or disables) the NORM sender congestion control operation for the session designated by the <em class="parameter"><code>sessionHandle</code></em> parameter. For best operation, this function should be called before the call to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> is made, but congestion control operation can be dynamically enabled/disabled during the course of sender operation. If the value of the <em class="parameter"><code>enable</code></em> parameter is <code class="constant">true</code>, congestion control operation is enabled while it is disabled for enable equal to <code class="constant">false</code>. When congestion control operation is enabled, the NORM sender automatically adjusts its transmission rate based on feedback from receivers. If bounds on transmission rate have been set (see <a class="link" href="#NormSetTxRateBounds" title="4.4.8. NormSetTxRateBounds()"><code class="literal">NormSetTxRateBounds()</code></a>) the rate adjustment will remain within the set bounds. The application will be notified of any changes to the sender transmission rate via a <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> of type <code class="constant">NORM_TX_RATE_CHANGED</code>.</p><p>The rate set by <a class="link" href="#NormSetTxRate" title="4.4.3. NormSetTxRate()"><code class="literal">NormSetTxRate()</code></a> has no effect when congestion control operation is enabled, <span class="emphasis"><em>unless</em></span> the <em class="parameter"><code>adjustRate</code></em> parameter here is set to <code class="constant">false</code>. When the <em class="parameter"><code>adjustRate</code></em> parameter is set to <code class="constant">false</code>, the NORM Congestion Control operates as usual, with feedback collected from the receiver set and the "current limiting receiver" identified, except that no actual adjustment is made to the sender's transmission rate. I.e., the transmission rate that was set by <code class="literal"><a class="link" href="#NormSetTxRate" title="4.4.3. NormSetTxRate()">NormSetTxRate()</a></code> is observed by the sender regardless of the feedback received. The <code class="constant">NORM_TX_RATE_CHANGED</code> notification will still occur as if the rate were being adjusted and the value returned by <a class="link" href="#NormGetTxRate" title="4.4.4. NormGetTxRate()"><code class="literal">NormGetTxRate()</code></a> reflects the rate that would have been used had the <em class="parameter"><code>adjustRate</code></em> parameter been enabled even though no actual rate change has occurred. The purpose of this variation of NORM Congestion Control operation is to allow applications to get a "suggested" rate from the NORM-CC mechanism. But, it is important to note that this "suggested" rate may or may not be appropriate since the operation of the NORM-CC algorithm is somewhat dependent on the associated NORM sender load on the network. For example, the "suggested" rate may be artificially high if the sender application has not been correspondingly setting the rate and actively transmitting data at that rate. This optional mode of operation is provided for EXPERIMENTAL purposes and is NOT RECOMMENDED for typical use of NORM.</p><p>NORM's congestion algorithm provides rate adjustment to fairly compete for available network bandwidth with other TCP, NORM, or similarly governed traffic flows.</p><p>(<span class="emphasis"><em>TBD - Describe the <code class="function">NormSetEcnSupport()</code> function as this experimental option matures.</em></span>)</p></div><div class="sect4" title="4.4.7.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3393"></a>4.4.7.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.8. NormSetTxRateBounds()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetTxRateBounds"></a>4.4.8. NormSetTxRateBounds()</h4></div></div></div><div class="sect4" title="4.4.8.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3401"></a>4.4.8.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormSetTxRateBounds" title="4.4.8. NormSetTxRateBounds()"><code class="literal">NormSetTxRateBounds</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
double rateMin,
double rateMax);</pre></div><div class="sect4" title="4.4.8.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3414"></a>4.4.8.2. Description</h5></div></div></div><p>This function sets the range of sender transmission rates within which the NORM congestion control algorithm is allowed to operate for the given <em class="parameter"><code>sessionHandle</code></em>. By default, the NORM congestion control algorithm operates with no lower or upper bound on its rate adjustment. This function allows this to be limited where <em class="parameter"><code>rateMin</code></em> corresponds to the minimum transmission rate (bps) and <em class="parameter"><code>rateMax</code></em> corresponds to the maximum transmission rate. One or both of these parameters may be set to values less than zero to remove one or both bounds. For example, the call "<a class="link" href="#NormSetTxRateBounds" title="4.4.8. NormSetTxRateBounds()"><code class="literal">NormSetTxRateBounds</code></a><code class="literal">(session, -1.0, 64000.0)</code>" will set an upper limit of 64 kbps for the sender transmission rate with no lower bound. These rate bounds apply only when congestion control operation is enabled (see <a class="link" href="#NormSetCongestionControl" title="4.4.7. NormSetCongestionControl()"><code class="literal">NormSetCongestionControl()</code></a>). If the current congestion control rate falls outside of the specified bounds, the sender transmission rate will be adjusted to stay within the set bounds.</p></div><div class="sect4" title="4.4.8.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3438"></a>4.4.8.3. Return Values</h5></div></div></div><p>This function returns <code class="constant">true</code> upon success. If both <em class="parameter"><code>rateMin</code></em> and <em class="parameter"><code>rateMax</code></em> are greater than or equal to zero, but (<em class="parameter"><code>rateMax</code></em> <code class="literal"><</code> <em class="parameter"><code>rateMin</code></em>), the rate bounds will remain unset or unchanged and the function will return <code class="constant">false</code>.</p></div></div><div class="sect3" title="4.4.9. NormSetTxCacheBounds()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetTxCacheBounds"></a>4.4.9. NormSetTxCacheBounds()</h4></div></div></div><div class="sect4" title="4.4.9.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3467"></a>4.4.9.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetTxCacheBounds" title="4.4.9. NormSetTxCacheBounds()"><code class="literal">NormSetTxCacheBounds</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
<a class="link" href="#NormSize" title="4.1.8. NormSize"><code class="literal">NormSize</code></a> sizeMax,
unsigned int countMin,
unsigned int countMax);</pre></div><div class="sect4" title="4.4.9.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3484"></a>4.4.9.2. Description</h5></div></div></div><p>This function sets limits that define the number and total size of pending transmit objects a NORM sender will allow to be enqueued by the application. Setting these bounds to large values means the NORM protocol engine will keep history and state for previously transmitted objects for a larger interval of time (depending upon the transmission rate) when the application is actively enqueueing additional objects in response to <code class="literal">NORM_TX_QUEUE_EMPTY</code> notifications. This can allow more time for receivers suffering degraded network conditions to make repair requests before the sender "purges" older objects from its "transmit cache" when new objects are enqueued. A <code class="literal">NORM_TX_OBJECT_PURGED</code> notification is issued when the enqueuing of a new transmit object causes the NORM transmit cache to overflow, indicating the NORM sender no longer needs to reference the designated old transmit object and the application is free to release related resources as needed.</p><p>The <em class="parameter"><code>sizeMax</code></em> parameter sets the maximum total size, in bytes, of enqueued objects allowed, providing the constraints of the <em class="parameter"><code>countMin</code></em> and <em class="parameter"><code>countMax</code></em> parameters are met. The <em class="parameter"><code>countMin</code></em> parameter sets the minimum number of objects the application may enqueue, regardless of the objects' sizes and the <em class="parameter"><code>sizeMax</code></em> value. For example, the default <em class="parameter"><code>sizeMax</code></em> value is 20 Mbyte and the default <em class="parameter"><code>countMin</code></em> is 8, thus allowing the application to always have at least 8 pending objects enqueued for transmission if it desires, even if their total size is greater than 20 Mbyte. Similarly, the <em class="parameter"><code>countMax</code></em> parameter sets a ceiling on how many objects may be enqueued, regardless of their total sizes with respect to the <em class="parameter"><code>sizeMax</code></em> setting. For example, the default <em class="parameter"><code>countMax</code></em> value is 256, which means the application is never allowed to have more than 256 objects pending transmission enqueued, even if they are 256 very small objects. Note that <em class="parameter"><code>countMax</code></em> must be greater than or equal to <em class="parameter"><code>countMin</code></em> and <em class="parameter"><code>countMin</code></em> is recommended to be at least two.</p><p>Note that in the case of <code class="literal">NORM_OBJECT_FILE</code> objects, some operating systems impose limits (e.g. 256) on how many open files a process may have at one time and it may be appropriate to limit the <em class="parameter"><code>countMax</code></em> value accordingly. In other cases, a large <em class="parameter"><code>countMin</code></em> or <em class="parameter"><code>countMax</code></em> may be desired to allow the NORM sender to act as virtual cache of files or other data available for reliable transmission. Future iterations of the NRL NORM implementation may support alternative NORM receiver "group join" policies that would allow the receivers to request transmission of cached content.</p><p>The utility of the <a class="link" href="#NormRequeueObject" title="4.4.21. NormRequeueObject()"><code class="literal">NormRequeueObject()</code></a> API call also depends on the parameters set by this function. The <a class="link" href="#NormRequeueObject" title="4.4.21. NormRequeueObject()"><code class="literal">NormRequeueObject()</code></a> call will only succeed when the given <em class="parameter"><code>objectHandle</code></em> corresponds to an object maintained in the NORM senders "transmit cache".</p></div><div class="sect4" title="4.4.9.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3563"></a>4.4.9.3. Return Values</h5></div></div></div><p>This function has no return value.</p></div></div><div class="sect3" title="4.4.10. NormSetAutoParity()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetAutoParity"></a>4.4.10. NormSetAutoParity()</h4></div></div></div><div class="sect4" title="4.4.10.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3571"></a>4.4.10.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetAutoParity" title="4.4.10. NormSetAutoParity()"><code class="literal">NormSetAutoParity</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
unsigned char autoParity);</pre></div><div class="sect4" title="4.4.10.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3584"></a>4.4.10.2. Description</h5></div></div></div><p>This function sets the quantity of proactive "auto parity" <code class="literal">NORM_DATA</code> messages sent at the end of each FEC coding block. By default (i.e., <em class="parameter"><code>autoParity</code></em> <code class="literal">=</code> <code class="constant">0</code>), FEC content is sent only in response to repair requests (NACKs) from receivers. But, by setting a non-zero value for <em class="parameter"><code>autoParity</code></em>, the sender can automatically accompany each coding block of transport object source data segments (<code class="literal">(NORM_DATA</code> messages) with the set number of FEC segments. The number of source symbol messages (segments) per FEC coding block is determined by the <em class="parameter"><code>blockSize</code></em> parameter used when <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> was called for the given <em class="parameter"><code>sessionHandle</code></em>.</p><p>The use of proactively-sent "auto parity" may eliminate the need for any receiver NACKing to achieve reliable transfer in networks with low packet loss. However, note that the quantity of "auto parity" set adds overhead to transport object transmission. In networks with a predictable level of packet loss and potentially large round-trip times, the use of "auto parity" may allow lower latency in the reliable delivery process. Also, its use may contribute to a smaller amount of receiver feedback as only receivers with exceptional packet loss may need to NACK for additional repair content.</p><p>The value of <em class="parameter"><code>autoParity</code></em> set must be less than or equal to the <em class="parameter"><code>numParity</code></em> parameter set when <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> was called for the given <em class="parameter"><code>sessionHandle</code></em>.</p></div><div class="sect4" title="4.4.10.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3634"></a>4.4.10.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.11. NormGetGrttEstimate()"><div class="titlepage"><div><div><h4 class="title"><a name="NormGetGrttEstimate"></a>4.4.11. NormGetGrttEstimate()</h4></div></div></div><div class="sect4" title="4.4.11.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3642"></a>4.4.11.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
double <a class="link" href="#NormGetGrttEstimate" title="4.4.11. NormGetGrttEstimate()"><code class="literal">NormGetGrttEstimate</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle);</pre></div><div class="sect4" title="4.4.11.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3655"></a>4.4.11.2. Description</h5></div></div></div><p>This function returns the sender's current estimate(in seconds) of group round-trip timing (GRTT) for the given NORM session. This function may be useful for applications to leverage for other purposes the assessment of round-trip timing made by the NORM protocol engine. For example, an application may scale its own timeouts based on connectivity delays among participants in a NORM session. Note that the <code class="literal">NORM_GRTT_UPDATED</code> event is posted (see <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a>) by the NORM protocol engine to indicate when changes in the local sender or remote senders' GRTT estimate occurs.</p></div><div class="sect4" title="4.4.11.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3667"></a>4.4.11.3. Return Values</h5></div></div></div><p>This function returns the current sender group round-trip timing (GRTT) estimate (in units of seconds). A value of <code class="constant">-1.0</code> is returned if an invalid session value is provided.</p></div></div><div class="sect3" title="4.4.12. NormSetGrttEstimate()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetGrttEstimate"></a>4.4.12. NormSetGrttEstimate()</h4></div></div></div><div class="sect4" title="4.4.12.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3678"></a>4.4.12.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetGrttEstimate" title="4.4.12. NormSetGrttEstimate()"><code class="literal">NormSetGrttEstimate</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
double grtt);</pre></div><div class="sect4" title="4.4.12.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3691"></a>4.4.12.2. Description</h5></div></div></div><p>This function sets the sender's estimate of group round-trip time (GRTT) (in units of seconds) for the given NORM <em class="parameter"><code>sessionHandle</code></em>. This function is expected to most typically used to initialize the sender's GRTT estimate prior to the call to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> when the application has a priori confidence that the default initial GRTT value of 0.5 second is inappropriate. The sender GRTT estimate will be updated during normal sender protocol operation after sender startup or if this call is made while sender operation is active. For experimental purposes (or very special application needs), this API provides a mechanism to control or disable the sender GRTT update process (see <a class="link" href="#NormSetGrttProbingMode" title="4.4.14. NormSetGrttProbingMode()"><code class="literal">NormSetGrttProbingMode()</code></a>). The <em class="parameter"><code>grtt</code></em> value (in seconds) will be limited to the maximum GRTT as set (see <a class="link" href="#NormSetGrttMax" title="4.4.13. NormSetGrttMax()"><code class="literal">NormSetGrttMax()</code></a>) or the default maximum of 10 seconds.</p><p>The sender GRTT is advertised to the receiver group and is used to scale various NORM protocol timers. The default NORM GRTT estimation process dynamically measures round-trip timing to determine an appropriate operating value. An overly-large GRTT estimate can introduce additional latency into the reliability process (resulting in a larger virtual delay*bandwidth product for the protocol and potentially requiring more buffer space to maintain reliability). An overly-small GRTT estimate may introduce the potential for feedback implosion, limiting the scalability of group size.</p><p>Also note that the advertised GRTT estimate can also be limited by transmission rate. When the sender transmission rate is low, the GRTT is also governed to a lower bound of the nominal packet transmission interval (i.e., <code class="literal">1/txRate</code>). This maintains the "event driven" nature of the NORM protocol with respect to receiver reception of NORM sender data and commands.</p></div><div class="sect4" title="4.4.12.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3721"></a>4.4.12.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.13. NormSetGrttMax()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetGrttMax"></a>4.4.13. NormSetGrttMax()</h4></div></div></div><div class="sect4" title="4.4.13.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3729"></a>4.4.13.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetGrttMax" title="4.4.13. NormSetGrttMax()"><code class="literal">NormSetGrttMax</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
double grttMax);</pre></div><div class="sect4" title="4.4.13.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3742"></a>4.4.13.2. Description</h5></div></div></div><p>This function sets the sender's maximum advertised GRTT value for the given NORM <em class="parameter"><code>sessionHandle</code></em>. The <em class="parameter"><code>grttMax</code></em> parameter, in units of seconds, limits the GRTT used by the group for scaling protocol timers, regardless of larger measured round trip times. The default maximum for the NRL NORM library is 10 seconds. See the <a class="link" href="#NormSetGrttEstimate" title="4.4.12. NormSetGrttEstimate()"><code class="literal">NormSetGrttEstimate()</code></a> function description for the purpose of the NORM GRTT measurement process.</p></div><div class="sect4" title="4.4.13.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3757"></a>4.4.13.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.14. NormSetGrttProbingMode()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetGrttProbingMode"></a>4.4.14. NormSetGrttProbingMode()</h4></div></div></div><div class="sect4" title="4.4.14.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3765"></a>4.4.14.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetGrttProbingMode" title="4.4.14. NormSetGrttProbingMode()"><code class="literal">NormSetGrttProbingMode</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
<a class="link" href="#NormProbingMode" title="4.1.14. NormProbingMode"><code class="literal">NormProbingMode</code></a> probingMode);</pre></div><div class="sect4" title="4.4.14.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3782"></a>4.4.14.2. Description</h5></div></div></div><p>This function sets the sender's mode of probing for round trip timing measurement responses from the receiver set for the given NORM <em class="parameter"><code>sessionHandle</code></em>. Possible values for the <em class="parameter"><code>probingMode</code></em> parameter include <code class="literal">NORM_PROBE_NONE</code>, <code class="literal">NORM_PROBE_PASSIVE</code>, and <code class="literal">NORM_PROBE_ACTIVE</code>. The default probing mode is <code class="literal">NORM_PROBE_ACTIVE</code>. In this mode, the receiver set explicitly acknowledges NORM sender GRTT probes (<code class="literal">(NORM_C</code><code class="literal"><code class="literal">M</code>D(CC)</code> messages) with <code class="literal">NORM_ACK</code> responses that are group-wise suppressed. Note that NORM receivers also will include their response to GRTT probing piggy-backed on any <code class="literal">NORM_NACK</code> messages sent in this mode as well to minimize feedback.</p><p>Note that the <code class="literal">NORM_PROBE_ACTIVE</code> probing mode is required and automatically set when NORM congestion control operation is enabled (see <a class="link" href="#NormSetCongestionControl" title="4.4.7. NormSetCongestionControl()"><code class="literal">NormSetCongestionControl()</code></a>). Thus, when congestion control is enabled, the <a class="link" href="#NormSetGrttProbingMode" title="4.4.14. NormSetGrttProbingMode()"><code class="literal">NormSetGrttProbingMode()</code></a> function has no effect.</p><p>If congestion control operation is not enabled, the NORM application may elect to reduce the volume of feedback traffic by setting the <em class="parameter"><code>probingMode</code></em> to <code class="literal">NORM_PROBE_PASSIVE</code>. Here, the NORM sender still transmits <code class="literal">NORM_CMD</code><code class="literal">(CC)</code> probe messages multiplexed with its data transmission, but the receiver set does not explicitly acknowledge these probes. Instead the receiver set is limited to opportunistically piggy-backing responses when <code class="literal">NORM_NACK</code> messages are generated. Note that this may, in some cases, introduce some opportunity for bursts of large volume receiver feedback when the sender's estimate of GRTT is incorrect due to the reduced probing feedback. But, in some controlled network environments, this option for passive probing may provide some benefits in reducing protocol overhead.</p><p>Finally, the <em class="parameter"><code>probingMode</code></em> can be set to <code class="literal">NORM_PROBE_NONE</code> to eliminate the overhead (and benefits) of NORM GRTT measurement entirely. In this case, the sender application must explicitly set its estimate of GRTT using the <a class="link" href="#NormSetGrttEstimate" title="4.4.12. NormSetGrttEstimate()"><code class="literal">NormSetGrttEstimate()</code></a> function. See this function for a description of the purpose of the NORM GRTT measurement.</p></div><div class="sect4" title="4.4.14.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3859"></a>4.4.14.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.15. NormSetGrttProbingInterval()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetGrttProbingInterval"></a>4.4.15. NormSetGrttProbingInterval()</h4></div></div></div><div class="sect4" title="4.4.15.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3867"></a>4.4.15.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetGrttProbingInterval" title="4.4.15. NormSetGrttProbingInterval()"><code class="literal">NormSetGrttProbingInterval</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
double intervalMin,
double intervalMax);</pre></div><div class="sect4" title="4.4.15.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3880"></a>4.4.15.2. Description</h5></div></div></div><p>This function controls the sender GRTT measurement and estimation process for the given NORM <em class="parameter"><code>sessionHandle</code></em>. The NORM sender multiplexes periodic transmission of <code class="literal">NORM_CMD</code>(CC) messages with its ongoing data transmission or when data transmission is idle. When NORM congestion control operation is enabled, these probes are sent once per RTT of the current limiting receiver (with respect to congestion control rate). In this case the <em class="parameter"><code>intervalMin</code></em> and <em class="parameter"><code>intervalMax</code></em> parameters (in units of seconds) control the rate at which the sender's estimate of GRTT is updated. At session start, the estimate is updated at <em class="parameter"><code>intervalMin</code></em> and the update interval time is doubled until <em class="parameter"><code>intervalMax</code></em> is reached. This dynamic allows for a rapid initial estimation of GRTT and a slower, steady-state update of GRTT. When congestion control is disabled and NORM GRTT probing is enabled (<code class="literal">(NORM_PROBE_ACTIVE</code> or <code class="literal">NORM_PROBE_PASSIVE</code>) the <em class="parameter"><code>intervalMin</code></em> and <em class="parameter"><code>intervalMax</code></em> values also determine the rate at which <code class="literal">NORM_CMD</code>(CC) probes are transmitted by the sender. Thus by setting larger values for <em class="parameter"><code>intervalMin</code></em> and <em class="parameter"><code>intervalMax</code></em>, the NORM sender application can reduce the overhead of the GRTT measurement process. However, this also reduces the ability of NORM to adapt to changes in GRTT.</p><p>The default NORM GRTT <em class="parameter"><code>intervalMin</code></em> and <em class="parameter"><code>intervalMax</code></em> values, i.e., when this call is not made, are <code class="constant">1.0</code> second and <code class="constant">30.0</code> seconds, respectively.</p></div><div class="sect4" title="4.4.15.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3938"></a>4.4.15.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.16. NormSetBackoffFactor()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetBackoffFactor"></a>4.4.16. NormSetBackoffFactor()</h4></div></div></div><div class="sect4" title="4.4.16.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3946"></a>4.4.16.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetBackoffFactor" title="4.4.16. NormSetBackoffFactor()"><code class="literal">NormSetBackoffFactor</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
double backoffFactor);</pre></div><div class="sect4" title="4.4.16.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3959"></a>4.4.16.2. Description</h5></div></div></div><p>This function sets the sender's "backoff factor" for the given <em class="parameter"><code>sessionHandle</code></em>. The <em class="parameter"><code>backoffFactor</code></em> (in units of seconds) is used to scale various timeouts related to the NACK repair process. The sender advertises its <em class="parameter"><code>backoffFactor</code></em> setting to the receiver group in NORM protocol message headers. The default <em class="parameter"><code>backoffFactor</code></em> for NORM sessions is <code class="constant">4.0</code> seconds. The <em class="parameter"><code>backoffFactor</code></em> is used to determine the maximum time that receivers may delay NACK transmissions (and other feedback messages) as part of NORM's probabilistic feedback suppression technique. For example, the maximum NACK delay time is <em class="parameter"><code>backoffFactor</code></em><code class="literal">*GRTT</code>. Thus a large <code class="literal">backoffFactor</code> value introduces latency into the NORM repair process. However, a small backoffFactor value causes feedback suppression to be less effective and increases the risk of feedback implosion for large receiver group sizes.</p><p>The default setting of <code class="constant">4.0</code> provides reasonable feedback suppression for moderate to large group sizes when multicast feedback is possible. The NORM specification recommends a <code class="literal">backoffFactor</code> value of <code class="constant">6.0</code> when unicast feedback is used. However, for demanding applications (with respect to repair latency) when group sizes are modest, a small (even <code class="constant">0.0</code>) <code class="literal">backoffFactor</code> value can be specified to reduce the latency of reliable data delivery.</p></div><div class="sect4" title="4.4.16.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4007"></a>4.4.16.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.17. NormSetGroupSize()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetGroupSize"></a>4.4.17. NormSetGroupSize()</h4></div></div></div><div class="sect4" title="4.4.17.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4015"></a>4.4.17.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetGroupSize" title="4.4.17. NormSetGroupSize()"><code class="literal">NormSetGroupSize</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
unsigned int groupSize);</pre></div><div class="sect4" title="4.4.17.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4028"></a>4.4.17.2. Description</h5></div></div></div><p>This function sets the sender's estimate of receiver group size for the given <em class="parameter"><code>sessionHandle</code></em>. The sender advertises its <em class="parameter"><code>groupSize</code></em> setting to the receiver group in NORM protocol message headers that, in turn, use this information to shape the distribution curve of their random timeouts for the timer-based, probabilistic feedback suppression technique used in the NORM protocol. Note that the <em class="parameter"><code>groupSize</code></em> estimate does not have to be very accurate and values within an order of magnitude of the actual group size tend to produce acceptable performance.</p><p>The default <em class="parameter"><code>groupSize</code></em> setting in NORM is <code class="constant">1,000</code> and thus can work well for a wide range of actual receiver group sizes. The penalty of an overly large estimate is statistically a little more latency in reliable data delivery with respect to the round trip time and some potential for excess feedback. A substantial underestimation of <em class="parameter"><code>groupSize</code></em> increases the risk of feedback implosion. Currently, the NORM implementation does not attempt to automatically measure <em class="parameter"><code>groupSize</code></em> from receiver feedback. Applications could add their own mechanism for this (perhaps keeping explicit track of group membership), or it is possible that future versions of the NRL NORM implementation may have some provision for automatic <em class="parameter"><code>groupSize</code></em> estimation by the sender based on receiver feedback messages.</p></div><div class="sect4" title="4.4.17.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4059"></a>4.4.17.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.18. NormSetTxRobustFactor()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetTxRobustFactor"></a>4.4.18. NormSetTxRobustFactor()</h4></div></div></div><div class="sect4" title="4.4.18.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4067"></a>4.4.18.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetTxRobustFactor" title="4.4.18. NormSetTxRobustFactor()"><code class="literal">NormSetTxRobustFactor</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
int txRobustFactor);</pre></div><div class="sect4" title="4.4.18.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4080"></a>4.4.18.2. Description</h5></div></div></div><p>This routine sets the "robustness factor" used for various NORM sender functions. These functions include the number of repetitions of "robustly-transmitted" NORM sender commands such as <code class="literal"><code class="literal">NORM_CMD</code>(FLUSH)</code> or similar application-defined commands, and the number of attempts that are made to collect positive acknowledgement from receivers. These commands are distinct from the NORM reliable data transmission process, but play a role in overall NORM protocol operation. The default <em class="parameter"><code>txRobustFactor</code></em> value is <code class="constant">20</code>. This relatively large value makes the NORM sender end-of-transmission flushing and positive acknowledgement collection functions somewhat immune from packet loss. However, for some applications, the default value may make the NORM protocol more "chatty" than desired (particularly if flushing is invoked often). In other situations where the network connectivity may be intermittent or extremely lossy, it may be useful to actually increase this value. The default value (<code class="constant">20</code>) is expected to provide reasonable operation across a wide range of network conditions and application types. Since this value is not communicated among NORM participants as part of the protocol operation, it is important that applications consistently set this value among all applications participating in a NORM session.</p><p>Setting <em class="parameter"><code>txRobustFactor</code></em> to a value of <code class="constant">-1</code> makes the redundant transmission of these commands continue indefinitely until completion. For example, with positive acknowledgement collection, the request process will continue indefinitely until all recipients requested acknowledge or the request is canceled by the application. Similarly, flushing commands would be transmitted repeatedly until data transmission is resumed. Typically, setting <em class="parameter"><code>txRobustFactor</code></em> to <code class="constant">-1</code> is not recommended.</p></div><div class="sect4" title="4.4.18.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4113"></a>4.4.18.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.19. NormFileEnqueue()"><div class="titlepage"><div><div><h4 class="title"><a name="NormFileEnqueue"></a>4.4.19. NormFileEnqueue()</h4></div></div></div><div class="sect4" title="4.4.19.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4121"></a>4.4.19.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> <a class="link" href="#NormFileEnqueue" title="4.4.19. NormFileEnqueue()"><code class="literal">NormFileEnqueue</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
const char* filename,
const char* infoPtr = NULL,
unsigned int infoLen = 0);</pre></div><div class="sect4" title="4.4.19.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4138"></a>4.4.19.2. Description</h5></div></div></div><p>This function enqueues a file for transmission within the specified NORM <em class="parameter"><code>sessionHandle</code></em>. Note that <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> must have been previously called before files or any transport objects may be enqueued and transmitted. The <em class="parameter"><code>fileName</code></em> parameter specifies the path to the file to be transmitted. The NORM protocol engine read and writes directly from/to file system storage for file transport, potentially providing for a very large virtual "repair window" as needed for some applications. While relative paths with respect to the "current working directory" may be used, it is recommended that full paths be used when possible. The optional <em class="parameter"><code>infoPtr</code></em> and <em class="parameter"><code>infoLen</code></em> parameters are used to associate <code class="literal">NORM_INFO</code> content with the sent transport object. The maximum allowed <em class="parameter"><code>infoLen</code></em> corresponds to the <em class="parameter"><code>segmentSize</code></em> used in the prior call to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a>. The use and interpretation of the <code class="literal">NORM_INFO</code> content is left to the application's discretion. Example usage of <code class="literal">NORM_INFO</code> content for <code class="literal">NORM_OBJECT_FILE</code> might include file name, creation date, MIME-type or other information which will enable NORM receivers to properly handle the file when reception is complete.</p><p>The application is allowed to enqueue multiple transmit objects within in the "transmit cache" bounds (see <a class="link" href="#NormSetTxCacheBounds" title="4.4.9. NormSetTxCacheBounds()"><code class="literal">NormSetTxCacheBounds()</code></a>) and enqueued objects are transmitted (and repaired as needed) within the limits determined by automated congestion control (see <a class="link" href="#NormSetCongestionControl" title="4.4.7. NormSetCongestionControl()"><code class="literal">NormSetCongestionControl()</code></a>) or fixed rate (see <code class="literal"><a class="link" href="#NormSetTxRate" title="4.4.3. NormSetTxRate()">NormSetTxRate()</a></code>) parameters.</p></div><div class="sect4" title="4.4.19.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4195"></a>4.4.19.3. Return Values</h5></div></div></div><p>A <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> is returned which the application may use in other NORM API calls as needed. This handle can be considered valid until the application explicitly cancels the object's transmission (see <a class="link" href="#NormObjectCancel" title="4.6.7. NormObjectCancel()"><code class="literal">NormObjectCancel()</code></a>) or a <code class="literal">NORM_TX_OBJECT_PURGED</code> event is received for the given object. Note the application may use the <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a> method if it wishes to refer to the object after the <code class="literal">NORM_TX_OBJECT_PURGED</code> notification. In this case, the application, when finished with the object, must use <a class="link" href="#NormObjectRelease" title="4.6.9. NormObjectRelease()"><code class="literal">NormObjectRelease()</code></a> to free any resources used or else a memory leak condition will result. A value of <code class="literal">NORM_OBJECT_INVALID</code> is return upon error. Possible failure conditions include the specified session is not operating as a NormSender, insufficient memory resources were available, or the "transmit cache" limits have been reached and all previously enqueued NORM transmit objects are pending transmission. Also the call will fail if the <em class="parameter"><code>infoLen</code></em> parameter exceeds the local <span class="emphasis"><em>NormSender</em></span> <em class="parameter"><code>segmentSize</code></em> limit.</p></div></div><div class="sect3" title="4.4.20. NormDataEnqueue()"><div class="titlepage"><div><div><h4 class="title"><a name="NormDataEnqueue"></a>4.4.20. NormDataEnqueue()</h4></div></div></div><div class="sect4" title="4.4.20.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4237"></a>4.4.20.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> <a class="link" href="#NormDataEnqueue" title="4.4.20. NormDataEnqueue()"><code class="literal">NormDataEnqueue</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
const char* dataPtr,
unsigned int dataLen,
const char* infoPtr = NULL,
unsigned int infoLen = 0);</pre></div><div class="sect4" title="4.4.20.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4254"></a>4.4.20.2. Description</h5></div></div></div><p>This function enqueues a segment of application memory space for transmission within the specified NORM <em class="parameter"><code>sessionHandle</code></em>. Note that <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> MUST have been previously called before files or any transport objects may be enqueued and transmitted. The <em class="parameter"><code>dataPtr</code></em> parameter must be a valid pointer to the area of application memory to be transmitted and the <em class="parameter"><code>dataLen</code></em> parameter indicates the quantity of data to transmit. The NORM protocol engine read and writes directly from/to application memory space so it is important that the application does not modify (or deallocate) the memory space during the time the NORM protocol engine may access this area. After calling <a class="link" href="#NormDataEnqueue" title="4.4.20. NormDataEnqueue()"><code class="literal">NormDataEnqueue()</code></a> for a specific application "dataPtr" memory space, the application MUST NOT deallocate (or change the contents of) that memory space until a <code class="literal">NORM_TX_OBJECT_PURGED</code> notification is received for the given object or the application itself explicitly cancels the object's transmission (see <a class="link" href="#NormObjectCancel" title="4.6.7. NormObjectCancel()"><code class="literal">NormObjectCancel()</code></a>).</p><p>The optional <em class="parameter"><code>infoPtr</code></em> and <em class="parameter"><code>infoLen</code></em> parameters are used to associate <code class="literal">NORM_INFO</code> content with the sent transport object. The maximum allowed <em class="parameter"><code>infoLen</code></em> corresponds to the <em class="parameter"><code>segmentSize</code></em> used in the prior call to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a>. The use and interpretation of the <code class="literal">NORM_INFO</code> content is left to the application's discretion. Example usage of <code class="literal">NORM_INFO</code> content for <code class="literal">NORM_OBJECT_DATA</code> might include application-defined data typing or other information which will enable NORM receiver applications to properly interpret the received data when reception is complete. Of course, it is possible that the application may embed such typing information in the object data content itself. This is left to the application's discretion.</p><p>The application is allowed to enqueue multiple transmit objects within in the "transmit cache" bounds (see <a class="link" href="#NormSetTxCacheBounds" title="4.4.9. NormSetTxCacheBounds()"><code class="literal">NormSetTxCacheBounds()</code></a>) and enqueued objects are transmitted (and repaired as needed) within the limits determined by automated congestion control (see <a class="link" href="#NormSetCongestionControl" title="4.4.7. NormSetCongestionControl()"><code class="literal">NormSetCongestionControl()</code></a>) or fixed rate (see <code class="literal"><a class="link" href="#NormSetTxRate" title="4.4.3. NormSetTxRate()">NormSetTxRate()</a></code>) parameters.</p></div><div class="sect4" title="4.4.20.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4327"></a>4.4.20.3. Return Values</h5></div></div></div><p>A <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> is returned which the application may use in other NORM API calls as needed. This handle can be considered valid until the application explicitly cancels the object's transmission (see <a class="link" href="#NormObjectCancel" title="4.6.7. NormObjectCancel()"><code class="literal">NormObjectCancel()</code></a>) or a <code class="literal">NORM_TX_OBJECT_PURGED</code> event is received for the given object. Note the application may use the <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a> method if it wishes to refer to the object after the <code class="literal">NORM_TX_OBJECT_PURGED</code> notification. In this case, the application, when finished with the object, must use <a class="link" href="#NormObjectRelease" title="4.6.9. NormObjectRelease()"><code class="literal">NormObjectRelease()</code></a> to free any resources used or else a memory leak condition will result. A value of <code class="literal">NORM_OBJECT_INVALID</code> is return upon error. Possible failure conditions include the specified session is not operating as a NormSender, insufficient memory resources were available, or the "transmit cache" limits have been reached and all previously enqueued NORM transmit objects are pending transmission. Also the call will fail if the <em class="parameter"><code>infoLen</code></em> parameter exceeds the local <span class="emphasis"><em>NormSender</em></span> <em class="parameter"><code>segmentSize</code></em> limit.</p></div></div><div class="sect3" title="4.4.21. NormRequeueObject()"><div class="titlepage"><div><div><h4 class="title"><a name="NormRequeueObject"></a>4.4.21. NormRequeueObject()</h4></div></div></div><div class="sect4" title="4.4.21.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4369"></a>4.4.21.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
boolNormRequeueObject(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle);</pre></div><div class="sect4" title="4.4.21.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4382"></a>4.4.21.2. Description</h5></div></div></div><p>This function allows the application to resend (or reset transmission of) a <code class="literal">NORM_OBJECT_FILE</code> or <code class="literal">NORM_OBJECT_DATA</code> transmit object that was previously enqueued for the indicated <em class="parameter"><code>sessionHandle</code></em>. This function is useful for applications sending to silent (non-NACKing) receivers as it enables the receivers to take advantage of multiple retransmissions of objects (including any auto-parity set, see <a class="link" href="#NormSetAutoParity" title="4.4.10. NormSetAutoParity()"><code class="literal">NormSetAutoParity()</code></a>) to more robustly receive content. The <em class="parameter"><code>objectHandle</code></em> parameter must be a valid transmit <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> that has not yet been "purged" from the sender's transmit queue. Upon success, the specified object will be fully retransmitted using the same NORM object transport identifier as was used on its initial transmission. This call may be made at any time to restart transmission of a previously-enqueued object, but the <code class="literal">NORM_TX_OBJECT_SENT</code> or <code class="literal">NORM_TX_FLUSH_COMPLETED</code> notifications can serve as good cues for an appropriate time to resend an object. If multiple objects are re-queued, they will be resent in order of their initial enqueueing.</p><p>The transmit cache bounds set by <a class="link" href="#NormSetTxCacheBounds" title="4.4.9. NormSetTxCacheBounds()"><code class="literal">NormSetTxCacheBounds()</code></a> determine the number of previously-sent objects retained in the sender's transmit queue and that are thus eligible to be requeued for retransmission. An object may be requeued via this call multiple times, but each distinct requeue should be done after an indication such as <code class="literal">NORM_TX_OBJECT_SENT</code> or <code class="literal">NORM_TX_FLUSH_COMPLETED</code> for the given object. Otherwise, the object will simply be reset from its current transmission point to transmit from the beginning (i.e. restart). Note that the object type <code class="literal">NORM_OBJECT_STREAM</code> cannot currently be requeued.</p><p>(TBD - should a "numRepeats" parameter be added to this function?)</p></div><div class="sect4" title="4.4.21.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4430"></a>4.4.21.3. Return Values</h5></div></div></div><p>A value of <code class="constant">true</code> is returned upon success and a value of <code class="constant">false</code> is returned upon failure. Possible reasons for failure include an invalid <em class="parameter"><code>objectHandle</code></em> was provided (i.e. a non-transmit object or transmit object that has been "purged" from the transmit queue (see <code class="literal">NORM_TX_OBJECT_PURGED</code>)) or the provided object was of type <code class="literal">NORM_OBJECT_STREAM</code>.</p></div></div><div class="sect3" title="4.4.22. NormStreamOpen()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStreamOpen"></a>4.4.22. NormStreamOpen()</h4></div></div></div><div class="sect4" title="4.4.22.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4453"></a>4.4.22.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> <a class="link" href="#NormStreamOpen" title="4.4.22. NormStreamOpen()"><code class="literal">NormStreamOpen</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
unsigned int bufferSize,
const char* infoPtr = NULL,
unsigned int infoLen = 0);</pre></div><div class="sect4" title="4.4.22.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4470"></a>4.4.22.2. Description</h5></div></div></div><p>This function opens a <code class="literal">NORM_OBJECT_STREAM</code> sender object and enqueues it for transmission within the indicated <em class="parameter"><code>sessionHandle</code></em>. NORM streams provide reliable, in-order delivery of data content written to the stream by the sender application. Note that no data is sent until subsequent calls to <a class="link" href="#NormStreamWrite" title="4.4.24. NormStreamWrite()"><code class="literal">NormStreamWrite()</code></a> are made unless <code class="literal">NORM_INFO</code> content is specified for the stream with the <em class="parameter"><code>infoPtr</code></em> and <em class="parameter"><code>infoLen</code></em> parameters. Example usage of <code class="literal">NORM_INFO</code> content for <code class="literal">NORM_OBJECT_STREAM</code> might include application-defined data typing or other information which will enable NORM receiver applications to properly interpret the received stream as it is being received. The NORM protocol engine buffers data written to the stream for original transmission and repair transmissions as needed to achieve reliable transfer. The <em class="parameter"><code>bufferSize</code></em> parameter controls the size of the stream's "repair window" which limits how far back the sender will "rewind" to satisfy receiver repair requests.</p><p>NORM, as a NACK-oriented protocol, currently lacks a mechanism for receivers to explicitly feedback flow control status to the sender unless the sender application specifically leverages NORM's optional positive-acknowledgement (ACK) features. Thus, the <em class="parameter"><code>bufferSize</code></em> selection plays an important role in reliable delivery of NORM stream content. Generally, a larger <em class="parameter"><code>bufferSize</code></em> value is safer with respect to reliability, but some applications may wish to limit how far the sender rewinds to repair receivers with poor connectivity with respect to the group at large. Such applications may set a smaller <em class="parameter"><code>bufferSize</code></em> to avoid the potential for large latency in data delivery (i.e. favor peak delivery latency over full reliability). This may result in breaks in the reliable delivery of stream data to some receivers, but this form of quasi-reliability while limiting latency may be useful for some types of applications (e.g. reliable real-time messaging, video or sensor or media data transport). Note that NORM receivers can quickly, automatically "resync" to the sender after such breaks if the application leverages the application message boundary recovery features of NORM (see <a class="link" href="#NormStreamMarkEom" title="4.4.29. NormStreamMarkEom()"><code class="literal">NormStreamMarkEom()</code></a>).</p><p>Note that the current implementation of NORM is designed to support only one active stream per session, and that any <code class="literal">NORM_OBJECT_DATA</code> or <code class="literal">NORM_OBJECT_FILE</code> objects enqueued for transmission will not begin transmission until an active stream is closed. Applications requiring multiple streams or concurrent file/data transfer SHOULD generally instantiate multiple <span class="emphasis"><em>NormSessions</em></span> as needed.</p><p>Note there is no corresponding "open" call for receiver streams. Receiver <code class="literal">NORM_OBJECT_STREAMs</code> are automatically opened by the NORM protocol engine and the receiver applications is notified of new streams via the <code class="literal">NORM_RX_OBJECT_NEW</code> notification (see <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a>).</p></div><div class="sect4" title="4.4.22.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4541"></a>4.4.22.3. Return Values</h5></div></div></div><p>A <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> is returned which the application may use in other NORM API calls as needed. This handle can be considered valid until the application explicitly cancels the object's transmission (see <a class="link" href="#NormObjectCancel" title="4.6.7. NormObjectCancel()"><code class="literal">NormObjectCancel()</code></a>) or a <code class="literal">NORM_TX_OBJECT_PURGED</code> event is received for the given object. Note the application may use the <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a> method if it wishes to refer to the object after the <code class="literal">NORM_TX_OBJECT_PURGED</code> notification. In this case, the application, when finished with the object, must use <a class="link" href="#NormObjectRelease" title="4.6.9. NormObjectRelease()"><code class="literal">NormObjectRelease()</code></a> to free any resources used or else a memory leak condition will result. A value of <code class="literal">NORM_OBJECT_INVALID</code> is return upon error. Possible failure conditions include the specified session is not operating as a <span class="emphasis"><em>NormSender</em></span>, insufficient memory resources were available, or the "transmit cache" bounds have been reached and all previously enqueued NORM transmit objects are pending transmission. Also the call will fail if the <em class="parameter"><code>infoLen</code></em> parameter exceeds the local <span class="emphasis"><em>NormSender</em></span> <em class="parameter"><code>segmentSize</code></em> limit.</p></div></div><div class="sect3" title="4.4.23. NormStreamClose()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStreamClose"></a>4.4.23. NormStreamClose()</h4></div></div></div><div class="sect4" title="4.4.23.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4586"></a>4.4.23.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormStreamClose" title="4.4.23. NormStreamClose()"><code class="literal">NormStreamClose</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> streamHandle,
bool graceful = false);</pre></div><div class="sect4" title="4.4.23.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4599"></a>4.4.23.2. Description</h5></div></div></div><p>This function halts transfer of the stream specified by the <em class="parameter"><code>streamHandle</code></em> parameter and releases any resources used unless the associated object has been explicitly retained by a call to <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a>. No further calls to <a class="link" href="#NormStreamWrite" title="4.4.24. NormStreamWrite()"><code class="literal">NormStreamWrite()</code></a> will be successful for the given <em class="parameter"><code>streamHandle</code></em>. The optional graceful parameter, when set to a value of true, may be used by NORM senders to initiate "graceful" shutdown of a transmit stream. In this case, the sender application will be notified that stream has (most likely) completed reliable transfer via the <code class="literal">NORM_TX_OBJECT_PURGED</code> notification upon completion of the graceful shutdown process. When the <em class="parameter"><code>graceful</code></em> option is set to <code class="constant">true</code>, receivers are notified of the stream end via an "stream end" stream control code in <code class="literal">NORM_DATA</code> message and will receive a <code class="literal">NORM_RX_OBJECT_COMPLETED</code> notification after all received stream content has been read. Otherwise, the stream is immediately terminated, regardless of receiver state. In this case, this function is equivalent to the <a class="link" href="#NormObjectCancel" title="4.6.7. NormObjectCancel()"><code class="literal">NormObjectCancel()</code></a> routine and may be used for sender or receiver streams. So, it is expected this function (<a class="link" href="#NormStreamClose" title="4.4.23. NormStreamClose()"><code class="literal">NormStreamClose()</code></a>) will typically be used for transmit streams by NORM senders.</p></div><div class="sect4" title="4.4.23.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4641"></a>4.4.23.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.24. NormStreamWrite()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStreamWrite"></a>4.4.24. NormStreamWrite()</h4></div></div></div><div class="sect4" title="4.4.24.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4649"></a>4.4.24.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
unsigned int <a class="link" href="#NormStreamWrite" title="4.4.24. NormStreamWrite()"><code class="literal">NormStreamWrite</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> streamHandle
const char* buffer,
unsigned int numBytes);</pre></div><div class="sect4" title="4.4.24.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4662"></a>4.4.24.2. Description</h5></div></div></div><p>This function enqueues data for transmission within the NORM stream specified by the <em class="parameter"><code>streamHandle</code></em> parameter. The <em class="parameter"><code>buffer</code></em> parameter must be a pointer to the data to be enqueued and the <em class="parameter"><code>numBytes</code></em> parameter indicates the length of the data content. Note this call does not block and will return immediately. The return value indicates the number of bytes copied from the provided buffer to the internal stream transmission buffers. Calls to this function will be successful unless the stream's transmit buffer space is fully occupied with data pending original or repair transmission if the stream's "push mode" is set to false (default, see <a class="link" href="#NormStreamSetPushEnable" title="4.4.27. NormStreamSetPushEnable()"><code class="literal">NormStreamSetPushEnable()</code></a> for details). If the stream's "push mode" is set to true, a call to <a class="link" href="#NormStreamWrite" title="4.4.24. NormStreamWrite()"><code class="literal">NormStreamWrite()</code></a> will always result in copying of application data to the stream at the cost of previously enqueued data pending transmission (original or repair) being dropped by the NORM protocol engine. While NORM NACK-based reliability does not provide explicit flow control, there is some degree of implicit flow control in limiting writing new data to the stream against pending repairs. Other flow control strategies are possible using the <a class="link" href="#NormSetWatermark" title="4.4.30. NormSetWatermark()"><code class="literal">NormSetWatermark()</code></a> function.<a class="link" href="#NormSetWatermark" title="4.4.30. NormSetWatermark()"><code class="literal">NormSetWatermark()</code></a> function.</p><p>The <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> values <code class="literal">NORM_TX_QUEUE_EMPTY</code> and <code class="literal">NORM_TX_QUEUE_VACANCY</code> are posted with the <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a><em class="parameter"><code>::object</code></em> field set to a valid sender stream <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> to indicate when the stream is ready for writing via this function. Note that the <code class="literal">NORM_TX_QUEUE_VACANCY</code> event type is posted only after the stream's transmit buffer has been completely filled. Thus, the application must make a call to <a class="link" href="#NormStreamWrite" title="4.4.24. NormStreamWrite()"><code class="literal">NormStreamWrite()</code></a> that copies less than the requested <em class="parameter"><code>numBytes</code></em> value (return value less than <em class="parameter"><code>numBytes</code></em>) before additional <code class="literal">NORM_TX_QUEUE_VACANCY</code> events are posted for the given <em class="parameter"><code>streamHandle</code></em> (i.e., the event type is not re-posted until the application has again filled the available stream transmit buffer space). By cueing off of <code class="literal">NORM_TX_QUEUE_EMPTY</code>, the application can write its "freshest" available data to the stream, but by cueing off of <code class="literal">NORM_TX_QUEUE_VACANCY</code>, an application can keep the NORM protocol engine busiest, to achieve the maximum possible throughput at high data rates.</p></div><div class="sect4" title="4.4.24.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4739"></a>4.4.24.3. Return Values</h5></div></div></div><p>This function returns the number of bytes of data successfully enqueued for NORM stream transmission. If the underlying send stream buffer is full, this function may return zero or a value less than the requested <em class="parameter"><code>numBytes</code></em>.</p></div></div><div class="sect3" title="4.4.25. NormStreamFlush()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStreamFlush"></a>4.4.25. NormStreamFlush()</h4></div></div></div><div class="sect4" title="4.4.25.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4750"></a>4.4.25.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormStreamFlush" title="4.4.25. NormStreamFlush()"><code class="literal">NormStreamFlush</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> streamHandle,
bool eom = false,
<a class="link" href="#NormFlushMode" title="4.1.13. NormFlushMode"><code class="literal">NormFlushMode</code></a> flushMode = <code class="literal">NORM_FLUSH_PASSIVE</code>);</pre></div><div class="sect4" title="4.4.25.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4770"></a>4.4.25.2. Description</h5></div></div></div><p>This function causes an immediate "flush" of the transmit stream specified by the <em class="parameter"><code>streamHandle</code></em> parameter. Normally, unless <a class="link" href="#NormStreamSetAutoFlush" title="4.4.26. NormStreamSetAutoFlush()"><code class="literal">NormStreamSetAutoFlush()</code></a> has been invoked, the NORM protocol engine buffers data written to a stream until it has accumulated a sufficient quantity to generate a <code class="literal">NORM_DATA</code> message with a full payload (as designated by the <em class="parameter"><code>segmentSize</code></em> parameter of the <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a> call). This results in most efficient operation with respect to protocol overhead. However, for some NORM streams, the application may not wish wait for such accumulation when critical data has been written to a stream. The default stream "flush" operation invoked via <a class="link" href="#NormStreamFlush" title="4.4.25. NormStreamFlush()"><code class="literal">NormStreamFlush()</code></a> for <em class="parameter"><code>flushMode</code></em> equal to <code class="literal">NORM_FLUSH_PASSIVE</code> causes NORM to immediately transmit all enqueued data for the stream (subject to session transmit rate limits), even if this results in <code class="literal">NORM_DATA</code> messages with "small" payloads. If the optional <em class="parameter"><code>flushMode</code></em> parameter is set to <code class="literal">NORM_FLUSH_ACTIVE</code>, the application can achieve reliable delivery of stream content up to the current write position in an even more proactive fashion. In this case, the sender additionally, actively transmits <code class="literal">NORM_CMD</code>(FLUSH) messages after any enqueued stream content has been sent. This immediately prompt receivers for repair requests which reduces latency of reliable delivery, but at a cost of some additional messaging. Note any such "active" flush activity will be terminated upon the next subsequent write to the stream. If <em class="parameter"><code>flushMode</code></em> is set to <code class="literal">NORM_FLUSH_NONE</code>, this call has no effect other than the optional end-of-message marking described here.</p><p>The optional <em class="parameter"><code>eom</code></em> parameter, when set to <code class="constant">true</code>, allows the sender application to mark an end-of-message indication (see <a class="link" href="#NormStreamMarkEom" title="4.4.29. NormStreamMarkEom()"><code class="literal">NormStreamMarkEom()</code></a>) for the stream and initiate flushing in a single function call. The end-of-message indication causes NORM to embed the appropriate message start byte offset in the <code class="literal">NORM_DATA</code> message generated following a subsequent write to the stream with the <code class="literal">NORM_FLAGS_MSG_START</code> flag. This mechanism provide a means for automatic application message boundary recovery when receivers join or re-sync to a sender mid-stream.</p><p>Note that frequent flushing, particularly for <code class="literal">NORM_FLUSH_ACTIVE</code> operation, may result in more NORM protocol activity than usual, so care must be taken in application design and deployment when scalability to large group sizes is expected.</p></div><div class="sect4" title="4.4.25.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4843"></a>4.4.25.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.26. NormStreamSetAutoFlush()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStreamSetAutoFlush"></a>4.4.26. NormStreamSetAutoFlush()</h4></div></div></div><div class="sect4" title="4.4.26.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4851"></a>4.4.26.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormStreamSetAutoFlush" title="4.4.26. NormStreamSetAutoFlush()"><code class="literal">NormStreamSetAutoFlush</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> streamHandle
<a class="link" href="#NormFlushMode" title="4.1.13. NormFlushMode"><code class="literal">NormFlushMode</code></a> flushMode);</pre></div><div class="sect4" title="4.4.26.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4868"></a>4.4.26.2. Description</h5></div></div></div><p>This function sets "automated flushing" for the NORM transmit stream indicated by the <em class="parameter"><code>streamHandle</code></em> parameter. By default, a NORM transmit stream is "flushed" only when explicitly requested by the application (see <a class="link" href="#NormStreamFlush" title="4.4.25. NormStreamFlush()"><code class="literal">NormStreamFlush()</code></a>). However, to simplify programming, the NORM API allows that automated flushing be enabled such that the "flush" operation occurs every time the full requested buffer provided to a <a class="link" href="#NormStreamWrite" title="4.4.24. NormStreamWrite()"><code class="literal">NormStreamWrite()</code></a> call is successfully enqueued. This may be appropriate for messaging applications where the provided buffers corresponds to an application messages requiring immediate, full transmission. This may make the NORM protocol perhaps more "chatty" than its typical "bulk transfer" form of operation, but can provide a useful capability for some applications.</p><p>Possible values for the <em class="parameter"><code>flushMode</code></em> parameter include <code class="literal">NORM_FLUSH_NONE</code>, <code class="literal">NORM_FLUSH_PASSIVE</code>, and <code class="literal">NORM_FLUSH_ACTIVE</code>. The default setting for a NORM stream is <code class="literal">NORM_FLUSH_NONE</code> where no flushing occurs unless explicitly requested via <a class="link" href="#NormStreamFlush" title="4.4.25. NormStreamFlush()"><code class="literal">NormStreamFlush()</code></a>. By setting the automated <em class="parameter"><code>flushMode</code></em> to <code class="literal">NORM_FLUSH_PASSIVE</code>, the only action taken is to immediately transmit any data that has been written to the stream, even if "runt" <code class="literal">NORM_DATA</code> messages (with payloads less than the <span class="emphasis"><em>NormSender</em></span> <em class="parameter"><code>segmentSize</code></em> parameter) are generated as a result. If <code class="literal">NORM_FLUSH_ACTIVE</code> is specified, the automated flushing operation is further augmented with the additional transmission of <code class="literal">NORM_C</code><code class="literal"><code class="literal">MD</code>(FLUSH)</code> messages to proactively excite the receiver group for repair requests.</p></div><div class="sect4" title="4.4.26.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4930"></a>4.4.26.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.27. NormStreamSetPushEnable()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStreamSetPushEnable"></a>4.4.27. NormStreamSetPushEnable()</h4></div></div></div><div class="sect4" title="4.4.27.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4938"></a>4.4.27.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormStreamSetPushEnable" title="4.4.27. NormStreamSetPushEnable()"><code class="literal">NormStreamSetPushEnable</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> streamHandle,
bool pushEnable);</pre></div><div class="sect4" title="4.4.27.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4951"></a>4.4.27.2. Description</h5></div></div></div><p>This function controls how the NORM API behaves when the application attempts to enqueue new stream data for transmission when the associated stream's transmit buffer is fully occupied with data pending original or repair transmission. By default (<em class="parameter"><code>pushEnable</code></em> <code class="literal">=</code> <code class="constant">false</code>), a call to <a class="link" href="#NormStreamWrite" title="4.4.24. NormStreamWrite()"><code class="literal">NormStreamWrite()</code></a> will return a zero value under this condition, indicating it was unable to enqueue the new data. However, if <em class="parameter"><code>pushEnable</code></em> is set to <code class="constant">true</code> for a given <em class="parameter"><code>streamHandle</code></em>, the NORM protocol engine will discard the oldest buffered stream data (even if it is pending repair transmission or has never been transmitted) as needed to enqueue the new data. Thus a call to <a class="link" href="#NormStreamWrite" title="4.4.24. NormStreamWrite()"><code class="literal">NormStreamWrite()</code></a> will never fail to copy data. This behavior may be desirable for applications where it is more important to quickly delivery new data than to reliably deliver older data written to a stream. The default behavior for a newly opened stream corresponds to <em class="parameter"><code>pushEnable</code></em> equals <code class="constant">false</code>. This limits the rate to which an application can write new data to the stream to the current transmission rate and status of the reliable repair process.</p></div><div class="sect4" title="4.4.27.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4988"></a>4.4.27.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.28. NormStreamHasVacancy()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStreamHasVacancy"></a>4.4.28. NormStreamHasVacancy()</h4></div></div></div><div class="sect4" title="4.4.28.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e4996"></a>4.4.28.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormStreamHasVacancy" title="4.4.28. NormStreamHasVacancy()"><code class="literal">NormStreamHasVacancy</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> <em class="parameter"><code>streamHandle</code></em>);</pre></div><div class="sect4" title="4.4.28.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5012"></a>4.4.28.2. Description</h5></div></div></div><p>This function can be used to query whether the transmit stream, specified by the <em class="parameter"><code>streamHandle</code></em> parameter, has buffer space available so that the application may successfully make a call to <a class="link" href="#NormStreamWrite" title="4.4.24. NormStreamWrite()"><code class="literal">NormStreamWrite()</code></a>. Normally, a call to <a class="link" href="#NormStreamWrite" title="4.4.24. NormStreamWrite()"><code class="literal">NormStreamWrite()</code></a> itself can be used to make this determination, but this function can be useful when "push mode" has been enabled (see the description of the <a class="link" href="#NormStreamSetPushEnable" title="4.4.27. NormStreamSetPushEnable()"><code class="literal">NormStreamSetPushEnable()</code></a> function) and the application wants to avoid overwriting data previously written to the stream that has not yet been transmitted. Note that when "push mode" is enabled, a call to <a class="link" href="#NormStreamWrite" title="4.4.24. NormStreamWrite()"><code class="literal">NormStreamWrite()</code></a> will always succeed, overwriting previously-enqueued data if necessary. Normally, this function will return true after a <code class="literal">NORM_TX_QUEUE_VACANCY</code> notification has been received for a given NORM stream object.</p></div><div class="sect4" title="4.4.28.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5039"></a>4.4.28.3. Return Values</h5></div></div></div><p>This function returns a value of <code class="constant">true</code> when there is transmit buffer space to which the application may write and <code class="constant">false</code> otherwise.</p></div></div><div class="sect3" title="4.4.29. NormStreamMarkEom()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStreamMarkEom"></a>4.4.29. NormStreamMarkEom()</h4></div></div></div><div class="sect4" title="4.4.29.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5053"></a>4.4.29.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormStreamMarkEom" title="4.4.29. NormStreamMarkEom()"><code class="literal">NormStreamMarkEom</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> <em class="parameter"><code>streamHandle</code></em>);</pre></div><div class="sect4" title="4.4.29.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5069"></a>4.4.29.2. Description</h5></div></div></div><p>This function allows the application to indicate to the NORM protocol engine that the last data successfully written to the stream indicated by <em class="parameter"><code>streamHandle</code></em> corresponded to the end of an application-defined message boundary. The end-of-message indication given here will cause the NORM protocol engine to embed the appropriate message start byte offset in the <code class="constant">NORM_DATA</code> message generated that contains the data for the subsequent application call to NormStreamWrite(). Use of this end-of-message marking enables NORM receivers to automatically re-sync to application-defined message boundaries when joining (or re-joining) a NORM session already in progress.</p></div><div class="sect4" title="4.4.29.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5080"></a>4.4.29.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.4.30. NormSetWatermark()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetWatermark"></a>4.4.30. NormSetWatermark()</h4></div></div></div><div class="sect4" title="4.4.30.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5088"></a>4.4.30.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormSetWatermark" title="4.4.30. NormSetWatermark()"><code class="literal">NormSetWatermark</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle,
bool overrideFlush = true);</pre></div><div class="sect4" title="4.4.30.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5105"></a>4.4.30.2. Description</h5></div></div></div><p>This function specifies a "watermark" transmission point at which NORM sender protocol operation should perform a flushing process and/or positive acknowledgment collection for a given <em class="parameter"><code>sessionHandle</code></em>. For <code class="literal">NORM_OBJECT_FILE</code> and <code class="literal">NORM_OBJECT_DATA</code> transmissions, the positive acknowledgement collection will begin when the specified object has been completely transmitted. The <em class="parameter"><code>objectHandle</code></em> parameter must be a valid handle to a previously-created sender object (see <a class="link" href="#NormFileEnqueue" title="4.4.19. NormFileEnqueue()"><code class="literal">NormFileEnqueue()</code></a>, <a class="link" href="#NormDataEnqueue" title="4.4.20. NormDataEnqueue()"><code class="literal">NormDataEnqueue()</code></a>, or <a class="link" href="#NormStreamOpen" title="4.4.22. NormStreamOpen()"><code class="literal">NormStreamOpen()</code></a>). For <code class="literal">NORM_OBJECT_STREAM</code> transmission, the positive acknowledgment collection begins immediately, using the current position (offset of most recent data written) of the sender stream as a reference.</p><p>The functions <a class="link" href="#NormAddAckingNode" title="4.4.32. NormAddAckingNode()"><code class="literal">NormAddAckingNode()</code></a> and <a class="link" href="#NormRemoveAckingNode" title="4.4.33. NormRemoveAckingNode()"><code class="literal">NormRemoveAckingNode()</code></a> are used to manage the list of <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> values corresponding to NORM receivers that are expected to explicitly acknowledge the watermark flushing messages transmitted by the sender. Note that the <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> <code class="literal">NORM_NODE_NONE</code> may be included in the list. Inclusion of <code class="literal">NORM_NODE_NONE</code> forces the watermark flushing process to proceed through a full <code class="literal">NORM_ROBUST_FACTOR</code> number of rounds before completing, prompting any receivers that have not completed reliable reception to the given watermark point to NACK for any repair needs. If NACKs occur, the flushing process is reset and repeated until completing with no NACKs for data through the given watermark transmission point are received. Thus, even without explicit positive acknowledgment, the sender can use this process (by adding <code class="literal">NORM_NODE_NONE</code> to the session's list of "acking nodes") for a high level of assurance that the receiver set is "happy" (completed reliable data reception) through the given object (or stream transmission point).</p><p>The event <code class="literal">NORM_TX_WATERMARK_COMPLETED</code> is posted for the given session when the flushing process or positive acknowledgment collection has completed. The process completes as soon as all listed receivers have responded unless <code class="literal">NORM_NODE_NONE</code> is included in the "acking node" list. The sender application may use the function <a class="link" href="#NormGetAckingStatus" title="4.4.35. NormGetAckingStatus()"><code class="literal">NormGetAckingStatus()</code></a> to determine the degree of success of the flushing process in general or for individual <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> values.</p><p>The flushing is conducted concurrently with ongoing data transmission and does not impede the progress of reliable data transfer. Thus the sender may still enqueue <span class="emphasis"><em>NormObjects</em></span> for transmission (or write to the existing stream) and the positive acknowledgement collection and flushing procedure will be multiplexed with the ongoing data transmission. However, the sender application may wish to defer from or limit itself in sending more data until a <code class="literal">NORM_TX_WATERMARK_COMPLETED</code> event is received for the given session. This provides a form of sender->receiver(s) flow control which does not exist in NORM's default protocol operation. If a subsequent call is made to <a class="link" href="#NormSetWatermark" title="4.4.30. NormSetWatermark()"><code class="literal">NormSetWatermark()</code></a> before the current acknowledgement request has completed, the pending acknowledgment request is canceled and the new one begins.</p><p>The optional <em class="parameter"><code>overrideFlush</code></em> parameter, when set to <code class="constant">true</code>, causes the watermark acknowledgment process that is established with this function call to potentially fully supersede the usual NORM end-of-transmission flushing process that occurs. If <em class="parameter"><code>overrideFlush</code></em> is set and the "watermark" transmission point corresponds to the last transmission that will result from data enqueued by the sending application, then the watermark flush completion will terminate the usual flushing process. I.e., if positive acknowledgement of watermark is received from the full "acking node list", then no further flushing is conducted. Thus, the <em class="parameter"><code>overrideFlush</code></em> parameter should only be set when the "acking node list" contains a complete list of intended recipients. This is useful for small receiver groups (or unicast operation) to reduce the "chattiness" of NORM's default end-of-transmission flush process. Note that once the watermark flush is completed and further data enqueued and transmitted, the normal default end-of-transmission behavior will be resumed unless another "watermark" is set with <em class="parameter"><code>overrideFlush</code></em> enabled. Thus, as long as new watermarks are established by successive use of this API call, this effectively "morphs" NORM into a protocol driven by positive acknowledgement behavior.</p></div><div class="sect4" title="4.4.30.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5212"></a>4.4.30.3. Return Values</h5></div></div></div><p>The function returns <code class="constant">true</code> upon successful establishment of the watermark point. The function may return <code class="constant">false</code> upon failure.</p></div></div><div class="sect3" title="4.4.31. NormCancelWatermark()"><div class="titlepage"><div><div><h4 class="title"><a name="NormCancelWatermark"></a>4.4.31. NormCancelWatermark()</h4></div></div></div><div class="sect4" title="4.4.31.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5226"></a>4.4.31.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormCancelWatermark" title="4.4.31. NormCancelWatermark()"><code class="literal">NormCancelWatermark</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle);</pre></div><div class="sect4" title="4.4.31.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5239"></a>4.4.31.2. Description</h5></div></div></div><p>This function cancels any "watermark" acknowledgement request that was previously set via the <a class="link" href="#NormSetWatermark" title="4.4.30. NormSetWatermark()"><code class="literal">NormSetWatermark()</code></a> function for the given <em class="parameter"><code>sessionHandle</code></em>. The status of any NORM receivers that may have acknowledged prior to cancellation can be queried using the <a class="link" href="#NormGetAckingStatus" title="4.4.35. NormGetAckingStatus()"><code class="literal">NormGetAckingStatus()</code></a> function even after <a class="link" href="#NormCancelWatermark" title="4.4.31. NormCancelWatermark()"><code class="literal">NormCancelWatermark()</code></a> is called. Typically, applications should wait until a event has been posted, but in some special cases it may be useful to terminate the acknowledgement collection process early.</p></div><div class="sect4" title="4.4.31.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5259"></a>4.4.31.3. Return Values</h5></div></div></div><p>The function has no return values.</p></div></div><div class="sect3" title="4.4.32. NormAddAckingNode()"><div class="titlepage"><div><div><h4 class="title"><a name="NormAddAckingNode"></a>4.4.32. NormAddAckingNode()</h4></div></div></div><div class="sect4" title="4.4.32.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5267"></a>4.4.32.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormAddAckingNode" title="4.4.32. NormAddAckingNode()"><code class="literal">NormAddAckingNode</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
<a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> nodeId);</pre></div><div class="sect4" title="4.4.32.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5284"></a>4.4.32.2. Description</h5></div></div></div><p>When this function is called, the specified <em class="parameter"><code>nodeId</code></em> is added to the list of <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> values (i.e., the "acking node" list) used when NORM sender operation performs positive acknowledgement (ACK) collection for the specified <em class="parameter"><code>sessionHandle</code></em>. The optional NORM positive acknowledgement collection occurs when a specified transmission point (see <a class="link" href="#NormSetWatermark" title="4.4.30. NormSetWatermark()"><code class="literal">NormSetWatermark()</code></a>) is reached or for specialized protocol actions such as positively-acknowledged application-defined commands.</p><p>Additionally the special value of <em class="parameter"><code>nodeId</code></em> equal to <code class="literal">NORM_NODE_NONE</code> may be set to force the watermark flushing process through a full <code class="literal">NORM_ROBUST_FACTOR</code> number of rounds regardless of actual acking nodes. Otherwise the flushing process is terminated when all of the nodes in the acking node list have responded. Setting a "watermark" and forcing a full flush process with the special <code class="literal">NORM_NODE_NONE</code> value of <em class="parameter"><code>nodeId</code></em> enables the resultant <code class="literal">NORM_TX_WATERMARK_COMPLETED</code> notification to be a indicator with high (but not absolute) assurance that the receiver set has completed reliable reception of content up through the "watermark" transmission point. This provides a form of scalable reliable multicast "flow control" for NACK-based operation without requiring explicit positive acknowledgement from all group members. Note that the use of the <code class="literal">NORM_NODE_NONE</code> value may be mixed with other <em class="parameter"><code>nodeId</code></em> for a mix of positive acknowledgement collection from some nodes and a measure of assurance for the group at large.</p></div><div class="sect4" title="4.4.32.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5329"></a>4.4.32.3. Return Values</h5></div></div></div><p>The function returns <code class="constant">true</code> upon success and <code class="constant">false</code> upon failure. The only failure condition is that insufficient memory resources were available. If a specific <em class="parameter"><code>nodeId</code></em> is added more than once, this has no effect.</p></div></div><div class="sect3" title="4.4.33. NormRemoveAckingNode()"><div class="titlepage"><div><div><h4 class="title"><a name="NormRemoveAckingNode"></a>4.4.33. NormRemoveAckingNode()</h4></div></div></div><div class="sect4" title="4.4.33.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5346"></a>4.4.33.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormRemoveAckingNode" title="4.4.33. NormRemoveAckingNode()"><code class="literal">NormRemoveAckingNode</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
<a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> nodeId);</pre></div><div class="sect4" title="4.4.33.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5363"></a>4.4.33.2. Description</h5></div></div></div><p>This function deletes the specified <em class="parameter"><code>nodeId</code></em> from the list of <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> values used when NORM sender operation performs positive acknowledgement (ACK) collection for the specified <em class="parameter"><code>sessionHandle</code></em>. Note that if the special <em class="parameter"><code>nodeId</code></em> value "<code class="literal">NORM_NODE_NONE"</code> has been added to the list, it too must be explicitly removed to change the watermark flushing behavior if desired.</p></div><div class="sect4" title="4.4.33.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5384"></a>4.4.33.3. Return Values</h5></div></div></div><p>The function has no return values.</p></div></div><div class="sect3" title="4.4.34. NormGetNextAckingNode()"><div class="titlepage"><div><div><h4 class="title"><a name="NormGetNextAckingNode"></a>4.4.34. NormGetNextAckingNode()</h4></div></div></div><div class="sect4" title="4.4.34.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5392"></a>4.4.34.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
NormNodeId <a class="link" href="#NormRemoveAckingNode" title="4.4.33. NormRemoveAckingNode()"><code class="literal">NormGetNextAckingNode</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> session, bool reset = false);</pre></div><div class="sect4" title="4.4.34.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5405"></a>4.4.34.2. Description</h5></div></div></div><p>This function iteratively retrieves the <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> values in the "acking node" list maintained by a NORM sender (see <a class="link" href="#NormAddAckingNode" title="4.4.32. NormAddAckingNode()"><code class="literal">NormAddAckingNode()</code></a>) for the given <em class="parameter"><code>sessionHandle</code></em>. If the optional <em class="parameter"><code>reset</code></em> parameter is set to a value of <code class="constant">true</code>, the first <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> value in the list is returned and subsequent calls to <a class="link" href="#NormGetNextAckingNode" title="4.4.34. NormGetNextAckingNode()"><code class="literal">NormGetNextAckingNode()</code></a>with the <em class="parameter"><code>reset</code></em> parameter set to its default <code class="constant">false</code> value will iteratively return the remaining <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> values contained in the list. A value of <code class="constant">NORM_NODE_NONE</code> is returned when the end of the list is reached.</p><p>The "acking node" list is populated with application calls to <a class="link" href="#NormAddAckingNode" title="4.4.32. NormAddAckingNode()"><code class="literal">NormAddAckingNode()</code></a> or auto-populated if that optional behavior is set for a NormSession. Note that this API does not enable the programmer to check if the <code class="constant">NORM_NODE_NONE</code> value itself is contained in the list. The programmer should keep track of that by other means.</p><p>The following code example illustrates how to use this call to iterate through the set of stored <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> values and get the current "acking status" for each:</p><pre class="programlisting">NormNodeId nextNodeId = NormGetNextAckingNode(session, true);
while(NORM_NODE_NONE != nextNodeId)
{
NormAckingStatus ackingStatus = NormGetAckingStatus(session, nextNodeId);
printf("ACKing node id = %lu acking status = %d\n", nextNodeId, (int)ackingStatus);
}</pre><p>As noted below, a good time to check the acking status of the receiver set is after a <code class="constant">NORM_TX_WATERMARK_COMPLETED</code> notification has occurred.</p></div><div class="sect4" title="4.4.34.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5470"></a>4.4.34.3. Return Values</h5></div></div></div><p>The function iteratively returns <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> values from the given session's local sender "acking node" list. A value of <code class="constant">NORM_NODE_NONE</code> is returned when the end of the list is reached.</p></div></div><div class="sect3" title="4.4.35. NormGetAckingStatus()"><div class="titlepage"><div><div><h4 class="title"><a name="NormGetAckingStatus"></a>4.4.35. NormGetAckingStatus()</h4></div></div></div><div class="sect4" title="4.4.35.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5485"></a>4.4.35.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
<a class="link" href="#NormAckingStatus" title="4.1.18. NormAckingStatus"><code class="literal">NormAckingStatus</code></a> <a class="link" href="#NormGetAckingStatus" title="4.4.35. NormGetAckingStatus()"><code class="literal">NormGetAckingStatus</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
<a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> nodeId = <code class="literal">NORM_NODE_ANY</code>);</pre></div><div class="sect4" title="4.4.35.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5509"></a>4.4.35.2. Description</h5></div></div></div><p>This function queries the status of the watermark flushing process and/or positive acknowledgment collection initiated by a prior call to <a class="link" href="#NormSetWatermark" title="4.4.30. NormSetWatermark()"><code class="literal">NormSetWatermark()</code></a> for the given <em class="parameter"><code>sessionHandle</code></em>. In general, it is expected that applications will invoke this function after the corresponding <code class="literal">NORM_TX_WATERMARK_COMPLETED</code> event has been posted. Setting the default parameter value <em class="parameter"><code>nodeId</code></em> = <code class="literal">NORM_NODE_ANY</code> returns a "status" indication for the overall process. Also, individual <em class="parameter"><code>nodeId</code></em> values may be queried using the <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> values of receivers that were included in previous calls to <a class="link" href="#NormAddAckingNode" title="4.4.32. NormAddAckingNode()"><code class="literal">NormAddAckingNode()</code></a> to populate the sender session's acking node list.</p><p>If the flushing/acknowledgment process is being used for application flow control, the sender application may wish to reset the watermark and flushing process (using <a class="link" href="#NormSetWatermark" title="4.4.30. NormSetWatermark()"><code class="literal">NormSetWatermark()</code></a>) if the response indicates that some nodes have failed to respond. However, note that the flushing/acknowledgment process itself does elicit NACKs from receivers as needed and is interrupted and reset by any repair response that occurs. Thus, even by the time the flushing process has completed (and <code class="literal">NORM_TX_WATERMARK_COMPLETED</code> is posted) once, this is an indication that the NORM protocol has made a valiant attempt to deliver the content. Resetting the watermark process can increase robustness, but it may be in vain to repeat this process multiple times when likely network connectivity has been lost or expected receivers have failed (dropped out, shut down, etc).</p></div><div class="sect4" title="4.4.35.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5550"></a>4.4.35.3. Return Values</h5></div></div></div><p>Possible return values include:</p><div class="informaltable"><table border="1"><colgroup><col width="50%"><col width="50%"></colgroup><tbody><tr><td><p><code class="literal">NORM_ACK_INVALID</code></p></td><td><p>The given <em class="parameter"><code>sessionHandle</code></em> is invalid or the given <em class="parameter"><code>nodeId</code></em> is not in the sender's acking list.</p></td></tr><tr><td><p><code class="literal">NORM_ACK_FAILURE</code></p></td><td><p>The positive acknowledgement collection process did not receive acknowledgment from every listed receiver (<em class="parameter"><code>nodeId</code></em> = <code class="literal">NORM_NODE_ANY</code>) or the identified <em class="parameter"><code>nodeId</code></em> did not respond.</p></td></tr><tr><td><p><code class="literal">NORM_ACK_PENDING</code></p></td><td><p>The flushing process at large has not yet completed (<em class="parameter"><code>nodeId</code></em> = <code class="literal">NORM_NODE_ANY</code>) or the given individual <em class="parameter"><code>nodeId</code></em> is still being queried for response.</p></td></tr><tr><td><p><code class="literal">NORM_ACK_SUCCESS</code></p></td><td><p>All receivers (<em class="parameter"><code>nodeId</code></em> = <code class="literal">NORM_NODE_ANY</code>) responded with positive acknowledgement or the given specific <em class="parameter"><code>nodeId</code></em> did acknowledge.</p></td></tr></tbody></table></div></div></div><div class="sect3" title="4.4.36. NormSendCommand()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSendCommand"></a>4.4.36. NormSendCommand()</h4></div></div></div><div class="sect4" title="4.4.36.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5626"></a>4.4.36.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormSendCommand" title="4.4.36. NormSendCommand()"><code class="literal">NormSendCommand</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> session,
const char* cmdBuffer,
unsigned int cmdLength,
bool robust = false); </pre></div><div class="sect4" title="4.4.36.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5639"></a>4.4.36.2. Description</h5></div></div></div><p>This function enqueues a NORM application-defined command for transmission. The <em class="parameter"><code>cmdBuffer</code></em> parameter points to a buffer containing the application-defined command content that will be contained in the <code class="literal">NORM_CMD(APPLICATION)</code> message payload. The <em class="parameter"><code>cmdLength</code></em> indicates the length of this content (in bytes) and MUST be less than or equal to the <em class="parameter"><code>segmentLength</code></em> value for the given <em class="parameter"><code>session</code></em> (see <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a>). The NORM command transmission will be multiplexed with any NORM data transmission. The command is NOT delivered reliably, but can be optionally transmitted with repetition (once per GRTT) according to the NORM transmit robust factor value (see <a class="link" href="#NormSetTxRobustFactor" title="4.4.18. NormSetTxRobustFactor()"><code class="literal">NormSetTxRobustFactor()</code></a>) for the given session if the <em class="parameter"><code>robust</code></em> parameter is set to <code class="constant">true</code>. The command transmission is subject to any congestion control or set rate limits for the NORM session. Once the command has been transmitted (with repetition if <em class="parameter"><code>robust</code></em> is set to <code class="constant">true</code>), a <code class="constant">NORM_TX_CMD_SENT</code> notification is issued. An application can only enqueue a <span class="emphasis"><em>single</em></span> command at a time (i.e. the <code class="constant">NORM_TX_CMD_SENT</code> notification must occur before another command can be sent). The <a class="link" href="#NormCancelCommand" title="4.4.37. NormCancelCommand()"><code class="literal">NormCancelCommand()</code></a> call is available to terminate command transmission if needed. Note that if a rapid succession of commands are sent it is possible that the commands may be delivered to the receivers out-of-order. Also, when repetition is requested (i.e., if <em class="parameter"><code>robust</code></em> is set to <code class="constant">true</code>) the receiver may receive duplicate copies of the same command. It is up to the application to provide any needed mechanism for detecting and/or filtering duplicate command reception.</p><p>The application-defined command feature allows NORM applications to provide some out-of-band (with respect to reliable data delivery) signaling to support session management or other functions. The reception of these "atomic" commands is relatively stateless (as compared to reliable data delivery) and thus it is possible for many senders within a group to send commands without extreme resource burden on receivers (i.e. other participants). Again, this "light-weight" signaling mechanism may be used to provide ancillary communication for the group. In the future, an additional API mechanism will be provided to support application-defined positive acknowledgement requests that could conceivably be used to help guarantee command delivery if desired.</p></div><div class="sect4" title="4.4.36.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5700"></a>4.4.36.3. Return Values</h5></div></div></div><p>The function returns <code class="constant">true</code> upon success. The function may fail, returning <code class="constant">false</code>, if the session is not set for sender operation (see <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a>), the <em class="parameter"><code>cmdLength</code></em> exceeds the configured session <em class="parameter"><code>segmentLength</code></em>, or a previously-enqueued command has not yet been sent.</p></div></div><div class="sect3" title="4.4.37. NormCancelCommand()"><div class="titlepage"><div><div><h4 class="title"><a name="NormCancelCommand"></a>4.4.37. NormCancelCommand()</h4></div></div></div><div class="sect4" title="4.4.37.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5724"></a>4.4.37.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormCancelCommand" title="4.4.37. NormCancelCommand()"><code class="literal">NormCancelCommand</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> session);</pre></div><div class="sect4" title="4.4.37.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5737"></a>4.4.37.2. Description</h5></div></div></div><p>This function terminates any pending <code class="literal">NORM_CMD(APPLICATION)</code> transmission that was previously initiated with the <a class="link" href="#NormSendCommand" title="4.4.36. NormSendCommand()"><code class="literal">NormSendCommand()</code></a> call. Due to the asynchrony of the NORM protocol engine thread and the application, it is possible that the command may have been already sent but the <a class="link" href="#NormCancelCommand" title="4.4.37. NormCancelCommand()"><code class="literal">NormCancelCommand()</code></a> call will ensure a <code class="constant">NORM_TX_CMD_SENT</code> notification is <span class="emphasis"><em>not</em></span> issued for that prior command.</p><p>The application-defined command feature allows NORM applications to provide some out-of-band (with respect to reliable data delivery) signaling to support session management or other functions. The reception of these "atomic" commands is relatively stateless (as compared to reliable data delivery) and thus it is possible for many senders within a group to send commands without extreme resource burden on receivers (i.e. other participants). Again, this "light-weight" signaling mechanism may be used to provide ancillary communication for the group. In the future, an additional API mechanism will be provided to support application-defined positive acknowledgement requests that could conceivably be used to help guarantee command delivery if desired.</p></div><div class="sect4" title="4.4.37.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5761"></a>4.4.37.3. Return Values</h5></div></div></div><p>The function has not return value.</p></div></div></div><div class="sect2" title="4.5. NORM Receiver Functions"><div class="titlepage"><div><div><h3 class="title"><a name="d0e5766"></a>4.5. NORM Receiver Functions</h3></div></div></div><div class="sect3" title="4.5.1. NormStartReceiver()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStartReceiver"></a>4.5.1. NormStartReceiver()</h4></div></div></div><div class="sect4" title="4.5.1.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5772"></a>4.5.1.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
unsigned long bufferSpace);</pre></div><div class="sect4" title="4.5.1.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5785"></a>4.5.1.2. Description</h5></div></div></div><p>This function initiates the application's participation as a receiver within the <span class="emphasis"><em>NormSession</em></span> identified by the <em class="parameter"><code>sessionHandle</code></em> parameter. The NORM protocol engine will begin providing the application with receiver-related <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> notifications, and, unless <a class="link" href="#NormSetSilentReceiver" title="4.5.5. NormSetSilentReceiver()"><code class="literal">NormSetSilentReceiver</code></a>(<code class="constant">true</code>) is invoked, respond to senders with appropriate protocol messages. The <em class="parameter"><code>bufferSpace</code></em> parameter is used to set a limit on the amount of <em class="parameter"><code>bufferSpace</code></em> allocated by the receiver per active <span class="emphasis"><em>NormSender</em></span> within the session. The appropriate <em class="parameter"><code>bufferSpace</code></em> to use is a function of expected network delay*bandwidth product and packet loss characteristics. A discussion of trade-offs associated with NORM transmit and receiver buffer space selection is provided later in this document. An insufficient <em class="parameter"><code>bufferSpace</code></em> allocation will result in potentially inefficient protocol operation, even though reliable operation may be maintained. In some cases of a large delay*bandwidth product and/or severe packet loss, a small <em class="parameter"><code>bufferSpace</code></em> allocation (coupled with the lack of explicit flow control in NORM) may result in the receiver "re-syncing" to the sender, resulting in "outages" in the reliable transmissions from a sender (this is analogous to a TCP connection timeout failure).</p></div><div class="sect4" title="4.5.1.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5825"></a>4.5.1.3. Return Values</h5></div></div></div><p>A value of <code class="constant">true</code> is returned upon success and <code class="constant">false</code> upon failure. The reasons failure may occur include limited system resources or that the network sockets required for session communication failed to open or properly configure.</p></div></div><div class="sect3" title="4.5.2. NormStopReceiver()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStopReceiver"></a>4.5.2. NormStopReceiver()</h4></div></div></div><div class="sect4" title="4.5.2.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5839"></a>4.5.2.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormStopReceiver" title="4.5.2. NormStopReceiver()"><code class="literal">NormStopReceiver</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
unsigned int gracePeriod = 0);</pre></div><div class="sect4" title="4.5.2.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5852"></a>4.5.2.2. Description</h5></div></div></div><p>This function ends the application's participation as a receiver in the <span class="emphasis"><em>NormSession</em></span> specified by the session parameter. By default, all receiver-related protocol activity is immediately halted and all receiver-related resources are freed (except for those which have been specifically retained (see <a class="link" href="#NormNodeRetain" title="4.7.7. NormNodeRetain()"><code class="literal">NormNodeRetain()</code></a> and <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a>). However, and optional <em class="parameter"><code>gracePeriod</code></em> parameter is provided to allow the receiver an opportunity to inform the group of its intention. This is applicable when the local receiving <span class="emphasis"><em>NormNode</em></span> has been designated as an active congestion control representative (i.e. current limiting receiver (CLR) or potential limiting receiver (PLR)). In this case, a non-zero <em class="parameter"><code>gracePeriod</code></em> value provides an opportunity for the receiver to respond to the applicable sender(s) so the sender will not expect further congestion control feedback from this receiver. The <em class="parameter"><code>gracePeriod</code></em> integer value is used as a multiplier with the largest sender GRTT to determine the actual time period for which the receiver will linger in the group to provide such feedback (i.e. <code class="literal">"graceTime" = (<em class="parameter"><code>gracePeriod</code></em> * GRTT)</code>). During this time, the receiver will not generate any requests for repair or other protocol actions aside from response to applicable congestion control probes. When the receiver is removed from the current list of receivers in the sender congestion control probe messages (or the <em class="parameter"><code>gracePeriod</code></em> expires, whichever comes first), the NORM protocol engine will post a <code class="literal">NORM_LOCAL_RECEIVER_CLOSED</code> event for the applicable session, and related resources are then freed.</p></div><div class="sect4" title="4.5.2.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5892"></a>4.5.2.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.5.3. NormSetRxCacheLimit()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetRxCacheLimit"></a>4.5.3. NormSetRxCacheLimit()</h4></div></div></div><div class="sect4" title="4.5.3.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5900"></a>4.5.3.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetRxCacheLimit" title="4.5.3. NormSetRxCacheLimit()"><code class="literal">NormSetRxCacheLimit</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
unsigned short countMax);</pre></div><div class="sect4" title="4.5.3.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5913"></a>4.5.3.2. Description</h5></div></div></div><p>This function sets a limit on the number of outstanding (pending) <span class="emphasis"><em>NormObjects</em></span> for which a receiver will keep state on a per-sender basis. Note that the value <em class="parameter"><code>countMax</code></em> sets a limit on the maximum consecutive range of objects that can be pending. The default value (when this function is not called) of <em class="parameter"><code>countMax</code></em> is <code class="constant">256</code>. This should be sufficient for most bulk transfer usage, but if small object sizes (e.g. small <code class="constant">NORM_OBJECT_DATA</code> messages) are being transferred, it may be useful to raise this limit in cases of high transmission speeds or large <delay*bandwidth, loss> network conditions. If the receiver cache limit is set too small (i.e. for high speed or large <delay*bandwidth> operation), the receiver may not maintain reliable reception or impact session throughput when flow control is enabled (see <a class="link" href="#NormSetFlowControl" title="4.4.6. NormSetFlowControl()"><code class="literal">NormSetFlowControl()</code></a>). The maximum allowed value of <em class="parameter"><code>countMax</code></em> is <code class="constant">16,384.</code></p><p>If this value is changed after <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a> has been called, it will only affect newly-detected remote senders, so this should typically be called before NORM receiver operation is initiated.</p></div><div class="sect4" title="4.5.3.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5948"></a>4.5.3.3. Return Values</h5></div></div></div><p>This function has no return value.</p></div></div><div class="sect3" title="4.5.4. NormSetRxSocketBuffer()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetRxSocketBuffer"></a>4.5.4. NormSetRxSocketBuffer()</h4></div></div></div><div class="sect4" title="4.5.4.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5956"></a>4.5.4.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormSetRxSocketBuffer" title="4.5.4. NormSetRxSocketBuffer()"><code class="literal">NormSetRxSocketBuffer</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
unsigned int bufferSize);</pre></div><div class="sect4" title="4.5.4.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5969"></a>4.5.4.2. Description</h5></div></div></div><p>This function allows the application to set an alternative, non-default buffer size for the UDP socket used by the specified NORM <em class="parameter"><code>sessionHandle</code></em> for packet reception. This may be necessary for high speed NORM sessions where the UDP receive socket buffer becomes a bottleneck when the NORM protocol engine (which is running as a user-space process) doesn't get to service the receive socket quickly enough resulting in packet loss when the socket buffer overflows. The <em class="parameter"><code>bufferSize</code></em> parameter specifies the socket buffer size in bytes. Different operating systems and sometimes system configurations allow different ranges of socket buffer sizes to be set. Note that a call to <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a> (or <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a>) must have been previously made for this call to succeed (i.e., the socket must be already open).</p></div><div class="sect4" title="4.5.4.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e5988"></a>4.5.4.3. Return Values</h5></div></div></div><p>This function returns <code class="constant">true</code> upon success and <code class="constant">false</code> upon failure. Possible reasons for failure include, 1) the specified session is not valid, 2) that NORM "receiver" (or "sender") operation has not yet been started for the given session, or 3) an invalid <em class="parameter"><code>bufferSize</code></em> specification was given.</p></div></div><div class="sect3" title="4.5.5. NormSetSilentReceiver()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetSilentReceiver"></a>4.5.5. NormSetSilentReceiver()</h4></div></div></div><div class="sect4" title="4.5.5.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6005"></a>4.5.5.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetSilentReceiver" title="4.5.5. NormSetSilentReceiver()"><code class="literal">NormSetSilentReceiver</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
bool silent,
INT32 maxDelay = -1);</pre></div><div class="sect4" title="4.5.5.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6018"></a>4.5.5.2. Description</h5></div></div></div><p>This function provides the option to configure a NORM receiver application as a "silent receiver". This mode of receiver operation dictates that the host does not generate any protocol messages while operating as a receiver within the specified <em class="parameter"><code>sessionHandle</code></em>. Setting the <em class="parameter"><code>silent</code></em> parameter to <code class="constant">true</code> enables silent receiver operation while setting it to <code class="constant">false</code> results in normal protocol operation where feedback is provided as needed for reliability and protocol operation. Silent receivers are dependent upon proactive FEC transmission (see <a class="link" href="#NormSetAutoParity" title="4.4.10. NormSetAutoParity()"><code class="literal">NormSetAutoParity()</code></a>) or using repair information requested by other non-silent receivers within the group to achieve reliable transfers.</p><p>The optional <em class="parameter"><code>maxDelay</code></em> parameter is most applicable for reception of the <code class="literal">NORM_OBJECT_STREAM</code> type. The default value of <em class="parameter"><code>maxDelay</code></em> <code class="literal">=</code> <code class="constant">-1</code> corresponds to normal operation where source data segments for incompletely-received FEC coding blocks (or transport objects) are passed to the application only when imposed buffer constraints (either the <code class="literal">NORM_OBJECT_STREAM</code> buffer size (see <a class="link" href="#NormStreamOpen" title="4.4.22. NormStreamOpen()"><code class="literal">NormStreamOpen()</code></a>) or the FEC receive buffer limit (see <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a>) require. Thus, the default behavior (<em class="parameter"><code>maxDelay</code></em> <code class="literal">=</code> <code class="constant">-1</code>), causes the receiver to buffer received FEC code blocks for as long as possible (within buffer constraints as newer data arrives) before allowing the application to read the data. Hence, the receive latency (delay) can be quite long depending upon buffer size settings, transmission rate, etc. When the <code class="constant">maxDelay</code> parameter is set to a non-negative value, the value determines the maximum number of FEC coding blocks (according to a NORM sender's current transmit position) the receiver will cache an incompletely-received FEC block before giving the application the (incomplete) set of received source segments. For example, a value of <em class="parameter"><code>maxDelay</code></em> <code class="literal">=</code> <code class="constant">0</code> will provide the receive application with any data from the previous FEC block as soon as a subsequent FEC block is begun reception. However, this provide no protection against the possibility of out-of-order delivery of packets by the network. Therefore, if lower latency operation is desired when using silent receivers, a minimum <em class="parameter"><code>maxDelay</code></em> value of <code class="constant">1</code> is recommended. For <code class="literal">NORM_OBJECT_FILE</code> and <code class="literal">NORM_OBJECT_DATA</code>, the only impact of a non-negative <em class="parameter"><code>maxDelay</code></em> value is that previous transport objects will be immediately aborted when subsequent object begin reception. Thus, it is not usually recommended to apply a non-negative <em class="parameter"><code>maxDelay</code></em> value when <code class="literal">NORM_OBJECT_STREAM</code> is not being used.</p></div><div class="sect4" title="4.5.5.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6109"></a>4.5.5.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.5.6. NormSetDefaultUnicastNack()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetDefaultUnicastNack"></a>4.5.6. NormSetDefaultUnicastNack()</h4></div></div></div><div class="sect4" title="4.5.6.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6117"></a>4.5.6.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetDefaultUnicastNack" title="4.5.6. NormSetDefaultUnicastNack()"><code class="literal">NormSetDefaultUnicastNack</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
bool enable);</pre></div><div class="sect4" title="4.5.6.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6130"></a>4.5.6.2. Description</h5></div></div></div><p>This function controls the default behavior determining the destination of receiver feedback messages generated while participating in the session. If the <em class="parameter"><code>enable</code></em> parameter is true, "unicast NACKing" is enabled for new remote senders while it is disabled for state equal to false. The NACKing behavior for current remote senders is not affected. When "unicast NACKing" is disabled (default), NACK messages are sent to the session address (usually a multicast address) and port, but when "unicast NACKing" is enabled, receiver feedback messages are sent to the unicast address (and port) based on the source address of sender messages received. For unicast NORM sessions, it is recommended that "unicast NACKing" be enabled. Note that receiver feedback messages subject to potential "unicast NACKing" include NACK-messages as well as some ACK messages such as congestion control feedback. Explicitly solicited ACK messages, such as those used to satisfy sender watermark acknowledgement requests (see <a class="link" href="#NormSetWatermark" title="4.4.30. NormSetWatermark()"><code class="literal">NormSetWatermark()</code></a>) are always unicast to the applicable sender. (<span class="emphasis"><em>TBD - provide API option so that all messages are multicast.</em></span>) The default session-wide behavior for unicast NACKing can be overridden via the <a class="link" href="#NormNodeSetUnicastNack" title="4.5.7. NormNodeSetUnicastNack()"><code class="literal">NormNodeSetUnicastNack()</code></a> function for individual remote senders.</p></div><div class="sect4" title="4.5.6.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6149"></a>4.5.6.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.5.7. NormNodeSetUnicastNack()"><div class="titlepage"><div><div><h4 class="title"><a name="NormNodeSetUnicastNack"></a>4.5.7. NormNodeSetUnicastNack()</h4></div></div></div><div class="sect4" title="4.5.7.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6157"></a>4.5.7.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormNodeSetUnicastNack" title="4.5.7. NormNodeSetUnicastNack()"><code class="literal">NormNodeSetUnicastNack</code></a>(<a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> senderNode,
bool enable);</pre></div><div class="sect4" title="4.5.7.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6170"></a>4.5.7.2. Description</h5></div></div></div><p>This function controls the destination address of receiver feedback messages generated in response to a specific remote NORM sender corresponding to the <em class="parameter"><code>senderNode</code></em> parameter. If <em class="parameter"><code>enable</code></em> is <code class="constant">true</code>, "unicast NACKing" is enabled while it is disabled for <em class="parameter"><code>enable</code></em> equal to <code class="constant">false</code>. See the description of <a class="link" href="#NormSetDefaultUnicastNack" title="4.5.6. NormSetDefaultUnicastNack()"><code class="literal">NormSetDefaultUnicastNack()</code></a> for details on "unicast NACKing" behavior.</p></div><div class="sect4" title="4.5.7.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6194"></a>4.5.7.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.5.8. NormSetDefaultSyncPolicy()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetDefaultSyncPolicy"></a>4.5.8. NormSetDefaultSyncPolicy()</h4></div></div></div><div class="sect4" title="4.5.8.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6202"></a>4.5.8.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetDefaultSyncPolicy" title="4.5.8. NormSetDefaultSyncPolicy()"><code class="literal">NormSetDefaultSyncPolicy</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
<a class="link" href="#NormSyncPolicy" title="4.1.15. NormSyncPolicy"><code class="literal">NormSyncPolicy</code></a> syncPolicy);</pre></div><div class="sect4" title="4.5.8.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6219"></a>4.5.8.2. Description</h5></div></div></div><p>This function sets the default "synchronization policy" used when beginning (or restarting) reception of objects from a remote sender (i.e., "syncing" to the sender) for the given <em class="parameter"><code>sessionHandle</code></em>. The "synchronization policy" is the behavior observed by the receiver with regards to what objects it attempts to reliably receive (via transmissions of Negative Acknowledgements to the sender(s) or group as needed). There are currently two synchronization policy types defined:</p><div class="informaltable"><table border="1"><colgroup><col width="50%"><col width="50%"></colgroup><tbody><tr><td><p><code class="literal">NORM_SYNC_CURRENT</code></p></td><td><p>Attempt reception of "current" and new objects only. (default)</p></td></tr><tr><td><p><code class="literal">NORM_SYNC_ALL</code></p></td><td><p>Attempt recovery and reliable reception of all objects held in sender transmit object cache and newer objects.</p></td></tr></tbody></table></div><p>The behavior of a receiver using the default <code class="constant">NORM_SYNC_CURRENT</code> policy is to attempt reliable reception only for the first received "current" and newer (with respect to the ordinal NORM object transport identifiers used by the protocol) objects from a given NORM sender. Additionally, reliable reception is only attempted when receiving a non-repair <code class="literal">NORM_DATA</code> message (or optionally a NORM positive acknowledgement request) from the <span class="emphasis"><em>first</em></span> forward error correction (FEC) encoding block of the given object. This somewhat conservative synchronization behavior helps prevent late-joining (or otherwise "flaky" with respect to group membership) receivers from penalizing other receivers in the group by causing the sender to "rewind" and transmit older object content to satisfy the late joiner instead of moving forward with transmission of new content. For large scale, loosely-organized multicast applications, the <code class="constant">NORM_SYNC_CURRENT</code> policy is typically recommended.</p><p>The <code class="constant">NORM_SYNC_ALL</code> policy allows newly joining receivers much more aggressive behavior as they will immediately NACK for all objects from the "current" object backwards through the entire range of objects set by the <a class="link" href="#NormSetRxCacheLimit" title="4.5.3. NormSetRxCacheLimit()"><code class="literal">NormSetRxCacheLimit()</code></a> function. This behavior depends upon the sender to issue an appropriate <code class="literal">NORM_CMD(SQUELCH)</code> response (if applicable) to align (i.e. "synchronize") the new receiver with its current transmit object cache (similar to a "repair window"). This synchronization behavior may be useful for unicast uses of NORM or other applications where the group membership is more carefully managed and it is important that all content (including older content) is received. Note that the sender transmit cache bounds (see <a class="link" href="#NormSetTxCacheBounds" title="4.4.9. NormSetTxCacheBounds()"><code class="literal">NormSetTxCacheBounds()</code></a>) and the receiver receive cache limit (see <a class="link" href="#NormSetRxCacheLimit" title="4.5.3. NormSetRxCacheLimit()"><code class="literal">NormSetRxCacheLimit()</code></a>) settings will limit how far back onto the sender transmission history that transmitted objects can be reliably recovered from the "current" transmission point when the receiver begins reception.</p><p>When this function is not invoked, the <code class="constant">NORM_SYNC_CURRENT</code> behavior is observed as the default receiver synchronization policy. This call SHOULD be made before <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a> is called.</p></div><div class="sect4" title="4.5.8.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6289"></a>4.5.8.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.5.9. NormSetDefaultNackingMode()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetDefaultNackingMode"></a>4.5.9. NormSetDefaultNackingMode()</h4></div></div></div><div class="sect4" title="4.5.9.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6297"></a>4.5.9.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetDefaultNackingMode" title="4.5.9. NormSetDefaultNackingMode()"><code class="literal">NormSetDefaultNackingMode</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
<a class="link" href="#NormNackingMode" title="4.1.16. NormNackingMode"><code class="literal">NormNackingMode</code></a> nackingMode);</pre></div><div class="sect4" title="4.5.9.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6314"></a>4.5.9.2. Description</h5></div></div></div><p>This function sets the default "nacking mode" used when receiving objects for the given <em class="parameter"><code>sessionHandle</code></em>. This allows the receiver application some control of its degree of participation in the repair process. By limiting receivers to only request repair of objects in which they are really interested in receiving, some overall savings in unnecessary network loading might be realized for some applications and users. Available nacking modes include:</p><div class="informaltable"><table border="1"><colgroup><col width="50%"><col width="50%"></colgroup><tbody><tr><td><p><code class="literal">NORM_NACK_NONE</code></p></td><td><p>Do not transmit any repair requests for the newly received object.</p></td></tr><tr><td><p><code class="literal">NORM_NACK_INFO_ONLY</code></p></td><td><p>Transmit repair requests for <code class="literal">NORM_INFO</code> content only as needed.</p></td></tr><tr><td><p><code class="literal">NORM_NACK_NORMAL</code></p></td><td><p>Transmit repair requests for entire object as needed.</p></td></tr></tbody></table></div><p>This function specifies the default behavior with respect to any new sender or object. This default behavior may be overridden for specific sender nodes or specific object using <a class="link" href="#NormNodeSetNackingMode" title="4.5.10. NormNodeSetNackingMode()"><code class="literal">NormNodeSetNackingMode()</code></a> or <a class="link" href="#NormObjectSetNackingMode" title="4.5.11. NormObjectSetNackingMode()"><code class="literal">NormObjectSetNackingMode()</code></a>, respectively. The receiver application's use of <code class="literal">NORM_NACK_NONE</code> essentially disables a guarantee of reliable reception, although the receiver may still take advantage of sender repair transmissions in response to other receivers' requests. When the sender provides, <code class="literal">NORM_INFO</code> content for transmitted objects, the <code class="literal">NORM_NACK_INFO_ONLY</code> mode may allows the receiver to reliably receive object context information from which it may choose to "upgrade" its <em class="parameter"><code>nackingMode</code></em> for the specific object via the <a class="link" href="#NormObjectSetNackingMode" title="4.5.11. NormObjectSetNackingMode()"><code class="literal">NormObjectSetNackingMode()</code></a> call. Similarly, the receiver may changes its default <em class="parameter"><code>nackingMode</code></em> with respect to specific senders via the <a class="link" href="#NormNodeSetNackingMode" title="4.5.10. NormNodeSetNackingMode()"><code class="literal">NormNodeSetNackingMode()</code></a> call. The default "default <em class="parameter"><code>nackingMode</code></em>" when this call is not made is <code class="literal">NORM_NACK_NORMAL</code>.</p></div><div class="sect4" title="4.5.9.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6391"></a>4.5.9.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.5.10. NormNodeSetNackingMode()"><div class="titlepage"><div><div><h4 class="title"><a name="NormNodeSetNackingMode"></a>4.5.10. NormNodeSetNackingMode()</h4></div></div></div><div class="sect4" title="4.5.10.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6399"></a>4.5.10.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormNodeSetNackingMode" title="4.5.10. NormNodeSetNackingMode()"><code class="literal">NormNodeSetNackingMode</code></a>(<a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> nodeHandle,
<a class="link" href="#NormNackingMode" title="4.1.16. NormNackingMode"><code class="literal">NormNackingMode</code></a> nackingMode);</pre></div><div class="sect4" title="4.5.10.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6416"></a>4.5.10.2. Description</h5></div></div></div><p>This function sets the default "nacking mode" used for receiving new objects from a specific sender as identified by the <em class="parameter"><code>nodeHandle</code></em> parameter. This overrides the default <em class="parameter"><code>nackingMode</code></em> set for the receive session. See <a class="link" href="#NormSetDefaultNackingMode" title="4.5.9. NormSetDefaultNackingMode()"><code class="literal">NormSetDefaultNackingMode()</code></a> for a description of possible <em class="parameter"><code>nackingMode</code></em> parameter values and other related information.</p></div><div class="sect4" title="4.5.10.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6434"></a>4.5.10.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.5.11. NormObjectSetNackingMode()"><div class="titlepage"><div><div><h4 class="title"><a name="NormObjectSetNackingMode"></a>4.5.11. NormObjectSetNackingMode()</h4></div></div></div><div class="sect4" title="4.5.11.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6442"></a>4.5.11.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormObjectSetNackingMode" title="4.5.11. NormObjectSetNackingMode()"><code class="literal">NormObjectSetNackingMode</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle,
<a class="link" href="#NormNackingMode" title="4.1.16. NormNackingMode"><code class="literal">NormNackingMode</code></a> nackingMode);</pre></div><div class="sect4" title="4.5.11.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6459"></a>4.5.11.2. Description</h5></div></div></div><p>This function sets the "nacking mode" used for receiving a specific transport object as identified by the <em class="parameter"><code>objectHandle</code></em> parameter. This overrides the default nacking mode set for the applicable sender node. See <a class="link" href="#NormSetDefaultNackingMode" title="4.5.9. NormSetDefaultNackingMode()"><code class="literal">NormSetDefaultNackingMode()</code></a> for a description of possible <em class="parameter"><code>nackingMode</code></em> parameter values and other related information.</p></div><div class="sect4" title="4.5.11.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6474"></a>4.5.11.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.5.12. NormSetDefaultRepairBoundary()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetDefaultRepairBoundary"></a>4.5.12. NormSetDefaultRepairBoundary()</h4></div></div></div><div class="sect4" title="4.5.12.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6482"></a>4.5.12.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetDefaultRepairBoundary" title="4.5.12. NormSetDefaultRepairBoundary()"><code class="literal">NormSetDefaultRepairBoundary</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
<a class="link" href="#NormRepairBoundary" title="4.1.17. NormRepairBoundary"><code class="literal">NormRepairBoundary</code></a> repairBoundary);</pre></div><div class="sect4" title="4.5.12.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6499"></a>4.5.12.2. Description</h5></div></div></div><p>This function allows the receiver application to customize, for a given <em class="parameter"><code>sessionHandle</code></em>, at what points the receiver initiates the NORM NACK repair process during protocol operation. Normally, the NORM receiver initiates NACKing for repairs at the FEC code block and transport object boundaries. For smaller block sizes, the NACK repair process is often/quickly initiated and the repair of an object will occur, as needed, during the transmission of the object. This default operation corresponds to <em class="parameter"><code>repairBoundary</code></em> equal to <code class="literal">NORM_BOUNDARY_BLOCK</code>. Using this function, the application may alternatively, setting <em class="parameter"><code>repairBoundary</code></em> equal to <code class="literal">NORM_BOUNDARY_OBJECT</code>, cause the protocol to defer NACK process initiation until the current transport object has been completely transmitted.</p></div><div class="sect4" title="4.5.12.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6519"></a>4.5.12.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.5.13. NormNodeSetRepairBoundary()"><div class="titlepage"><div><div><h4 class="title"><a name="NormNodeSetRepairBoundary"></a>4.5.13. NormNodeSetRepairBoundary()</h4></div></div></div><div class="sect4" title="4.5.13.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6527"></a>4.5.13.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormNodeSetRepairBoundary" title="4.5.13. NormNodeSetRepairBoundary()"><code class="literal">NormNodeSetRepairBoundary</code></a>(<a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> nodeHandle,
<a class="link" href="#NormRepairBoundary" title="4.1.17. NormRepairBoundary"><code class="literal">NormRepairBoundary</code></a> repairBoundary);</pre></div><div class="sect4" title="4.5.13.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6544"></a>4.5.13.2. Description</h5></div></div></div><p>This function allows the receiver application to customize, for the specific remote sender referenced by the <em class="parameter"><code>nodeHandle</code></em> parameter, at what points the receiver initiates the NORM NACK repair process during protocol operation. See the description of <a class="link" href="#NormSetDefaultRepairBoundary" title="4.5.12. NormSetDefaultRepairBoundary()"><code class="literal">NormSetDefaultRepairBoundary()</code></a> for further details on the impact of setting the NORM receiver repair boundary and possible values for the <em class="parameter"><code>repairBoundary</code></em> parameter.</p></div><div class="sect4" title="4.5.13.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6559"></a>4.5.13.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.5.14. NormSetDefaultRxRobustFactor()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetDefaultRxRobustFactor"></a>4.5.14. NormSetDefaultRxRobustFactor()</h4></div></div></div><div class="sect4" title="4.5.14.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6567"></a>4.5.14.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetDefaultRxRobustFactor" title="4.5.14. NormSetDefaultRxRobustFactor()"><code class="literal">NormSetDefaultRxRobustFactor</code></a>(<a class="link" href="#NormSessionHandle" title="4.1.2. NormSessionHandle"><code class="literal">NormSessionHandle</code></a> sessionHandle,
int rxRobustFactor);</pre></div><div class="sect4" title="4.5.14.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6580"></a>4.5.14.2. Description</h5></div></div></div><p>This routine controls how persistently NORM receivers will maintain state for sender(s) and continue to request repairs from the sender(s) even when packet reception has ceased. The <em class="parameter"><code>rxRobustFactor</code></em> value determines how many times a NORM receiver will self-initiate NACKing (repair requests) upon cessation of packet reception from a sender. The default value is <code class="constant">20</code>. Setting <em class="parameter"><code>rxRobustFactor</code></em> to <code class="constant">-1</code> will make the NORM receiver infinitely persistent (i.e., it will continue to NACK indefinitely as long as it is missing data content). It is important to note that the <a class="link" href="#NormSetTxRobustFactor" title="4.4.18. NormSetTxRobustFactor()"><code class="literal">NormSetTxRobustFactor()</code></a> also affects receiver operation in setting the time interval that is used to gauge that sender packet transmission has ceased (i.e., the sender inactivity timeout). This "timeout" interval is a equal of (<code class="literal"><code class="constant">2</code> * GRTT * <em class="parameter"><code>txRobustFactor</code></em></code>). Thus the overall timeout before a NORM receiver quits NACKing is (<code class="literal"><em class="parameter"><code>rxRobustFactor</code></em> * <code class="constant">2</code> * GRTT * <em class="parameter"><code>txRobustFactor</code></em></code>).</p><p>The <a class="link" href="#NormNodeSetRxRobustFactor" title="4.5.15. NormNodeSetRxRobustFactor()"><code class="literal">NormNodeSetRxRobustFactor()</code></a> function can be used to control this behavior on a per-sender basis. When a new remote sender is detected, the default <em class="parameter"><code>rxRobustFactor</code></em> set here is used. Again, the default value is <code class="constant">20</code>.</p></div><div class="sect4" title="4.5.14.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6630"></a>4.5.14.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.5.15. NormNodeSetRxRobustFactor()"><div class="titlepage"><div><div><h4 class="title"><a name="NormNodeSetRxRobustFactor"></a>4.5.15. NormNodeSetRxRobustFactor()</h4></div></div></div><div class="sect4" title="4.5.15.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6638"></a>4.5.15.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormNodeSetRxRobustFactor" title="4.5.15. NormNodeSetRxRobustFactor()"><code class="literal">NormNodeSetRxRobustFactor</code></a>(<a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> nodeHandle,
int rxRobustFactor);</pre></div><div class="sect4" title="4.5.15.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6651"></a>4.5.15.2. Description</h5></div></div></div><p>This routine sets the <em class="parameter"><code>rxRobustFactor</code></em> as described in <a class="link" href="#NormSetDefaultRxRobustFactor" title="4.5.14. NormSetDefaultRxRobustFactor()"><code class="literal">NormSetDefaultRxRobustFactor()</code></a> for an individual remote sender identified by the <em class="parameter"><code>nodeHandle</code></em> parameter. See the description of <a class="link" href="#NormSetDefaultRxRobustFactor" title="4.5.14. NormSetDefaultRxRobustFactor()"><code class="literal">NormSetDefaultRxRobustFactor()</code></a> for details</p></div><div class="sect4" title="4.5.15.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6670"></a>4.5.15.3. Return Values</h5></div></div></div><p>This function has no return values.</p></div></div><div class="sect3" title="4.5.16. NormStreamRead()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStreamRead"></a>4.5.16. NormStreamRead()</h4></div></div></div><div class="sect4" title="4.5.16.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6678"></a>4.5.16.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormStreamRead" title="4.5.16. NormStreamRead()"><code class="literal">NormStreamRead</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> streamHandle,
char* buffer
unsigned int* numBytes);</pre></div><div class="sect4" title="4.5.16.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6691"></a>4.5.16.2. Description</h5></div></div></div><p>This function can be used by the receiver application to read any available data from an incoming NORM stream. NORM receiver applications "learn" of available NORM streams via <code class="literal">NORM_RX_OBJECT_NEW</code> notification events. The <em class="parameter"><code>streamHandle</code></em> parameter here must correspond to a valid <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> value provided during such a prior <code class="literal">NORM_RX_OBJECT_NEW</code> notification. The <em class="parameter"><code>buffer</code></em> parameter must be a pointer to an array where the received data can be stored of a length as referenced by the <em class="parameter"><code>numBytes</code></em> pointer. On successful completion, the <em class="parameter"><code>numBytes</code></em> storage will be modified to indicate the actual number of bytes copied into the provided <em class="parameter"><code>buffer</code></em>. If the <em class="parameter"><code>numBytes</code></em> storage is modified to a zero value, this indicates that no stream data was currently available for reading.</p><p>Note that <a class="link" href="#NormStreamRead" title="4.5.16. NormStreamRead()"><code class="literal">NormStreamRead()</code></a> is never a blocking call and only returns failure (<code class="constant">false</code>) when a break in the integrity of the received stream occurs. The <code class="literal">NORM_RX_OBJECT_UPDATE</code> provides an indication to when there is stream data available for reading. When such notification occurs, the application should repeatedly read from the stream until the <em class="parameter"><code>numBytes</code></em> storage is set to zero, even if a <code class="constant">false</code> value is returned. Additional <code class="literal">NORM_RX_OBJECT_UPDATE</code> notifications might not be posted until the application has read all available data.</p></div><div class="sect4" title="4.5.16.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6745"></a>4.5.16.3. Return Values</h5></div></div></div><p>This function normally returns a value of <code class="constant">true</code>. However, if a break in the integrity of the reliable received stream occurs (or the stream has been ended by the sender), a value of <code class="constant">false</code> is returned to indicate the break. Unless the stream has been ended (and the receiver application will receive <code class="literal">NORM_RX_OBJECT_COMPLETED</code> notification for the stream in that case), the application may continue to read from the stream as the NORM protocol will automatically "resync" to streams, even if network conditions are sufficiently poor that breaks in reliability occur. If such a "break" and "resync" occurs, the application may be able to leverage other NORM API calls such as <a class="link" href="#NormStreamSeekMsgStart" title="4.5.17. NormStreamSeekMsgStart()"><code class="literal">NormStreamSeekMsgStart()</code></a> or <a class="link" href="#NormStreamGetReadOffset" title="4.5.18. NormStreamGetReadOffset()"><code class="literal">NormStreamGetReadOffset()</code></a> if needed to recover its alignment with received stream content. This depends upon the nature of the application and its stream content.</p></div></div><div class="sect3" title="4.5.17. NormStreamSeekMsgStart()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStreamSeekMsgStart"></a>4.5.17. NormStreamSeekMsgStart()</h4></div></div></div><div class="sect4" title="4.5.17.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6770"></a>4.5.17.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormStreamSeekMsgStart" title="4.5.17. NormStreamSeekMsgStart()"><code class="literal">NormStreamSeekMsgStart</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> streamHandle);</pre></div><div class="sect4" title="4.5.17.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6783"></a>4.5.17.2. Description</h5></div></div></div><p>This function advances the read offset of the receive stream referenced by the <em class="parameter"><code>streamHandle</code></em> parameter to align with the next available message boundary. Message boundaries are defined by the sender application using the <a class="link" href="#NormStreamMarkEom" title="4.4.29. NormStreamMarkEom()"><code class="literal">NormStreamMarkEom()</code></a> call. Note that any received data prior to the next message boundary is discarded by the NORM protocol engine and is not available to the application (i.e., there is currently no "rewind" function for a NORM stream). Also note this call cannot be used to skip messages. Once a valid message boundary is found, the application must read from the stream using <a class="link" href="#NormStreamRead" title="4.5.16. NormStreamRead()"><code class="literal">NormStreamRead()</code></a> to further advance the read offset. The current offset (in bytes) for the stream can be retrieved via <a class="link" href="#NormStreamGetReadOffset" title="4.5.18. NormStreamGetReadOffset()"><code class="literal">NormStreamGetReadOffset()</code></a>.</p></div><div class="sect4" title="4.5.17.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6803"></a>4.5.17.3. Return Values</h5></div></div></div><p>This function returns a value of <code class="constant">true</code> when start-of-message is found. The next call to <a class="link" href="#NormStreamRead" title="4.5.16. NormStreamRead()"><code class="literal">NormStreamRead()</code></a> will retrieve data aligned with the message start. If no new message boundary is found in the buffered receive data for the stream, the function returns a value of <code class="constant">false</code>. In this case, the application should defer repeating a call to this function until a subsequent <code class="literal">NORM_RX_OBJECT_UPDATE</code> notification is posted.</p></div></div><div class="sect3" title="4.5.18. NormStreamGetReadOffset()"><div class="titlepage"><div><div><h4 class="title"><a name="NormStreamGetReadOffset"></a>4.5.18. NormStreamGetReadOffset()</h4></div></div></div><div class="sect4" title="4.5.18.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6824"></a>4.5.18.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
unsigned long <a class="link" href="#NormStreamGetReadOffset" title="4.5.18. NormStreamGetReadOffset()"><code class="literal">NormStreamGetReadOffset</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> streamHandle);</pre></div><div class="sect4" title="4.5.18.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6837"></a>4.5.18.2. Description</h5></div></div></div><p>This function retrieves the current read offset value for the receive stream indicated by the <em class="parameter"><code>streamHandle</code></em> parameter. Note that for very long-lived streams, this value may wrap. Thus, in general, applications should not be highly dependent upon the stream offset, but this feature may be valuable for certain applications which associate some application context with stream position.</p></div><div class="sect4" title="4.5.18.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6845"></a>4.5.18.3. Return Values</h5></div></div></div><p>This function returns the current read offset in bytes. The return value is undefined for sender streams. There is no error result.</p></div></div></div><div class="sect2" title="4.6. NORM Object Functions"><div class="titlepage"><div><div><h3 class="title"><a name="d0e6850"></a>4.6. NORM Object Functions</h3></div></div></div><p>The functions described in this section may be used for sender or receiver purposes to manage transmission and reception of NORM transport objects. In most cases, the receiver will be the typical user of these functions to retrieve additional information on newly-received objects. All of these functions require a valid <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> argument which specifies the applicable object. Note that <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> values obtained from a <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> notification may be considered valid only until a subsequent call to <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a>, unless explicitly retained by the application (see <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a>). <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> values obtained as a result of <a class="link" href="#NormFileEnqueue" title="4.4.19. NormFileEnqueue()"><code class="literal">NormFileEnqueue()</code></a>, <a class="link" href="#NormDataEnqueue" title="4.4.20. NormDataEnqueue()"><code class="literal">NormDataEnqueue()</code></a>, or <a class="link" href="#NormStreamOpen" title="4.4.22. NormStreamOpen()"><code class="literal">NormStreamOpen()</code></a> calls can be considered valid only until a corresponding <code class="literal">NORM_TX_OBJECT_PURGED</code> notification is posted or the object is dequeued using <a class="link" href="#NormObjectCancel" title="4.6.7. NormObjectCancel()"><code class="literal">NormObjectCancel()</code></a>, unless, again, otherwise explicitly retained (see <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a>).</p><div class="sect3" title="4.6.1. NormObjectGetType()"><div class="titlepage"><div><div><h4 class="title"><a name="NormObjectGetType"></a>4.6.1. NormObjectGetType()</h4></div></div></div><div class="sect4" title="4.6.1.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6905"></a>4.6.1.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
<a class="link" href="#NormObjectType" title="4.1.7. NormObjectType"><code class="literal">NormObjectType</code></a> <a class="link" href="#NormObjectGetType" title="4.6.1. NormObjectGetType()"><code class="literal">NormObjectGetType</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle);</pre></div><div class="sect4" title="4.6.1.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6922"></a>4.6.1.2. Description</h5></div></div></div><p>This function can be used to determine the object type (<code class="literal">(NORM_OBJECT_DAT</code>, <code class="literal">NORM_OBJECT_FILE</code>, or <code class="literal">NORM_OBJECT_STREAM</code>) for the NORM transport object identified by the <em class="parameter"><code>objectHandle</code></em> parameter. The <em class="parameter"><code>objectHandle</code></em> must refer to a current, valid transport object.</p></div><div class="sect4" title="4.6.1.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6942"></a>4.6.1.3. Return Values</h5></div></div></div><p>This function returns the NORM object type. Valid NORM object types include <code class="literal">NORM_OBJECT_DATA</code>, <code class="literal">NORM_OBJECT_FILE</code>, or <code class="literal">NORM_OBJECT_STREAM</code>. A type value of <code class="literal">NORM_OBJECT_NONE</code> will be returned for an <em class="parameter"><code>objectHandle</code></em> value of <code class="literal">NORM_OBJECT_INVALID</code>.</p></div></div><div class="sect3" title="4.6.2. NormObjectHasInfo()"><div class="titlepage"><div><div><h4 class="title"><a name="NormObjectHasInfo"></a>4.6.2. NormObjectHasInfo()</h4></div></div></div><div class="sect4" title="4.6.2.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6968"></a>4.6.2.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormObjectHasInfo" title="4.6.2. NormObjectHasInfo()"><code class="literal">NormObjectHasInfo</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle);</pre></div><div class="sect4" title="4.6.2.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6981"></a>4.6.2.2. Description</h5></div></div></div><p>This function can be used to determine if the sender has associated any <code class="literal">NORM_INFO</code> content with the transport object specified by the <em class="parameter"><code>objectHandle</code></em> parameter. This can even be used before the <code class="literal">NORM_INFO</code> content is delivered to the receiver and a <code class="literal">NORM_RX_OBJECT_INFO</code> notification is posted.</p></div><div class="sect4" title="4.6.2.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e6998"></a>4.6.2.3. Return Values</h5></div></div></div><p>A value of <code class="constant">true</code> is returned if <code class="literal">NORM_INFO</code> is (or will be) available for the specified transport object. A value of <code class="constant">false</code> is returned otherwise.</p></div></div><div class="sect3" title="4.6.3. NormObjectGetInfoLength()"><div class="titlepage"><div><div><h4 class="title"><a name="NormObjectGetInfoLength"></a>4.6.3. NormObjectGetInfoLength()</h4></div></div></div><div class="sect4" title="4.6.3.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7015"></a>4.6.3.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
unsigned short <a class="link" href="#NormObjectGetInfoLength" title="4.6.3. NormObjectGetInfoLength()"><code class="literal">NormObjectGetInfoLength</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle);</pre></div><div class="sect4" title="4.6.3.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7028"></a>4.6.3.2. Description</h5></div></div></div><p>This function can be used to determine the length of currently available <code class="literal">NORM_INFO</code> content (if any) associated with the transport object referenced by the <em class="parameter"><code>objectHandle</code></em> parameter.</p></div><div class="sect4" title="4.6.3.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7039"></a>4.6.3.3. Return Values</h5></div></div></div><p>The length of the <code class="literal">NORM_INFO</code> content, in bytes, of currently available for the specified transport object is returned. A value of <code class="constant">0</code> is returned if no <code class="literal">NORM_INFO</code> content is currently available or associated with the object.</p></div></div><div class="sect3" title="4.6.4. NormObjectGetInfo()"><div class="titlepage"><div><div><h4 class="title"><a name="NormObjectGetInfo"></a>4.6.4. NormObjectGetInfo()</h4></div></div></div><div class="sect4" title="4.6.4.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7056"></a>4.6.4.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
unsigned short <a class="link" href="#NormObjectGetInfo" title="4.6.4. NormObjectGetInfo()"><code class="literal">NormObjectGetInfo</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle,
char* buffer,
unsigned short bufferLen);</pre></div><div class="sect4" title="4.6.4.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7069"></a>4.6.4.2. Description</h5></div></div></div><p>This function copies any <code class="literal">NORM_INFO</code> content associated (by the sender application) with the transport object specified by <em class="parameter"><code>objectHandle</code></em> into the provided memory space referenced by the buffer parameter. The <em class="parameter"><code>bufferLen</code></em> parameter indicates the length of the buffer space in bytes. If the provided <em class="parameter"><code>bufferLen</code></em> is less than the actual <code class="literal">NORM_INFO</code> length, a partial copy will occur. The actual length of <code class="literal">NORM_INFO</code> content available for the specified object is returned. However, note that until a <code class="literal">NORM_RX_OBJECT_INFO</code> notification is posted to the receive application, no <code class="literal">NORM_INFO</code> content is available and a zero result will be returned, even if <code class="literal">NORM_INFO</code> content may be subsequently available. The <a class="link" href="#NormObjectHasInfo" title="4.6.2. NormObjectHasInfo()"><code class="literal">NormObjectHasInfo()</code></a> call can be used to determine if any <code class="literal">NORM_INFO</code> content will ever be available for a specified transport object (i.e., determine if the sender has associated any <code class="literal">NORM_INFO</code> with the object in question).</p></div><div class="sect4" title="4.6.4.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7111"></a>4.6.4.3. Return Values</h5></div></div></div><p>The actual length of currently available <code class="literal">NORM_INFO</code> content for the specified transport object is returned. This function can be used to determine the length of <code class="literal">NORM_INFO</code> content for the object even if a NULL buffer value and zero <em class="parameter"><code>bufferLen</code></em> is provided. A zero value is returned if <code class="literal">NORM_INFO</code> content has not yet been received (or is non-existent) for the specified object.</p></div></div><div class="sect3" title="4.6.5. NormObjectGetSize()"><div class="titlepage"><div><div><h4 class="title"><a name="NormObjectGetSize"></a>4.6.5. NormObjectGetSize()</h4></div></div></div><div class="sect4" title="4.6.5.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7131"></a>4.6.5.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
<a class="link" href="#NormSize" title="4.1.8. NormSize"><code class="literal">NormSize</code></a> <a class="link" href="#NormObjectGetSize" title="4.6.5. NormObjectGetSize()"><code class="literal">NormObjectGetSize</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle);</pre></div><div class="sect4" title="4.6.5.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7148"></a>4.6.5.2. Description</h5></div></div></div><p>This function can be used to determine the size (in bytes) of the transport object specified by the <em class="parameter"><code>objectHandle</code></em> parameter. NORM can support large object sizes for the <code class="literal">NORM_OBJECT_FILE</code> type, so typically the NORM library is built with any necessary, related macros defined such that operating system large file support is enabled (e.g., "<code class="literal">#define <code class="constant">_FILE_OFFSET_BITS</code> <code class="constant">64</code></code>" or equivalent). The <a class="link" href="#NormSize" title="4.1.8. NormSize"><code class="literal">NormSize</code></a> type is defined accordingly, so the application should be built with the same large file support configuration.</p><p>For objects of type <code class="literal">NORM_OBJECT_STREAM</code>, the size returned here corresponds to the stream buffer size set by the sender application when opening the referenced stream object.</p></div><div class="sect4" title="4.6.5.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7176"></a>4.6.5.3. Return Values</h5></div></div></div><p>A size of the data content of the specified object, in bytes, is returned. Note that it may be possible that some objects have zero data content, but do have <code class="literal">NORM_INFO</code> content available.</p></div></div><div class="sect3" title="4.6.6. NormObjectGetBytesPending()"><div class="titlepage"><div><div><h4 class="title"><a name="NormObjectGetBytesPending"></a>4.6.6. NormObjectGetBytesPending()</h4></div></div></div><div class="sect4" title="4.6.6.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7187"></a>4.6.6.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
<a class="link" href="#NormSize" title="4.1.8. NormSize"><code class="literal">NormSize</code></a> <a class="link" href="#NormObjectGetBytesPending" title="4.6.6. NormObjectGetBytesPending()"><code class="literal">NormObjectGetBytesPending</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle);</pre></div><div class="sect4" title="4.6.6.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7204"></a>4.6.6.2. Description</h5></div></div></div><p>This function can be used to determine the progress of reception of the NORM transport object identified by the <em class="parameter"><code>objectHandle</code></em> parameter. This function indicates the number of bytes that are pending reception (I.e., when the object is completely received, "bytes pending" will equal ZERO). This function is not necessarily applicable to objects of type <code class="literal">NORM_OBJECT_STREAM</code> which do not have a finite size. Note it is possible that this function might also be useful to query the "transmit pending" status of sender objects, but it does not account for pending FEC repair transmissions and thus may not produce useful results for this purpose.</p></div><div class="sect4" title="4.6.6.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7215"></a>4.6.6.3. Return Values</h5></div></div></div><p>A number of object source data bytes pending reception (or transmission) is returned.</p></div></div><div class="sect3" title="4.6.7. NormObjectCancel()"><div class="titlepage"><div><div><h4 class="title"><a name="NormObjectCancel"></a>4.6.7. NormObjectCancel()</h4></div></div></div><div class="sect4" title="4.6.7.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7223"></a>4.6.7.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormObjectCancel" title="4.6.7. NormObjectCancel()"><code class="literal">NormObjectCancel</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle);</pre></div><div class="sect4" title="4.6.7.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7236"></a>4.6.7.2. Description</h5></div></div></div><p>This function immediately cancels the transmission of a local sender transport object or the reception of a specified object from a remote sender as specified by the <em class="parameter"><code>objectHandle</code></em> parameter. The <em class="parameter"><code>objectHandle</code></em> must refer to a currently valid NORM transport object. Any resources used by the transport object in question are immediately freed unless the object has been otherwise retained by the application via the <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a> call. Unless the application has retained the object in such fashion, the object in question should be considered invalid and the application must not again reference the <em class="parameter"><code>objectHandle</code></em> after this call is made.</p><p>If the canceled object is a sender object not completely received by participating receivers, the receivers will be informed of the object's cancellation via the NORM protocol <code class="literal">NORM_CMD</code>(SQUELCH) message in response to any NACKs requesting repair or retransmission of the applicable object. In the case of receive objects, the NORM receiver will not make further requests for repair of the indicated object, but furthermore, will acknowledge the object as completed with respect to any associated positive acknowledgement requests (see <a class="link" href="#NormSetWatermark" title="4.4.30. NormSetWatermark()"><code class="literal">NormSetWatermark()</code></a>).</p></div><div class="sect4" title="4.6.7.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7263"></a>4.6.7.3. Return Values</h5></div></div></div><p>This function has no return value.</p></div></div><div class="sect3" title="4.6.8. NormObjectRetain()"><div class="titlepage"><div><div><h4 class="title"><a name="NormObjectRetain"></a>4.6.8. NormObjectRetain()</h4></div></div></div><div class="sect4" title="4.6.8.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7271"></a>4.6.8.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle);</pre></div><div class="sect4" title="4.6.8.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7284"></a>4.6.8.2. Description</h5></div></div></div><p>This function "retains" the <em class="parameter"><code>objectHandle</code></em> and any state associated with it for further use by the application even when the NORM protocol engine may no longer require access to the associated transport object. Normally, the application is guaranteed that a given <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> is valid only while it is being actively transported by NORM (i.e., for sender objects, from the time an object is created by the application until it is canceled by the application or purged (see the <code class="literal">NORM_TX_OBJECT_PURGED</code> notification) by the protocol engine, or, for receiver objects, from the time of the object's <code class="literal">NORM_RX_OBJECT_NEW</code> notification until its reception is canceled by the application or a <code class="literal">NORM_RX_OBJECT_COMPLETED</code> or <code class="literal">NORM_RX_OBJECT_ABORTED</code> notification is posted). Note that an application may refer to a given object after any related notification until the application makes a subsequent call to <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a>.</p><p>When the application makes a call to <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a> for a given <em class="parameter"><code>objectHandle</code></em>, the application may use that <em class="parameter"><code>objectHandle</code></em> value in any NORM API calls until the application makes a call to <a class="link" href="#NormObjectRelease" title="4.6.9. NormObjectRelease()"><code class="literal">NormObjectRelease()</code></a> for the given object. Note that the application MUST make a corresponding call to <a class="link" href="#NormObjectRelease" title="4.6.9. NormObjectRelease()"><code class="literal">NormObjectRelease()</code></a> for each call it has made to <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a> in order to free any system resources (i.e., memory) used by that object. Also note that retaining a receive object also automatically retains any state associated with the <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> corresponding to the remote sender of that receive object so that the application may use NORM node API calls for the value returned by <a class="link" href="#NormObjectGetSender" title="4.6.14. NormObjectGetSender()"><code class="literal">NormObjectGetSender()</code></a> as needed.</p></div><div class="sect4" title="4.6.8.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7344"></a>4.6.8.3. Return Values</h5></div></div></div><p>This function has no return value.</p></div></div><div class="sect3" title="4.6.9. NormObjectRelease()"><div class="titlepage"><div><div><h4 class="title"><a name="NormObjectRelease"></a>4.6.9. NormObjectRelease()</h4></div></div></div><div class="sect4" title="4.6.9.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7352"></a>4.6.9.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormObjectRelease" title="4.6.9. NormObjectRelease()"><code class="literal">NormObjectRelease</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle);</pre></div><div class="sect4" title="4.6.9.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7365"></a>4.6.9.2. Description</h5></div></div></div><p>This function complements the <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a> call by immediately freeing any resources associated with the given <em class="parameter"><code>objectHandle</code></em>, assuming the underlying NORM protocol engine no longer requires access to the corresponding transport object. Note the NORM protocol engine retains/releases state for associated objects for its own needs and thus it is very unsafe for an application to call <a class="link" href="#NormObjectRelease" title="4.6.9. NormObjectRelease()"><code class="literal">NormObjectRelease()</code></a> for an <em class="parameter"><code>objectHandle</code></em> for which it has not previously explicitly retained via <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a>.</p></div><div class="sect4" title="4.6.9.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7388"></a>4.6.9.3. Return Values</h5></div></div></div><p>This function has no return value.</p></div></div><div class="sect3" title="4.6.10. NormFileGetName()"><div class="titlepage"><div><div><h4 class="title"><a name="NormFileGetName"></a>4.6.10. NormFileGetName()</h4></div></div></div><div class="sect4" title="4.6.10.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7396"></a>4.6.10.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormFileGetName" title="4.6.10. NormFileGetName()"><code class="literal">NormFileGetName</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle,
char* nameBuffer,
unsigned int bufferLen);</pre></div><div class="sect4" title="4.6.10.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7409"></a>4.6.10.2. Description</h5></div></div></div><p>This function copies the name, as a <code class="constant">NULL</code>-terminated string, of the file object specified by the <em class="parameter"><code>objectHandle</code></em> parameter into the <em class="parameter"><code>nameBuffer</code></em> of length <em class="parameter"><code>bufferLen</code></em> bytes provided by the application. The <em class="parameter"><code>objectHandle</code></em> parameter must refer to a valid <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> for an object of type <code class="literal">NORM_OBJECT_FILE</code>. If the actual name is longer than the provided <em class="parameter"><code>bufferLen</code></em>, a partial copy will occur. Note that the file name consists of the entire path name of the specified file object and the application should give consideration to operating system file path lengths when providing the <em class="parameter"><code>nameBuffer</code></em>.</p></div><div class="sect4" title="4.6.10.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7442"></a>4.6.10.3. Return Values</h5></div></div></div><p>This function returns <code class="constant">true</code> upon success and <code class="constant">false</code> upon failure. Possible failure conditions include the <em class="parameter"><code>objectHandle</code></em> does not refer to an object of type <code class="literal">NORM_OBJECT_FILE</code>.</p></div></div><div class="sect3" title="4.6.11. NormFileRename()"><div class="titlepage"><div><div><h4 class="title"><a name="NormFileRename"></a>4.6.11. NormFileRename()</h4></div></div></div><div class="sect4" title="4.6.11.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7462"></a>4.6.11.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormFileRename" title="4.6.11. NormFileRename()"><code class="literal">NormFileRename</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle,
const char* fileName);</pre></div><div class="sect4" title="4.6.11.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7475"></a>4.6.11.2. Description</h5></div></div></div><p>This function renames the file used to store content for the <code class="literal">NORM_OBJECT_FILE</code> transport object specified by the <em class="parameter"><code>objectHandle</code></em> parameter. This allows receiver applications to rename (or move) received files as needed. NORM uses temporary file names for received files until the application explicitly renames the file. For example, sender applications may choose to use the <code class="literal">NORM_INFO</code> content associated with a file object to provide name and/or typing information to receivers. The <em class="parameter"><code>fileName</code></em> parameter must be a <code class="constant">NULL</code>-terminated string which should specify the full desired path name to be used. NORM will attempt to create sub-directories as needed to satisfy the request. Note that existing files of the same name may be overwritten.</p></div><div class="sect4" title="4.6.11.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7495"></a>4.6.11.3. Return Values</h5></div></div></div><p>This function returns true upon success and false upon failure. Possible failure conditions include the case where the <em class="parameter"><code>objectHandle</code></em> does not refer to an object of type <code class="literal">NORM_OBJECT_FILE</code> and where NORM was unable to successfully create any needed directories and/or the file itself.</p></div></div><div class="sect3" title="4.6.12. NormDataAccessData()"><div class="titlepage"><div><div><h4 class="title"><a name="NormDataAccessData"></a>4.6.12. NormDataAccessData()</h4></div></div></div><div class="sect4" title="4.6.12.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7509"></a>4.6.12.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
const char* <a class="link" href="#NormDataAccessData" title="4.6.12. NormDataAccessData()"><code class="literal">NormDataAccessData</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle);</pre></div><div class="sect4" title="4.6.12.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7522"></a>4.6.12.2. Description</h5></div></div></div><p>This function allows the application to access the data storage area associated with a transport object of type <code class="literal">NORM_OBJECT_DATA</code>. For example, the application may use this function to copy the received data content for its own use. Alternatively, the application may establish "ownership" for the allocated memory space using the <a class="link" href="#NormDataDetachData" title="4.6.13. NormDataDetachData()"><code class="literal">NormDataDetachData()</code></a> function if it is desired to avoid the copy.</p><p>If the object specified by the <em class="parameter"><code>objectHandle</code></em> parameter has no data content (or is not of type <code class="literal">NORM_OBJECT_DATA</code>), a NULL value may be returned. The application MUST NOT attempt to modify the memory space used by <code class="literal">NORM_OBJECT_DATA</code> objects during the time an associated <em class="parameter"><code>objectHandle</code></em> is valid. The length of data storage area can be determined with a call to <a class="link" href="#NormObjectGetSize" title="4.6.5. NormObjectGetSize()"><code class="literal">NormObjectGetSize()</code></a> for the same <em class="parameter"><code>objectHandle</code></em> value.</p></div><div class="sect4" title="4.6.12.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7555"></a>4.6.12.3. Return Values</h5></div></div></div><p>This function returns a pointer to the data storage area for the specified transport object. A NULL value may be returned if the object has no associated data content or is not of type <code class="literal">NORM_OBJECT_DATA</code>.</p></div></div><div class="sect3" title="4.6.13. NormDataDetachData()"><div class="titlepage"><div><div><h4 class="title"><a name="NormDataDetachData"></a>4.6.13. NormDataDetachData()</h4></div></div></div><div class="sect4" title="4.6.13.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7566"></a>4.6.13.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
char* <a class="link" href="#NormDataDetachData" title="4.6.13. NormDataDetachData()"><code class="literal">NormDataDetachData</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle);</pre></div><div class="sect4" title="4.6.13.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7579"></a>4.6.13.2. Description</h5></div></div></div><p>This function allows the application to disassociate data storage allocated by the NORM protocol engine for a receive object from the <code class="literal">NORM_OBJECT_DATA</code> transport object specified by the <em class="parameter"><code>objectHandle</code></em> parameter. It is important that this function is called after the NORM protocol engine has indicated it is finished with the data object (i.e., after a <code class="literal">NORM_TX_OBJECT_PURGED</code>, <code class="literal">NORM_RX_OBJECT_COMPLETED</code>, or <code class="literal">NORM_RX_OBJECT_ABORTED</code> notification event). But the application must call <a class="link" href="#NormDataDetachData" title="4.6.13. NormDataDetachData()"><code class="literal">NormDataDetachData()</code></a> before a call is made to <a class="link" href="#NormObjectCancel" title="4.6.7. NormObjectCancel()"><code class="literal">NormObjectCancel()</code></a> or <a class="link" href="#NormObjectRelease" title="4.6.9. NormObjectRelease()"><code class="literal">NormObjectRelease()</code></a> for the object if it plans to access the data content afterwards. Otherwise, the NORM protocol engine will free the applicable memory space when the associated <code class="literal">NORM_OBJECT_DATA</code> transport object is deleted and the application will be unable to access the received data unless it has previously copied the content.</p><p>Once the application has used this call to "detach" the data content, it is the application's responsibility to subsequently free the data storage space as needed.</p></div><div class="sect4" title="4.6.13.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7616"></a>4.6.13.3. Return Values</h5></div></div></div><p>This function returns a pointer to the data storage area for the specified transport object. A <code class="constant">NULL</code> value may be returned if the object has no associated data content or is not of type <code class="literal">NORM_OBJECT_DATA</code>.</p></div></div><div class="sect3" title="4.6.14. NormObjectGetSender()"><div class="titlepage"><div><div><h4 class="title"><a name="NormObjectGetSender"></a>4.6.14. NormObjectGetSender()</h4></div></div></div><div class="sect4" title="4.6.14.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7630"></a>4.6.14.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
<a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> <a class="link" href="#NormObjectGetSender" title="4.6.14. NormObjectGetSender()"><code class="literal">NormObjectGetSender</code></a>(<a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> objectHandle);</pre></div><div class="sect4" title="4.6.14.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7647"></a>4.6.14.2. Description</h5></div></div></div><p>This function retrieves the <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> corresponding to the remote sender of the transport object associated with the given <em class="parameter"><code>objectHandle</code></em> parameter. Note that the returned <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> value is only valid for the same period that the <em class="parameter"><code>objectHandle</code></em> is valid. The returned <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> may optionally be retained for further use by the application using the <a class="link" href="#NormNodeRetain" title="4.7.7. NormNodeRetain()"><code class="literal">NormNodeRetain()</code></a> function call. The returned value can be used in the NORM Node Functions described later in this document.</p></div><div class="sect4" title="4.6.14.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7674"></a>4.6.14.3. Return Values</h5></div></div></div><p>This function returns the <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> corresponding to the remote sender of the transport object associated with the given <em class="parameter"><code>objectHandle</code></em> parameter. A value of <code class="literal">NORM_NODE_INVALID</code> is returned if the specified <em class="parameter"><code>objectHandle</code></em> references a locally originated, sender object.</p></div></div></div><div class="sect2" title="4.7. NORM Node Functions"><div class="titlepage"><div><div><h3 class="title"><a name="d0e7692"></a>4.7. NORM Node Functions</h3></div></div></div><p>The functions described in this section may be used for NORM sender or receiver (most typically receiver) purposes to retrieve additional information about a remote <span class="emphasis"><em>NormNode</em></span>, given a valid <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a>. Note that, unless specifically retained (see <a class="link" href="#NormNodeRetain" title="4.7.7. NormNodeRetain()"><code class="literal">NormNodeRetain()</code></a>), a <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> provided in a <a class="link" href="#NormEvent" title="4.1.11. NormEvent"><code class="literal">NormEvent</code></a> notification should be considered valid only until a subsequent call to <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a> is made. <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> values retrieved using <a class="link" href="#NormObjectGetSender" title="4.6.14. NormObjectGetSender()"><code class="literal">NormObjectGetSender()</code></a> can be considered valid for the same period of time as the corresponding <a class="link" href="#NormObjectHandle" title="4.1.6. NormObjectHandle"><code class="literal">NormObjectHandle</code></a> is valid.</p><div class="sect3" title="4.7.1. NormNodeGetId()"><div class="titlepage"><div><div><h4 class="title"><a name="NormNodeGetId"></a>4.7.1. NormNodeGetId()</h4></div></div></div><div class="sect4" title="4.7.1.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7735"></a>4.7.1.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
<a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> <a class="link" href="#NormNodeGetId" title="4.7.1. NormNodeGetId()"><code class="literal">NormNodeGetId</code></a>(<a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> nodeHandle);</pre></div><div class="sect4" title="4.7.1.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7752"></a>4.7.1.2. Description</h5></div></div></div><p>This function retrieves the <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> identifier for the remote participant referenced by the given <em class="parameter"><code>nodeHandle</code></em> value. The <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> is a 32-bit value used within the NORM protocol to uniquely identify participants within a NORM session. The participants identifiers are assigned by the application or derived (by the NORM API code) from the host computers default IP address.</p></div><div class="sect4" title="4.7.1.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7768"></a>4.7.1.3. Return Values</h5></div></div></div><p>This function returns the <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> value associated with the specified <em class="parameter"><code>nodeHandle</code></em>. In the case <em class="parameter"><code>nodeHandle</code></em> is equal to <code class="literal">NORM_NODE_INVALID</code>, the return value will be <code class="literal">NORM_NODE_NONE</code>.</p></div></div><div class="sect3" title="4.7.2. NormNodeGetAddress()"><div class="titlepage"><div><div><h4 class="title"><a name="NormNodeGetAddress"></a>4.7.2. NormNodeGetAddress()</h4></div></div></div><div class="sect4" title="4.7.2.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7792"></a>4.7.2.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormNodeGetAddress" title="4.7.2. NormNodeGetAddress()"><code class="literal">NormNodeGetAddress</code></a>(<a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> nodeHandle,
char* addrBuffer,
unsigned int* bufferLen,
unsigned short* port = NULL);</pre></div><div class="sect4" title="4.7.2.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7805"></a>4.7.2.2. Description</h5></div></div></div><p>This function retrieves the current network source address detected for packets received from remote NORM sender referenced by the <em class="parameter"><code>nodeHandle</code></em> parameter. The <em class="parameter"><code>addrBuffer</code></em> must be a pointer to storage of <em class="parameter"><code>bufferLen</code></em> bytes in length in which the referenced sender node's address will be returned. Optionally, the remote sender source port number (see <a class="link" href="#NormSetTxPort" title="4.3.6. NormSetTxPort()"><code class="literal">NormSetTxPort()</code></a>) is also returned if the optional port pointer to storage parameter is provided in the call. Note that in the case of Network Address Translation (NAT) or other firewall activities, the source address detected by the NORM receiver may not be the original address of the original NORM sender.</p></div><div class="sect4" title="4.7.2.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7823"></a>4.7.2.3. Return Values</h5></div></div></div><p>A value of <code class="constant">true</code> is returned upon success and <code class="constant">false</code> upon failure. An invalid <em class="parameter"><code>nodeHandle</code></em> parameter value would lead to such failure.</p></div></div><div class="sect3" title="4.7.3. NormNodeGetGrtt()"><div class="titlepage"><div><div><h4 class="title"><a name="NormNodeGetGrtt"></a>4.7.3. NormNodeGetGrtt()</h4></div></div></div><div class="sect4" title="4.7.3.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7840"></a>4.7.3.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
double <a class="link" href="#NormNodeGetId" title="4.7.1. NormNodeGetId()"><code class="literal">NormNodeGetId</code></a>(<a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> nodeHandle);</pre></div><div class="sect4" title="4.7.3.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7853"></a>4.7.3.2. Description</h5></div></div></div><p>This function retrieves the advertised estimate of group round-trip timing (GRTT) for the remote sender referenced by the given <em class="parameter"><code>nodeHandle</code></em> value. Newly-starting senders that have been participating as a receiver within a group may wish to use this function to provide a more accurate startup estimate of GRTT (see <a class="link" href="#NormSetGrttEstimate" title="4.4.12. NormSetGrttEstimate()"><code class="literal">NormSetGrttEstimate()</code></a>) prior to a call to <a class="link" href="#NormStartSender" title="4.4.1. NormStartSender()"><code class="literal">NormStartSender()</code></a>. Applications may use this information for other purpose as well. Note that the <code class="literal">NORM_GRTT_UPDATED</code> event is posted (see <a class="link" href="#NormGetNextEvent" title="4.2.6. NormGetNextEvent()"><code class="literal">NormGetNextEvent()</code></a>) by the NORM protocol engine to indicate when changes in the local sender or remote senders' GRTT estimate occurs.</p></div><div class="sect4" title="4.7.3.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7876"></a>4.7.3.3. Return Values</h5></div></div></div><p>This function returns the remote sender's advertised GRTT estimate in units of seconds. A value of <code class="constant">-1.0</code> is returned upon failure. An invalid <em class="parameter"><code>nodeHandle</code></em> parameter value will lead to such failure.</p></div></div><div class="sect3" title="4.7.4. NormNodeGetCommand()"><div class="titlepage"><div><div><h4 class="title"><a name="NormNodeGetCommand"></a>4.7.4. NormNodeGetCommand()</h4></div></div></div><div class="sect4" title="4.7.4.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7890"></a>4.7.4.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormNodeGetCommand" title="4.7.4. NormNodeGetCommand()"><code class="literal">NormNodeGetCommand</code></a>(<a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> nodeHandle,
char* buffer,
unsigned int* buflen);</pre></div><div class="sect4" title="4.7.4.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7903"></a>4.7.4.2. Description</h5></div></div></div><p>This function retrieves the content of an application-defined command that was received from a remote sender associated with the given <em class="parameter"><code>nodeHandle</code></em>. This call should be made in response to the <code class="constant">NORM_RX_CMD_NEW</code> notification. This notification is issued for each command received. However the application may use this call to poll for received commands if desired. Additionally, the received command length can be "queried" by setting the value referenced by the <em class="parameter"><code>buflen</code></em> parameter to <code class="constant">ZERO</code>. Upon return, this value referenced by the <em class="parameter"><code>buflen</code></em> parameter is adjusted to reflect the command length. Then a subsequent call to <a class="link" href="#NormNodeGetCommand" title="4.7.4. NormNodeGetCommand()"><code class="literal">NormNodeGetCommand()</code></a> can be made with an appropriately-sized buffer to retrieve the received command content. The command size will be less than or equal to the NORM segment size configured for the given remote sender.</p><p>Note that if a rapid succession of commands are sent it is possible that the commands may be delivered to the receivers out-of-order. Also, when repetition is requested (i.e., if <em class="parameter"><code>robust</code></em> is set to <code class="constant">true</code>) the receiver may receive duplicate copies of the same command. It is up to the application to provide any needed mechanism for detecting and/or filtering duplicate command reception.</p></div><div class="sect4" title="4.7.4.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7935"></a>4.7.4.3. Return Values</h5></div></div></div><p>This function returns <code class="constant">true</code> upon successful retrieval of command content. A return value of <code class="constant">false</code> indicates that either no command was available or the provided buffer size (<em class="parameter"><code>buflen</code></em> parameter) was inadequate. The value referenced by the <em class="parameter"><code>buflen</code></em> parameter is adjusted to indicate the actual command length (in bytes) upon return.</p></div></div><div class="sect3" title="4.7.5. NormNodeFreeBuffers()"><div class="titlepage"><div><div><h4 class="title"><a name="NormNodeFreeBuffers"></a>4.7.5. NormNodeFreeBuffers()</h4></div></div></div><div class="sect4" title="4.7.5.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7955"></a>4.7.5.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormNodeFreeBuffers" title="4.7.5. NormNodeFreeBuffers()"><code class="literal">NormNodeFreeBuffers</code></a>(<a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> nodeHandle);</pre></div><div class="sect4" title="4.7.5.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7968"></a>4.7.5.2. Description</h5></div></div></div><p>This function releases memory resources that were allocated for a remote sender. For example, the receiver application may wish to free memory resources when receiving a <code class="constant">NORM_REMOTE_SENDER_INACTIVE</code> notification for a given remote sender when multiple senders may be providing content. The NORM protocol engine allocates memory for reliable transport buffering on a per sender basis according to the limit set in the <a class="link" href="#NormStartReceiver" title="4.5.1. NormStartReceiver()"><code class="literal">NormStartReceiver()</code></a> call. These buffering resources comprise the majority of the state allocated for a given remote sender. For NORM applications with possibly multiple senders active at different times, this function can be used to manage to amount of memory allocated for reliable reception. If a sender becomes "active" again after a call to <a class="link" href="#NormNodeFreeBuffers" title="4.7.5. NormNodeFreeBuffers()"><code class="literal">NormNodeFreeBuffers()</code></a>, new memory resources will be allocated. Note that state for any pending (uncompleted) objects will be dropped when this function is called and the receiver may request retransmission and repair of content if the sender once again becomes "active". The application SHOULD call <a class="link" href="#NormObjectCancel" title="4.6.7. NormObjectCancel()"><code class="literal">NormObjectCancel()</code></a> for any pending objects <span class="emphasis"><em>before</em></span> calling <a class="link" href="#NormNodeFreeBuffers" title="4.7.5. NormNodeFreeBuffers()"><code class="literal">NormNodeFreeBuffers()</code></a> if it wishes to never receive those pending objects. Alternatively, a call to <a class="link" href="#NormNodeDelete" title="4.7.6. NormNodeDelete()"><code class="literal">NormNodeDelete()</code></a> will completely eliminate all state for a given remote sender and, if that sender becomes "active" again, it will be treated as a completely new sender.</p></div><div class="sect4" title="4.7.5.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e7999"></a>4.7.5.3. Return Values</h5></div></div></div><p>This function has no return value.</p></div></div><div class="sect3" title="4.7.6. NormNodeDelete()"><div class="titlepage"><div><div><h4 class="title"><a name="NormNodeDelete"></a>4.7.6. NormNodeDelete()</h4></div></div></div><div class="sect4" title="4.7.6.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8007"></a>4.7.6.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormNodeDelete" title="4.7.6. NormNodeDelete()"><code class="literal">NormNodeDelete</code></a>(<a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> nodeHandle);</pre></div><div class="sect4" title="4.7.6.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8020"></a>4.7.6.2. Description</h5></div></div></div><p>This function can be used by a NORM receiver application to completely remove the state associated with a remote sender for the given <em class="parameter"><code>nodeHandle</code></em>. For example, when a <code class="constant">NORM_REMOTE_SENDER_INACTIVE</code> notification occurs for a given sender, the application may wish to completely free <span class="emphasis"><em>all</em></span> associated resources. Note this is distinct from the <a class="link" href="#NormNodeFreeBuffers" title="4.7.5. NormNodeFreeBuffers()"><code class="literal">NormNodeFreeBuffers()</code></a> call where only the buffering resources are freed and other state pertaining to the sender is kept. If the deleted sender again becomes "active", it will be treated as a brand new sender. Unless explicitly retained with a call to <a class="link" href="#NormNodeRetain" title="4.7.7. NormNodeRetain()"><code class="literal">NormNodeRetain()</code></a>, the <em class="parameter"><code>nodeHandle</code></em> should be considered invalid after this call is made. Additionally, any <span class="type">NormObjectHandle</span> values for pending objects from this sender are also invalidated (unless otherwise retained), although <code class="constant">NORM_RX_OBJECT_ABORTED</code> notifications may be issued for those pending objects.</p></div><div class="sect4" title="4.7.6.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8051"></a>4.7.6.3. Return Values</h5></div></div></div><p>This function has no return value.</p></div></div><div class="sect3" title="4.7.7. NormNodeRetain()"><div class="titlepage"><div><div><h4 class="title"><a name="NormNodeRetain"></a>4.7.7. NormNodeRetain()</h4></div></div></div><div class="sect4" title="4.7.7.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8059"></a>4.7.7.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormNodeRetain" title="4.7.7. NormNodeRetain()"><code class="literal">NormNodeRetain</code></a>(<a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> nodeHandle);</pre></div><div class="sect4" title="4.7.7.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8072"></a>4.7.7.2. Description</h5></div></div></div><p>In the same manner as the <a class="link" href="#NormObjectRetain" title="4.6.8. NormObjectRetain()"><code class="literal">NormObjectRetain()</code></a> function, this function allows the application to retain state associated with a given <em class="parameter"><code>nodeHandle</code></em> value even when the underlying NORM protocol engine might normally free the associated state and thus invalidate the <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a>. If the application uses this function, it must make a corresponding call to <a class="link" href="#NormNodeRelease" title="4.7.8. NormNodeRelease()"><code class="literal">NormNodeRelease()</code></a> when finished with the node information to avoid a memory leak condition. <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> values (unless retained) are valid from the time of a <code class="literal">NORM_REMOTE_SENDER_NEW</code> notification until a complimentary <code class="literal">NORM_REMOTE_SENDER_PURGED</code> notification. During that interval, the application will receive <code class="literal">NORM_REMOTE_SENDER_ACTIVE</code> and <code class="literal">NORM_REMOTE_SENDER_INACTIVE</code> notifications according to the sender's message transmission activity within the session.</p><p>It is important to note that, if the NORM protocol engine posts a <code class="literal">NORM_REMOTE_SENDER_PURGED</code> notification for a given <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a>, the NORM protocol engine could possibly, subsequently establish a new, different <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> value for the same remote sender (i.e., one of equivalent <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a>) if it again becomes active in the session. A new <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> may likely be established even if the application has retained the previous <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> value. Therefore, to the application, it might appear that two different senders with the same <a class="link" href="#NormNodeId" title="4.1.5. NormNodeId"><code class="literal">NormNodeId</code></a> are participating if these notifications are not carefully monitored. This behavior is contingent upon how the application has configured the NORM protocol engine to manage resources when there is potential for a large number of remote senders within a session (related APIs are TBD). For example, the application may wish to control which specific remote senders for which it keeps state (or limit the memory resources used for remote sender state, etc) and the NORM API may be extended in the future to control this behavior.</p></div><div class="sect4" title="4.7.7.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8137"></a>4.7.7.3. Return Values</h5></div></div></div><p>This function has no return value.</p></div></div><div class="sect3" title="4.7.8. NormNodeRelease()"><div class="titlepage"><div><div><h4 class="title"><a name="NormNodeRelease"></a>4.7.8. NormNodeRelease()</h4></div></div></div><div class="sect4" title="4.7.8.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8145"></a>4.7.8.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormNodeRelease" title="4.7.8. NormNodeRelease()"><code class="literal">NormNodeRelease</code></a>(<a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a> nodeHandle);</pre></div><div class="sect4" title="4.7.8.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8158"></a>4.7.8.2. Description</h5></div></div></div><p>In complement to the <a class="link" href="#NormNodeRetain" title="4.7.7. NormNodeRetain()"><code class="literal">NormNodeRetain()</code></a> function, this API call releases the specified <em class="parameter"><code>nodeHandle</code></em> so that the NORM protocol engine may free associated resources as needed. Once this call is made, the application should no longer reference the specified <a class="link" href="#NormNodeHandle" title="4.1.4. NormNodeHandle"><code class="literal">NormNodeHandle</code></a>, unless it is still valid.</p></div><div class="sect4" title="4.7.8.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8174"></a>4.7.8.3. Return Values</h5></div></div></div><p>This function has no return value.</p></div></div></div><div class="sect2" title="4.8. NORM Debugging Functions"><div class="titlepage"><div><div><h3 class="title"><a name="d0e8179"></a>4.8. NORM Debugging Functions</h3></div></div></div><p>This section describes some additional function calls that are available to set debugging output options and control other aspects of the NORM implementation.</p><div class="sect3" title="4.8.1. NormSetDebugLevel()"><div class="titlepage"><div><div><h4 class="title"><a name="NormSetDebugLevel"></a>4.8.1. NormSetDebugLevel()</h4></div></div></div><div class="sect4" title="4.8.1.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8187"></a>4.8.1.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
void <a class="link" href="#NormSetDebugLevel" title="4.8.1. NormSetDebugLevel()"><code class="literal">NormSetDebugLevel</code></a>(unsigned int level);</pre></div><div class="sect4" title="4.8.1.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8196"></a>4.8.1.2. Description</h5></div></div></div><p>This function controls the verbosity of NORM debugging output. Higher values of level result in more detailed output. The highest level of debugging is 12. The debug output consists of text written to STDOUT by default but may be directed to a log file using the <a class="link" href="#NormOpenDebugLog" title="4.8.2. NormOpenDebugLog()"><code class="literal">NormOpenDebugLog()</code></a> function.</p></div><div class="sect4" title="4.8.1.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8205"></a>4.8.1.3. Return Values</h5></div></div></div><p>This function has no return value.</p></div></div><div class="sect3" title="4.8.2. NormOpenDebugLog()"><div class="titlepage"><div><div><h4 class="title"><a name="NormOpenDebugLog"></a>4.8.2. NormOpenDebugLog()</h4></div></div></div><div class="sect4" title="4.8.2.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8213"></a>4.8.2.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormOpenDebugLog" title="4.8.2. NormOpenDebugLog()"><code class="literal">NormOpenDebugLog</code></a>(NormInstanceHandle instance, const char* fileName);</pre></div><div class="sect4" title="4.8.2.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8222"></a>4.8.2.2. Description</h5></div></div></div><p>This function allows NORM debug output to be directed to a file instead of the default <code class="constant">STDERR</code>.</p></div><div class="sect4" title="4.8.2.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8230"></a>4.8.2.3. Return Values</h5></div></div></div><p>The function returns <code class="constant">true</code> on success. If the specified file cannot be opened a value of <code class="constant">false</code> is returned.</p></div></div><div class="sect3" title="4.8.3. NormCloseDebugLog()"><div class="titlepage"><div><div><h4 class="title"><a name="NormCloseDebugLog"></a>4.8.3. NormCloseDebugLog()</h4></div></div></div><div class="sect4" title="4.8.3.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8244"></a>4.8.3.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormCloseDebugLog" title="4.8.3. NormCloseDebugLog()"><code class="literal">NormCloseDebugLog</code></a>(NormInstanceHandle instance);</pre></div><div class="sect4" title="4.8.3.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8253"></a>4.8.3.2. Description</h5></div></div></div><p>TBD</p></div><div class="sect4" title="4.8.3.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8258"></a>4.8.3.3. Return Values</h5></div></div></div><p>TBD</p></div></div><div class="sect3" title="4.8.4. NormOpenDebugPipe()"><div class="titlepage"><div><div><h4 class="title"><a name="NormOpenDebugPipe"></a>4.8.4. NormOpenDebugPipe()</h4></div></div></div><div class="sect4" title="4.8.4.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8266"></a>4.8.4.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormOpenDebugPipe" title="4.8.4. NormOpenDebugPipe()"><code class="literal">NormOpenDebugPipe</code></a>(NormInstanceHandle instance, const char* pipeName);</pre></div><div class="sect4" title="4.8.4.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8275"></a>4.8.4.2. Description</h5></div></div></div><p>TBD</p></div><div class="sect4" title="4.8.4.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8280"></a>4.8.4.3. Return Values</h5></div></div></div><p>TBD</p></div></div><div class="sect3" title="4.8.5. NormCloseDebugPipe()"><div class="titlepage"><div><div><h4 class="title"><a name="NormCloseDebugPipe"></a>4.8.5. NormCloseDebugPipe()</h4></div></div></div><div class="sect4" title="4.8.5.1. Synopsis"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8288"></a>4.8.5.1. Synopsis</h5></div></div></div><pre class="programlisting">#include <normApi.h>
bool <a class="link" href="#NormCloseDebugPipe" title="4.8.5. NormCloseDebugPipe()"><code class="literal">NormCloseDebugPipe</code></a>(NormInstanceHandle instance);</pre></div><div class="sect4" title="4.8.5.2. Description"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8297"></a>4.8.5.2. Description</h5></div></div></div><p>TBD</p></div><div class="sect4" title="4.8.5.3. Return Values"><div class="titlepage"><div><div><h5 class="title"><a name="d0e8302"></a>4.8.5.3. Return Values</h5></div></div></div><p>TBD</p></div></div></div></div></div></body></html>
|
