Debian Codegraph @

debian/missing-sources/NormDeveloperGuide.html

raw
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4 <article>
5 <articleinfo>
6 <title><inlinemediaobject>
7 <imageobject>
8 <imagedata align="center" fileref="NormLogo.gif" scale="50"/>
9 </imageobject>
10 </inlinemediaobject> NORM Developer's Guide (version 1.5b5)</title>
11
12 <titleabbrev>NORM Developer's Guide</titleabbrev>
13
14 <abstract>
15 <para>This document describes an application programming interface (API)
16 for the <ulink url="http://norm.pf.itd.nrl.navy.mil/">Nack-Oriented
17 Reliable Multicast (NORM)</ulink> protocol implementation developed by
18 the Protocol Engineering and Advance Networking (<ulink
19 url="http://cs.itd.nrl.navy.mil/">PROTEAN</ulink>) Research Group of the
20 United States <ulink url="http://www.nrl.navy.mil/">Naval Research
21 Laboratory</ulink> (NRL). The NORM protocol provides general purpose
22 reliable data transport for applications wishing to use Internet
23 Protocol (IP) Multicast services for group data delivery. NORM can also
24 support unicast (point-to-point) data communication and may be used for
25 such when deemed appropriate. The current NORM protocol specification is
26 given in the <ulink url="http://www.ietf.org/">Internet Engineering Task
27 Force</ulink> (IETF) <ulink
28 url="http://norm.pf.itd.nrl.navy.mil/rfc3940.pdf">RFC 3940</ulink>. This
29 document is currently a reference guide to the NORM API of the NRL
30 reference implementation. More tutorial material may be include in a
31 future version of this document or a separate developer's tutorial may
32 be created at a later date.</para>
33 </abstract>
34 </articleinfo>
35
36 <sect1>
37 <title>Background</title>
38
39 <para>This document describes an application programming interface (API)
40 for the <ulink url="http://norm.pf.itd.nrl.navy.mil/">Nack-Oriented
41 Reliable Multicast (NORM)</ulink> protocol implementation developed by the
42 Protocol Engineering and Advance Networking (<ulink
43 url="http://cs.itd.nrl.navy.mil/">PROTEAN</ulink>) Research Group of the
44 United States <ulink url="http://www.nrl.navy.mil/">Naval Research
45 Laboratory</ulink> (NRL). The NORM protocol provides general purpose
46 reliable data transport for applications wishing to use Internet Protocol
47 (IP) Multicast services for group data delivery. NORM can also support
48 unicast (point-to-point) data communication and may be used for such when
49 deemed appropriate. The current NORM protocol specification is given in
50 the <ulink url="http://www.ietf.org/">Internet Engineering Task
51 Force</ulink> (IETF) <ulink
52 url="http://norm.pf.itd.nrl.navy.mil/rfc5740.pdf">RFC 5740</ulink>.</para>
53
54 <para>The NORM protocol is designed to provide end-to-end reliable
55 transport of bulk data objects or streams over generic IP multicast
56 routing and forwarding services. NORM uses a selective, negative
57 acknowledgement (NACK) mechanism for transport reliability and offers
58 additional protocol mechanisms to conduct reliable multicast sessions with
59 limited "a priori" coordination among senders and receivers. A congestion
60 control scheme is specified to allow the NORM protocol to fairly share
61 available network bandwidth with other transport protocols such as
62 Transmission Control Protocol (TCP). It is capable of operating with both
63 reciprocal multicast routing among senders and receivers and with
64 asymmetric connectivity (possibly a unicast return path) from the senders
65 to receivers. The protocol offers a number of features to allow different
66 types of applications or possibly other higher-level transport protocols
67 to utilize its service in different ways. The protocol leverages the use
68 of FEC-based repair and other proven reliable multicast transport
69 techniques in its design.</para>
70
71 <para>The NRL NORM library attempts to provide a general useful capability
72 for development of reliable multicast applications for bulk file or other
73 data delivery as well as support of stream-based transport with possible
74 real-time delivery requirements. The API allows access to many NORM
75 protocol parameters and control functions to tailor performance for
76 specific applications. While default parameters, where provided, can be
77 useful to a potential wide range of requirements, the many different
78 possible group communication paradigms dictate different needs for
79 different applications. Even with NORM, the developer should have a
80 thorough understanding of the specific application's group communication
81 needs.</para>
82 </sect1>
83
84 <sect1>
85 <title>Overview</title>
86
87 <para>The NORM API has been designed to provide simple, straightforward
88 access to and control of NORM protocol state and functions. Functions are
89 provided to create and initialize instances of the NORM API and associated
90 transport sessions (<emphasis>NormSessions</emphasis>). Subsequently, NORM
91 data transmission (<emphasis>NormSender</emphasis>) operation can be
92 activated and the application can queue various types of data
93 (<emphasis>NormObjects</emphasis>) for reliable transport. Additionally or
94 alternatively, NORM reception (<emphasis>NormReceiver</emphasis>)
95 operation can also be enabled on a per-session basis and the protocol
96 implementation alerts the application of receive events.</para>
97
98 <para>By default, the NORM API will create an operating system thread in
99 which the NORM protocol engine runs. This allows user application code and
100 the underlying NORM code to execute somewhat independently of one another.
101 The NORM protocol thread notifies the application of various protocol
102 events through a thread-safe event dispatching mechanism and API calls are
103 provided to allow the application to control NORM operation. (Note: API
104 mechanisms for lower-level, non-threaded control and execution of the NORM
105 protocol engine code may also be provided in the future.)</para>
106
107 <para>The NORM API operation can be roughly summarized with the following
108 categories of functions:</para>
109
110 <orderedlist>
111 <listitem>
112 <para>API Initialization</para>
113 </listitem>
114
115 <listitem>
116 <para>Session Creation and Control</para>
117 </listitem>
118
119 <listitem>
120 <para>Data Transport</para>
121 </listitem>
122
123 <listitem>
124 <para>API Event Notification</para>
125 </listitem>
126 </orderedlist>
127
128 <para>Note the order of these categories roughly reflects the order of
129 function calls required to use NORM in an application. The first step is
130 to create and initialize, as needed, at least one instance of the NORM
131 API. Then one or more NORM transport sessions (where a "session"
132 corresponds to data exchanges on a given multicast group (or unicast
133 address) and host port number) may be created and controlled. Applications
134 may participate as senders and/or receivers within a NORM session. NORM
135 senders transmit data to the session destination address (usually an IP
136 multicast group) while receivers are notified of incoming data. The NORM
137 API provides and event notification scheme to notify the application of
138 significant sender and receiver events. There are also a number support
139 functions provided for the application to control and monitor its
140 participation within a NORM transport session.</para>
141
142 <sect2>
143 <title>API Initialization</title>
144
145 <para>The NORM API requires that an application explicitly create at
146 least one instance of the NORM protocol engine that is subsequently used
147 as a conduit for further NORM API calls. By default, the NORM protocol
148 engine runs in its own operating system thread and interacts with the
149 application in a thread-safe manner through the API calls and event
150 dispatching mechanism.</para>
151
152 <para>In general, only a single thread should access the <link
153 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
154 API call for a given <emphasis>NormInstance</emphasis>. This function
155 serves as the conduit for delivering NORM protocol engine events to the
156 application. A NORM application can be designed to be single-threaded,
157 even with multiple active NormSessions, but also multiple API instances
158 can be created (see <link
159 linkend="NormCreateInstance"><literal>NormCreateInstance()</literal></link>)
160 as needed for applications with specific requirements for accessing and
161 controlling participation in multiple <emphasis>NormSessions</emphasis>
162 from separate operating system multiple threads. Or, alternatively, a
163 single <emphasis>NormInstance</emphasis> could be used, with a "master
164 thread" serving as an intermediary between the <link
165 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
166 function, demultiplexing and dispatching events as appropriate to other
167 "child threads" that are created to handle
168 "per-<emphasis>NormSession</emphasis>" input/output. The advantage of
169 this alternative approach is that the end result would be one NORM
170 protocol engine thread plus one "master thread" plus one "child thread"
171 per <emphasis>NormSession</emphasis> instead of two threads (protocol
172 engine plus application thread) per <emphasis>NormSession</emphasis> if
173 such multi-threaded operation is needed by the application.</para>
174 </sect2>
175
176 <sect2>
177 <title>Session Creation and Control</title>
178
179 <para>Once an API instance has been successfully created, the
180 application may then create NORM transport session instances as needed.
181 The application can participate in each session as a sender and/or
182 receiver of data. If an application is participating as a sender, it may
183 enqueue data transport objects for transmission. The control of
184 transmission is largely left to the senders and API calls are provided
185 to control transmission rate, FEC parameters, etc. Applications
186 participating as receivers will be notified via the NORM API's event
187 dispatching mechanism of pending and completed reliable reception of
188 data along with other significant events. Additionally, API controls for
189 some optional NORM protocol mechanisms, such as positive acknowledgment
190 collection, are also provided.</para>
191
192 <para>Note when multiple senders are involved, receivers allocate system
193 resources (buffer space) for each active sender. With a very large
194 number of concurrently active senders, this may translate to significant
195 memory allocation on receiver nodes. Currently, the API allows the
196 application to control how much buffer space is allocated for each
197 active sender (NOTE: In the future, API functions may be provided limit
198 the number of active senders monitored and/or provide the application
199 with finer control over receive buffer allocation, perhaps on a per
200 sender basis).</para>
201 </sect2>
202
203 <sect2>
204 <title>Data Transport</title>
205
206 <para>The NORM protocol supports transport of three basic types of data
207 content. These include the types <literal>NORM_OBJECT_FILE</literal> and
208 <literal>NORM_OBJECT_DATA</literal> which represent predetermined,
209 fixed-size application data content. The only differentiation with
210 respect to these two types is the implicit "hint" to the receiver to use
211 non-volatile (i.e. file system) storage or memory. This "hint" lets the
212 receiver allocate appropriate storage space with no other information on
213 the incoming data. The NORM implementation reads/writes data for the
214 <literal>NORM_OBJECT_FILE</literal> type directly from/to file storage,
215 while application memory space is accessed for the
216 <literal>NORM_OBJECT_DATA</literal> type. The third data content type,
217 <literal>NORM_OBJECT_STREAM</literal>, represents unbounded, possibly
218 persistent, streams of data content. Using this transport paradigm,
219 traditional, byte-oriented streaming transport service (e.g. similar to
220 that provided by a TCP socket) can be provided. Additionally, NORM has
221 provisions for application-defined message-oriented transport where
222 receivers can recover message boundaries without any "handshake" with
223 the sender. Stream content is buffered by the NORM implementation for
224 transmission/retransmission and as it is received.</para>
225
226 <sect3>
227 <title>Data Transmission</title>
228
229 <para>The behavior of data transport operation is largely placed in
230 the control of the NORM sender(s). NORM senders controls their data
231 transmission rate, forward error correction (FEC) encoding settings,
232 and parameters controlling feedback from the receiver group. Multiple
233 senders may operate in a session, each with independent transmission
234 parameters. NORM receivers learn needed parameter values from fields
235 in NORM message headers.</para>
236
237 <para>NORM transport "objects" (file, data, or stream) are queued for
238 transmission by NORM senders. NORM senders may also cancel
239 transmission of objects at any time. The NORM sender controls the
240 transmission rate either manually (fixed transmission rate) or
241 automatically when NORM congestion control operation is enabled. The
242 NORM congestion control mechanism is designed to be "friendly" to
243 other data flows on the network, fairly sharing available
244 bandwidth.<link
245 linkend="NormSetAutoParity"><literal>NormSetAutoParity()</literal></link>)
246 to achieve reliable transfer) receive object transmission before any
247 extensive repair process that may be required to satisfy other
248 receivers with poor network connectivity. The repair boundary can also
249 be set for individual remote senders using the <link
250 linkend="NormNodeSetRepairBoundary"><literal>NormNodeSetRepairBoundary()</literal></link>
251 function.<literal>NORM_OBJECT_FILE</literal> objects. This function
252 must be called before any file objects may be received and thus should
253 be called before any calls to <link
254 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
255 are made. However, note that the cache directory may be changed even
256 during active NORM reception. In this case, the new specified
257 directory path will be used for subsequently-received files. Any files
258 received before a directory path change will remain in the previous
259 cache location. Note that the <link
260 linkend="NormFileRename"><literal>NormFileRename()</literal></link>
261 function may be used to rename, and thus potentially move, received
262 files after reception has begun.</para>
263
264 <para>By default, the NORM sender transmits application-enqueued data
265 content, providing repair transmissions (usually in the form of FEC
266 messages) only when requested by NACKs from the receivers. However,
267 the application may also configure NORM to proactively send some
268 amount of FEC content along with the original data content to create a
269 "robust" transmission that, in some cases, may be reliably received
270 without any NACKing activity. This can allow for some degree of
271 reliable protocol operation even without receiver feedback available.
272 NORM senders may also requeue (within the limits of "transmit cache"
273 settings) objects for repeat transmission, and receivers may combine
274 together multiple transmissions to reliably receive content.
275 Additionally, hybrid proactive/reactive FEC repair operation is
276 possible with the receiver NACK process as a "backup" for when network
277 packet loss exceeds the repair capability of the proactive FEC
278 settings.</para>
279
280 <para>The NRL NORM implementation also supports optional collection of
281 positive acknowledgment from a subset of the receiver group at
282 application-determined positions during data transmission. The NORM
283 API allows the application to specify the receiver subset ("acking
284 node list") and set "watermark" points for which positive
285 acknowledgement is collected. This process can provide the application
286 with explicit flow control for an application-determined critical set
287 of receivers in the group.</para>
288
289 <para>For a NORM application to perform data transmission, it must
290 first create a session using <link
291 linkend="NormCreateSession"><literal>NormCreateSession()</literal></link>
292 and make a call to <link
293 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
294 before sending actual user data. The functions <link
295 linkend="NormFileEnqueue"><literal>NormFileEnqueue()</literal></link>,
296 <link
297 linkend="NormDataEnqueue"><literal>NormDataEnqueue()</literal></link>,
298 and <link
299 linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
300 are available for the application to pass data to the NORM protocol
301 engine for transmission. Note that to use <link
302 linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>,
303 a "sender stream" must first be created using <link
304 linkend="NormStreamOpen"><literal>NormStreamOpen()</literal></link>.
305 In the case of <link
306 linkend="NormFileEnqueue"><literal>NormFileEnqueue()</literal></link>
307 and <link
308 linkend="NormDataEnqueue"><literal>NormDataEnqueue()</literal></link>,
309 the NORM protocol engine directly accesses the application file or
310 memory space to refer to the transmitted content and does not make its
311 own copy of this data.</para>
312
313 <para>The calls to enqueue transport objects or write to a stream may
314 be called at any time, but the <literal>NORM_TX_QUEUE_EMPTY</literal>
315 and <literal>NORM_TX_QUEUE_VACANCY</literal> notification events (see
316 <link
317 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>)
318 provide useful cues for when these functions may be successfully
319 called. Typically, an application might catch both
320 <literal>NORM_TX_QUEUE_EMPTY</literal> and
321 <literal>NORM_TX_QUEUE_VACANCY</literal> event types as cues for
322 enqueuing additional transport objects or writing to a stream.
323 However, an application may choose to cue off of
324 <literal>NORM_TX_QUEUE_EMPTY</literal> only if it wishes to provide
325 the "freshest" data to NORM for transmission. The advantage of
326 additionally using <literal>NORM_TX_QUEUE_VACANCY</literal> is that if
327 the application uses this cue to fill up NORM transport object or
328 stream buffers, it can keep the NORM stream busy sending data and
329 realize the highest possible transmission rate when attempting very
330 high speed communication (Otherwise, the NORM protocol engine may
331 experience some "dead air time" waiting for the application thread to
332 respond to a <literal>NORM_TX_QUEUE_EMPTY</literal> event). Note the
333 sender application can control buffer depths as needed with the <link
334 linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>
335 and <link
336 linkend="NormStreamOpen"><literal>NormStreamOpen()</literal></link>
337 calls. Additionally, it is possible for applications to configure the
338 transmit object "cache" (see <link
339 linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>)
340 and use the <link
341 linkend="NormRequeueObject"><literal>NormRequeueObject()</literal></link>
342 call (for objects that have not yet received a
343 <parameter>NORM_TX_OBJECT_PURGED</parameter> notification) to effect a
344 sort of "data carousel" operation with repeated transmission of the
345 cached objects. The <parameter>NORM_TX_OBJECT_SENT</parameter>
346 notification can be used a cue to properly control the "requeue"
347 cycle(s).</para>
348
349 <para>The NORM implementation provides a form of timer-based flow
350 control that limits how quickly sender applications may enqueue new
351 objects or stream data for transmission. The <link
352 linkend="NormSetFlowControl"><literal>NormSetFlowControl()</literal></link>
353 call is provided to control this behavior, including the option to
354 disable it. This timer-based mechanism is a type of "soft" flow
355 control by allowing receivers "sufficient" time to request repair of
356 pending data the sender has enqueued. A more explicit form of flow
357 control using the optional "watermark flushing" mechanism is described
358 below.</para>
359
360 <para>Another cue that can be leveraged by the sender application to
361 determine when it is appropriate to enqueue (or write) additional data
362 for transmission is the <literal>NORM_TX_WATERMARK_COMPLETED</literal>
363 event. This event is posted when the flushing or explicit positive
364 acknowledgment collection process has completed for a "watermark"
365 point in transmission that was set by the sender (see <link
366 linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
367 and <link
368 linkend="NormAddAckingNode"><literal>NormAddAckingNode()</literal></link>).
369 A list of <link
370 linkend="NormNodeId"><literal>NormNodeId</literal></link> values can
371 be supplied from which explicit acknowledgement is expected and/or the
372 <link linkend="NormNodeId"><literal>NormNodeId</literal></link>
373 <literal>NORM_NODE_NONE</literal> can be set (using <link
374 linkend="NormAddAckingNode"><literal>NormAddAckingNode()</literal></link>)
375 for completion of a NACK-based version of the watermark flushing
376 procedure. This flushing process can be used as a flow control
377 mechanism for NORM applications. Note this is distinct from NORM's
378 congestion control mechanism that, while it provides network-friendly
379 transmission rate control, does guarantee flow control to receiving
380 nodes.<literal>NORM_NODE_NONE</literal> can be set (using <link
381 linkend="NormAddAckingNode"><literal>NormAddAckingNode()</literal></link>)
382 for completion of a NACK-based version of the watermark flushing
383 procedure. This flushing process can be used as a flow control
384 mechanism for NORM applications. Note this is distinct from NORM's
385 congestion control mechanism that, while it provides network-friendly
386 transmission rate control, does guarantee flow control to receiving
387 nodes.</para>
388 </sect3>
389
390 <sect3>
391 <title>Data Reception</title>
392
393 <para>NORM receiver applications learn of active senders and their
394 corresponding pending and completed data transfers, etc via the API
395 event dispatching mechanism. By default, NORM receivers use NACK
396 messages to request repair of transmitted content from the originating
397 sender as needed to achieve reliable transfer. Some API functions are
398 available to provide some additional control over the NACKing
399 behavior, such as initially NACKing for <literal>NORM_INFO</literal>
400 content only or even to the extent of disabling receiver feedback
401 (silent receiver or emission-controlled (EMCON) operation) entirely.
402 Otherwise, the parameters and operation of reliable data transmission
403 are left to sender applications and receivers learn of sender
404 parameters in NORM protocol message headers and are instructed by
405 <literal>NORM_CMD</literal> messages from the sender(s).</para>
406
407 <para>With respect to the NORM API, the receiver application is
408 informed of new senders and receive data objects via the the
409 <parameter>NORM_REMOTE_SENDER_NEW</parameter> and
410 <parameter>NORM_RX_OBJECT_NEW</parameter> notifications, respectfully.
411 Additionally, object reception progress is indicated with the
412 <parameter>NORM_RX_OBJECT_UPDATED</parameter> notification and this
413 also serves as an indicator for the
414 <parameter>NORM_OBJECT_STREAM</parameter> type that the receive
415 application should make calls to <link
416 linkend="NormStreamRead"><literal>NormStreamRead()</literal></link> to
417 read newly received stream content. NORM sender status is also
418 conveyed via the <parameter>NORM_REMOTE_SENDER_ACTIVE</parameter> and
419 NORM_REMOTE_SENDER_INACTIVE notifications. For example, the receiver
420 application may use the
421 <parameter>NORM_REMOTE_SENDER_INACTIVE</parameter> as a cue to make
422 calls to <link
423 linkend="NormNodeFreeBuffers"><literal>NormNodeFreeBuffers()</literal></link>
424 and/or <link
425 linkend="NormNodeDelete"><literal>NormNodeDelete()</literal></link> to
426 free memory resources allocated for buffering received content for the
427 given sender. The amount of memory allocated <emphasis>per
428 sender</emphasis> is set in the <link
429 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
430 call.</para>
431 </sect3>
432 </sect2>
433
434 <sect2>
435 <title>API Event Notification</title>
436
437 <para>An asynchronous event dispatching mechanism is provided to notify
438 the application of significant NORM protocol events. The centerpiece of
439 this is the <link
440 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
441 function that can be used to retrieve the next NORM protocol engine
442 event in the form of a <link
443 linkend="NormEvent"><literal>NormEvent</literal></link> structure. This
444 function will typically block until a <link
445 linkend="NormEvent"><literal>NormEvent</literal></link> occurs. However,
446 non-blocking operation may be achieved by using the <link
447 linkend="NormGetDescriptor"><literal>NormGetDescriptor()</literal></link>
448 call to get a <link
449 linkend="NormDescriptor"><type>NormDescriptor</type></link> (file
450 descriptor) value (Unix <type>int</type> or Win32 <type>HANDLE</type>)
451 suitable for use in a asynchronous I/O monitoring functions such as the
452 Unix <function>select()</function> or Win32
453 <function>MsgWaitForMultipleObjects()</function> system calls. The a
454 <link linkend="NormDescriptor"><type>NormDescriptor</type></link> will
455 be signaled when a <link
456 linkend="NormEvent"><literal>NormEvent</literal></link> is available.
457 For Win32 platforms, dispatching of a user-defined Windows message for
458 NORM event notification is also planned for a future update to the NORM
459 API.</para>
460 </sect2>
461 </sect1>
462
463 <sect1>
464 <title>Build Notes</title>
465
466 <para>To build applications that use the NORM library, a path to the
467 "normApi.h" header file must be provided and the linker step needs to
468 reference the NORM library file ("<filename>libnorm.a</filename>" for Unix
469 platforms and "<filename>Norm.lib</filename>" for Win32 platforms). NORM
470 also depends upon the NRL Protean Protocol Prototyping toolkit "Protokit"
471 library (a.k.a "Protolib") (static library files
472 "<filename>libProtokit.a</filename>" for Unix and
473 "<filename>Protokit.lib</filename>" for Win32). Shared or
474 dynamically-linked versions of these libraries may also be built from the
475 NORM source code or provided. Depending upon the platform, some additional
476 library dependencies may be required to support the needs of NORM and/or
477 Protokit. These are described below.</para>
478
479 <para>The "makefiles" directory contains Unix Makefiles for various
480 platforms the "win32" and "wince" sub-directories there contain Microsoft
481 Visual C++ (VC++) and Embedded VC++ project files for building the NORM
482 implementation. Additionally, a "waf" (Python-based build tool) build
483 option is supported that can be used to build and install the NORM library
484 code on the supported platforms. Finally, Python and Java bindings to the
485 NORM API are included and "src/python" and "src/java" directories contain
486 the code for these and the "makefiles/java" directory contains Makefiles
487 to build the NORM Java JNI bindings. Note the "waf" tool can also be used
488 to build the Java and Python bindings.</para>
489
490 <sect2>
491 <title>Unix Platforms</title>
492
493 <para>NORM has been built and tested on Linux (various architectures),
494 MacOS (BSD), Solaris, and IRIX (SGI) platforms. The code should be
495 readily portable to other Unix platforms.</para>
496
497 <para>To support IPv6 operation, the NORM and the Protokit library must
498 be compiled with the "<constant>HAVE_IPV6</constant>" macro defined.
499 This is default in the NORM and Protokit Makefiles for platforms that
500 support IPv6. It is important that NORM and Protokit be built with this
501 macro defined the same. With NORM, it is recommended that "large file
502 support" options be enabled when possible.</para>
503
504 <para>The NORM API uses threading so that the NORM protocol engine may
505 run independent of the application. Thus the "POSIX Threads" library
506 must be included ("-pthread") in the linking step. MacOS/BSD also
507 requires the addition of the "-lresolv" (resolver) library and Solaris
508 requires the dynamic loader, network/socket, and resolver libraries
509 ("-lnsl -lsocket -lresolv") to achieve successful compilation. The
510 Makefiles in the NORM source code distribution are a reference for these
511 requirements. Note that MacOS 9 and earlier are not supported.</para>
512
513 <para>Additionally, it is critical that the
514 _<constant>FILE_OFFSET_BITS</constant> macro be consistently defined for
515 the NORM library build and the application build using the library. The
516 distributed NORM Makefiles have
517 <constant>-D_FILE_OFFSET_BITS=64</constant> set in the compilation to
518 enable "large file support". Applications built using NORM should have
519 the same compilation option set to operate correctly (The definition of
520 the <link linkend="NormSize"><literal>NormSize</literal></link> type in
521 "<filename>normApi.h</filename>" depends upon this compilation
522 flag).</para>
523 </sect2>
524
525 <sect2>
526 <title>Win32/WiNCE Platforms</title>
527
528 <para>NORM has been built using Microsoft's Visual C++ (6.0 and .NET)
529 and Embedded VC++ 4.2 environments. In addition to proper macro
530 definitions (e.g., HAVE_IPV6, etc) that are included in the respective
531 "Protokit" and "NORM" project files, it is important that common code
532 generation settings be used when building the NORM application. The NORM
533 and Protokit projects are built with the "Multi-threading DLL" library
534 usage set. The NORM API requires multi-threading support. This is a
535 critical setting and numerous compiler and linker errors will result if
536 this is not properly set for your application project.</para>
537
538 <para>NORM and Protokit also depend on the Winsock 2.0
539 ("<filename>ws2_32.lib</filename>" (or "<filename>ws2.lib</filename>"
540 (WinCE)) and the IP Helper API ("<filename>iphlpapi.lib</filename>")
541 libraries and these must be included in the project "Link"
542 attributes.</para>
543
544 <para>An additional note is that a bug in VC++ 6.0 and earlier compilers
545 (includes embedded VC++ 4.x compilers) prevent compilation of
546 Protokit-based code with debugging capabilities enabled. However, this
547 has been resolved in VC++ .NET and is hoped to be resolved in the future
548 for the WinCE build tools.</para>
549
550 <para>Operation on Windows NT4 (and perhaps other older Windows
551 operating systems) requires that the compile time macro
552 <constant>WINVER=0x0400</constant> defined. This is because the version
553 of the IP Helper API library (<filename>iphlpapi.lib</filename>) used by
554 <emphasis>Protolib</emphasis> (and hence NORM) for this system doesn't
555 support some of the functions defined for this library. This may be
556 related to IPv6 support issues so it may be possible that the Protolib
557 build could be tweaked to provide a single binary executable suitable
558 for IPv4 operation only across a large range of Windows
559 platforms.</para>
560 </sect2>
561 </sect1>
562
563 <sect1>
564 <title>API Reference</title>
565
566 <para>This section provides a reference to the NORM API variable types,
567 constants and functions.</para>
568
569 <sect2>
570 <title>API Variable Types and Constants</title>
571
572 <para>The NORM API defines and enumerates a number of supporting
573 variable types and values which are used in different function calls.
574 The variable types are described here.</para>
575
576 <sect3 id="NormInstanceHandle">
577 <title>NormInstanceHandle</title>
578
579 <para>The <link
580 linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link>
581 type is returned when a NORM API instance is created (see <link
582 linkend="NormCreateInstance"><literal>NormCreateInstance()</literal></link>).
583 This handle can be subsequently used for API calls which require
584 reference to a specific NORM API instance. By default, each NORM API
585 instance instantiated creates an operating system thread for protocol
586 operation. Note that multiple NORM transport sessions may be created
587 for a single API instance. In general, it is expected that
588 applications will create a single NORM API instance, but some
589 multi-threaded application designs may prefer multiple corresponding
590 NORM API instances. The value <literal>NORM_INSTANCE_INVALID</literal>
591 corresponds to an invalid API instance.</para>
592 </sect3>
593
594 <sect3 id="NormSessionHandle">
595 <title>NormSessionHandle</title>
596
597 <para>The <link
598 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>
599 type is used to reference NORM transport sessions which have been
600 created using the <link
601 linkend="NormCreateSession"><literal>NormCreateSession()</literal></link>
602 API call. Multiple <link
603 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>
604 values may be associated with a given <link
605 linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link>.
606 The special value <literal>NORM_SESSION_INVALID</literal> is used to
607 refer to invalid session references.</para>
608 </sect3>
609
610 <sect3 id="NormSessionId">
611 <title>NormSessionId</title>
612
613 <para>The <link
614 linkend="NormSessionId"><literal>NormSessionId</literal></link> type
615 is used by applications to uniquely identify their instance of
616 participation as a sender within a <emphasis>NormSession</emphasis>.
617 This type is a parameter to the <link
618 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
619 function. Robust applications can use different <link
620 linkend="NormSessionId"><literal>NormSessionId</literal></link> values
621 when initiating sender operation so that receivers can discriminate
622 when a sender has terminated and restarted (whether intentional or due
623 to system failure). For example, an application could cache its prior
624 <link linkend="NormSessionId"><literal>NormSessionId</literal></link>
625 value in non-volatile storage which could then be recovered and
626 incremented (for example) upon system restart to produce a new value.
627 The <link
628 linkend="NormSessionId"><literal>NormSessionId</literal></link> value
629 is used for the value of the instance_id field in NORM protocol sender
630 messages (see the NORM protocol specification) and receivers use this
631 field to detect sender restart within a
632 <emphasis>NormSession</emphasis>.</para>
633 </sect3>
634
635 <sect3 id="NormNodeHandle">
636 <title>NormNodeHandle</title>
637
638 <para>The <link
639 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> type
640 is used to reference state kept by the NORM implementation with
641 respect to other participants within a
642 <emphasis>NormSession</emphasis>. Most typically, the <link
643 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> is
644 used by receiver applications to dereference information about remote
645 senders of data as needed. The special value
646 <literal>NORM_NODE_INVALID</literal> corresponds to an invalid
647 reference.</para>
648 </sect3>
649
650 <sect3 id="NormNodeId">
651 <title>NormNodeId</title>
652
653 <para>The <link
654 linkend="NormNodeId"><literal>NormNodeId</literal></link> type
655 corresponds to a 32-bit numeric value which should uniquely identify a
656 participant (node) in a given <emphasis>NormSession</emphasis>. The
657 <link
658 linkend="NormNodeGetId"><literal>NormNodeGetId()</literal></link>
659 function can be used to retrieve this value given a valid <link
660 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>. The
661 special value <literal>NORM_NODE_NONE</literal> corresponds to an
662 invalid (or null) node while the value
663 <literal>NORM_NODE_ANY</literal> serves as a wild card value for some
664 functions.</para>
665 </sect3>
666
667 <sect3 id="NormObjectHandle">
668 <title>NormObjectHandle</title>
669
670 <para>The <link
671 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
672 type is used to reference state kept for data transport objects being
673 actively transmitted or received. The state kept for NORM transport
674 objects is temporary, but the NORM API provides a function to
675 persistently retain state associated with a sender or receiver <link
676 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
677 (see <link
678 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>)
679 if needed. For sender objects, unless explicitly retained, the <link
680 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
681 can be considered valid until the referenced object is explicitly
682 canceled (see <link
683 linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>)
684 or purged from the sender transmission queue (see the event
685 <literal>NORM_TX_OBJECT_PURGED</literal>). For receiver objects, these
686 handles should be treated as valid only until a subsequent call to
687 <link
688 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
689 unless, again, specifically retained. The special value
690 <literal>NORM_OBJECT_INVALID</literal> corresponds to an invalid
691 transport object reference.</para>
692 </sect3>
693
694 <sect3 id="NormObjectType">
695 <title>NormObjectType</title>
696
697 <para>The <link
698 linkend="NormObjectType"><literal>NormObjectType</literal></link> type
699 is an enumeration of possible NORM data transport object types. As
700 previously mentioned, valid types include:</para>
701
702 <orderedlist>
703 <listitem>
704 <para><literal>NORM_OBJECT_FILE</literal></para>
705 </listitem>
706
707 <listitem>
708 <para><literal>NORM_OBJECT_DATA</literal>, and</para>
709 </listitem>
710
711 <listitem>
712 <para><literal>NORM_OBJECT_STREAM</literal></para>
713 </listitem>
714 </orderedlist>
715
716 <para>Given a <link
717 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>,
718 the application may determine an object's type using the <link
719 linkend="NormObjectGetType"><literal>NormObjectGetType()</literal></link>
720 function call. A special <link
721 linkend="NormObjectType"><literal>NormObjectType</literal></link>
722 value, <literal>NORM_OBJECT_NONE</literal>, indicates an invalid
723 object type.</para>
724 </sect3>
725
726 <sect3 id="NormSize">
727 <title>NormSize</title>
728
729 <para>The <link linkend="NormSize"><literal>NormSize</literal></link>
730 is the type used for <emphasis>NormObject</emphasis> size information.
731 For example, the <link
732 linkend="NormObjectGetSize"><literal>NormObjectGetSize()</literal></link>
733 function returns a value of type <link
734 linkend="NormSize"><literal>NormSize</literal></link>. The range of
735 <link linkend="NormSize"><literal>NormSize</literal></link> values
736 depends upon the operating system and NORM library compilation
737 settings. With "large file support" enabled, as is the case with
738 distributed NORM library "Makefiles", the <link
739 linkend="NormSize"><literal>NormSize</literal></link> type is a 64-bit
740 integer. However, some platforms may support only 32-bit object
741 sizes.</para>
742 </sect3>
743
744 <sect3 id="NormObjectTransportId">
745 <title>NormObjectTransportId</title>
746
747 <para>The <link
748 linkend="NormObjectTransportId"><literal>NormObjectTransportId</literal></link>
749 type is a 16-bit numerical value assigned to
750 <emphasis>NormObjects</emphasis> by senders during active transport.
751 These values are temporarily unique with respect to a given sender
752 within a <emphasis>NormSession</emphasis> and may be "recycled" for
753 use for future transport objects. NORM sender nodes assign these
754 values in a monotonically increasing fashion during the course of a
755 session as part of protocol operation. Typically, the application
756 should not need access to these values, but an API call such as
757 <function>NormObjectGetTransportId()</function>
758 (<emphasis>TBD</emphasis>) may be provided to retrieve these values if
759 needed. (Note this type may be deprecated; i.e., it may not be needed
760 at since the <link
761 linkend="NormRequeueObject"><function>NormRequeueObject()</function></link>
762 function is implemented using handles only, but _some_ applications
763 requiring persistence even after a system reboot may need the ability
764 to recall previous transport ids?)</para>
765 </sect3>
766
767 <sect3 id="NormEventType">
768 <title>NormEventType</title>
769
770 <para>The <link
771 linkend="NormEventType"><literal>NormEventType</literal></link> is an
772 enumeration of NORM API events. "Events" are used by the NORM API to
773 signal the application of significant NORM protocol operation events
774 (e.g., receipt of a new receive object, etc). A description of
775 possible <link
776 linkend="NormEventType"><literal>NormEventType</literal></link> values
777 and their interpretation is given below. The function call <link
778 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
779 is used to retrieve events from the NORM protocol engine.</para>
780 </sect3>
781
782 <sect3 id="NormEvent">
783 <title>NormEvent</title>
784
785 <para>The <link
786 linkend="NormEvent"><literal>NormEvent</literal></link> type is a
787 structure used to describe significant NORM protocol events. This
788 structure is defined as follows:</para>
789
790 <para><programlisting>typedef struct
791 {
792 NormEventType type;
793 <link linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session;
794 <link linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> node;
795 <link linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> object;
796 } <link linkend="NormEvent"><literal>NormEvent</literal></link>;</programlisting></para>
797
798 <para>The <parameter>type</parameter> field indicates the <link
799 linkend="NormEventType"><literal>NormEventType</literal></link> and
800 determines how the other fields should be interpreted. Note that not
801 all <link
802 linkend="NormEventType"><literal>NormEventType</literal></link> fields
803 are relevant to all events. The <parameter>session</parameter>,
804 <parameter>node</parameter>, and <parameter>object</parameter> fields
805 indicate the applicable <link
806 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>,
807 <link
808 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>, and
809 <link
810 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>,
811 respectively, to which the event applies. NORM protocol events are
812 made available to the application via the <link
813 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
814 function call.</para>
815 </sect3>
816
817 <sect3 id="NormDescriptor">
818 <title>NormDescriptor</title>
819
820 <para>The <link
821 linkend="NormDescriptor"><literal>NormDescriptor</literal></link> type
822 can provide a reference to a corresponding file descriptor (Unix
823 <type>int</type> or Win32 <type>HANDLE</type>) for the
824 <emphasis>NormInstance</emphasis>. For a given <link
825 linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link>,
826 the <link
827 linkend="NormGetDescriptor"><literal>NormGetDescriptor()</literal></link>
828 function can be used to retrieve a <link
829 linkend="NormDescriptor"><literal>NormDescriptor</literal></link>
830 value that may, in turn, used in appropriate system calls (e.g.
831 <function>select()</function> or
832 <function>MsgWaitForMultipleObjects()</function>) to asynchronously
833 monitor the NORM protocol engine for notification events (see <link
834 linkend="NormEvent"><literal>NormEvent</literal></link>
835 description).</para>
836 </sect3>
837
838 <sect3 id="NormFlushMode">
839 <title>NormFlushMode</title>
840
841 <para>The <link
842 linkend="NormFlushMode"><literal>NormFlushMode</literal></link> type
843 consists of the following enumeration:</para>
844
845 <para><programlisting>enum <link linkend="NormFlushMode"><literal>NormFlushMode</literal></link>
846 <literal>{
847 NORM_FLUSH_NON</literal>E<literal>,
848 NORM_FLUSH_PASSIV</literal>E<literal>,
849 NORM_FLUSH_ACTIV</literal>E
850 };</programlisting></para>
851
852 <para>The use and interpretation of these values is given in the
853 descriptions of <link
854 linkend="NormStreamFlush"><literal>NormStreamFlush()</literal></link>
855 and <link
856 linkend="NormStreamSetAutoFlush"><literal>NormStreamSetAutoFlush()</literal></link>
857 functions.</para>
858 </sect3>
859
860 <sect3 id="NormProbingMode">
861 <title>NormProbingMode</title>
862
863 <para>The <link
864 linkend="NormProbingMode"><literal>NormProbingMode</literal></link>
865 type consists of the following enumeration:</para>
866
867 <para><programlisting>enum <link linkend="NormProbingMode"><literal>NormProbingMode</literal></link>
868 {
869 <literal>NORM_PROBE_NON</literal>E<literal>,
870 NORM_PROBE_PASSIV</literal>E<literal>,
871 NORM_PROBE_ACTIV</literal>E
872 };</programlisting></para>
873
874 <para>The use and interpretation of these values is given in the
875 description of <link
876 linkend="NormSetGrttProbingMode"><literal>NormSetGrttProbingMode()</literal></link>
877 function.</para>
878 </sect3>
879
880 <sect3 id="NormSyncPolicy">
881 <title>NormSyncPolicy</title>
882
883 <para>The <link
884 linkend="NormSyncPolicy"><literal>NormSyncPolicy</literal></link> type
885 consists of the following enumeration:</para>
886
887 <para><programlisting>enum <link linkend="NormSyncPolicy"><literal>NormSyncPolicy</literal></link>
888 {
889 <literal>NORM_SYNC_CURRENT</literal><literal>,
890 NORM_</literal>SYNC_ALL<literal>
891 };</literal></programlisting></para>
892
893 <para>The use and interpretation of these values is given in the
894 descriptions of the <link
895 linkend="NormSetDefaultSyncPolicy"><literal>NormSetDefaultSyncPolicy()</literal></link>
896 function.</para>
897 </sect3>
898
899 <sect3 id="NormNackingMode">
900 <title>NormNackingMode</title>
901
902 <para>The <link
903 linkend="NormNackingMode"><literal>NormNackingMode</literal></link>
904 type consists of the following enumeration:</para>
905
906 <para><programlisting>enum <link linkend="NormNackingMode"><literal>NormNackingMode</literal></link>
907 {
908 <literal>NORM_NACK_NON</literal>E<literal>,
909 NORM_NACK_INFO_ONL</literal>Y,
910 <literal>NORM_NACK_NORMAL
911 };</literal></programlisting></para>
912
913 <para>The use and interpretation of these values is given in the
914 descriptions of the <link
915 linkend="NormSetDefaultNackingMode"><literal>NormSetDefaultNackingMode()</literal></link>,
916 <link
917 linkend="NormNodeSetNackingMode"><literal>NormNodeSetNackingMode()</literal></link>
918 and <link
919 linkend="NormObjectSetNackingMode"><literal>NormObjectSetNackingMode()</literal></link>
920 functions.</para>
921 </sect3>
922
923 <sect3 id="NormRepairBoundary">
924 <title>NormRepairBoundary</title>
925
926 <para>The <link
927 linkend="NormRepairBoundary"><literal>NormRepairBoundary</literal></link>
928 types consists of the following enumeration:</para>
929
930 <para><programlisting>enum <link linkend="NormRepairBoundary"><literal>NormRepairBoundary</literal></link>
931 {<literal>
932 NORM_BOUNDARY_BLOC</literal>K,
933 N<literal>ORM_BOUNDARY_OBJECT
934 };</literal></programlisting></para>
935
936 <para>The interpretation of these values is given in the descriptions
937 of the <link
938 linkend="NormSetDefaultRepairBoundary"><literal>NormSetDefaultRepairBoundary()</literal></link>
939 and <link
940 linkend="NormNodeSetRepairBoundary"><literal>NormNodeSetRepairBoundary()</literal></link>
941 functions.</para>
942 </sect3>
943
944 <sect3 id="NormAckingStatus">
945 <title>NormAckingStatus</title>
946
947 <para>The <link
948 linkend="NormAckingStatus"><literal>NormAckingStatus</literal></link>
949 consist of the following enumeration:</para>
950
951 <para><programlisting>enum <link linkend="NormAckingStatus"><literal>NormAckingStatus</literal></link>
952 {
953 <literal>NORM_ACK_INVALID</literal>,<literal>
954 NORM_ACK_FAILUR</literal>E<literal>,
955 NORM_ACK_PENDIN</literal>G,
956 <literal>NORM_ACK_SUCCES</literal>S
957 };</programlisting></para>
958
959 <para>The interpretation of these values is given in the descriptions
960 of the <link
961 linkend="NormGetAckingStatus"><literal>NormGetAckingStatus()</literal></link>
962 function.</para>
963 </sect3>
964 </sect2>
965
966 <sect2>
967 <title>API Initialization and Operation</title>
968
969 <para>The first step in using the NORM API is to create an "instance" of
970 the NORM protocol engine. Note that multiple instances may be created by
971 the application if necessary, but generally only a single instance is
972 required since multiple <emphasis>NormSessions</emphasis> may be managed
973 under a single NORM API instance.</para>
974
975 <sect3 id="NormCreateInstance">
976 <title>NormCreateInstance()</title>
977
978 <sect4>
979 <title>Synopsis</title>
980
981 <programlisting>#include &lt;normApi.h&gt;
982
983 <link linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link> <link
984 linkend="NormCreateInstance"><literal>NormCreateInstance</literal></link>(bool <parameter>priorityBoost</parameter> = false);</programlisting>
985 </sect4>
986
987 <sect4>
988 <title>Description</title>
989
990 <para>This function creates an instance of a NORM protocol engine
991 and is the necessary first step before any other API functions may
992 be used. With the instantiation of the NORM protocol engine, an
993 operating system thread is created for protocol execution. The
994 returned <link
995 linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link>
996 value may be used in subsequent API calls as needed, such <link
997 linkend="NormCreateSession"><literal>NormCreateSession()</literal></link>,
998 etc. The optional <parameter>priorityBoost</parameter> parameter,
999 when set to a value of true, specifies that the NORM protocol engine
1000 thread be run with higher priority scheduling. On Win32 platforms,
1001 this corresponds to
1002 <constant>THREAD_PRIORITY_TIME_CRITICAL</constant> and on Unix
1003 systems with the <function>sched_setscheduler()</function> API, an
1004 attempt to get the maximum allowed <constant>SCHED_FIFO</constant>
1005 priority is made. The use of this option should be carefully
1006 evaluated since, depending upon the application's scheduling
1007 priority and NORM API usage, this may have adverse effects instead
1008 of a guaranteed performance increase!</para>
1009 </sect4>
1010
1011 <sect4>
1012 <title>Return Values</title>
1013
1014 <para>A value of <literal>NORM_INSTANCE_INVALID</literal> is
1015 returned upon failure. The function will only fail if system
1016 resources are unavailable to allocate the instance and/or create the
1017 corresponding thread.</para>
1018 </sect4>
1019 </sect3>
1020
1021 <sect3 id="NormDestroyInstance">
1022 <title>NormDestroyInstance()</title>
1023
1024 <sect4>
1025 <title>Synopsis</title>
1026
1027 <programlisting>#include &lt;normApi.h&gt;
1028
1029 void <link linkend="NormDestroyInstance"><literal>NormDestroyInstance</literal></link>(<link
1030 linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link> instanceHandle);</programlisting>
1031 </sect4>
1032
1033 <sect4>
1034 <title>Description</title>
1035
1036 <para>The <link
1037 linkend="NormDestroyInstance"><literal>NormDestroyInstance()</literal></link>
1038 function immediately shuts down and destroys the NORM protocol
1039 engine instance referred to by the
1040 <parameter>instanceHandle</parameter> parameter. The application
1041 should make no subsequent references to the indicated <link
1042 linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link>
1043 or any other API handles or objects associated with it. However, the
1044 application is still responsible for releasing any object handles it
1045 has retained (see <link
1046 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
1047 and <link
1048 linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>).</para>
1049 </sect4>
1050
1051 <sect4>
1052 <title>Return Values</title>
1053
1054 <para>The function has no return value.</para>
1055 </sect4>
1056 </sect3>
1057
1058 <sect3 id="NormStopInstance">
1059 <title>NormStopInstance()</title>
1060
1061 <sect4>
1062 <title>Synopsis</title>
1063
1064 <programlisting>#include &lt;normApi.h&gt;
1065
1066 void <link linkend="NormStopInstance"><literal>NormStopInstance</literal></link>(<link
1067 linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link> instanceHandle);</programlisting>
1068 </sect4>
1069
1070 <sect4>
1071 <title>Description</title>
1072
1073 <para>This function immediately stops the NORM protocol engine
1074 thread corresponding to the given
1075 <parameter>instanceHandle</parameter> parameter. It also posts a
1076 "dummy" notification event so that if another thread is blocked on a
1077 call to <link
1078 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>,
1079 that thread will be released. Hence, for some multi-threaded uses of
1080 the NORM API, this function may be useful as a preliminary step to
1081 safely coordinate thread shutdown before a call is made to <link
1082 linkend="NormDestroyInstance"><literal>NormDestroyInstance()</literal></link>.
1083 After <link
1084 linkend="NormStopInstance"><literal>NormStopInstance()</literal></link>
1085 is called and any pending events posted prior to its call have been
1086 retrieved, <link
1087 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
1088 will return a value of <constant>false</constant>.</para>
1089
1090 <para>When this function is invoked, state for any
1091 <emphasis>NormSessions</emphasis> associated with the given instance
1092 is "frozen". The complementary function, <link
1093 linkend="NormRestartInstance"><literal>NormRestartInstance()</literal></link>
1094 can be subsequently used to "unfreeze" and resume NORM protocol
1095 operation (a new thread is created and started).</para>
1096 </sect4>
1097
1098 <sect4>
1099 <title>Return Values</title>
1100
1101 <para>The function has no return value.</para>
1102 </sect4>
1103 </sect3>
1104
1105 <sect3 id="NormRestartInstance">
1106 <title>NormRestartInstance()</title>
1107
1108 <sect4>
1109 <title>Synopsis</title>
1110
1111 <programlisting>#include &lt;normApi.h&gt;
1112
1113 bool <link linkend="NormRestartInstance"><literal>NormRestartInstance</literal></link>(<link
1114 linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link> instanceHandle);</programlisting>
1115 </sect4>
1116
1117 <sect4>
1118 <title>Description</title>
1119
1120 <para>This function creates and starts an operating system thread to
1121 resume NORM protocol engine operation for the given
1122 <parameter>instanceHandle</parameter> that was previously stopped by
1123 a call to <link
1124 linkend="NormStopInstance"><literal>NormStopInstance()</literal></link>.
1125 It is not expected that this function will be used often, but there
1126 may be special application cases where "freezing" and later resuming
1127 NORM protocol operation may be useful.</para>
1128 </sect4>
1129
1130 <sect4>
1131 <title>Return Values</title>
1132
1133 <para>The function returns <constant>true</constant> when the NORM
1134 protocol engine thread is successfully restarted, and
1135 <constant>false</constant> otherwise.</para>
1136 </sect4>
1137 </sect3>
1138
1139 <sect3 id="NormSetCacheDirectory">
1140 <title>NormSetCacheDirectory()</title>
1141
1142 <sect4>
1143 <title>Synopsis</title>
1144
1145 <programlisting>#include &lt;normApi.h&gt;
1146
1147 bool <link linkend="NormSetCacheDirectory"><literal>NormSetCacheDirectory</literal></link>(<link
1148 linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link> instanceHandle,
1149 const char* cachePath);</programlisting>
1150 </sect4>
1151
1152 <sect4>
1153 <title>Description</title>
1154
1155 <para>This function sets the directory path used by receivers to
1156 cache newly-received <constant>NORM_OBJECT_FILE</constant> content.
1157 The <parameter>instanceHandle</parameter> parameter specifies the
1158 NORM protocol engine instance (all <emphasis>NormSessions</emphasis>
1159 associated with that <parameter>instanceHandle</parameter> share the
1160 same cache path) and the <parameter>cachePath</parameter> is a
1161 string specifying a valid (and writable) directory path.</para>
1162 </sect4>
1163
1164 <sect4>
1165 <title>Return Values</title>
1166
1167 <para>The function returns <constant>true</constant> on success and
1168 <constant>false</constant> on failure. The failure conditions are
1169 that the indicated directory does not exist or the process does not
1170 have permissions to write.</para>
1171 </sect4>
1172 </sect3>
1173
1174 <sect3 id="NormGetNextEvent">
1175 <title>NormGetNextEvent()</title>
1176
1177 <sect4>
1178 <title>Synopsis</title>
1179
1180 <programlisting>#include &lt;normApi.h&gt;
1181
1182 bool <link linkend="NormGetNextEvent"><literal>NormGetNextEvent</literal></link>(<link
1183 linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link> instanceHandle,
1184 <link linkend="NormEvent"><literal>NormEvent*</literal></link> theEvent);</programlisting>
1185 </sect4>
1186
1187 <sect4>
1188 <title>Description</title>
1189
1190 <para>This function retrieves the next available NORM protocol event
1191 from the protocol engine. The <parameter>instanceHandle</parameter>
1192 parameter specifies the applicable NORM protocol engine, and the
1193 <parameter>theEvent</parameter> parameter must be a valid pointer to
1194 a <link linkend="NormEvent"><literal>NormEvent</literal></link>
1195 structure capable of receiving the NORM event information. For
1196 expected reliable protocol operation, the application should make
1197 every attempt to retrieve and process NORM notification events in a
1198 timely manner.</para>
1199
1200 <para>Note that this is currently the only blocking call in the NORM
1201 API. But non-blocking operation may be achieved by using the <link
1202 linkend="NormGetDescriptor"><literal>NormGetDescriptor()</literal></link>
1203 function to obtain a descriptor (<type>int</type> for Unix or
1204 <type>HANDLE</type> for WIN32) suitable for asynchronous
1205 input/output (I/O) notification using such system calls the Unix
1206 <function>select()</function> or Win32
1207 <function>WaitForMultipleObjects()</function> calls. The descriptor
1208 is signaled when a notification event is pending and a call to <link
1209 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
1210 will not block.<link
1211 linkend="NormGetNextEvent"><literal>NormGetNextEvent</literal></link></para>
1212 </sect4>
1213
1214 <sect4>
1215 <title>Return Values</title>
1216
1217 <para>The function returns <constant>true</constant> when a <link
1218 linkend="NormEvent"><type>NormEvent</type></link> is successfully
1219 retrieved, and <constant>false</constant> otherwise. Note that a
1220 return value of <constant>false</constant> does
1221 <emphasis>not</emphasis> indicate an error or signify end of NORM
1222 operation.</para>
1223 </sect4>
1224
1225 <sect4>
1226 <title>NORM Notification Event Types</title>
1227
1228 <para>The following table enumerates the possible <link
1229 linkend="NormEvent"><literal>NormEvent</literal></link> values and
1230 describes how these notifications should be interpreted as they are
1231 retrieved by the application via the <link
1232 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
1233 function call.</para>
1234
1235 <informaltable frame="all">
1236 <tgroup cols="2">
1237 <colspec colnum="1" colwidth="1*"/>
1238
1239 <colspec colnum="2" colwidth="2.5*"/>
1240
1241 <tbody>
1242 <row>
1243 <entry nameend="c2" namest="c1"><para><emphasis
1244 role="bold">Sender Notifications:</emphasis></para></entry>
1245 </row>
1246
1247 <row>
1248 <entry><para><literal>NORM_TX_QUEUE_VACANCY</literal></para></entry>
1249
1250 <entry><para>This event indicates that there is room for
1251 additional transmit objects to be enqueued, or, if the
1252 handle of <literal>NORM_OBJECT_STREAM</literal> is given in
1253 the corresponding event "object" field, the application may
1254 successfully write to the indicated stream object. Note this
1255 event is not dispatched until a call to <link
1256 linkend="NormFileEnqueue"><literal>NormFileEnqueue()</literal></link>,
1257 <link
1258 linkend="NormDataEnqueue"><literal>NormDataEnqueue()</literal></link>,
1259 or <link
1260 linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
1261 fails because of a filled transmit cache or stream
1262 buffer.</para></entry>
1263 </row>
1264
1265 <row>
1266 <entry><para><literal>NORM_TX_QUEUE_EMPTY</literal></para></entry>
1267
1268 <entry><para>This event indicates the NORM protocol engine
1269 has no new data pending transmission and the application may
1270 enqueue additional objects for transmission. If the handle
1271 of a sender <literal>NORM_OBJECT_STREAM</literal> is given
1272 in the corresponding event "object" field, this indicates
1273 the stream transmit buffer has been emptied and the sender
1274 application may write to the stream (Use of
1275 <literal>NORM_TX_QUEUE_VACANCY</literal> may be preferred
1276 for this purpose since it allows the application to keep the
1277 NORM protocol engine busier sending data, resulting in
1278 higher throughput when attempting very high transfer
1279 rates).</para></entry>
1280 </row>
1281
1282 <row>
1283 <entry><para><literal>NORM_TX_FLUSH_COMPLETED</literal></para></entry>
1284
1285 <entry><para>This event indicates that the flushing process
1286 the NORM sender observes when it no longer has data ready
1287 for transmission has completed. The completion of the
1288 flushing process is a reasonable indicator (with a
1289 sufficient NORM "robust factor" value) that the receiver set
1290 no longer has any pending repair requests. Note the use of
1291 NORM's optional positive acknowledgement feature is more
1292 deterministic in this regards, but this notification is
1293 useful when there are non-acking (NACK-only) receivers. The
1294 default NORM robust factor of 20 (20 flush messages are sent
1295 at end-of-transmission) provides a high assurance of
1296 reliable transmission, even with packet loss rates of
1297 50%.</para></entry>
1298 </row>
1299
1300 <row>
1301 <entry><para><literal>NORM_TX_WATERMARK_COMPLETED</literal></para></entry>
1302
1303 <entry><para>This event indicates that the flushing process
1304 initiated by a prior application call to <link
1305 linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
1306 has completed The posting of this event indicates the
1307 appropriate time for the application to make a call <link
1308 linkend="NormGetAckingStatus"><literal>NormGetAckingStatus()</literal></link>
1309 to determine the results of the watermark flushing
1310 process.</para></entry>
1311 </row>
1312
1313 <row>
1314 <entry><para><literal>NORM_TX_OBJECT_SENT</literal></para></entry>
1315
1316 <entry><para>This event indicates that the transport object
1317 referenced by the event's "object" field has completed at
1318 least one pass of total transmission. Note that this does
1319 not guarantee that reliable transmission has yet completed;
1320 only that the entire object content has been transmitted.
1321 Depending upon network behavior, several rounds of NACKing
1322 and repair transmissions may be required to complete
1323 reliable transfer.</para></entry>
1324 </row>
1325
1326 <row>
1327 <entry><para><literal>NORM_TX_OBJECT_PURGED</literal></para></entry>
1328
1329 <entry><para>This event indicates that the NORM protocol
1330 engine will no longer refer to the transport object
1331 identified by the event's "object' field. Typically, this
1332 will occur when the application has enqueued more objects
1333 than space available within the set sender transmit cache
1334 bounds (see <link
1335 linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>).
1336 Posting of this notification means the application is free
1337 to free any resources (memory, files, etc) associated with
1338 the indicated "object". After this event, the given "object"
1339 handle (<link
1340 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>)
1341 is no longer valid unless it is specifically retained by the
1342 application.<link
1343 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link></para></entry>
1344 </row>
1345
1346 <row>
1347 <entry><literal>NORM_TX_CMD_SENT</literal></entry>
1348
1349 <entry>This event indicates that an application-defined
1350 command previously enqueued with a call to <link
1351 linkend="NormSendCommand"><literal>NormSendCommand()</literal></link>
1352 has been transmitted, including any repetition.</entry>
1353 </row>
1354
1355 <row>
1356 <entry><literal>NORM_TX_RATE_CHANGED</literal></entry>
1357
1358 <entry>This event indicates that NORM Congestion Control
1359 operation has adjusted the transmission rate. The <link
1360 linkend="NormGetTxRate"><literal>NormGetTxRate()</literal></link>
1361 call may be used to retrieve the new corresponding
1362 transmission rate. Note that if <link
1363 linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>
1364 was called with its <parameter>adjustRate</parameter>
1365 parameter set to <constant>false</constant>, then no actual
1366 rate change has occurred and the rate value returned by
1367 <link
1368 linkend="NormGetTxRate"><literal>NormGetTxRate()</literal></link>
1369 reflects a "suggested" rate and not the actual transmission
1370 rate.</entry>
1371 </row>
1372
1373 <row>
1374 <entry><para><literal>NORM_LOCAL_SENDER_CLOSED</literal></para></entry>
1375
1376 <entry><para>This event is posted when the NORM protocol
1377 engine completes the "graceful shutdown" of its
1378 participation as a sender in the indicated "session" (see
1379 <link
1380 linkend="NormStopSender"><literal>NormStopSender()</literal></link>).</para></entry>
1381 </row>
1382
1383 <row>
1384 <entry><para><literal>NORM_CC_ACTIVE</literal></para></entry>
1385
1386 <entry><para>This event indicates that congestion control
1387 feedback from receivers has begun to be received (This also
1388 implies that receivers in the group are actually present and
1389 can be used as a cue to begin data transmission.). Note that
1390 congestion control must be enabled (see <link
1391 linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>)
1392 for this event to be posted. Congestion control feedback can
1393 be assumed to be received until a
1394 <literal>NORM_CC_INACTIVE</literal> event is
1395 posted.</para></entry>
1396 </row>
1397
1398 <row>
1399 <entry><para><literal>NORM_CC_INACTIVE</literal></para></entry>
1400
1401 <entry><para>This event indicates there has been no recent
1402 congestion control feedback received from the receiver set
1403 and that the local NORM sender has reached its minimum
1404 transmit rate. Applications may wish to refrain from new
1405 data transmission until a <literal>NORM_CC_ACTIVE</literal>
1406 event is posted. This notification is only posted when
1407 congestion control operation is enabled (see <link
1408 linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>)
1409 and a previous <literal>NORM_CC_ACTIVE</literal> event has
1410 occurred.</para></entry>
1411 </row>
1412
1413 <row>
1414 <entry nameend="c2" namest="c1"><para><emphasis
1415 role="bold">Receiver
1416 Notifications:</emphasis></para></entry>
1417 </row>
1418
1419 <row>
1420 <entry><para><literal>NORM_REMOTE_SENDER_NEW</literal></para></entry>
1421
1422 <entry><para>This event is posted when a receiver first
1423 receives messages from a specific remote NORM sender. This
1424 marks the beginning of the interval during which the
1425 application may reference the provided "node" handle (<link
1426 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>).</para></entry>
1427 </row>
1428
1429 <row>
1430 <entry><para><literal>NORM_REMOTE_SENDER_ACTIVE</literal></para></entry>
1431
1432 <entry><para>This event is posted when a previously inactive
1433 (or new) remote <anchor id="OLE_LINK5"/> <anchor
1434 id="OLE_LINK4"/>sender is detected operating as an active
1435 sender within the session.</para></entry>
1436 </row>
1437
1438 <row>
1439 <entry><para><literal>NORM_REMOTE_SENDER_INACTIVE</literal></para></entry>
1440
1441 <entry><para>This event is posted after a significant period
1442 of inactivity (no sender messages received) of a specific
1443 NORM sender within the session. The NORM protocol engine
1444 frees buffering resources allocated for this sender when it
1445 becomes inactive.</para></entry>
1446 </row>
1447
1448 <row>
1449 <entry><para><literal>NORM_REMOTE_SENDER_PURGED</literal></para></entry>
1450
1451 <entry><para>This event is posted when the NORM protocol
1452 engine frees resources for, and thus invalidates the
1453 indicated "node" handle.</para></entry>
1454 </row>
1455
1456 <row>
1457 <entry><para><literal>NORM_RX_OBJECT_NEW</literal></para></entry>
1458
1459 <entry><para>This event is posted when reception of a new
1460 transport object begins and marks the beginning of the
1461 interval during which the specified "object" (<link
1462 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>)
1463 is valid.</para></entry>
1464 </row>
1465
1466 <row>
1467 <entry><para><literal>NORM_RX_OBJECT_INFO</literal></para></entry>
1468
1469 <entry><para>This notification is posted when the
1470 <literal>NORM_INFO</literal> content for the indicated
1471 "object" is received.</para></entry>
1472 </row>
1473
1474 <row>
1475 <entry><para><literal>NORM_RX_OBJECT_UPDATED</literal></para></entry>
1476
1477 <entry><para>This event indicates that the identified
1478 receive "object" has newly received data
1479 content.</para></entry>
1480 </row>
1481
1482 <row>
1483 <entry><para><literal>NORM_RX_OBJECT_COMPLETED</literal></para></entry>
1484
1485 <entry><para>This event is posted when a receive object is
1486 completely received, including available
1487 <literal>NORM_INFO</literal> content. Unless the application
1488 specifically retains the "object" handle, the indicated
1489 <link
1490 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
1491 becomes invalid and must no longer be
1492 referenced.</para></entry>
1493 </row>
1494
1495 <row>
1496 <entry><para><literal>NORM_RX_OBJECT_ABORTED</literal></para></entry>
1497
1498 <entry><para>This notification is posted when a pending
1499 receive object's transmission is aborted by the remote
1500 sender. Unless the application specifically retains the
1501 "object" handle, the indicated <link
1502 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
1503 becomes invalid and must no longer be
1504 referenced.</para></entry>
1505 </row>
1506
1507 <row>
1508 <entry><constant>NORM_RX_CMD_NEW</constant></entry>
1509
1510 <entry>This event indicates that an application-defined
1511 command has been received from a remote sender. The
1512 <type>NormEvent</type> node element indicates the
1513 <type>NormNodeHandle</type> value associated with the given
1514 sender. The <link
1515 linkend="NormNodeGetCommand"><literal>NormNodeGetCommand()</literal></link>
1516 call can be used to retrieve the received command
1517 content.</entry>
1518 </row>
1519
1520 <row>
1521 <entry nameend="c2" namest="c1"><para><emphasis
1522 role="bold">Miscellaneous
1523 Notifications:</emphasis></para></entry>
1524 </row>
1525
1526 <row>
1527 <entry><para><literal>NORM_GRTT_UPDATED</literal></para></entry>
1528
1529 <entry><para>This notification indicates that either the
1530 local sender estimate of GRTT has changed, or that a remote
1531 sender's estimate of GRTT has changed. The "sender" member
1532 of the <link
1533 linkend="NormEvent"><literal>NormEvent</literal></link> is
1534 set to <literal>NORM_NODE_INVALID</literal> if the local
1535 sender's GRTT estimate has changed or to the <link
1536 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
1537 of the remote sender that has updated its estimate of
1538 GRTT.</para></entry>
1539 </row>
1540
1541 <row>
1542 <entry><para><literal>NORM_EVENT_INVALID</literal></para></entry>
1543
1544 <entry><para>This <link
1545 linkend="NormEventType"><literal>NormEventType</literal></link>
1546 indicates an invalid or "null" notification which should be
1547 ignored.</para></entry>
1548 </row>
1549 </tbody>
1550 </tgroup>
1551 </informaltable>
1552 </sect4>
1553
1554 <sect4>
1555 <title>Return Values</title>
1556
1557 <para>This function generally blocks the thread of application
1558 execution until a <link
1559 linkend="NormEvent"><literal>NormEvent</literal></link> is available
1560 and returns <constant>true</constant> when a <link
1561 linkend="NormEvent"><literal>NormEvent</literal></link> is
1562 available. However, there are some exceptional cases when the
1563 function may immediately return even when no event is pending. In
1564 these cases, the return value is <constant>false</constant>
1565 indicating the <link
1566 linkend="NormEvent"><literal>NormEvent</literal></link> should be
1567 ignored.</para>
1568
1569 <para><emphasis>Win32 Note: A future version of this API will
1570 provide an option to have a user-defined Window message posted when
1571 a NORM API event is pending. (Also some event filtering calls may be
1572 provided (e.g. avoid the potentially numerous
1573 <literal>NORM_RX_OBJECT_UPDATED</literal> events if not needed by
1574 the application)).</emphasis></para>
1575 </sect4>
1576 </sect3>
1577
1578 <sect3 id="NormGetDescriptor">
1579 <title>NormGetDescriptor()</title>
1580
1581 <sect4>
1582 <title>Synopsis</title>
1583
1584 <programlisting>#include &lt;normApi.h&gt;
1585
1586 <link linkend="NormDescriptor"><literal>NormDescriptor</literal></link> <link
1587 linkend="NormGetDescriptor"><literal>NormGetDescriptor</literal></link>(<link
1588 linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link> instance);</programlisting>
1589 </sect4>
1590
1591 <sect4>
1592 <title>Description</title>
1593
1594 <para>This function is used to retrieve a <link
1595 linkend="NormDescriptor"><literal>NormDescriptor</literal></link>
1596 (Unix <type>int</type> file descriptor or Win32 <type>HANDLE</type>)
1597 suitable for asynchronous I/O notification to avoid blocking calls
1598 to <link
1599 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>.
1600 A <link
1601 linkend="NormDescriptor"><literal>NormDescriptor</literal></link> is
1602 available for each protocol engine instance created using <link
1603 linkend="NormCreateInstance">NormCreateInstance()</link>. The
1604 descriptor returned is suitable for use as an input (or "read")
1605 descriptor which is signaled when a NORM protocol event is ready for
1606 retrieval via <link
1607 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>.
1608 Hence, a call to <link
1609 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
1610 will not block when the descriptor has been signaled. The Unix
1611 <function>select()</function> or Win32
1612 <function>WaitForMultipleObjects()</function> system calls can be
1613 used to detect when the <link
1614 linkend="NormDescriptor"><literal>NormDescriptor</literal></link> is
1615 signaled. Note that for Unix <function>select()</function> call
1616 usage, the NORM descriptor should be treated as a "read"
1617 descriptor.</para>
1618 </sect4>
1619
1620 <sect4>
1621 <title>Return Values</title>
1622
1623 <para>A <link
1624 linkend="NormDescriptor"><type>NormDescriptor</type></link> value is
1625 returned which is valid until a call to <link
1626 linkend="NormDestroyInstance"><literal>NormDestroyInstance()</literal></link>
1627 is made. Upon error, a value of
1628 <literal>NORM_DESCRIPTOR_INVALID</literal> is returned.</para>
1629 </sect4>
1630 </sect3>
1631 </sect2>
1632
1633 <sect2>
1634 <title>Session Creation and Control Functions</title>
1635
1636 <para>Whether participating in a NORM protocol session as a sender,
1637 receiver, or both, there are some common API calls used to instantiate a
1638 <emphasis>NormSession</emphasis> and set some common session parameters.
1639 Functions are provided to control network socket and multicast
1640 parameters. Additionally, a "user data" value may be associated with a
1641 <link
1642 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>
1643 for programming convenience when dealing with multiple sessions.</para>
1644
1645 <sect3 id="NormCreateSession">
1646 <title>NormCreateSession()</title>
1647
1648 <sect4>
1649 <title>Synopsis</title>
1650
1651 <programlisting>#include &lt;normApi.h<link
1652 linkend="NormSessionHandle"><literal>
1653 NormSessionHandle</literal></link> <link linkend="NormCreateSession"><literal>NormCreateSession</literal></link>(<link
1654 linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link> instance,
1655 const char* address,
1656 unsigned short port,
1657 <link linkend="NormNodeId"><literal>NormNodeId</literal></link> localId);</programlisting>
1658 </sect4>
1659
1660 <sect4>
1661 <title>Description</title>
1662
1663 <para>This function creates a NORM protocol session
1664 (<emphasis>NormSession</emphasis>) using the
1665 <parameter>address</parameter> (multicast or unicast) and
1666 <parameter>port</parameter> parameters provided. While session state
1667 is allocated and initialized, active session participation does not
1668 begin until a call is made to <link
1669 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
1670 and/or <link
1671 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
1672 to join the specified multicast group (if applicable) and start
1673 protocol operation. The following parameters are required in this
1674 function call:</para>
1675
1676 <informaltable frame="all">
1677 <tgroup cols="2">
1678 <colspec colnum="1" colwidth="1*"/>
1679
1680 <colspec colnum="2" colwidth="5*"/>
1681
1682 <tbody>
1683 <row>
1684 <entry><para><literal>instance</literal></para></entry>
1685
1686 <entry><para>This must be a valid <link
1687 linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link>
1688 previously obtained with a call to <link
1689 linkend="NormCreateInstance"><literal>NormCreateInstance()</literal></link>.</para></entry>
1690 </row>
1691
1692 <row>
1693 <entry><para><literal>address</literal></para></entry>
1694
1695 <entry><para>This points to a string containing an IP
1696 address (e.g. dotted decimal IPv4 address (or IPv6 address)
1697 or name resolvable to a valid IP address. The specified
1698 address (along with the port number) determines the
1699 destination of NORM messages sent. For multicast sessions,
1700 NORM senders and receivers must use a common multicast
1701 address and port number. For unicast sessions, the sender
1702 and receiver must use a common port number, but specify the
1703 other node's IP address as the session address (Although
1704 note that receiver-only unicast nodes who are providing
1705 unicast feedback to senders will not generate any messages
1706 to the session IP address and the address parameter value is
1707 thus inconsequential for this special case).</para></entry>
1708 </row>
1709
1710 <row>
1711 <entry><para><literal>port</literal></para></entry>
1712
1713 <entry><para>This must be a valid, unused port number
1714 corresponding to the desired NORM session address. See the
1715 address parameter description for more
1716 details.</para></entry>
1717 </row>
1718
1719 <row>
1720 <entry><para><literal>localId</literal></para></entry>
1721
1722 <entry><para>The <parameter>localId</parameter> parameter
1723 specifies the <link
1724 linkend="NormNodeId"><literal>NormNodeId</literal></link>
1725 that should be used to identify the application's presence
1726 in the <emphasis>NormSession</emphasis>. All participant's
1727 in a <emphasis>NormSession</emphasis> should use unique
1728 <parameter>localId</parameter> values. The application may
1729 specify a value of <literal>NORM_NODE_ANY</literal> or
1730 <literal>NORM_NODE_ANY</literal> for the
1731 <parameter>localId</parameter> parameter. In this case, the
1732 NORM implementation will attempt to pick an identifier based
1733 on the host computer's "default" IP address (based on the
1734 computer's default host name). Note there is a chance that
1735 this approach may not provide unique node identifiers in
1736 some situations and the NORM protocol does not currently
1737 provide a mechanism to detect or resolve <link
1738 linkend="NormNodeId"><literal>NormNodeId</literal></link>
1739 collisions. Thus, the application should explicitly specify
1740 the <parameter>localId</parameter> unless there is a high
1741 degree of confidence that the default IP address will
1742 provide a unique identifier.</para></entry>
1743 </row>
1744 </tbody>
1745 </tgroup>
1746 </informaltable>
1747 </sect4>
1748
1749 <sect4>
1750 <title>Return Values</title>
1751
1752 <para>The returned <link
1753 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>
1754 value is valid until a call to <link
1755 linkend="NormDestroySession"><literal>NormDestroySession()</literal></link>
1756 is made. A value of <literal>NORM_SESSION_INVALID</literal> is
1757 returned upon error.</para>
1758 </sect4>
1759 </sect3>
1760
1761 <sect3 id="NormDestroySession">
1762 <title>NormDestroySession()</title>
1763
1764 <sect4>
1765 <title>Synopsis</title>
1766
1767 <programlisting>#include &lt;normApi.h&gt;
1768
1769 void <link linkend="NormDestroySession"><literal>NormDestroySession</literal></link>(<link
1770 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle);</programlisting>
1771 </sect4>
1772
1773 <sect4>
1774 <title>Description</title>
1775
1776 <para>This function immediately terminates the application's
1777 participation in the <emphasis>NormSession</emphasis> identified by
1778 the <parameter>sessionHandle</parameter> parameter and frees any
1779 resources used by that session. An exception to this is that the
1780 application is responsible for releasing any explicitly retained
1781 <link
1782 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
1783 values (See <link
1784 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
1785 and <link
1786 linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>).</para>
1787 </sect4>
1788
1789 <sect4>
1790 <title>Return Values</title>
1791
1792 <para>This function has no returned values.</para>
1793 </sect4>
1794 </sect3>
1795
1796 <sect3 id="NormSetUserData">
1797 <title>NormSetUserData()</title>
1798
1799 <sect4>
1800 <title>Synopsis</title>
1801
1802 <programlisting>#include &lt;normApi.h&gt;
1803
1804 void <link linkend="NormSetUserData"><literal>NormSetUserData</literal></link>(<link
1805 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
1806 const void* userData);</programlisting>
1807 </sect4>
1808
1809 <sect4>
1810 <title>Description</title>
1811
1812 <para>This function allows the application to attach a value to the
1813 previously-created <emphasis>NormSession</emphasis> instance
1814 specified by the <parameter>sessionHandle</parameter> parameter.
1815 This value is not used or interpreted by NORM, but is available to
1816 the application for use at the programmer's discretion. The set
1817 <parameter>userData</parameter> value can be later retrieved using
1818 the <link
1819 linkend="NormGetUserData"><literal>NormGetUserData()</literal></link>
1820 function call.</para>
1821 </sect4>
1822
1823 <sect4>
1824 <title>Return Values</title>
1825
1826 <para>This function has no returned values.</para>
1827 </sect4>
1828 </sect3>
1829
1830 <sect3 id="NormGetUserData">
1831 <title>NormGetUserData()</title>
1832
1833 <sect4>
1834 <title>Synopsis</title>
1835
1836 <programlisting>#include &lt;normApi.h&gt;
1837
1838 const void* <link linkend="NormGetUserData"><literal>NormGetUserData</literal></link>(<link
1839 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle);</programlisting>
1840 </sect4>
1841
1842 <sect4>
1843 <title>Description</title>
1844
1845 <para>This function retrieves the "user data" value set for the
1846 specified <parameter>sessionHandle</parameter> with a prior call to
1847 <link
1848 linkend="NormSetUserData"><literal>NormSetUserData()</literal></link>.</para>
1849 </sect4>
1850
1851 <sect4>
1852 <title>Return Values</title>
1853
1854 <para>This function returns the user data value set for the
1855 specified session. If no user data value has been previously set, a
1856 NULL (i.e., <literal>(<type>const void*</type>)0)</literal> value is
1857 returned.</para>
1858 </sect4>
1859 </sect3>
1860
1861 <sect3 id="NormGetLocalNodeId">
1862 <title>NormGetLocalNodeId()</title>
1863
1864 <sect4>
1865 <title>Synopsis</title>
1866
1867 <programlisting>#include &lt;normApi.h&gt;
1868
1869 <link linkend="NormNodeId"><literal>NormNodeId</literal></link> <link
1870 linkend="NormGetLocalNodeId"><literal>NormGetLocalNodeId</literal></link>(<link
1871 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle);</programlisting>
1872 </sect4>
1873
1874 <sect4>
1875 <title>Description</title>
1876
1877 <para>This function retrieves the <link
1878 linkend="NormNodeId"><literal>NormNodeId</literal></link> value used
1879 for the application's participation in the
1880 <emphasis>NormSession</emphasis> identified by the
1881 <parameter>sessionHandle</parameter> parameter. The value may have
1882 been explicitly set during the <link
1883 linkend="NormCreateSession"><literal>NormCreateSession()</literal></link>
1884 call or may have been automatically derived using the host
1885 computer's "default" IP network address.</para>
1886 </sect4>
1887
1888 <sect4>
1889 <title>Return Valuess</title>
1890
1891 <para>The returned value indicates the <emphasis>NormNode</emphasis>
1892 identifier used by the NORM protocol engine for the local
1893 application's participation in the specified
1894 <emphasis>NormSession</emphasis>.</para>
1895 </sect4>
1896 </sect3>
1897
1898 <sect3 id="NormSetTxPort">
1899 <title>NormSetTxPort()</title>
1900
1901 <sect4>
1902 <title>Synopsis</title>
1903
1904 <programlisting>#include &lt;normApi.h&gt;
1905
1906 bool <link linkend="NormSetTxPort"><literal>NormSetTxPort</literal></link>(<link
1907 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
1908 unsigned short txPort,
1909 bool enableReuse = false,
1910 const char* txBindAddress = (const char*)0);</programlisting>
1911 </sect4>
1912
1913 <sect4>
1914 <title>Description</title>
1915
1916 <para>This function is used to force NORM to use a specific port
1917 number for UDP packets sent for the specified
1918 <parameter>sessionHandle</parameter>. Additionally, it can
1919 optionally enable reuse of the specified port number and/or specify
1920 a specific source address binding that is used for packet
1921 transmission. By default, NORM uses separate port numbers for packet
1922 transmission and session packet reception (the receive port is
1923 specified as part of the <link
1924 linkend="NormCreateSession"><literal>NormCreateSession()</literal></link>
1925 call), allowing the operating system to pick a freely available port
1926 for transmission. This call allows the application to pick a
1927 specific port number for transmission, and furthermore allows the
1928 application to even specify the same port number for transmission as
1929 is used for reception. However, the use of separate transmit/receive
1930 ports allows NORM to discriminate when unicast feedback is occurring
1931 and thus it is not generally recommended that the transmit port be
1932 set to the same value as the session receive port.</para>
1933
1934 <para>The <parameter>enableReuse</parameter> parameter, when set to
1935 <constant>true</constant>, allows that the specified port may be
1936 reused for multiple sessions, but care must be taken when enabling
1937 this option. The <parameter>txBindAddress</parameter> parameter
1938 allows specification of a specific source address binding for packet
1939 transmission. The specified address MUST be a valid unicast IP
1940 address assigned and configured for the host system. Additionally,
1941 the address specified must be compatible with multicast routing
1942 and/or the interfaces specified in any calls to <link
1943 linkend="NormSetMulticastInterface"><literal>NormSetMulticastInterface()</literal></link>
1944 for the given session when IP multicast is used.</para>
1945
1946 <para>When the <parameter>txPort</parameter> is set equal to the
1947 session port number and a <parameter>txBindAddress</parameter> is
1948 not specified or set equal to the session address, a single socket
1949 is used for both transmission and reception. If the same port number
1950 is desired for both packet transmission and reception,
1951 <emphasis>and</emphasis> a specific source address binding is set,
1952 then the <parameter>enableReuse</parameter> parameter MUST be (and
1953 is automatically) set to <constant>true</constant> for successful
1954 operation. In this case, the receive socket is bound to session
1955 address if it is multicast and the transmit socket is bound to the
1956 specified <parameter>txAddress</parameter> although both are bound
1957 to the same port number.</para>
1958
1959 <para>Note this call MUST be made <emphasis>before</emphasis> any
1960 calls to <link
1961 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
1962 or <link
1963 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
1964 for the given session to work as described.</para>
1965 </sect4>
1966
1967 <sect4>
1968 <title>Return Values</title>
1969
1970 <para>This function returns <constant>true</constant> upon success
1971 and <constant>false</constant> upon failure. Failure will occur if a
1972 <parameter>txBindAddress</parameter> is provided that does not
1973 correspond to a valid, configured IP address for the local host
1974 system.</para>
1975 </sect4>
1976 </sect3>
1977
1978 <sect3 id="NormSetTxOnly">
1979 <title>NormSetTxOnly()</title>
1980
1981 <sect4>
1982 <title>Synopsis</title>
1983
1984 <programlisting>#include &lt;normApi.h&gt;
1985
1986 void <link linkend="NormStopSender"><literal>NormSetTxOnly</literal></link>(<link
1987 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
1988 bool txOnly,
1989 bool connectToSessionAddress = false);</programlisting>
1990 </sect4>
1991
1992 <sect4>
1993 <title>Description</title>
1994
1995 <para>This function limits the <emphasis>NormSession</emphasis> to
1996 perform NORM sender functions only. It also limits the underlying
1997 NORM UDP socket usage to open only a single transmit socket
1998 (tx_socket) and does <emphasis>not</emphasis> open or bind a receive
1999 socket for the given session address or port number. Thus, if this
2000 property is set, any NORM receivers MUST enable unicast feedback via
2001 a call to the <link
2002 linkend="NormSetDefaultUnicastNack">NormSetDefaultUnicastNack()</link>
2003 or appropriate <link
2004 linkend="NormNodeSetUnicastNack">NormNodeSetUnicastNack()</link>
2005 function in order for their feedback messages (NACKs and ACKs) to be
2006 received by this sender. The purpose of this function is to allow
2007 NORM sender sessions to be created as separate process from a
2008 corresponding NORM receiver session for the same session address and
2009 port number. By default (when this call is not made), a
2010 <emphasis>NormSession</emphasis>, even when acting as only a sender
2011 (see<link linkend="NormStartSender"> NormStartSender()</link>) opens
2012 two separate UDP sockets including a "receive" socket bound to the
2013 session port number and a "transmit" socket used for message
2014 transmission and reception of unicast feedback messages when
2015 receivers are so configured.</para>
2016
2017 <para>The optional <parameter>connectToSessionAddress</parameter>
2018 parameter, when set to <constant>true</constant>, causes the
2019 underlying NORM code to "<function>connect()</function>" the UDP
2020 socket to the session (remote receiver) address and port number. If
2021 the corresponding NORM remote receiver instance uses <link
2022 linkend="NormSetTxPort">NormSetTxPort()</link> to set its transmit
2023 port to the same as the session port number, the result is a unique
2024 binding between this "tx only" sender instance and the remote NORM
2025 receiver instance. With proper use of <link
2026 linkend="NormSetRxPortReuse">NormSetRxPortReuse()</link>, this
2027 allows multiple senders to be properly associated (i.e., binded with
2028 respect to UDP socket packet demultiplexing) with multiple receivers
2029 on a single host (all using the same session port number). Note the
2030 NORM receiver MUST also use the <link
2031 linkend="NormSetDefaultUnicastNack">NormSetDefaultUnicastNack()</link>
2032 call so that its feedback messages are directed to the "tx only"
2033 sender address/port. The motivation for this API call is to allow
2034 systems have NORM sender and receiver instances in separate
2035 processes supporting a set (e.g. a mesh) of unicast connections to
2036 other hosts. The only constraint is that the senders uses a "tx
2037 port" number that is different from the "rx port" number. This
2038 enables firewall configurations that only open a pair of UDP ports
2039 and allow for connection among an arbitrary number of hosts. This
2040 option is really only relevant for unicast NORM sessions.</para>
2041 </sect4>
2042
2043 <sect4>
2044 <title>Return Values</title>
2045
2046 <para>This function has no return values.</para>
2047 </sect4>
2048 </sect3>
2049
2050 <sect3 id="NormSetRxPortReuse">
2051 <title>NormSetRxPortReuse()</title>
2052
2053 <sect4>
2054 <title>Synopsis</title>
2055
2056 <programlisting>#include &lt;normApi.h&gt;
2057
2058 void <link linkend="NormSetRxPortReuse"><literal>NormSetRxPortReuse</literal></link>(<link
2059 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session,
2060 bool enableReuse,
2061 const char* rxBindAddress = (const char*)0,
2062 const char* senderAddress = (const char*)0,
2063 UINT16 senderPort = 0);</programlisting>
2064 </sect4>
2065
2066 <sect4>
2067 <title>Description</title>
2068
2069 <para>This function allows the user to control the port reuse and
2070 binding behavior for the receive socket used for the given NORM
2071 <parameter>sessionHandle</parameter>. When the
2072 <parameter>enablReuse</parameter> parameter is set to
2073 <constant>true</constant>, reuse of the
2074 <emphasis>NormSession</emphasis> port number by multiple NORM
2075 instances or sessions is enabled.</para>
2076
2077 <para>If the optional <parameter>rxBindAddress</parameter> is
2078 supplied (an IP address or host name in string form), the socket
2079 will bind() to the given address when it is opened in a call to
2080 NormStartReceiver() or NormStartSender(). The
2081 <parameter>rxBindAddress</parameter> MUST be the session multicast
2082 address (if it is a multicast session) or a valid local unicast
2083 address in the case of NORM unicast operation. This binding limits
2084 the socket to receive only packets destined for the specified
2085 <parameter>rxBindAddress</parameter>. This allows multiple NORM
2086 sessions to reuse the same port number, but use different multicast
2087 addresses (or allow for multiple NORM sessions for multiple local
2088 unicast addresses).</para>
2089
2090 <para>The optional <parameter>senderAddress</parameter> and
2091 <parameter>senderPort</parameter> parameters can be used to
2092 connect() the underlying NORM receive socket to specific
2093 address/port. This limits the socket to receiving only packets from
2094 the specified
2095 <parameter>senderAddress</parameter>/<parameter>senderPort</parameter>.
2096 This, with receive port reuse enabled, allows for multiple NORM
2097 receiver instances to be listening to different NORM senders and
2098 have proper UDP socket demultiplexing occur. Note that it is also
2099 possible to have single NORM receiver receive transmissions from
2100 multiple senders, but in some cases it may be desirable for separate
2101 NORM processes or threads to be used to handle reception from
2102 separate senders. Thus, this socket binding option is
2103 provided.</para>
2104
2105 <para>When this call is not made in any form, the default socket
2106 binding to IP address INADDR_ANY (equivalent to when this call is
2107 made and <parameter>rxBindAddress</parameter> is set to
2108 <constant>NULL</constant>) allows the
2109 <emphasis>NormSession</emphasis> receive socket to receive any
2110 multicast or unicast transmissions to the session port number
2111 provided in the call to <link
2112 linkend="NormCreateSession"><literal>NormCreateSession()</literal></link>.
2113 This allows a NORM receiver to receive from senders sending to a
2114 multicast session address or the receiver's unicast address. As
2115 mentioned, enabling port reuse and binding the session destination
2116 address allows multiple NORM sessions on the same port number, but
2117 participating in different multicast groups.</para>
2118
2119 <para>Note this call MUST be made <emphasis>before</emphasis> any
2120 calls to <link
2121 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
2122 or <link
2123 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
2124 for the given <parameter>sessionHandle</parameter> to
2125 succeed.</para>
2126
2127 <para>This call could also be used in conjunction with <link
2128 linkend="NormSetMulticastInterface"><literal>NormSetMulticastInterface()</literal></link>
2129 so that multiple <emphasis>NormSessions</emphasis>, using the same
2130 port and multicast address, could separately cover multiple network
2131 interfaces (and some sort of application-layer bridging of reliable
2132 multicast could be realized if desired).</para>
2133 </sect4>
2134
2135 <sect4>
2136 <title>Return Values</title>
2137
2138 <para>This function has no return values.</para>
2139 </sect4>
2140 </sect3>
2141
2142 <sect3 id="NormSetMulticastInterface">
2143 <title>NormSetMulticastInterface()</title>
2144
2145 <sect4>
2146 <title>Synopsis</title>
2147
2148 <programlisting>#include &lt;normApi.h&gt;
2149
2150 bool <link linkend="NormSetMulticastInterface"><literal>NormSetMulticastInterface</literal></link>(<link
2151 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session,
2152 const char* interfaceName);</programlisting>
2153 </sect4>
2154
2155 <sect4>
2156 <title>Description</title>
2157
2158 <para>This function specifies which host network interface is used
2159 for IP Multicast transmissions and group membership. This should be
2160 called <emphasis>before</emphasis> any call to <link
2161 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
2162 or <link
2163 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
2164 is made so that the IP multicast group is joined on the proper host
2165 interface. However, if a call to <link
2166 linkend="NormSetMulticastInterface"><literal>NormSetMulticastInterface()</literal></link>
2167 is made after either of these function calls, the call will not
2168 affect the group membership interface, but only dictate that a
2169 possibly different network interface is used for transmitted NORM
2170 messages. Thus, the code:</para>
2171
2172 <para><programlisting><link linkend="NormSetMulticastInterface"><literal>NormSetMulticastInterface</literal></link>(session, "interface1");
2173 <link linkend="NormStartReceiver"><literal>NormStartReceiver</literal></link>(session, ...);<link
2174 linkend="NormSetMulticastInterface"><literal>
2175 NormSetMulticastInterface</literal></link>(session, "interface2");</programlisting></para>
2176
2177 <para>will result in NORM group membership (i.e. multicast
2178 reception) being managed on "<literal>interface1</literal>" while
2179 NORM multicast transmissions are made via
2180 "<literal>interface2</literal>".</para>
2181 </sect4>
2182
2183 <sect4>
2184 <title>Return Values</title>
2185
2186 <para>A return value of <constant>true</constant> indicates success
2187 while a return value of <constant>false</constant> indicates that
2188 the specified interface was invalid. This function will always
2189 return <constant>true</constant> if made before calls to <link
2190 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
2191 or <link
2192 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>.
2193 However, those calls may fail if an invalid interface was specified
2194 with the call described here.</para>
2195 </sect4>
2196 </sect3>
2197
2198 <sect3 id="NormSetMulticastInterface">
2199 <title>NormSetSSM()</title>
2200
2201 <sect4>
2202 <title>Synopsis</title>
2203
2204 <programlisting>#include &lt;normApi.h&gt;
2205
2206 bool <link linkend="NormSetMulticastInterface"><literal>NormSetSSM</literal></link>(<link
2207 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session,
2208 const char* sourceAddress);</programlisting>
2209 </sect4>
2210
2211 <sect4>
2212 <title>Description</title>
2213
2214 <para>This function sets the source address for Source-Specific
2215 Multicast (SSM) operation. This should be called
2216 <emphasis>before</emphasis> any call to <link
2217 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
2218 or <link
2219 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
2220 is made so that the proper group join is done. The receiver
2221 application MUST also use the <link
2222 linkend="NormSetDefaultUnicastNack"><literal>NormSetDefaultUnicastNack()</literal></link>
2223 call so that feedback traffic is directed back to appropriate
2224 sender.</para>
2225 </sect4>
2226
2227 <sect4>
2228 <title>Return Values</title>
2229
2230 <para>A return value of <constant>true</constant> indicates success
2231 while a return value of <constant>false</constant> indicates that
2232 the specified source address was invalid. Note that if a valid IP
2233 address is specified but is improper for SSM (e.g., an IP multicast
2234 address) the later calls to <link
2235 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
2236 or <link
2237 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
2238 may fail.</para>
2239 </sect4>
2240 </sect3>
2241
2242 <sect3 id="NormSetTTL">
2243 <title>NormSetTTL()</title>
2244
2245 <sect4>
2246 <title>Synopsis</title>
2247
2248 <programlisting>#include &lt;normApi.h&gt;
2249
2250 bool <link linkend="NormSetTTL"><literal>NormSetTTL</literal></link>(<link
2251 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session,
2252 unsigned char ttl);</programlisting>
2253 </sect4>
2254
2255 <sect4>
2256 <title>Description</title>
2257
2258 <para>This function specifies the time-to-live
2259 (<parameter>ttl</parameter>) for IP Multicast datagrams generated by
2260 NORM for the specified <parameter>sessionHandle</parameter>. The IP
2261 TTL field limits the number of router "hops" that a generated
2262 multicast packet may traverse before being dropped. For example, if
2263 TTL is equal to one, the transmissions will be limited to the local
2264 area network (LAN) of the host computers network interface. Larger
2265 TTL values should be specified to span large networks. Also note
2266 that some multicast router configurations use artificial "TTL
2267 threshold" values to constrain some multicast traffic to an
2268 administrative boundary. In these cases, the NORM TTL setting must
2269 also exceed the router "TTL threshold" in order for the NORM traffic
2270 to be allowed to exit the administrative area.</para>
2271 </sect4>
2272
2273 <sect4>
2274 <title>Return Values</title>
2275
2276 <para>A return value of <constant>true</constant> indicates success
2277 while a return value of <constant>false</constant> indicates that
2278 the specified <parameter>ttl</parameter> could not be set. This
2279 function will always return <constant>true</constant> if made before
2280 calls to <link
2281 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
2282 or <link
2283 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>.
2284 However, those calls may fail if the desired
2285 <parameter>ttl</parameter> value cannot be set.</para>
2286 </sect4>
2287 </sect3>
2288
2289 <sect3 id="NormSetTOS">
2290 <title>NormSetTOS()</title>
2291
2292 <sect4>
2293 <title>Synopsis</title>
2294
2295 <programlisting>#include &lt;normApi.h&gt;
2296
2297 bool <link linkend="NormSetTOS"><literal>NormSetTOS</literal></link>(<link
2298 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
2299 unsigned char tos);</programlisting>
2300 </sect4>
2301
2302 <sect4>
2303 <title>Description</title>
2304
2305 <para>This function specifies the type-of-service
2306 (<parameter>tos</parameter>) field value used in IP Multicast
2307 datagrams generated by NORM for the specified
2308 <parameter>sessionHandle</parameter>. The IP TOS field value can be
2309 used as an indicator that a "flow" of packets may merit special
2310 Quality-of-Service (QoS) treatment by network devices. Users should
2311 refer to applicable QoS information for their network to determine
2312 the expected interpretation and treatment (if any) of packets with
2313 explicit TOS marking.</para>
2314 </sect4>
2315
2316 <sect4>
2317 <title>Return Values</title>
2318
2319 <para>A return value of <constant>true</constant> indicates success
2320 while a return value of <constant>false</constant> indicates that
2321 the specified <parameter>tos</parameter> could not be set. This
2322 function will always return <constant>true</constant> if made before
2323 calls to <link
2324 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
2325 or <link
2326 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>.
2327 However, those calls may fail if the desired
2328 <parameter>tos</parameter> value cannot be set.</para>
2329 </sect4>
2330 </sect3>
2331
2332 <sect3 id="NormSetLoopback">
2333 <title>NormSetLoopback()</title>
2334
2335 <sect4>
2336 <title>Synopsis</title>
2337
2338 <programlisting>#include &lt;normApi.h&gt;
2339
2340 void <link linkend="NormSetLoopback"><literal>NormSetLoopback</literal></link>(<link
2341 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
2342 bool loopbackEnable);</programlisting>
2343 </sect4>
2344
2345 <sect4>
2346 <title>Description</title>
2347
2348 <para>This function enables or disables loopback operation for the
2349 indicated NORM <parameter>sessionHandle</parameter>. If
2350 <parameter>loopbackEnable</parameter> is set to
2351 <constant>true</constant>, loopback operation is enabled which
2352 allows the application to receive its own message traffic. Thus, an
2353 application which is both actively receiving and sending may receive
2354 its own transmissions. Note it is expected that this option would be
2355 principally be used for test purposes and that applications would
2356 generally not need to transfer data to themselves. If
2357 <parameter>loopbackEnable</parameter> is false, the application is
2358 prevented from receiving its own NORM message transmissions. By
2359 default, loopback operation is disabled when a
2360 <emphasis>NormSession</emphasis> is created.</para>
2361 </sect4>
2362
2363 <sect4>
2364 <title>Return Values</title>
2365
2366 <para>This function has no return values.</para>
2367 </sect4>
2368 </sect3>
2369
2370 <sect3 id="NormSetFragmentation">
2371 <title>NormSetFragmentation()</title>
2372
2373 <sect4>
2374 <title>Synopsis</title>
2375
2376 <programlisting>#include &lt;normApi.h&gt;
2377
2378 bool <link linkend="NormSetFragmentation"><literal>NormSetFragmentation</literal></link>(<link
2379 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
2380 bool fragmentation);</programlisting>
2381 </sect4>
2382
2383 <sect4>
2384 <title>Description</title>
2385
2386 <para>This function sets an underlying socket option that enables or
2387 disables IP datagram fragmentation by network intermediate systems
2388 according to whether the <parameter>fragmentation</parameter>
2389 parameter is set to a value of <constant>true</constant> or
2390 <constant>false</constant>, respectively. If set to
2391 <constant>true</constant> to enable fragmentation, the DF (don't
2392 fragment) bit of the headers of NORM UDP/IP packets sent will be
2393 cleared. Otherwise the DF bit is set and packets will not be
2394 fragmented by network devices if they exceed a link Maximum
2395 Transmission Unit (MTU) and will instead be dropped. For IP
2396 Multicast destinations, some operating systems may always set the DF
2397 bit of transmitted packets, regardless of the setting here and the
2398 underlying socket option status. Typically, the DF bit is set (i.e.,
2399 fragmentation disabled) by default on most operating systems.</para>
2400
2401 <para>This call is not currently functional on the Mac OSX system
2402 that does not support the needed
2403 <constant>IP_MTU_DISCOVER</constant> or
2404 <constant>IP_DONTFRAG</constant> socket options.</para>
2405 </sect4>
2406
2407 <sect4>
2408 <title>Return Values</title>
2409
2410 <para>This function returns <constant>true</constant> upon success
2411 and <constant>false</constant> upon failure.</para>
2412 </sect4>
2413 </sect3>
2414 </sect2>
2415
2416 <sect2>
2417 <title><anchor id="_NORM_Sender_Functions"/>NORM Sender
2418 Functions</title>
2419
2420 <para>The functions described in this section apply only to NORM sender
2421 operation. Applications may participate strictly as senders or as
2422 receivers, or may act as both in the context of a NORM protocol session.
2423 The NORM sender is responsible for most parameters pertaining to its
2424 transmission of data. This includes transmission rate, data segmentation
2425 sizes, FEC coding parameters, stream buffer sizes, etc.</para>
2426
2427 <sect3 id="NormStartSender">
2428 <title>NormStartSender()</title>
2429
2430 <sect4>
2431 <title>Synopsis</title>
2432
2433 <programlisting>#include &lt;normApi.h&gt;
2434
2435 bool <link linkend="NormStartSender"><literal>NormStartSender</literal></link>(<link
2436 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
2437 <link linkend="NormSessionId"><literal>NormSessionId</literal></link> instanceId,
2438 unsigned long bufferSpace,
2439 unsigned short segmentSize,
2440 unsigned char blockSize,
2441 unsigned char numParity);</programlisting>
2442 </sect4>
2443
2444 <sect4>
2445 <title>Description</title>
2446
2447 <para>The application's participation as a sender within a specified
2448 <emphasis>NormSession</emphasis> begins when this function is
2449 called. This includes protocol activity such as congestion control
2450 and/or group round-trip timing (GRTT) feedback collection and
2451 application API activity such as posting of sender-related <link
2452 linkend="NormEvent"><literal>NormEvent</literal></link>
2453 notifications. The parameters required for this function call
2454 include:</para>
2455
2456 <informaltable frame="all">
2457 <tgroup cols="2">
2458 <colspec colnum="1" colwidth="1*"/>
2459
2460 <colspec colnum="2" colwidth="5*"/>
2461
2462 <tbody>
2463 <row>
2464 <entry><para><parameter>sessionHandle</parameter></para></entry>
2465
2466 <entry><para>This must be a valid <link
2467 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>
2468 previously obtained with a call to <link
2469 linkend="NormCreateSession"><literal>NormCreateSession()</literal></link>.</para></entry>
2470 </row>
2471
2472 <row>
2473 <entry><para><parameter>instanceId</parameter></para></entry>
2474
2475 <entry><para>Application-defined value used as the
2476 <constant>instance_id</constant> field of NORM sender
2477 messages for the application's participation within a
2478 session. Receivers can detect when a sender has terminated
2479 and restarted if the application uses different
2480 <parameter>instanceId</parameter> values when initiating
2481 sender operation. For example, a robust application could
2482 cache previous <parameter>instanceId</parameter> values in
2483 non-volatile storage and gracefully recover (without
2484 confusing receivers) from a total system shutdown and reboot
2485 by using a new <parameter>instanceId</parameter> value upon
2486 restart.</para></entry>
2487 </row>
2488
2489 <row>
2490 <entry><para><parameter>bufferSpace</parameter></para></entry>
2491
2492 <entry><para>This specifies the maximum memory space (in
2493 bytes) the NORM protocol engine is allowed to use to buffer
2494 any sender calculated FEC segments and repair state for the
2495 session. The optimum <parameter>bufferSpace</parameter>
2496 value is function of the network topology bandwidth*delay
2497 product and packet loss characteristics. If the
2498 <parameter>bufferSpace</parameter> limit is too small, the
2499 protocol may operate less efficiently as the sender is
2500 required to possibly recalculate FEC parity segments and/or
2501 provide less efficient repair transmission strategies
2502 (resort to explicit repair) when state is dropped due to
2503 constrained buffering resources. However, note the protocol
2504 will still provide reliable transfer. A large
2505 <parameter>bufferSpace</parameter> allocation is safer at
2506 the expense of possibly committing more memory
2507 resources.</para></entry>
2508 </row>
2509
2510 <row>
2511 <entry><para><parameter>segmentSize</parameter></para></entry>
2512
2513 <entry><para>This parameter sets the maximum payload size
2514 (in bytes) of NORM sender messages (not including any NORM
2515 message header fields). A sender's
2516 <parameter>segmentSize</parameter> value is also used by
2517 receivers to limit the payload content of some feedback
2518 messages (e.g. <literal>NORM_NACK</literal> message content,
2519 etc.) generated in response to that sender. Note different
2520 senders within a <emphasis>NormSession</emphasis> may use
2521 different segmentSize values. Generally, the appropriate
2522 segment size to use is dependent upon the types of networks
2523 forming the multicast topology, but applications may choose
2524 different values for other purposes. Note that application
2525 designers MUST account for the size of NORM message headers
2526 when selecting a <parameter>segmentSize</parameter>. For
2527 example, the <literal>NORM_DATA</literal> message header for
2528 a <literal>NORM_OBJECT_STREAM</literal> with full header
2529 extensions is 48 bytes in length. In this case, the UDP
2530 payload size of these messages generated by NORM would be up
2531 to (48 + <parameter>segmentSize</parameter>)
2532 bytes.</para></entry>
2533 </row>
2534
2535 <row>
2536 <entry><para><parameter>blockSize</parameter></para></entry>
2537
2538 <entry><para>This parameter sets the number of source symbol
2539 segments (packets) per coding block, for the systematic
2540 Reed-Solomon FEC code used in the current NORM
2541 implementation. For traditional systematic block code
2542 "(n,k)" nomenclature, the <parameter>blockSize</parameter>
2543 value corresponds to "k". NORM logically segments transport
2544 object data content into coding blocks and the
2545 <parameter>blockSize</parameter> parameter determines the
2546 number of source symbol segments (packets) comprising a
2547 single coding block where each source symbol segment is up
2548 to <parameter>segmentSize</parameter> bytes in length.. A
2549 given block's parity symbol segments are calculated using
2550 the corresponding set of source symbol segments. The maximum
2551 <parameter>blockSize</parameter> allowed by the 8-bit
2552 Reed-Solomon codes in NORM is <constant>255</constant>, with
2553 the further limitation that
2554 (<parameter>blockSize</parameter> +
2555 <parameter>numParity</parameter>) &lt;=
2556 <constant>255</constant>.</para></entry>
2557 </row>
2558
2559 <row>
2560 <entry><para><parameter>numParity</parameter></para></entry>
2561
2562 <entry><para>This parameter sets the maximum number of
2563 parity symbol segments (packets) the sender is willing to
2564 calculate per FEC coding block. The parity symbol segments
2565 for a block are calculated from the corresponding
2566 <parameter>blockSize</parameter> source symbol segments. In
2567 the "<literal>(n,k)</literal>" nomenclature mention above,
2568 the <parameter>numParity</parameter> value corresponds to
2569 "<literal>n - k</literal>". A property of the Reed-Solomon
2570 FEC codes used in the current NORM implementation is that
2571 one parity segment can fill any one erasure (missing segment
2572 (packet)) for a coding block. For a given
2573 <parameter>blockSize</parameter>, the maximum numParity
2574 value is (<constant>255</constant> -
2575 <parameter>blockSize</parameter>). However, note that
2576 computational complexity increases significantly with
2577 increasing <parameter>numParity</parameter> values and
2578 applications may wish to be conservative with respect to
2579 <parameter>numParity</parameter> selection, given
2580 anticipated network packet loss conditions and group size
2581 scalability concerns. Additional FEC code options may be
2582 provided for this NORM implementation in the future with
2583 different parameters, capabilities, trade-offs, and
2584 computational requirements.</para></entry>
2585 </row>
2586 </tbody>
2587 </tgroup>
2588 </informaltable>
2589
2590 <para>These parameters are currently immutable with respect to a
2591 sender's participation within a <emphasis>NormSession</emphasis>.
2592 Sender operation must be stopped (see <link
2593 linkend="NormStopSender"><literal>NormStopSender()</literal></link>)
2594 and restarted with another call to <link
2595 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
2596 if these parameters require alteration. The API may be extended in
2597 the future to support additional flexibility here, if required. For
2598 example, the NORM protocol "<parameter>intance_id</parameter>" field
2599 may possibly be leveraged to permit a node to establish multiple
2600 virtual presences as a sender within a
2601 <emphasis>NormSession</emphasis> in the future. This would allow the
2602 sender to provide multiple concurrent streams of transport, with
2603 possibly different FEC and other parameters if appropriate within
2604 the context of a single <emphasis>NormSession</emphasis>. Again,
2605 this extended functionality is not yet supported in this
2606 implementation.</para>
2607 </sect4>
2608
2609 <sect4>
2610 <title>Return Values</title>
2611
2612 <para>A value of <constant>true</constant> is returned upon success
2613 and <constant>false</constant> upon failure. The reasons failure may
2614 occur include limited system resources or that the network sockets
2615 required for communication failed to open or properly configure.
2616 (<emphasis>TBD - Provide a <function>NormGetError</function>(<link
2617 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>
2618 <parameter>sessionHandle</parameter>) function to retrieve a more
2619 specific error indication for this and other
2620 functions.</emphasis>)</para>
2621 </sect4>
2622 </sect3>
2623
2624 <sect3 id="NormStopSender">
2625 <title>NormStopSender()</title>
2626
2627 <sect4>
2628 <title>Synopsis</title>
2629
2630 <programlisting>#include &lt;normApi.h&gt;
2631
2632 void <link linkend="NormStopSender"><literal>NormStopSender</literal></link>(<link
2633 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
2634 bool graceful = false);</programlisting>
2635 </sect4>
2636
2637 <sect4>
2638 <title>Description</title>
2639
2640 <para>This function terminates the application's participation in a
2641 <emphasis>NormSession</emphasis> as a sender. By default, the sender
2642 will immediately exit the session identified by the
2643 <parameter>sessionHandle</parameter> parameter without notifying the
2644 receiver set of its intention. However a "graceful shutdown" option,
2645 enabled by setting the <parameter>graceful</parameter> parameter to
2646 true, is provided to terminate sender operation gracefully,
2647 notifying the receiver set its pending exit with appropriate
2648 protocol messaging. A <link
2649 linkend="NormEvent"><literal>NormEvent</literal></link>,
2650 <literal>NORM_LOCAL_SENDER_CLOSED</literal>, is dispatched when the
2651 graceful shutdown process has completed.</para>
2652 </sect4>
2653
2654 <sect4>
2655 <title>Return Values</title>
2656
2657 <para>This function has no return values.</para>
2658 </sect4>
2659 </sect3>
2660
2661 <sect3 id="NormSetTxRate">
2662 <title>NormSetTxRate()</title>
2663
2664 <sect4>
2665 <title>Synopsis</title>
2666
2667 <programlisting>#include &lt;normApi.h&gt;
2668
2669 void <link linkend="NormSetTxRate"><literal>NormSetTxRate</literal></link>(<link
2670 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
2671 double rate);</programlisting>
2672 </sect4>
2673
2674 <sect4>
2675 <title>Description</title>
2676
2677 <para>This function sets the transmission
2678 <parameter>rate</parameter> (in bits per second (bps)) limit used
2679 for <emphasis>NormSender</emphasis> transmissions for the given
2680 <parameter>sessionHandle</parameter>. For fixed-rate transmission of
2681 <literal>NORM_OBJECT_FILE</literal> or
2682 <literal>NORM_OBJECT_DATA</literal>, this limit determines the data
2683 rate at which NORM protocol messages and data content are sent. For
2684 <literal>NORM_OBJECT_STREAM</literal> transmissions, this is the
2685 maximum rate allowed for transmission (i.e. if the application
2686 writes to the stream at a lower rate, a lower average NORM
2687 transmission rate will occur). Note that the application will need
2688 to consider the overhead of NORM protocol headers when determining
2689 an appropriate transmission rate for its purposes. When NORM
2690 congestion control is enabled (see <link
2691 linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>),
2692 the <parameter>rate</parameter> set here will be set, but congestion
2693 control operation, if enabled, may quickly readjust the transmission
2694 rate.</para>
2695 </sect4>
2696
2697 <sect4>
2698 <title>Return Values</title>
2699
2700 <para>This function has no return values.</para>
2701 </sect4>
2702 </sect3>
2703
2704 <sect3 id="NormGetTxRate">
2705 <title>NormGetTxRate()</title>
2706
2707 <sect4>
2708 <title>Synopsis</title>
2709
2710 <programlisting>#include &lt;normApi.h&gt;
2711
2712 double <link linkend="NormGetTxRate"><literal>NormGetTxRate</literal></link>(<link
2713 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle);</programlisting>
2714 </sect4>
2715
2716 <sect4>
2717 <title>Description</title>
2718
2719 <para>This function retrieves the current sender transmission rate
2720 in units of bits per second (bps) for the given
2721 <parameter>sessionHandle</parameter>. When NORM congestion control
2722 is enabled (see <link
2723 linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>),
2724 this reflects the current rate set (or suggested) by NORM congestion
2725 control operation. Otherwise, this returns the rate that was set
2726 with the <literal><link
2727 linkend="NormSetTxRate">NormSetTxRate()</link></literal>
2728 call.</para>
2729 </sect4>
2730
2731 <sect4>
2732 <title>Return Values</title>
2733
2734 <para>This function returns the sender transmission rate in units of
2735 bits per second (bps).</para>
2736 </sect4>
2737 </sect3>
2738
2739 <sect3 id="NormSetTxSocketBuffer">
2740 <title>NormSetTxSocketBuffer()</title>
2741
2742 <sect4>
2743 <title>Synopsis</title>
2744
2745 <programlisting>#include &lt;normApi.h&gt;
2746
2747 bool <link linkend="NormSetTxSocketBuffer"><literal>NormSetTxSocketBuffer</literal></link>(<link
2748 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
2749 unsigned int bufferSize);</programlisting>
2750 </sect4>
2751
2752 <sect4>
2753 <title>Description</title>
2754
2755 <para>This function can be used to set a non-default socket buffer
2756 size for the UDP socket used by the specified NORM
2757 <parameter>sessionHandle</parameter> for data transmission. The
2758 <parameter>bufferSize</parameter> parameter specifies the desired
2759 socket buffer size in bytes. Large transmit socket buffer sizes may
2760 be necessary to achieve high transmission rates when NORM, as a
2761 user-space process, is unable to precisely time its packet
2762 transmissions. Similarly, NORM receivers may need to set large
2763 receive socket buffer sizes to achieve successful, sustained high
2764 data rate reception (see <link
2765 linkend="NormSetRxSocketBuffer"><literal>NormSetRxSocketBuffer()</literal></link>).
2766 Typically, it is more important to set the receive socket buffer
2767 size (see <link
2768 linkend="NormSetRxSocketBuffer"><literal>NormSetRxSocketBuffer()</literal></link>)
2769 as this maintains reliability (i.e. by avoiding receive socket
2770 buffer overflow) at high data rates while setting a larger transmit
2771 socket buffer size allows higher average transmission rates to be
2772 achieved.</para>
2773 </sect4>
2774
2775 <sect4>
2776 <title>Return Values</title>
2777
2778 <para>This function returns <constant>true</constant> upon success
2779 and <constant>false</constant> upon failure. Possible failure modes
2780 include an invalid <parameter>sessionHandle</parameter> parameter, a
2781 call to <link
2782 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
2783 or <link
2784 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
2785 has not yet been made for the session, or an invalid
2786 <parameter>bufferSize</parameter> was given. Note some operating
2787 systems may require additional system configuration to use
2788 non-standard socket buffer sizes.</para>
2789 </sect4>
2790 </sect3>
2791
2792 <sect3 id="NormSetFlowControl">
2793 <title>NormSetFlowControl()</title>
2794
2795 <sect4>
2796 <title>Synopsis</title>
2797
2798 <programlisting>#include &lt;normApi.h&gt;
2799
2800 void <link linkend="NormSetFlowControl"><literal>NormSetFlowControl</literal></link>(<link
2801 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
2802 double flowControlFactor);</programlisting>
2803 </sect4>
2804
2805 <sect4>
2806 <title>Description</title>
2807
2808 <para>This function controls a scaling factor that is used for
2809 sender timer-based flow control for the the specified NORM
2810 <parameter>sessionHandle</parameter>. Timer-based flow control works
2811 by preventing the NORM sender application from enqueueing new
2812 transmit objects or stream data that would purge "old" objects or
2813 stream data when there has been recent NACK activity for those old
2814 objects or data. If the <parameter>flowControlFactor</parameter> is
2815 set to <constant>ZERO</constant>, then the flow control mechanism is
2816 effectively disabled. Larger
2817 <parameter>flowControlFactor</parameter> values enforce more robust
2818 flow control by forcing the sender to maintain state longer, but
2819 then larger transmit buffer, stream buffer, transmit cache bounds
2820 and receive cache limits (see <link
2821 linkend="NormStartSender"><literal>NormStartSender()</literal></link>,
2822 <link
2823 linkend="NormStreamOpen"><literal>NormStreamOpen()</literal></link>,
2824 <link
2825 linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>,
2826 and <link
2827 linkend="NormSetRxCacheLimit"><literal>NormSetRxCacheLimit()</literal></link>,
2828 respectively) may be needed to maintain throughput in larger
2829 &lt;delay*bandwidth, loss&gt; conditions. Effectively, a larger
2830 <parameter>flowControlFactor</parameter> can favor reliability over
2831 throughput when buffer-constrained.</para>
2832
2833 <para>The <parameter>flowControlFactor</parameter> is used to
2834 compute a delay time for when a sender buffered object (or block of
2835 stream data) may be released (i.e. purged) after transmission or
2836 applicable NACKs reception. The delay time function is:</para>
2837
2838 <para><programlisting>flowControlDelay = flowControlFactor * GRTT * (backoffFactor + 1)</programlisting></para>
2839
2840 <para>where the "<literal>GRTT</literal>" is the sender's advertised
2841 GRTT estimate and the <literal>backoffFactor</literal> is the
2842 sender's configured timer-based feedback scaling factor.</para>
2843
2844 <para>The default value (when this function is not called) of the
2845 <parameter>flowControlFactor</parameter> is
2846 <constant>2.0</constant>. Note that a NORM application can also
2847 implement more explicit, deterministic flow control through use of
2848 the <link
2849 linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
2850 API call, potentially even requiring positive acknowledgement of
2851 older data before enqueueing new data. Note that using the <link
2852 linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
2853 API call with a <constant>NORM_NODE_NONE</constant> member in acking
2854 node list to force a "full" watermark flush is somewhat equivalent
2855 to timer-based flow control with a
2856 <parameter>flowControlFactor</parameter> equal to <literal>2.0 *
2857 txRobustFactor</literal>.</para>
2858
2859 <para>If such explicit flow control is implemented by the
2860 application, then a reduced <parameter>flowControlFactor</parameter>
2861 (or even <constant>ZERO</constant>) may be used. If "push mode" is
2862 enabled for a <constant>NORM_OBJECT_STREAM</constant> (see <link
2863 linkend="NormStreamSetPushEnable"><literal>NormStreamSetPushEnable()</literal></link>),
2864 then flow control has no effect for the stream.</para>
2865 </sect4>
2866
2867 <sect4>
2868 <title>Return Values</title>
2869
2870 <para>This function has no return values.</para>
2871 </sect4>
2872 </sect3>
2873
2874 <sect3 id="NormSetCongestionControl">
2875 <title>NormSetCongestionControl()</title>
2876
2877 <sect4>
2878 <title>Synopsis</title>
2879
2880 <programlisting>#include &lt;normApi.h&gt;
2881
2882 void <link linkend="NormSetCongestionControl"><literal>NormSetCongestionControl</literal></link>(<link
2883 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
2884 bool enable,
2885 bool adjustRate = true);</programlisting>
2886 </sect4>
2887
2888 <sect4>
2889 <title>Description</title>
2890
2891 <para>This function enables (or disables) the NORM sender congestion
2892 control operation for the session designated by the
2893 <parameter>sessionHandle</parameter> parameter. For best operation,
2894 this function should be called before the call to <link
2895 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
2896 is made, but congestion control operation can be dynamically
2897 enabled/disabled during the course of sender operation. If the value
2898 of the <parameter>enable</parameter> parameter is
2899 <constant>true</constant>, congestion control operation is enabled
2900 while it is disabled for enable equal to <constant>false</constant>.
2901 When congestion control operation is enabled, the NORM sender
2902 automatically adjusts its transmission rate based on feedback from
2903 receivers. If bounds on transmission rate have been set (see <link
2904 linkend="NormSetTxRateBounds"><literal>NormSetTxRateBounds()</literal></link>)
2905 the rate adjustment will remain within the set bounds. The
2906 application will be notified of any changes to the sender
2907 transmission rate via a <link
2908 linkend="NormEvent"><literal>NormEvent</literal></link> of type
2909 <constant>NORM_TX_RATE_CHANGED</constant>.</para>
2910
2911 <para>The rate set by <link
2912 linkend="NormSetTxRate"><literal>NormSetTxRate()</literal></link>
2913 has no effect when congestion control operation is enabled,
2914 <emphasis>unless</emphasis> the <parameter>adjustRate</parameter>
2915 parameter here is set to <constant>false</constant>. When the
2916 <parameter>adjustRate</parameter> parameter is set to
2917 <constant>false</constant>, the NORM Congestion Control operates as
2918 usual, with feedback collected from the receiver set and the
2919 "current limiting receiver" identified, except that no actual
2920 adjustment is made to the sender's transmission rate. I.e., the
2921 transmission rate that was set by <literal><link
2922 linkend="NormSetTxRate">NormSetTxRate()</link></literal> is observed
2923 by the sender regardless of the feedback received. The
2924 <constant>NORM_TX_RATE_CHANGED</constant> notification will still
2925 occur as if the rate were being adjusted and the value returned by
2926 <link
2927 linkend="NormGetTxRate"><literal>NormGetTxRate()</literal></link>
2928 reflects the rate that would have been used had the
2929 <parameter>adjustRate</parameter> parameter been enabled even though
2930 no actual rate change has occurred. The purpose of this variation of
2931 NORM Congestion Control operation is to allow applications to get a
2932 "suggested" rate from the NORM-CC mechanism. But, it is important to
2933 note that this "suggested" rate may or may not be appropriate since
2934 the operation of the NORM-CC algorithm is somewhat dependent on the
2935 associated NORM sender load on the network. For example, the
2936 "suggested" rate may be artificially high if the sender application
2937 has not been correspondingly setting the rate and actively
2938 transmitting data at that rate. This optional mode of operation is
2939 provided for EXPERIMENTAL purposes and is NOT RECOMMENDED for
2940 typical use of NORM.</para>
2941
2942 <para>NORM's congestion algorithm provides rate adjustment to fairly
2943 compete for available network bandwidth with other TCP, NORM, or
2944 similarly governed traffic flows.</para>
2945
2946 <para>(<emphasis>TBD - Describe the
2947 <function>NormSetEcnSupport()</function> function as this
2948 experimental option matures.</emphasis>)</para>
2949 </sect4>
2950
2951 <sect4>
2952 <title>Return Values</title>
2953
2954 <para>This function has no return values.</para>
2955 </sect4>
2956 </sect3>
2957
2958 <sect3 id="NormSetTxRateBounds">
2959 <title>NormSetTxRateBounds()</title>
2960
2961 <sect4>
2962 <title>Synopsis</title>
2963
2964 <programlisting>#include &lt;normApi.h&gt;
2965
2966 bool <link linkend="NormSetTxRateBounds"><literal>NormSetTxRateBounds</literal></link>(<link
2967 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
2968 double rateMin,
2969 double rateMax);</programlisting>
2970 </sect4>
2971
2972 <sect4>
2973 <title>Description</title>
2974
2975 <para>This function sets the range of sender transmission rates
2976 within which the NORM congestion control algorithm is allowed to
2977 operate for the given <parameter>sessionHandle</parameter>. By
2978 default, the NORM congestion control algorithm operates with no
2979 lower or upper bound on its rate adjustment. This function allows
2980 this to be limited where <parameter>rateMin</parameter> corresponds
2981 to the minimum transmission rate (bps) and
2982 <parameter>rateMax</parameter> corresponds to the maximum
2983 transmission rate. One or both of these parameters may be set to
2984 values less than zero to remove one or both bounds. For example, the
2985 call "<link
2986 linkend="NormSetTxRateBounds"><literal>NormSetTxRateBounds</literal></link><literal>(session,
2987 -1.0, 64000.0)</literal>" will set an upper limit of 64 kbps for the
2988 sender transmission rate with no lower bound. These rate bounds
2989 apply only when congestion control operation is enabled (see <link
2990 linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>).
2991 If the current congestion control rate falls outside of the
2992 specified bounds, the sender transmission rate will be adjusted to
2993 stay within the set bounds.</para>
2994 </sect4>
2995
2996 <sect4>
2997 <title>Return Values</title>
2998
2999 <para>This function returns <constant>true</constant> upon success.
3000 If both <parameter>rateMin</parameter> and
3001 <parameter>rateMax</parameter> are greater than or equal to zero,
3002 but (<parameter>rateMax</parameter> <literal>&lt;</literal>
3003 <parameter>rateMin</parameter>), the rate bounds will remain unset
3004 or unchanged and the function will return
3005 <constant>false</constant>.</para>
3006 </sect4>
3007 </sect3>
3008
3009 <sect3 id="NormSetTxCacheBounds">
3010 <title>NormSetTxCacheBounds()</title>
3011
3012 <sect4>
3013 <title>Synopsis</title>
3014
3015 <programlisting>#include &lt;normApi.h&gt;
3016
3017 void <link linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds</literal></link>(<link
3018 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
3019 <link linkend="NormSize"><literal>NormSize</literal></link> sizeMax,
3020 unsigned int countMin,
3021 unsigned int countMax);</programlisting>
3022 </sect4>
3023
3024 <sect4>
3025 <title>Description</title>
3026
3027 <para>This function sets limits that define the number and total
3028 size of pending transmit objects a NORM sender will allow to be
3029 enqueued by the application. Setting these bounds to large values
3030 means the NORM protocol engine will keep history and state for
3031 previously transmitted objects for a larger interval of time
3032 (depending upon the transmission rate) when the application is
3033 actively enqueueing additional objects in response to
3034 <literal>NORM_TX_QUEUE_EMPTY</literal> notifications. This can allow
3035 more time for receivers suffering degraded network conditions to
3036 make repair requests before the sender "purges" older objects from
3037 its "transmit cache" when new objects are enqueued. A
3038 <literal>NORM_TX_OBJECT_PURGED</literal> notification is issued when
3039 the enqueuing of a new transmit object causes the NORM transmit
3040 cache to overflow, indicating the NORM sender no longer needs to
3041 reference the designated old transmit object and the application is
3042 free to release related resources as needed.</para>
3043
3044 <para>The <parameter>sizeMax</parameter> parameter sets the maximum
3045 total size, in bytes, of enqueued objects allowed, providing the
3046 constraints of the <parameter>countMin</parameter> and
3047 <parameter>countMax</parameter> parameters are met. The
3048 <parameter>countMin</parameter> parameter sets the minimum number of
3049 objects the application may enqueue, regardless of the objects'
3050 sizes and the <parameter>sizeMax</parameter> value. For example, the
3051 default <parameter>sizeMax</parameter> value is 20 Mbyte and the
3052 default <parameter>countMin</parameter> is 8, thus allowing the
3053 application to always have at least 8 pending objects enqueued for
3054 transmission if it desires, even if their total size is greater than
3055 20 Mbyte. Similarly, the <parameter>countMax</parameter> parameter
3056 sets a ceiling on how many objects may be enqueued, regardless of
3057 their total sizes with respect to the <parameter>sizeMax</parameter>
3058 setting. For example, the default <parameter>countMax</parameter>
3059 value is 256, which means the application is never allowed to have
3060 more than 256 objects pending transmission enqueued, even if they
3061 are 256 very small objects. Note that
3062 <parameter>countMax</parameter> must be greater than or equal to
3063 <parameter>countMin</parameter> and <parameter>countMin</parameter>
3064 is recommended to be at least two.</para>
3065
3066 <para>Note that in the case of <literal>NORM_OBJECT_FILE</literal>
3067 objects, some operating systems impose limits (e.g. 256) on how many
3068 open files a process may have at one time and it may be appropriate
3069 to limit the <parameter>countMax</parameter> value accordingly. In
3070 other cases, a large <parameter>countMin</parameter> or
3071 <parameter>countMax</parameter> may be desired to allow the NORM
3072 sender to act as virtual cache of files or other data available for
3073 reliable transmission. Future iterations of the NRL NORM
3074 implementation may support alternative NORM receiver "group join"
3075 policies that would allow the receivers to request transmission of
3076 cached content.</para>
3077
3078 <para>The utility of the <link
3079 linkend="NormRequeueObject"><literal>NormRequeueObject()</literal></link>
3080 API call also depends on the parameters set by this function. The
3081 <link
3082 linkend="NormRequeueObject"><literal>NormRequeueObject()</literal></link>
3083 call will only succeed when the given
3084 <parameter>objectHandle</parameter> corresponds to an object
3085 maintained in the NORM senders "transmit cache".</para>
3086 </sect4>
3087
3088 <sect4>
3089 <title>Return Values</title>
3090
3091 <para>This function has no return value.</para>
3092 </sect4>
3093 </sect3>
3094
3095 <sect3 id="NormSetAutoParity">
3096 <title>NormSetAutoParity()</title>
3097
3098 <sect4>
3099 <title>Synopsis</title>
3100
3101 <programlisting>#include &lt;normApi.h&gt;
3102
3103 void <link linkend="NormSetAutoParity"><literal>NormSetAutoParity</literal></link>(<link
3104 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
3105 unsigned char autoParity);</programlisting>
3106 </sect4>
3107
3108 <sect4>
3109 <title>Description</title>
3110
3111 <para>This function sets the quantity of proactive "auto parity"
3112 <literal>NORM_DATA</literal> messages sent at the end of each FEC
3113 coding block. By default (i.e., <parameter>autoParity</parameter>
3114 <literal>=</literal> <constant>0</constant>), FEC content is sent
3115 only in response to repair requests (NACKs) from receivers. But, by
3116 setting a non-zero value for <parameter>autoParity</parameter>, the
3117 sender can automatically accompany each coding block of transport
3118 object source data segments (<literal>(NORM_DATA</literal> messages)
3119 with the set number of FEC segments. The number of source symbol
3120 messages (segments) per FEC coding block is determined by the
3121 <parameter>blockSize</parameter> parameter used when <link
3122 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
3123 was called for the given
3124 <parameter>sessionHandle</parameter>.</para>
3125
3126 <para>The use of proactively-sent "auto parity" may eliminate the
3127 need for any receiver NACKing to achieve reliable transfer in
3128 networks with low packet loss. However, note that the quantity of
3129 "auto parity" set adds overhead to transport object transmission. In
3130 networks with a predictable level of packet loss and potentially
3131 large round-trip times, the use of "auto parity" may allow lower
3132 latency in the reliable delivery process. Also, its use may
3133 contribute to a smaller amount of receiver feedback as only
3134 receivers with exceptional packet loss may need to NACK for
3135 additional repair content.</para>
3136
3137 <para>The value of <parameter>autoParity</parameter> set must be
3138 less than or equal to the <parameter>numParity</parameter> parameter
3139 set when <link
3140 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
3141 was called for the given
3142 <parameter>sessionHandle</parameter>.</para>
3143 </sect4>
3144
3145 <sect4>
3146 <title>Return Values</title>
3147
3148 <para>This function has no return values.</para>
3149 </sect4>
3150 </sect3>
3151
3152 <sect3 id="NormGetGrttEstimate">
3153 <title>NormGetGrttEstimate()</title>
3154
3155 <sect4>
3156 <title>Synopsis</title>
3157
3158 <programlisting>#include &lt;normApi.h&gt;
3159
3160 double <link linkend="NormGetGrttEstimate"><literal>NormGetGrttEstimate</literal></link>(<link
3161 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle);</programlisting>
3162 </sect4>
3163
3164 <sect4>
3165 <title>Description</title>
3166
3167 <para>This function returns the sender's current estimate(in
3168 seconds) of group round-trip timing (GRTT) for the given NORM
3169 session. This function may be useful for applications to leverage
3170 for other purposes the assessment of round-trip timing made by the
3171 NORM protocol engine. For example, an application may scale its own
3172 timeouts based on connectivity delays among participants in a NORM
3173 session. Note that the <literal>NORM_GRTT_UPDATED</literal> event is
3174 posted (see <link
3175 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>)
3176 by the NORM protocol engine to indicate when changes in the local
3177 sender or remote senders' GRTT estimate occurs.</para>
3178 </sect4>
3179
3180 <sect4>
3181 <title>Return Values</title>
3182
3183 <para>This function returns the current sender group round-trip
3184 timing (GRTT) estimate (in units of seconds). A value of
3185 <constant>-1.0</constant> is returned if an invalid session value is
3186 provided.</para>
3187 </sect4>
3188 </sect3>
3189
3190 <sect3 id="NormSetGrttEstimate">
3191 <title>NormSetGrttEstimate()</title>
3192
3193 <sect4>
3194 <title>Synopsis</title>
3195
3196 <programlisting>#include &lt;normApi.h&gt;
3197
3198 void <link linkend="NormSetGrttEstimate"><literal>NormSetGrttEstimate</literal></link>(<link
3199 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
3200 double grtt);</programlisting>
3201 </sect4>
3202
3203 <sect4>
3204 <title>Description</title>
3205
3206 <para>This function sets the sender's estimate of group round-trip
3207 time (GRTT) (in units of seconds) for the given NORM
3208 <parameter>sessionHandle</parameter>. This function is expected to
3209 most typically used to initialize the sender's GRTT estimate prior
3210 to the call to <link
3211 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
3212 when the application has a priori confidence that the default
3213 initial GRTT value of 0.5 second is inappropriate. The sender GRTT
3214 estimate will be updated during normal sender protocol operation
3215 after sender startup or if this call is made while sender operation
3216 is active. For experimental purposes (or very special application
3217 needs), this API provides a mechanism to control or disable the
3218 sender GRTT update process (see <link
3219 linkend="NormSetGrttProbingMode"><literal>NormSetGrttProbingMode()</literal></link>).
3220 The <parameter>grtt</parameter> value (in seconds) will be limited
3221 to the maximum GRTT as set (see <link
3222 linkend="NormSetGrttMax"><literal>NormSetGrttMax()</literal></link>)
3223 or the default maximum of 10 seconds.</para>
3224
3225 <para>The sender GRTT is advertised to the receiver group and is
3226 used to scale various NORM protocol timers. The default NORM GRTT
3227 estimation process dynamically measures round-trip timing to
3228 determine an appropriate operating value. An overly-large GRTT
3229 estimate can introduce additional latency into the reliability
3230 process (resulting in a larger virtual delay*bandwidth product for
3231 the protocol and potentially requiring more buffer space to maintain
3232 reliability). An overly-small GRTT estimate may introduce the
3233 potential for feedback implosion, limiting the scalability of group
3234 size.</para>
3235
3236 <para>Also note that the advertised GRTT estimate can also be
3237 limited by transmission rate. When the sender transmission rate is
3238 low, the GRTT is also governed to a lower bound of the nominal
3239 packet transmission interval (i.e., <literal>1/txRate</literal>).
3240 This maintains the "event driven" nature of the NORM protocol with
3241 respect to receiver reception of NORM sender data and
3242 commands.</para>
3243 </sect4>
3244
3245 <sect4>
3246 <title>Return Values</title>
3247
3248 <para>This function has no return values.</para>
3249 </sect4>
3250 </sect3>
3251
3252 <sect3 id="NormSetGrttMax">
3253 <title>NormSetGrttMax()</title>
3254
3255 <sect4>
3256 <title>Synopsis</title>
3257
3258 <programlisting>#include &lt;normApi.h&gt;
3259
3260 void <link linkend="NormSetGrttMax"><literal>NormSetGrttMax</literal></link>(<link
3261 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
3262 double grttMax);</programlisting>
3263 </sect4>
3264
3265 <sect4>
3266 <title>Description</title>
3267
3268 <para>This function sets the sender's maximum advertised GRTT value
3269 for the given NORM <parameter>sessionHandle</parameter>. The
3270 <parameter>grttMax</parameter> parameter, in units of seconds,
3271 limits the GRTT used by the group for scaling protocol timers,
3272 regardless of larger measured round trip times. The default maximum
3273 for the NRL NORM library is 10 seconds. See the <link
3274 linkend="NormSetGrttEstimate"><literal>NormSetGrttEstimate()</literal></link>
3275 function description for the purpose of the NORM GRTT measurement
3276 process.</para>
3277 </sect4>
3278
3279 <sect4>
3280 <title>Return Values</title>
3281
3282 <para>This function has no return values.</para>
3283 </sect4>
3284 </sect3>
3285
3286 <sect3 id="NormSetGrttProbingMode">
3287 <title>NormSetGrttProbingMode()</title>
3288
3289 <sect4>
3290 <title>Synopsis</title>
3291
3292 <programlisting>#include &lt;normApi.h&gt;
3293
3294 void <link linkend="NormSetGrttProbingMode"><literal>NormSetGrttProbingMode</literal></link>(<link
3295 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
3296 <link linkend="NormProbingMode"><literal>NormProbingMode</literal></link> probingMode);</programlisting>
3297 </sect4>
3298
3299 <sect4>
3300 <title>Description</title>
3301
3302 <para>This function sets the sender's mode of probing for round trip
3303 timing measurement responses from the receiver set for the given
3304 NORM <parameter>sessionHandle</parameter>. Possible values for the
3305 <parameter>probingMode</parameter> parameter include
3306 <literal>NORM_PROBE_NONE</literal>,
3307 <literal>NORM_PROBE_PASSIVE</literal>, and
3308 <literal>NORM_PROBE_ACTIVE</literal>. The default probing mode is
3309 <literal>NORM_PROBE_ACTIVE</literal>. In this mode, the receiver set
3310 explicitly acknowledges NORM sender GRTT probes
3311 (<literal>(NORM_C</literal><literal><literal>M</literal>D(CC)</literal>
3312 messages) with <literal>NORM_ACK</literal> responses that are
3313 group-wise suppressed. Note that NORM receivers also will include
3314 their response to GRTT probing piggy-backed on any
3315 <literal>NORM_NACK</literal> messages sent in this mode as well to
3316 minimize feedback.</para>
3317
3318 <para>Note that the <literal>NORM_PROBE_ACTIVE</literal> probing
3319 mode is required and automatically set when NORM congestion control
3320 operation is enabled (see <link
3321 linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>).
3322 Thus, when congestion control is enabled, the <link
3323 linkend="NormSetGrttProbingMode"><literal>NormSetGrttProbingMode()</literal></link>
3324 function has no effect.</para>
3325
3326 <para>If congestion control operation is not enabled, the NORM
3327 application may elect to reduce the volume of feedback traffic by
3328 setting the <parameter>probingMode</parameter> to
3329 <literal>NORM_PROBE_PASSIVE</literal>. Here, the NORM sender still
3330 transmits <literal>NORM_CMD</literal><literal>(CC)</literal> probe
3331 messages multiplexed with its data transmission, but the receiver
3332 set does not explicitly acknowledge these probes. Instead the
3333 receiver set is limited to opportunistically piggy-backing responses
3334 when <literal>NORM_NACK</literal> messages are generated. Note that
3335 this may, in some cases, introduce some opportunity for bursts of
3336 large volume receiver feedback when the sender's estimate of GRTT is
3337 incorrect due to the reduced probing feedback. But, in some
3338 controlled network environments, this option for passive probing may
3339 provide some benefits in reducing protocol overhead.</para>
3340
3341 <para>Finally, the <parameter>probingMode</parameter> can be set to
3342 <literal>NORM_PROBE_NONE</literal> to eliminate the overhead (and
3343 benefits) of NORM GRTT measurement entirely. In this case, the
3344 sender application must explicitly set its estimate of GRTT using
3345 the <link
3346 linkend="NormSetGrttEstimate"><literal>NormSetGrttEstimate()</literal></link>
3347 function. See this function for a description of the purpose of the
3348 NORM GRTT measurement.</para>
3349 </sect4>
3350
3351 <sect4>
3352 <title>Return Values</title>
3353
3354 <para>This function has no return values.</para>
3355 </sect4>
3356 </sect3>
3357
3358 <sect3 id="NormSetGrttProbingInterval">
3359 <title>NormSetGrttProbingInterval()</title>
3360
3361 <sect4>
3362 <title>Synopsis</title>
3363
3364 <programlisting>#include &lt;normApi.h&gt;
3365
3366 void <link linkend="NormSetGrttProbingInterval"><literal>NormSetGrttProbingInterval</literal></link>(<link
3367 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
3368 double intervalMin,
3369 double intervalMax);</programlisting>
3370 </sect4>
3371
3372 <sect4>
3373 <title>Description</title>
3374
3375 <para>This function controls the sender GRTT measurement and
3376 estimation process for the given NORM
3377 <parameter>sessionHandle</parameter>. The NORM sender multiplexes
3378 periodic transmission of <literal>NORM_CMD</literal>(CC) messages
3379 with its ongoing data transmission or when data transmission is
3380 idle. When NORM congestion control operation is enabled, these
3381 probes are sent once per RTT of the current limiting receiver (with
3382 respect to congestion control rate). In this case the
3383 <parameter>intervalMin</parameter> and
3384 <parameter>intervalMax</parameter> parameters (in units of seconds)
3385 control the rate at which the sender's estimate of GRTT is updated.
3386 At session start, the estimate is updated at
3387 <parameter>intervalMin</parameter> and the update interval time is
3388 doubled until <parameter>intervalMax</parameter> is reached. This
3389 dynamic allows for a rapid initial estimation of GRTT and a slower,
3390 steady-state update of GRTT. When congestion control is disabled and
3391 NORM GRTT probing is enabled (<literal>(NORM_PROBE_ACTIVE</literal>
3392 or <literal>NORM_PROBE_PASSIVE</literal>) the
3393 <parameter>intervalMin</parameter> and
3394 <parameter>intervalMax</parameter> values also determine the rate at
3395 which <literal>NORM_CMD</literal>(CC) probes are transmitted by the
3396 sender. Thus by setting larger values for
3397 <parameter>intervalMin</parameter> and
3398 <parameter>intervalMax</parameter>, the NORM sender application can
3399 reduce the overhead of the GRTT measurement process. However, this
3400 also reduces the ability of NORM to adapt to changes in GRTT.</para>
3401
3402 <para>The default NORM GRTT <parameter>intervalMin</parameter> and
3403 <parameter>intervalMax</parameter> values, i.e., when this call is
3404 not made, are <constant>1.0</constant> second and
3405 <constant>30.0</constant> seconds, respectively.</para>
3406 </sect4>
3407
3408 <sect4>
3409 <title>Return Values</title>
3410
3411 <para>This function has no return values.</para>
3412 </sect4>
3413 </sect3>
3414
3415 <sect3 id="NormSetBackoffFactor">
3416 <title>NormSetBackoffFactor()</title>
3417
3418 <sect4>
3419 <title>Synopsis</title>
3420
3421 <programlisting>#include &lt;normApi.h&gt;
3422
3423 void <link linkend="NormSetBackoffFactor"><literal>NormSetBackoffFactor</literal></link>(<link
3424 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
3425 double backoffFactor);</programlisting>
3426 </sect4>
3427
3428 <sect4>
3429 <title>Description</title>
3430
3431 <para>This function sets the sender's "backoff factor" for the given
3432 <parameter>sessionHandle</parameter>. The
3433 <parameter>backoffFactor</parameter> (in units of seconds) is used
3434 to scale various timeouts related to the NACK repair process. The
3435 sender advertises its <parameter>backoffFactor</parameter> setting
3436 to the receiver group in NORM protocol message headers. The default
3437 <parameter>backoffFactor</parameter> for NORM sessions is
3438 <constant>4.0</constant> seconds. The
3439 <parameter>backoffFactor</parameter> is used to determine the
3440 maximum time that receivers may delay NACK transmissions (and other
3441 feedback messages) as part of NORM's probabilistic feedback
3442 suppression technique. For example, the maximum NACK delay time is
3443 <parameter>backoffFactor</parameter><literal>*GRTT</literal>. Thus a
3444 large <literal>backoffFactor</literal> value introduces latency into
3445 the NORM repair process. However, a small backoffFactor value causes
3446 feedback suppression to be less effective and increases the risk of
3447 feedback implosion for large receiver group sizes.</para>
3448
3449 <para>The default setting of <constant>4.0</constant> provides
3450 reasonable feedback suppression for moderate to large group sizes
3451 when multicast feedback is possible. The NORM specification
3452 recommends a <literal>backoffFactor</literal> value of
3453 <constant>6.0</constant> when unicast feedback is used. However, for
3454 demanding applications (with respect to repair latency) when group
3455 sizes are modest, a small (even <constant>0.0</constant>)
3456 <literal>backoffFactor</literal> value can be specified to reduce
3457 the latency of reliable data delivery.</para>
3458 </sect4>
3459
3460 <sect4>
3461 <title>Return Values</title>
3462
3463 <para>This function has no return values.</para>
3464 </sect4>
3465 </sect3>
3466
3467 <sect3 id="NormSetGroupSize">
3468 <title>NormSetGroupSize()</title>
3469
3470 <sect4>
3471 <title>Synopsis</title>
3472
3473 <programlisting>#include &lt;normApi.h&gt;
3474
3475 void <link linkend="NormSetGroupSize"><literal>NormSetGroupSize</literal></link>(<link
3476 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
3477 unsigned int groupSize);</programlisting>
3478 </sect4>
3479
3480 <sect4>
3481 <title>Description</title>
3482
3483 <para>This function sets the sender's estimate of receiver group
3484 size for the given <parameter>sessionHandle</parameter>. The sender
3485 advertises its <parameter>groupSize</parameter> setting to the
3486 receiver group in NORM protocol message headers that, in turn, use
3487 this information to shape the distribution curve of their random
3488 timeouts for the timer-based, probabilistic feedback suppression
3489 technique used in the NORM protocol. Note that the
3490 <parameter>groupSize</parameter> estimate does not have to be very
3491 accurate and values within an order of magnitude of the actual group
3492 size tend to produce acceptable performance.</para>
3493
3494 <para>The default <parameter>groupSize</parameter> setting in NORM
3495 is <constant>1,000</constant> and thus can work well for a wide
3496 range of actual receiver group sizes. The penalty of an overly large
3497 estimate is statistically a little more latency in reliable data
3498 delivery with respect to the round trip time and some potential for
3499 excess feedback. A substantial underestimation of
3500 <parameter>groupSize</parameter> increases the risk of feedback
3501 implosion. Currently, the NORM implementation does not attempt to
3502 automatically measure <parameter>groupSize</parameter> from receiver
3503 feedback. Applications could add their own mechanism for this
3504 (perhaps keeping explicit track of group membership), or it is
3505 possible that future versions of the NRL NORM implementation may
3506 have some provision for automatic <parameter>groupSize</parameter>
3507 estimation by the sender based on receiver feedback messages.</para>
3508 </sect4>
3509
3510 <sect4>
3511 <title>Return Values</title>
3512
3513 <para>This function has no return values.</para>
3514 </sect4>
3515 </sect3>
3516
3517 <sect3 id="NormSetTxRobustFactor">
3518 <title>NormSetTxRobustFactor()</title>
3519
3520 <sect4>
3521 <title>Synopsis</title>
3522
3523 <programlisting>#include &lt;normApi.h&gt;
3524
3525 void <link linkend="NormSetTxRobustFactor"><literal>NormSetTxRobustFactor</literal></link>(<link
3526 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
3527 int txRobustFactor);</programlisting>
3528 </sect4>
3529
3530 <sect4>
3531 <title>Description</title>
3532
3533 <para>This routine sets the "robustness factor" used for various
3534 NORM sender functions. These functions include the number of
3535 repetitions of "robustly-transmitted" NORM sender commands such as
3536 <literal><literal>NORM_CMD</literal>(FLUSH)</literal> or similar
3537 application-defined commands, and the number of attempts that are
3538 made to collect positive acknowledgement from receivers. These
3539 commands are distinct from the NORM reliable data transmission
3540 process, but play a role in overall NORM protocol operation. The
3541 default <parameter>txRobustFactor</parameter> value is
3542 <constant>20</constant>. This relatively large value makes the NORM
3543 sender end-of-transmission flushing and positive acknowledgement
3544 collection functions somewhat immune from packet loss. However, for
3545 some applications, the default value may make the NORM protocol more
3546 "chatty" than desired (particularly if flushing is invoked often).
3547 In other situations where the network connectivity may be
3548 intermittent or extremely lossy, it may be useful to actually
3549 increase this value. The default value (<constant>20</constant>) is
3550 expected to provide reasonable operation across a wide range of
3551 network conditions and application types. Since this value is not
3552 communicated among NORM participants as part of the protocol
3553 operation, it is important that applications consistently set this
3554 value among all applications participating in a NORM session.</para>
3555
3556 <para>Setting <parameter>txRobustFactor</parameter> to a value of
3557 <constant>-1</constant> makes the redundant transmission of these
3558 commands continue indefinitely until completion. For example, with
3559 positive acknowledgement collection, the request process will
3560 continue indefinitely until all recipients requested acknowledge or
3561 the request is canceled by the application. Similarly, flushing
3562 commands would be transmitted repeatedly until data transmission is
3563 resumed. Typically, setting <parameter>txRobustFactor</parameter> to
3564 <constant>-1</constant> is not recommended.</para>
3565 </sect4>
3566
3567 <sect4>
3568 <title>Return Values</title>
3569
3570 <para>This function has no return values.</para>
3571 </sect4>
3572 </sect3>
3573
3574 <sect3 id="NormFileEnqueue">
3575 <title>NormFileEnqueue()</title>
3576
3577 <sect4>
3578 <title>Synopsis</title>
3579
3580 <programlisting>#include &lt;normApi.h&gt;
3581
3582 <link linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> <link
3583 linkend="NormFileEnqueue"><literal>NormFileEnqueue</literal></link>(<link
3584 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
3585 const char* filename,
3586 const char* infoPtr = NULL,
3587 unsigned int infoLen = 0);</programlisting>
3588 </sect4>
3589
3590 <sect4>
3591 <title>Description</title>
3592
3593 <para>This function enqueues a file for transmission within the
3594 specified NORM <parameter>sessionHandle</parameter>. Note that <link
3595 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
3596 must have been previously called before files or any transport
3597 objects may be enqueued and transmitted. The
3598 <parameter>fileName</parameter> parameter specifies the path to the
3599 file to be transmitted. The NORM protocol engine read and writes
3600 directly from/to file system storage for file transport, potentially
3601 providing for a very large virtual "repair window" as needed for
3602 some applications. While relative paths with respect to the "current
3603 working directory" may be used, it is recommended that full paths be
3604 used when possible. The optional <parameter>infoPtr</parameter> and
3605 <parameter>infoLen</parameter> parameters are used to associate
3606 <literal>NORM_INFO</literal> content with the sent transport object.
3607 The maximum allowed <parameter>infoLen</parameter> corresponds to
3608 the <parameter>segmentSize</parameter> used in the prior call to
3609 <link
3610 linkend="NormStartSender"><literal>NormStartSender()</literal></link>.
3611 The use and interpretation of the <literal>NORM_INFO</literal>
3612 content is left to the application's discretion. Example usage of
3613 <literal>NORM_INFO</literal> content for
3614 <literal>NORM_OBJECT_FILE</literal> might include file name,
3615 creation date, MIME-type or other information which will enable NORM
3616 receivers to properly handle the file when reception is
3617 complete.</para>
3618
3619 <para>The application is allowed to enqueue multiple transmit
3620 objects within in the "transmit cache" bounds (see <link
3621 linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>)
3622 and enqueued objects are transmitted (and repaired as needed) within
3623 the limits determined by automated congestion control (see <link
3624 linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>)
3625 or fixed rate (see <literal><link
3626 linkend="NormSetTxRate">NormSetTxRate()</link></literal>)
3627 parameters.</para>
3628 </sect4>
3629
3630 <sect4>
3631 <title>Return Values</title>
3632
3633 <para>A <link
3634 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
3635 is returned which the application may use in other NORM API calls as
3636 needed. This handle can be considered valid until the application
3637 explicitly cancels the object's transmission (see <link
3638 linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>)
3639 or a <literal>NORM_TX_OBJECT_PURGED</literal> event is received for
3640 the given object. Note the application may use the <link
3641 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
3642 method if it wishes to refer to the object after the
3643 <literal>NORM_TX_OBJECT_PURGED</literal> notification. In this case,
3644 the application, when finished with the object, must use <link
3645 linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>
3646 to free any resources used or else a memory leak condition will
3647 result. A value of <literal>NORM_OBJECT_INVALID</literal> is return
3648 upon error. Possible failure conditions include the specified
3649 session is not operating as a NormSender, insufficient memory
3650 resources were available, or the "transmit cache" limits have been
3651 reached and all previously enqueued NORM transmit objects are
3652 pending transmission. Also the call will fail if the
3653 <parameter>infoLen</parameter> parameter exceeds the local
3654 <emphasis>NormSender</emphasis> <parameter>segmentSize</parameter>
3655 limit.</para>
3656 </sect4>
3657 </sect3>
3658
3659 <sect3 id="NormDataEnqueue">
3660 <title>NormDataEnqueue()</title>
3661
3662 <sect4>
3663 <title>Synopsis</title>
3664
3665 <programlisting>#include &lt;normApi.h&gt;
3666
3667 <link linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> <link
3668 linkend="NormDataEnqueue"><literal>NormDataEnqueue</literal></link>(<link
3669 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
3670 const char* dataPtr,
3671 unsigned int dataLen,
3672 const char* infoPtr = NULL,
3673 unsigned int infoLen = 0);</programlisting>
3674 </sect4>
3675
3676 <sect4>
3677 <title>Description</title>
3678
3679 <para>This function enqueues a segment of application memory space
3680 for transmission within the specified NORM
3681 <parameter>sessionHandle</parameter>. Note that <link
3682 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
3683 MUST have been previously called before files or any transport
3684 objects may be enqueued and transmitted. The
3685 <parameter>dataPtr</parameter> parameter must be a valid pointer to
3686 the area of application memory to be transmitted and the
3687 <parameter>dataLen</parameter> parameter indicates the quantity of
3688 data to transmit. The NORM protocol engine read and writes directly
3689 from/to application memory space so it is important that the
3690 application does not modify (or deallocate) the memory space during
3691 the time the NORM protocol engine may access this area. After
3692 calling <link
3693 linkend="NormDataEnqueue"><literal>NormDataEnqueue()</literal></link>
3694 for a specific application "dataPtr" memory space, the application
3695 MUST NOT deallocate (or change the contents of) that memory space
3696 until a <literal>NORM_TX_OBJECT_PURGED</literal> notification is
3697 received for the given object or the application itself explicitly
3698 cancels the object's transmission (see <link
3699 linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>).</para>
3700
3701 <para>The optional <parameter>infoPtr</parameter> and
3702 <parameter>infoLen</parameter> parameters are used to associate
3703 <literal>NORM_INFO</literal> content with the sent transport object.
3704 The maximum allowed <parameter>infoLen</parameter> corresponds to
3705 the <parameter>segmentSize</parameter> used in the prior call to
3706 <link
3707 linkend="NormStartSender"><literal>NormStartSender()</literal></link>.
3708 The use and interpretation of the <literal>NORM_INFO</literal>
3709 content is left to the application's discretion. Example usage of
3710 <literal>NORM_INFO</literal> content for
3711 <literal>NORM_OBJECT_DATA</literal> might include
3712 application-defined data typing or other information which will
3713 enable NORM receiver applications to properly interpret the received
3714 data when reception is complete. Of course, it is possible that the
3715 application may embed such typing information in the object data
3716 content itself. This is left to the application's discretion.</para>
3717
3718 <para>The application is allowed to enqueue multiple transmit
3719 objects within in the "transmit cache" bounds (see <link
3720 linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>)
3721 and enqueued objects are transmitted (and repaired as needed) within
3722 the limits determined by automated congestion control (see <link
3723 linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>)
3724 or fixed rate (see <literal><link
3725 linkend="NormSetTxRate">NormSetTxRate()</link></literal>)
3726 parameters.</para>
3727 </sect4>
3728
3729 <sect4>
3730 <title>Return Values</title>
3731
3732 <para>A <link
3733 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
3734 is returned which the application may use in other NORM API calls as
3735 needed. This handle can be considered valid until the application
3736 explicitly cancels the object's transmission (see <link
3737 linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>)
3738 or a <literal>NORM_TX_OBJECT_PURGED</literal> event is received for
3739 the given object. Note the application may use the <link
3740 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
3741 method if it wishes to refer to the object after the
3742 <literal>NORM_TX_OBJECT_PURGED</literal> notification. In this case,
3743 the application, when finished with the object, must use <link
3744 linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>
3745 to free any resources used or else a memory leak condition will
3746 result. A value of <literal>NORM_OBJECT_INVALID</literal> is return
3747 upon error. Possible failure conditions include the specified
3748 session is not operating as a NormSender, insufficient memory
3749 resources were available, or the "transmit cache" limits have been
3750 reached and all previously enqueued NORM transmit objects are
3751 pending transmission. Also the call will fail if the
3752 <parameter>infoLen</parameter> parameter exceeds the local
3753 <emphasis>NormSender</emphasis> <parameter>segmentSize</parameter>
3754 limit.</para>
3755 </sect4>
3756 </sect3>
3757
3758 <sect3 id="NormRequeueObject">
3759 <title>NormRequeueObject()</title>
3760
3761 <sect4>
3762 <title>Synopsis</title>
3763
3764 <programlisting>#include &lt;normApi.h&gt;
3765
3766 bool NormRequeueObject(<link linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
3767 <link linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
3768 </sect4>
3769
3770 <sect4>
3771 <title>Description</title>
3772
3773 <para>This function allows the application to resend (or reset
3774 transmission of) a <literal>NORM_OBJECT_FILE</literal> or
3775 <literal>NORM_OBJECT_DATA</literal> transmit object that was
3776 previously enqueued for the indicated
3777 <parameter>sessionHandle</parameter>. This function is useful for
3778 applications sending to silent (non-NACKing) receivers as it enables
3779 the receivers to take advantage of multiple retransmissions of
3780 objects (including any auto-parity set, see <link
3781 linkend="NormSetAutoParity"><literal>NormSetAutoParity()</literal></link>)
3782 to more robustly receive content. The
3783 <parameter>objectHandle</parameter> parameter must be a valid
3784 transmit <link
3785 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
3786 that has not yet been "purged" from the sender's transmit queue.
3787 Upon success, the specified object will be fully retransmitted using
3788 the same NORM object transport identifier as was used on its initial
3789 transmission. This call may be made at any time to restart
3790 transmission of a previously-enqueued object, but the
3791 <literal>NORM_TX_OBJECT_SENT</literal> or
3792 <literal>NORM_TX_FLUSH_COMPLETED</literal> notifications can serve
3793 as good cues for an appropriate time to resend an object. If
3794 multiple objects are re-queued, they will be resent in order of
3795 their initial enqueueing.</para>
3796
3797 <para>The transmit cache bounds set by <link
3798 linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>
3799 determine the number of previously-sent objects retained in the
3800 sender's transmit queue and that are thus eligible to be requeued
3801 for retransmission. An object may be requeued via this call multiple
3802 times, but each distinct requeue should be done after an indication
3803 such as <literal>NORM_TX_OBJECT_SENT</literal> or
3804 <literal>NORM_TX_FLUSH_COMPLETED</literal> for the given object.
3805 Otherwise, the object will simply be reset from its current
3806 transmission point to transmit from the beginning (i.e. restart).
3807 Note that the object type <literal>NORM_OBJECT_STREAM</literal>
3808 cannot currently be requeued.</para>
3809
3810 <para>(TBD - should a "numRepeats" parameter be added to this
3811 function?)</para>
3812 </sect4>
3813
3814 <sect4>
3815 <title>Return Values</title>
3816
3817 <para>A value of <constant>true</constant> is returned upon success
3818 and a value of <constant>false</constant> is returned upon failure.
3819 Possible reasons for failure include an invalid
3820 <parameter>objectHandle</parameter> was provided (i.e. a
3821 non-transmit object or transmit object that has been "purged" from
3822 the transmit queue (see <literal>NORM_TX_OBJECT_PURGED</literal>))
3823 or the provided object was of type
3824 <literal>NORM_OBJECT_STREAM</literal>.</para>
3825 </sect4>
3826 </sect3>
3827
3828 <sect3 id="NormStreamOpen">
3829 <title>NormStreamOpen()</title>
3830
3831 <sect4>
3832 <title>Synopsis</title>
3833
3834 <programlisting>#include &lt;normApi.h&gt;
3835
3836 <link linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> <link
3837 linkend="NormStreamOpen"><literal>NormStreamOpen</literal></link>(<link
3838 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
3839 unsigned int bufferSize,
3840 const char* infoPtr = NULL,
3841 unsigned int infoLen = 0);</programlisting>
3842 </sect4>
3843
3844 <sect4>
3845 <title>Description</title>
3846
3847 <para>This function opens a <literal>NORM_OBJECT_STREAM</literal>
3848 sender object and enqueues it for transmission within the indicated
3849 <parameter>sessionHandle</parameter>. NORM streams provide reliable,
3850 in-order delivery of data content written to the stream by the
3851 sender application. Note that no data is sent until subsequent calls
3852 to <link
3853 linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
3854 are made unless <literal>NORM_INFO</literal> content is specified
3855 for the stream with the <parameter>infoPtr</parameter> and
3856 <parameter>infoLen</parameter> parameters. Example usage of
3857 <literal>NORM_INFO</literal> content for
3858 <literal>NORM_OBJECT_STREAM</literal> might include
3859 application-defined data typing or other information which will
3860 enable NORM receiver applications to properly interpret the received
3861 stream as it is being received. The NORM protocol engine buffers
3862 data written to the stream for original transmission and repair
3863 transmissions as needed to achieve reliable transfer. The
3864 <parameter>bufferSize</parameter> parameter controls the size of the
3865 stream's "repair window" which limits how far back the sender will
3866 "rewind" to satisfy receiver repair requests.</para>
3867
3868 <para>NORM, as a NACK-oriented protocol, currently lacks a mechanism
3869 for receivers to explicitly feedback flow control status to the
3870 sender unless the sender application specifically leverages NORM's
3871 optional positive-acknowledgement (ACK) features. Thus, the
3872 <parameter>bufferSize</parameter> selection plays an important role
3873 in reliable delivery of NORM stream content. Generally, a larger
3874 <parameter>bufferSize</parameter> value is safer with respect to
3875 reliability, but some applications may wish to limit how far the
3876 sender rewinds to repair receivers with poor connectivity with
3877 respect to the group at large. Such applications may set a smaller
3878 <parameter>bufferSize</parameter> to avoid the potential for large
3879 latency in data delivery (i.e. favor peak delivery latency over full
3880 reliability). This may result in breaks in the reliable delivery of
3881 stream data to some receivers, but this form of quasi-reliability
3882 while limiting latency may be useful for some types of applications
3883 (e.g. reliable real-time messaging, video or sensor or media data
3884 transport). Note that NORM receivers can quickly, automatically
3885 "resync" to the sender after such breaks if the application
3886 leverages the application message boundary recovery features of NORM
3887 (see <link
3888 linkend="NormStreamMarkEom"><literal>NormStreamMarkEom()</literal></link>).</para>
3889
3890 <para>Note that the current implementation of NORM is designed to
3891 support only one active stream per session, and that any
3892 <literal>NORM_OBJECT_DATA</literal> or
3893 <literal>NORM_OBJECT_FILE</literal> objects enqueued for
3894 transmission will not begin transmission until an active stream is
3895 closed. Applications requiring multiple streams or concurrent
3896 file/data transfer SHOULD generally instantiate multiple
3897 <emphasis>NormSessions</emphasis> as needed.</para>
3898
3899 <para>Note there is no corresponding "open" call for receiver
3900 streams. Receiver <literal>NORM_OBJECT_STREAMs</literal> are
3901 automatically opened by the NORM protocol engine and the receiver
3902 applications is notified of new streams via the
3903 <literal>NORM_RX_OBJECT_NEW</literal> notification (see <link
3904 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>).</para>
3905 </sect4>
3906
3907 <sect4>
3908 <title>Return Values</title>
3909
3910 <para>A <link
3911 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
3912 is returned which the application may use in other NORM API calls as
3913 needed. This handle can be considered valid until the application
3914 explicitly cancels the object's transmission (see <link
3915 linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>)
3916 or a <literal>NORM_TX_OBJECT_PURGED</literal> event is received for
3917 the given object. Note the application may use the <link
3918 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
3919 method if it wishes to refer to the object after the
3920 <literal>NORM_TX_OBJECT_PURGED</literal> notification. In this case,
3921 the application, when finished with the object, must use <link
3922 linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>
3923 to free any resources used or else a memory leak condition will
3924 result. A value of <literal>NORM_OBJECT_INVALID</literal> is return
3925 upon error. Possible failure conditions include the specified
3926 session is not operating as a <emphasis>NormSender</emphasis>,
3927 insufficient memory resources were available, or the "transmit
3928 cache" bounds have been reached and all previously enqueued NORM
3929 transmit objects are pending transmission. Also the call will fail
3930 if the <parameter>infoLen</parameter> parameter exceeds the local
3931 <emphasis>NormSender</emphasis> <parameter>segmentSize</parameter>
3932 limit.</para>
3933 </sect4>
3934 </sect3>
3935
3936 <sect3 id="NormStreamClose">
3937 <title>NormStreamClose()</title>
3938
3939 <sect4>
3940 <title>Synopsis</title>
3941
3942 <programlisting>#include &lt;normApi.h&gt;
3943
3944 void <link linkend="NormStreamClose"><literal>NormStreamClose</literal></link>(<link
3945 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle,
3946 bool graceful = false);</programlisting>
3947 </sect4>
3948
3949 <sect4>
3950 <title>Description</title>
3951
3952 <para>This function halts transfer of the stream specified by the
3953 <parameter>streamHandle</parameter> parameter and releases any
3954 resources used unless the associated object has been explicitly
3955 retained by a call to <link
3956 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>.
3957 No further calls to <link
3958 linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
3959 will be successful for the given
3960 <parameter>streamHandle</parameter>. The optional graceful
3961 parameter, when set to a value of true, may be used by NORM senders
3962 to initiate "graceful" shutdown of a transmit stream. In this case,
3963 the sender application will be notified that stream has (most
3964 likely) completed reliable transfer via the
3965 <literal>NORM_TX_OBJECT_PURGED</literal> notification upon
3966 completion of the graceful shutdown process. When the
3967 <parameter>graceful</parameter> option is set to
3968 <constant>true</constant>, receivers are notified of the stream end
3969 via an "stream end" stream control code in
3970 <literal>NORM_DATA</literal> message and will receive a
3971 <literal>NORM_RX_OBJECT_COMPLETED</literal> notification after all
3972 received stream content has been read. Otherwise, the stream is
3973 immediately terminated, regardless of receiver state. In this case,
3974 this function is equivalent to the <link
3975 linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>
3976 routine and may be used for sender or receiver streams. So, it is
3977 expected this function (<link
3978 linkend="NormStreamClose"><literal>NormStreamClose()</literal></link>)
3979 will typically be used for transmit streams by NORM senders.</para>
3980 </sect4>
3981
3982 <sect4>
3983 <title>Return Values</title>
3984
3985 <para>This function has no return values.</para>
3986 </sect4>
3987 </sect3>
3988
3989 <sect3 id="NormStreamWrite">
3990 <title>NormStreamWrite()</title>
3991
3992 <sect4>
3993 <title>Synopsis</title>
3994
3995 <programlisting>#include &lt;normApi.h&gt;
3996
3997 unsigned int <link linkend="NormStreamWrite"><literal>NormStreamWrite</literal></link>(<link
3998 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle
3999 const char* buffer,
4000 unsigned int numBytes);</programlisting>
4001 </sect4>
4002
4003 <sect4>
4004 <title>Description</title>
4005
4006 <para>This function enqueues data for transmission within the NORM
4007 stream specified by the <parameter>streamHandle</parameter>
4008 parameter. The <parameter>buffer</parameter> parameter must be a
4009 pointer to the data to be enqueued and the
4010 <parameter>numBytes</parameter> parameter indicates the length of
4011 the data content. Note this call does not block and will return
4012 immediately. The return value indicates the number of bytes copied
4013 from the provided buffer to the internal stream transmission
4014 buffers. Calls to this function will be successful unless the
4015 stream's transmit buffer space is fully occupied with data pending
4016 original or repair transmission if the stream's "push mode" is set
4017 to false (default, see <link
4018 linkend="NormStreamSetPushEnable"><literal>NormStreamSetPushEnable()</literal></link>
4019 for details). If the stream's "push mode" is set to true, a call to
4020 <link
4021 linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
4022 will always result in copying of application data to the stream at
4023 the cost of previously enqueued data pending transmission (original
4024 or repair) being dropped by the NORM protocol engine. While NORM
4025 NACK-based reliability does not provide explicit flow control, there
4026 is some degree of implicit flow control in limiting writing new data
4027 to the stream against pending repairs. Other flow control strategies
4028 are possible using the <link
4029 linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
4030 function.<link
4031 linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
4032 function.</para>
4033
4034 <para>The <link
4035 linkend="NormEvent"><literal>NormEvent</literal></link> values
4036 <literal>NORM_TX_QUEUE_EMPTY</literal> and
4037 <literal>NORM_TX_QUEUE_VACANCY</literal> are posted with the <link
4038 linkend="NormEvent"><literal>NormEvent</literal></link><parameter>::object</parameter>
4039 field set to a valid sender stream <link
4040 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
4041 to indicate when the stream is ready for writing via this function.
4042 Note that the <literal>NORM_TX_QUEUE_VACANCY</literal> event type is
4043 posted only after the stream's transmit buffer has been completely
4044 filled. Thus, the application must make a call to <link
4045 linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
4046 that copies less than the requested <parameter>numBytes</parameter>
4047 value (return value less than <parameter>numBytes</parameter>)
4048 before additional <literal>NORM_TX_QUEUE_VACANCY</literal> events
4049 are posted for the given <parameter>streamHandle</parameter> (i.e.,
4050 the event type is not re-posted until the application has again
4051 filled the available stream transmit buffer space). By cueing off of
4052 <literal>NORM_TX_QUEUE_EMPTY</literal>, the application can write
4053 its "freshest" available data to the stream, but by cueing off of
4054 <literal>NORM_TX_QUEUE_VACANCY</literal>, an application can keep
4055 the NORM protocol engine busiest, to achieve the maximum possible
4056 throughput at high data rates.</para>
4057 </sect4>
4058
4059 <sect4>
4060 <title>Return Values</title>
4061
4062 <para>This function returns the number of bytes of data successfully
4063 enqueued for NORM stream transmission. If the underlying send stream
4064 buffer is full, this function may return zero or a value less than
4065 the requested <parameter>numBytes</parameter>.</para>
4066 </sect4>
4067 </sect3>
4068
4069 <sect3 id="NormStreamFlush">
4070 <title>NormStreamFlush()</title>
4071
4072 <sect4>
4073 <title>Synopsis</title>
4074
4075 <programlisting>#include &lt;normApi.h&gt;
4076
4077 void <link linkend="NormStreamFlush"><literal>NormStreamFlush</literal></link>(<link
4078 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle,
4079 bool eom = false,
4080 <link linkend="NormFlushMode"><literal>NormFlushMode</literal></link> flushMode = <literal>NORM_FLUSH_PASSIVE</literal>);</programlisting>
4081 </sect4>
4082
4083 <sect4>
4084 <title>Description</title>
4085
4086 <para>This function causes an immediate "flush" of the transmit
4087 stream specified by the <parameter>streamHandle</parameter>
4088 parameter. Normally, unless <link
4089 linkend="NormStreamSetAutoFlush"><literal>NormStreamSetAutoFlush()</literal></link>
4090 has been invoked, the NORM protocol engine buffers data written to a
4091 stream until it has accumulated a sufficient quantity to generate a
4092 <literal>NORM_DATA</literal> message with a full payload (as
4093 designated by the <parameter>segmentSize</parameter> parameter of
4094 the <link
4095 linkend="NormStartSender"><literal>NormStartSender()</literal></link>
4096 call). This results in most efficient operation with respect to
4097 protocol overhead. However, for some NORM streams, the application
4098 may not wish wait for such accumulation when critical data has been
4099 written to a stream. The default stream "flush" operation invoked
4100 via <link
4101 linkend="NormStreamFlush"><literal>NormStreamFlush()</literal></link>
4102 for <parameter>flushMode</parameter> equal to
4103 <literal>NORM_FLUSH_PASSIVE</literal> causes NORM to immediately
4104 transmit all enqueued data for the stream (subject to session
4105 transmit rate limits), even if this results in
4106 <literal>NORM_DATA</literal> messages with "small" payloads. If the
4107 optional <parameter>flushMode</parameter> parameter is set to
4108 <literal>NORM_FLUSH_ACTIVE</literal>, the application can achieve
4109 reliable delivery of stream content up to the current write position
4110 in an even more proactive fashion. In this case, the sender
4111 additionally, actively transmits <literal>NORM_CMD</literal>(FLUSH)
4112 messages after any enqueued stream content has been sent. This
4113 immediately prompt receivers for repair requests which reduces
4114 latency of reliable delivery, but at a cost of some additional
4115 messaging. Note any such "active" flush activity will be terminated
4116 upon the next subsequent write to the stream. If
4117 <parameter>flushMode</parameter> is set to
4118 <literal>NORM_FLUSH_NONE</literal>, this call has no effect other
4119 than the optional end-of-message marking described here.</para>
4120
4121 <para>The optional <parameter>eom</parameter> parameter, when set to
4122 <constant>true</constant>, allows the sender application to mark an
4123 end-of-message indication (see <link
4124 linkend="NormStreamMarkEom"><literal>NormStreamMarkEom()</literal></link>)
4125 for the stream and initiate flushing in a single function call. The
4126 end-of-message indication causes NORM to embed the appropriate
4127 message start byte offset in the <literal>NORM_DATA</literal>
4128 message generated following a subsequent write to the stream with
4129 the <literal>NORM_FLAGS_MSG_START</literal> flag. This mechanism
4130 provide a means for automatic application message boundary recovery
4131 when receivers join or re-sync to a sender mid-stream.</para>
4132
4133 <para>Note that frequent flushing, particularly for
4134 <literal>NORM_FLUSH_ACTIVE</literal> operation, may result in more
4135 NORM protocol activity than usual, so care must be taken in
4136 application design and deployment when scalability to large group
4137 sizes is expected.</para>
4138 </sect4>
4139
4140 <sect4>
4141 <title>Return Values</title>
4142
4143 <para>This function has no return values.</para>
4144 </sect4>
4145 </sect3>
4146
4147 <sect3 id="NormStreamSetAutoFlush">
4148 <title>NormStreamSetAutoFlush()</title>
4149
4150 <sect4>
4151 <title>Synopsis</title>
4152
4153 <programlisting>#include &lt;normApi.h&gt;
4154
4155 void <link linkend="NormStreamSetAutoFlush"><literal>NormStreamSetAutoFlush</literal></link>(<link
4156 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle
4157 <link linkend="NormFlushMode"><literal>NormFlushMode</literal></link> flushMode);</programlisting>
4158 </sect4>
4159
4160 <sect4>
4161 <title>Description</title>
4162
4163 <para>This function sets "automated flushing" for the NORM transmit
4164 stream indicated by the <parameter>streamHandle</parameter>
4165 parameter. By default, a NORM transmit stream is "flushed" only when
4166 explicitly requested by the application (see <link
4167 linkend="NormStreamFlush"><literal>NormStreamFlush()</literal></link>).
4168 However, to simplify programming, the NORM API allows that automated
4169 flushing be enabled such that the "flush" operation occurs every
4170 time the full requested buffer provided to a <link
4171 linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
4172 call is successfully enqueued. This may be appropriate for messaging
4173 applications where the provided buffers corresponds to an
4174 application messages requiring immediate, full transmission. This
4175 may make the NORM protocol perhaps more "chatty" than its typical
4176 "bulk transfer" form of operation, but can provide a useful
4177 capability for some applications.</para>
4178
4179 <para>Possible values for the <parameter>flushMode</parameter>
4180 parameter include <literal>NORM_FLUSH_NONE</literal>,
4181 <literal>NORM_FLUSH_PASSIVE</literal>, and
4182 <literal>NORM_FLUSH_ACTIVE</literal>. The default setting for a NORM
4183 stream is <literal>NORM_FLUSH_NONE</literal> where no flushing
4184 occurs unless explicitly requested via <link
4185 linkend="NormStreamFlush"><literal>NormStreamFlush()</literal></link>.
4186 By setting the automated <parameter>flushMode</parameter> to
4187 <literal>NORM_FLUSH_PASSIVE</literal>, the only action taken is to
4188 immediately transmit any data that has been written to the stream,
4189 even if "runt" <literal>NORM_DATA</literal> messages (with payloads
4190 less than the <emphasis>NormSender</emphasis>
4191 <parameter>segmentSize</parameter> parameter) are generated as a
4192 result. If <literal>NORM_FLUSH_ACTIVE</literal> is specified, the
4193 automated flushing operation is further augmented with the
4194 additional transmission of
4195 <literal>NORM_C</literal><literal><literal>MD</literal>(FLUSH)</literal>
4196 messages to proactively excite the receiver group for repair
4197 requests.</para>
4198 </sect4>
4199
4200 <sect4>
4201 <title>Return Values</title>
4202
4203 <para>This function has no return values.</para>
4204 </sect4>
4205 </sect3>
4206
4207 <sect3 id="NormStreamSetPushEnable">
4208 <title>NormStreamSetPushEnable()</title>
4209
4210 <sect4>
4211 <title>Synopsis</title>
4212
4213 <programlisting>#include &lt;normApi.h&gt;
4214
4215 void <link linkend="NormStreamSetPushEnable"><literal>NormStreamSetPushEnable</literal></link>(<link
4216 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle,
4217 bool pushEnable);</programlisting>
4218 </sect4>
4219
4220 <sect4>
4221 <title>Description</title>
4222
4223 <para>This function controls how the NORM API behaves when the
4224 application attempts to enqueue new stream data for transmission
4225 when the associated stream's transmit buffer is fully occupied with
4226 data pending original or repair transmission. By default
4227 (<parameter>pushEnable</parameter> <literal>=</literal>
4228 <constant>false</constant>), a call to <link
4229 linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
4230 will return a zero value under this condition, indicating it was
4231 unable to enqueue the new data. However, if
4232 <parameter>pushEnable</parameter> is set to
4233 <constant>true</constant> for a given
4234 <parameter>streamHandle</parameter>, the NORM protocol engine will
4235 discard the oldest buffered stream data (even if it is pending
4236 repair transmission or has never been transmitted) as needed to
4237 enqueue the new data. Thus a call to <link
4238 linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
4239 will never fail to copy data. This behavior may be desirable for
4240 applications where it is more important to quickly delivery new data
4241 than to reliably deliver older data written to a stream. The default
4242 behavior for a newly opened stream corresponds to
4243 <parameter>pushEnable</parameter> equals <constant>false</constant>.
4244 This limits the rate to which an application can write new data to
4245 the stream to the current transmission rate and status of the
4246 reliable repair process.</para>
4247 </sect4>
4248
4249 <sect4>
4250 <title>Return Values</title>
4251
4252 <para>This function has no return values.</para>
4253 </sect4>
4254 </sect3>
4255
4256 <sect3 id="NormStreamHasVacancy">
4257 <title>NormStreamHasVacancy()</title>
4258
4259 <sect4>
4260 <title>Synopsis</title>
4261
4262 <programlisting>#include &lt;normApi.h&gt;
4263
4264 bool <link linkend="NormStreamHasVacancy"><literal>NormStreamHasVacancy</literal></link>(<link
4265 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> <parameter>streamHandle</parameter>);</programlisting>
4266 </sect4>
4267
4268 <sect4>
4269 <title>Description</title>
4270
4271 <para>This function can be used to query whether the transmit
4272 stream, specified by the <parameter>streamHandle</parameter>
4273 parameter, has buffer space available so that the application may
4274 successfully make a call to <link
4275 linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>.
4276 Normally, a call to <link
4277 linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
4278 itself can be used to make this determination, but this function can
4279 be useful when "push mode" has been enabled (see the description of
4280 the <link
4281 linkend="NormStreamSetPushEnable"><literal>NormStreamSetPushEnable()</literal></link>
4282 function) and the application wants to avoid overwriting data
4283 previously written to the stream that has not yet been transmitted.
4284 Note that when "push mode" is enabled, a call to <link
4285 linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
4286 will always succeed, overwriting previously-enqueued data if
4287 necessary. Normally, this function will return true after a
4288 <literal>NORM_TX_QUEUE_VACANCY</literal> notification has been
4289 received for a given NORM stream object.</para>
4290 </sect4>
4291
4292 <sect4>
4293 <title>Return Values</title>
4294
4295 <para>This function returns a value of <constant>true</constant>
4296 when there is transmit buffer space to which the application may
4297 write and <constant>false</constant> otherwise.</para>
4298 </sect4>
4299 </sect3>
4300
4301 <sect3 id="NormStreamMarkEom">
4302 <title>NormStreamMarkEom()</title>
4303
4304 <sect4>
4305 <title>Synopsis</title>
4306
4307 <programlisting>#include &lt;normApi.h&gt;
4308
4309 void <link linkend="NormStreamMarkEom"><literal>NormStreamMarkEom</literal></link>(<link
4310 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> <parameter>streamHandle</parameter>);</programlisting>
4311 </sect4>
4312
4313 <sect4>
4314 <title>Description</title>
4315
4316 <para>This function allows the application to indicate to the NORM
4317 protocol engine that the last data successfully written to the
4318 stream indicated by <parameter>streamHandle</parameter> corresponded
4319 to the end of an application-defined message boundary. The
4320 end-of-message indication given here will cause the NORM protocol
4321 engine to embed the appropriate message start byte offset in the
4322 <constant>NORM_DATA</constant> message generated that contains the
4323 data for the subsequent application call to NormStreamWrite(). Use
4324 of this end-of-message marking enables NORM receivers to
4325 automatically re-sync to application-defined message boundaries when
4326 joining (or re-joining) a NORM session already in progress.</para>
4327 </sect4>
4328
4329 <sect4>
4330 <title>Return Values</title>
4331
4332 <para>This function has no return values.</para>
4333 </sect4>
4334 </sect3>
4335
4336 <sect3 id="NormSetWatermark">
4337 <title>NormSetWatermark()</title>
4338
4339 <sect4>
4340 <title>Synopsis</title>
4341
4342 <programlisting>#include &lt;normApi.h&gt;
4343
4344 bool <link linkend="NormSetWatermark"><literal>NormSetWatermark</literal></link>(<link
4345 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
4346 <link linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle,
4347 bool overrideFlush = true);</programlisting>
4348 </sect4>
4349
4350 <sect4>
4351 <title>Description</title>
4352
4353 <para>This function specifies a "watermark" transmission point at
4354 which NORM sender protocol operation should perform a flushing
4355 process and/or positive acknowledgment collection for a given
4356 <parameter>sessionHandle</parameter>. For
4357 <literal>NORM_OBJECT_FILE</literal> and
4358 <literal>NORM_OBJECT_DATA</literal> transmissions, the positive
4359 acknowledgement collection will begin when the specified object has
4360 been completely transmitted. The <parameter>objectHandle</parameter>
4361 parameter must be a valid handle to a previously-created sender
4362 object (see <link
4363 linkend="NormFileEnqueue"><literal>NormFileEnqueue()</literal></link>,
4364 <link
4365 linkend="NormDataEnqueue"><literal>NormDataEnqueue()</literal></link>,
4366 or <link
4367 linkend="NormStreamOpen"><literal>NormStreamOpen()</literal></link>).
4368 For <literal>NORM_OBJECT_STREAM</literal> transmission, the positive
4369 acknowledgment collection begins immediately, using the current
4370 position (offset of most recent data written) of the sender stream
4371 as a reference.</para>
4372
4373 <para>The functions <link
4374 linkend="NormAddAckingNode"><literal>NormAddAckingNode()</literal></link>
4375 and <link
4376 linkend="NormRemoveAckingNode"><literal>NormRemoveAckingNode()</literal></link>
4377 are used to manage the list of <link
4378 linkend="NormNodeId"><literal>NormNodeId</literal></link> values
4379 corresponding to NORM receivers that are expected to explicitly
4380 acknowledge the watermark flushing messages transmitted by the
4381 sender. Note that the <link
4382 linkend="NormNodeId"><literal>NormNodeId</literal></link>
4383 <literal>NORM_NODE_NONE</literal> may be included in the list.
4384 Inclusion of <literal>NORM_NODE_NONE</literal> forces the watermark
4385 flushing process to proceed through a full
4386 <literal>NORM_ROBUST_FACTOR</literal> number of rounds before
4387 completing, prompting any receivers that have not completed reliable
4388 reception to the given watermark point to NACK for any repair needs.
4389 If NACKs occur, the flushing process is reset and repeated until
4390 completing with no NACKs for data through the given watermark
4391 transmission point are received. Thus, even without explicit
4392 positive acknowledgment, the sender can use this process (by adding
4393 <literal>NORM_NODE_NONE</literal> to the session's list of "acking
4394 nodes") for a high level of assurance that the receiver set is
4395 "happy" (completed reliable data reception) through the given object
4396 (or stream transmission point).</para>
4397
4398 <para>The event <literal>NORM_TX_WATERMARK_COMPLETED</literal> is
4399 posted for the given session when the flushing process or positive
4400 acknowledgment collection has completed. The process completes as
4401 soon as all listed receivers have responded unless
4402 <literal>NORM_NODE_NONE</literal> is included in the "acking node"
4403 list. The sender application may use the function <link
4404 linkend="NormGetAckingStatus"><literal>NormGetAckingStatus()</literal></link>
4405 to determine the degree of success of the flushing process in
4406 general or for individual <link
4407 linkend="NormNodeId"><literal>NormNodeId</literal></link>
4408 values.</para>
4409
4410 <para>The flushing is conducted concurrently with ongoing data
4411 transmission and does not impede the progress of reliable data
4412 transfer. Thus the sender may still enqueue
4413 <emphasis>NormObjects</emphasis> for transmission (or write to the
4414 existing stream) and the positive acknowledgement collection and
4415 flushing procedure will be multiplexed with the ongoing data
4416 transmission. However, the sender application may wish to defer from
4417 or limit itself in sending more data until a
4418 <literal>NORM_TX_WATERMARK_COMPLETED</literal> event is received for
4419 the given session. This provides a form of sender-&gt;receiver(s)
4420 flow control which does not exist in NORM's default protocol
4421 operation. If a subsequent call is made to <link
4422 linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
4423 before the current acknowledgement request has completed, the
4424 pending acknowledgment request is canceled and the new one
4425 begins.</para>
4426
4427 <para>The optional <parameter>overrideFlush</parameter> parameter,
4428 when set to <constant>true</constant>, causes the watermark
4429 acknowledgment process that is established with this function call
4430 to potentially fully supersede the usual NORM end-of-transmission
4431 flushing process that occurs. If
4432 <parameter>overrideFlush</parameter> is set and the "watermark"
4433 transmission point corresponds to the last transmission that will
4434 result from data enqueued by the sending application, then the
4435 watermark flush completion will terminate the usual flushing
4436 process. I.e., if positive acknowledgement of watermark is received
4437 from the full "acking node list", then no further flushing is
4438 conducted. Thus, the <parameter>overrideFlush</parameter> parameter
4439 should only be set when the "acking node list" contains a complete
4440 list of intended recipients. This is useful for small receiver
4441 groups (or unicast operation) to reduce the "chattiness" of NORM's
4442 default end-of-transmission flush process. Note that once the
4443 watermark flush is completed and further data enqueued and
4444 transmitted, the normal default end-of-transmission behavior will be
4445 resumed unless another "watermark" is set with
4446 <parameter>overrideFlush</parameter> enabled. Thus, as long as new
4447 watermarks are established by successive use of this API call, this
4448 effectively "morphs" NORM into a protocol driven by positive
4449 acknowledgement behavior.</para>
4450 </sect4>
4451
4452 <sect4>
4453 <title>Return Values</title>
4454
4455 <para>The function returns <constant>true</constant> upon successful
4456 establishment of the watermark point. The function may return
4457 <constant>false</constant> upon failure.</para>
4458 </sect4>
4459 </sect3>
4460
4461 <sect3 id="NormCancelWatermark">
4462 <title>NormCancelWatermark()</title>
4463
4464 <sect4>
4465 <title>Synopsis</title>
4466
4467 <programlisting>#include &lt;normApi.h&gt;
4468
4469 bool <link linkend="NormCancelWatermark"><literal>NormCancelWatermark</literal></link>(<link
4470 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle);</programlisting>
4471 </sect4>
4472
4473 <sect4>
4474 <title>Description</title>
4475
4476 <para>This function cancels any "watermark" acknowledgement request
4477 that was previously set via the <link
4478 linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
4479 function for the given <parameter>sessionHandle</parameter>. The
4480 status of any NORM receivers that may have acknowledged prior to
4481 cancellation can be queried using the <link
4482 linkend="NormGetAckingStatus"><literal>NormGetAckingStatus()</literal></link>
4483 function even after <link
4484 linkend="NormCancelWatermark"><literal>NormCancelWatermark()</literal></link>
4485 is called. Typically, applications should wait until a event has
4486 been posted, but in some special cases it may be useful to terminate
4487 the acknowledgement collection process early.</para>
4488 </sect4>
4489
4490 <sect4>
4491 <title>Return Values</title>
4492
4493 <para>The function has no return values.</para>
4494 </sect4>
4495 </sect3>
4496
4497 <sect3 id="NormAddAckingNode">
4498 <title>NormAddAckingNode()</title>
4499
4500 <sect4>
4501 <title>Synopsis</title>
4502
4503 <programlisting>#include &lt;normApi.h&gt;
4504
4505 bool <link linkend="NormAddAckingNode"><literal>NormAddAckingNode</literal></link>(<link
4506 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
4507 <link linkend="NormNodeId"><literal>NormNodeId</literal></link> nodeId);</programlisting>
4508 </sect4>
4509
4510 <sect4>
4511 <title>Description</title>
4512
4513 <para>When this function is called, the specified
4514 <parameter>nodeId</parameter> is added to the list of <link
4515 linkend="NormNodeId"><literal>NormNodeId</literal></link> values
4516 (i.e., the "acking node" list) used when NORM sender operation
4517 performs positive acknowledgement (ACK) collection for the specified
4518 <parameter>sessionHandle</parameter>. The optional NORM positive
4519 acknowledgement collection occurs when a specified transmission
4520 point (see <link
4521 linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>)
4522 is reached or for specialized protocol actions such as
4523 positively-acknowledged application-defined commands.</para>
4524
4525 <para>Additionally the special value of
4526 <parameter>nodeId</parameter> equal to
4527 <literal>NORM_NODE_NONE</literal> may be set to force the watermark
4528 flushing process through a full
4529 <literal>NORM_ROBUST_FACTOR</literal> number of rounds regardless of
4530 actual acking nodes. Otherwise the flushing process is terminated
4531 when all of the nodes in the acking node list have responded.
4532 Setting a "watermark" and forcing a full flush process with the
4533 special <literal>NORM_NODE_NONE</literal> value of
4534 <parameter>nodeId</parameter> enables the resultant
4535 <literal>NORM_TX_WATERMARK_COMPLETED</literal> notification to be a
4536 indicator with high (but not absolute) assurance that the receiver
4537 set has completed reliable reception of content up through the
4538 "watermark" transmission point. This provides a form of scalable
4539 reliable multicast "flow control" for NACK-based operation without
4540 requiring explicit positive acknowledgement from all group members.
4541 Note that the use of the <literal>NORM_NODE_NONE</literal> value may
4542 be mixed with other <parameter>nodeId</parameter> for a mix of
4543 positive acknowledgement collection from some nodes and a measure of
4544 assurance for the group at large.</para>
4545 </sect4>
4546
4547 <sect4>
4548 <title>Return Values</title>
4549
4550 <para>The function returns <constant>true</constant> upon success
4551 and <constant>false</constant> upon failure. The only failure
4552 condition is that insufficient memory resources were available. If a
4553 specific <parameter>nodeId</parameter> is added more than once, this
4554 has no effect.</para>
4555 </sect4>
4556 </sect3>
4557
4558 <sect3 id="NormRemoveAckingNode">
4559 <title>NormRemoveAckingNode()</title>
4560
4561 <sect4>
4562 <title>Synopsis</title>
4563
4564 <programlisting>#include &lt;normApi.h&gt;
4565
4566 void <link linkend="NormRemoveAckingNode"><literal>NormRemoveAckingNode</literal></link>(<link
4567 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
4568 <link linkend="NormNodeId"><literal>NormNodeId</literal></link> nodeId);</programlisting>
4569 </sect4>
4570
4571 <sect4>
4572 <title>Description</title>
4573
4574 <para>This function deletes the specified
4575 <parameter>nodeId</parameter> from the list of <link
4576 linkend="NormNodeId"><literal>NormNodeId</literal></link> values
4577 used when NORM sender operation performs positive acknowledgement
4578 (ACK) collection for the specified
4579 <parameter>sessionHandle</parameter>. Note that if the special
4580 <parameter>nodeId</parameter> value
4581 "<literal>NORM_NODE_NONE"</literal> has been added to the list, it
4582 too must be explicitly removed to change the watermark flushing
4583 behavior if desired.</para>
4584 </sect4>
4585
4586 <sect4>
4587 <title>Return Values</title>
4588
4589 <para>The function has no return values.</para>
4590 </sect4>
4591 </sect3>
4592
4593 <sect3 id="NormGetNextAckingNode">
4594 <title>NormGetNextAckingNode()</title>
4595
4596 <sect4>
4597 <title>Synopsis</title>
4598
4599 <programlisting>#include &lt;normApi.h&gt;
4600
4601 NormNodeId <link linkend="NormRemoveAckingNode"><literal>NormGetNextAckingNode</literal></link>(<link
4602 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session, bool reset = false);</programlisting>
4603 </sect4>
4604
4605 <sect4>
4606 <title>Description</title>
4607
4608 <para>This function iteratively retrieves the <link
4609 linkend="NormNodeId"><literal>NormNodeId</literal></link> values in
4610 the "acking node" list maintained by a NORM sender (see <link
4611 linkend="NormAddAckingNode"><literal>NormAddAckingNode()</literal></link>)
4612 for the given <parameter>sessionHandle</parameter>. If the optional
4613 <parameter>reset</parameter> parameter is set to a value of
4614 <constant>true</constant>, the first <link
4615 linkend="NormNodeId"><literal>NormNodeId</literal></link> value in
4616 the list is returned and subsequent calls to <link
4617 linkend="NormGetNextAckingNode"><literal>NormGetNextAckingNode()</literal></link>with
4618 the <parameter>reset</parameter> parameter set to its default
4619 <constant>false</constant> value will iteratively return the
4620 remaining <link
4621 linkend="NormNodeId"><literal>NormNodeId</literal></link> values
4622 contained in the list. A value of
4623 <constant>NORM_NODE_NONE</constant> is returned when the end of the
4624 list is reached.</para>
4625
4626 <para>The "acking node" list is populated with application calls to
4627 <link
4628 linkend="NormAddAckingNode"><literal>NormAddAckingNode()</literal></link>
4629 or auto-populated if that optional behavior is set for a
4630 NormSession. Note that this API does not enable the programmer to
4631 check if the <constant>NORM_NODE_NONE</constant> value itself is
4632 contained in the list. The programmer should keep track of that by
4633 other means.</para>
4634
4635 <para>The following code example illustrates how to use this call to
4636 iterate through the set of stored <link
4637 linkend="NormNodeId"><literal>NormNodeId</literal></link> values and
4638 get the current "acking status" for each:</para>
4639
4640 <para><programlisting>NormNodeId nextNodeId = NormGetNextAckingNode(session, true);
4641 while(NORM_NODE_NONE != nextNodeId)
4642 {
4643 NormAckingStatus ackingStatus = NormGetAckingStatus(session, nextNodeId);
4644 printf("ACKing node id = %lu acking status = %d\n", nextNodeId, (int)ackingStatus);
4645 }</programlisting>As noted below, a good time to check the acking status of
4646 the receiver set is after a
4647 <constant>NORM_TX_WATERMARK_COMPLETED</constant> notification has
4648 occurred.</para>
4649 </sect4>
4650
4651 <sect4>
4652 <title>Return Values</title>
4653
4654 <para>The function iteratively returns <link
4655 linkend="NormNodeId"><literal>NormNodeId</literal></link> values
4656 from the given session's local sender "acking node" list. A value of
4657 <constant>NORM_NODE_NONE</constant> is returned when the end of the
4658 list is reached.</para>
4659 </sect4>
4660 </sect3>
4661
4662 <sect3 id="NormGetAckingStatus">
4663 <title>NormGetAckingStatus()</title>
4664
4665 <sect4>
4666 <title>Synopsis</title>
4667
4668 <programlisting>#include &lt;normApi.h&gt;
4669
4670 <link linkend="NormAckingStatus"><literal>NormAckingStatus</literal></link> <link
4671 linkend="NormGetAckingStatus"><literal>NormGetAckingStatus</literal></link>(<link
4672 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
4673 <link linkend="NormNodeId"><literal>NormNodeId</literal></link> nodeId = <literal>NORM_NODE_ANY</literal>);</programlisting>
4674 </sect4>
4675
4676 <sect4>
4677 <title>Description</title>
4678
4679 <para>This function queries the status of the watermark flushing
4680 process and/or positive acknowledgment collection initiated by a
4681 prior call to <link
4682 linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
4683 for the given <parameter>sessionHandle</parameter>. In general, it
4684 is expected that applications will invoke this function after the
4685 corresponding <literal>NORM_TX_WATERMARK_COMPLETED</literal> event
4686 has been posted. Setting the default parameter value
4687 <parameter>nodeId</parameter> = <literal>NORM_NODE_ANY</literal>
4688 returns a "status" indication for the overall process. Also,
4689 individual <parameter>nodeId</parameter> values may be queried using
4690 the <link linkend="NormNodeId"><literal>NormNodeId</literal></link>
4691 values of receivers that were included in previous calls to <link
4692 linkend="NormAddAckingNode"><literal>NormAddAckingNode()</literal></link>
4693 to populate the sender session's acking node list.</para>
4694
4695 <para>If the flushing/acknowledgment process is being used for
4696 application flow control, the sender application may wish to reset
4697 the watermark and flushing process (using <link
4698 linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>)
4699 if the response indicates that some nodes have failed to respond.
4700 However, note that the flushing/acknowledgment process itself does
4701 elicit NACKs from receivers as needed and is interrupted and reset
4702 by any repair response that occurs. Thus, even by the time the
4703 flushing process has completed (and
4704 <literal>NORM_TX_WATERMARK_COMPLETED</literal> is posted) once, this
4705 is an indication that the NORM protocol has made a valiant attempt
4706 to deliver the content. Resetting the watermark process can increase
4707 robustness, but it may be in vain to repeat this process multiple
4708 times when likely network connectivity has been lost or expected
4709 receivers have failed (dropped out, shut down, etc).</para>
4710 </sect4>
4711
4712 <sect4>
4713 <title>Return Values</title>
4714
4715 <para>Possible return values include:</para>
4716
4717 <informaltable frame="all">
4718 <tgroup cols="2">
4719 <tbody>
4720 <row>
4721 <entry><para><literal>NORM_ACK_INVALID</literal></para></entry>
4722
4723 <entry><para>The given <parameter>sessionHandle</parameter>
4724 is invalid or the given <parameter>nodeId</parameter> is not
4725 in the sender's acking list.</para></entry>
4726 </row>
4727
4728 <row>
4729 <entry><para><literal>NORM_ACK_FAILURE</literal></para></entry>
4730
4731 <entry><para>The positive acknowledgement collection process
4732 did not receive acknowledgment from every listed receiver
4733 (<parameter>nodeId</parameter> =
4734 <literal>NORM_NODE_ANY</literal>) or the identified
4735 <parameter>nodeId</parameter> did not
4736 respond.</para></entry>
4737 </row>
4738
4739 <row>
4740 <entry><para><literal>NORM_ACK_PENDING</literal></para></entry>
4741
4742 <entry><para>The flushing process at large has not yet
4743 completed (<parameter>nodeId</parameter> =
4744 <literal>NORM_NODE_ANY</literal>) or the given individual
4745 <parameter>nodeId</parameter> is still being queried for
4746 response.</para></entry>
4747 </row>
4748
4749 <row>
4750 <entry><para><literal>NORM_ACK_SUCCESS</literal></para></entry>
4751
4752 <entry><para>All receivers (<parameter>nodeId</parameter> =
4753 <literal>NORM_NODE_ANY</literal>) responded with positive
4754 acknowledgement or the given specific
4755 <parameter>nodeId</parameter> did
4756 acknowledge.</para></entry>
4757 </row>
4758 </tbody>
4759 </tgroup>
4760 </informaltable>
4761 </sect4>
4762 </sect3>
4763
4764 <sect3 id="NormSendCommand">
4765 <title>NormSendCommand()</title>
4766
4767 <sect4>
4768 <title>Synopsis</title>
4769
4770 <programlisting>#include &lt;normApi.h&gt;
4771
4772 bool <link linkend="NormSendCommand"><literal>NormSendCommand</literal></link>(<link
4773 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session,
4774 const char* cmdBuffer,
4775 unsigned int cmdLength,
4776 bool robust = false); </programlisting>
4777 </sect4>
4778
4779 <sect4>
4780 <title>Description</title>
4781
4782 <para>This function enqueues a NORM application-defined command for
4783 transmission. The <parameter>cmdBuffer</parameter> parameter points
4784 to a buffer containing the application-defined command content that
4785 will be contained in the <literal>NORM_CMD(APPLICATION)</literal>
4786 message payload. The <parameter>cmdLength</parameter> indicates the
4787 length of this content (in bytes) and MUST be less than or equal to
4788 the <parameter>segmentLength</parameter> value for the given
4789 <parameter>session</parameter> (see <link
4790 linkend="NormStartSender"><literal>NormStartSender()</literal></link>).
4791 The NORM command transmission will be multiplexed with any NORM data
4792 transmission. The command is NOT delivered reliably, but can be
4793 optionally transmitted with repetition (once per GRTT) according to
4794 the NORM transmit robust factor value (see <link
4795 linkend="NormSetTxRobustFactor"><literal>NormSetTxRobustFactor()</literal></link>)
4796 for the given session if the <parameter>robust</parameter> parameter
4797 is set to <constant>true</constant>. The command transmission is
4798 subject to any congestion control or set rate limits for the NORM
4799 session. Once the command has been transmitted (with repetition if
4800 <parameter>robust</parameter> is set to <constant>true</constant>),
4801 a <constant>NORM_TX_CMD_SENT</constant> notification is issued. An
4802 application can only enqueue a <emphasis>single</emphasis> command
4803 at a time (i.e. the <constant>NORM_TX_CMD_SENT</constant>
4804 notification must occur before another command can be sent). The
4805 <link
4806 linkend="NormCancelCommand"><literal>NormCancelCommand()</literal></link>
4807 call is available to terminate command transmission if needed. Note
4808 that if a rapid succession of commands are sent it is possible that
4809 the commands may be delivered to the receivers out-of-order. Also,
4810 when repetition is requested (i.e., if <parameter>robust</parameter>
4811 is set to <constant>true</constant>) the receiver may receive
4812 duplicate copies of the same command. It is up to the application to
4813 provide any needed mechanism for detecting and/or filtering
4814 duplicate command reception.</para>
4815
4816 <para>The application-defined command feature allows NORM
4817 applications to provide some out-of-band (with respect to reliable
4818 data delivery) signaling to support session management or other
4819 functions. The reception of these "atomic" commands is relatively
4820 stateless (as compared to reliable data delivery) and thus it is
4821 possible for many senders within a group to send commands without
4822 extreme resource burden on receivers (i.e. other participants).
4823 Again, this "light-weight" signaling mechanism may be used to
4824 provide ancillary communication for the group. In the future, an
4825 additional API mechanism will be provided to support
4826 application-defined positive acknowledgement requests that could
4827 conceivably be used to help guarantee command delivery if
4828 desired.</para>
4829 </sect4>
4830
4831 <sect4>
4832 <title>Return Values</title>
4833
4834 <para>The function returns <constant>true</constant> upon success.
4835 The function may fail, returning <constant>false</constant>, if the
4836 session is not set for sender operation (see <link
4837 linkend="NormStartSender"><literal>NormStartSender()</literal></link>),
4838 the <parameter>cmdLength</parameter> exceeds the configured session
4839 <parameter>segmentLength</parameter>, or a previously-enqueued
4840 command has not yet been sent.</para>
4841 </sect4>
4842 </sect3>
4843
4844 <sect3 id="NormCancelCommand">
4845 <title>NormCancelCommand()</title>
4846
4847 <sect4>
4848 <title>Synopsis</title>
4849
4850 <programlisting>#include &lt;normApi.h&gt;
4851
4852 void <link linkend="NormCancelCommand"><literal>NormCancelCommand</literal></link>(<link
4853 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session);</programlisting>
4854 </sect4>
4855
4856 <sect4>
4857 <title>Description</title>
4858
4859 <para>This function terminates any pending
4860 <literal>NORM_CMD(APPLICATION)</literal> transmission that was
4861 previously initiated with the <link
4862 linkend="NormSendCommand"><literal>NormSendCommand()</literal></link>
4863 call. Due to the asynchrony of the NORM protocol engine thread and
4864 the application, it is possible that the command may have been
4865 already sent but the <link
4866 linkend="NormCancelCommand"><literal>NormCancelCommand()</literal></link>
4867 call will ensure a <constant>NORM_TX_CMD_SENT</constant>
4868 notification is <emphasis>not</emphasis> issued for that prior
4869 command.</para>
4870
4871 <para>The application-defined command feature allows NORM
4872 applications to provide some out-of-band (with respect to reliable
4873 data delivery) signaling to support session management or other
4874 functions. The reception of these "atomic" commands is relatively
4875 stateless (as compared to reliable data delivery) and thus it is
4876 possible for many senders within a group to send commands without
4877 extreme resource burden on receivers (i.e. other participants).
4878 Again, this "light-weight" signaling mechanism may be used to
4879 provide ancillary communication for the group. In the future, an
4880 additional API mechanism will be provided to support
4881 application-defined positive acknowledgement requests that could
4882 conceivably be used to help guarantee command delivery if
4883 desired.</para>
4884 </sect4>
4885
4886 <sect4>
4887 <title>Return Values</title>
4888
4889 <para>The function has not return value.</para>
4890 </sect4>
4891 </sect3>
4892 </sect2>
4893
4894 <sect2>
4895 <title>NORM Receiver Functions</title>
4896
4897 <sect3 id="NormStartReceiver">
4898 <title>NormStartReceiver()</title>
4899
4900 <sect4>
4901 <title>Synopsis</title>
4902
4903 <programlisting>#include &lt;normApi.h&gt;
4904
4905 bool <link linkend="NormStartReceiver"><literal>NormStartReceiver</literal></link>(<link
4906 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
4907 unsigned long bufferSpace);</programlisting>
4908 </sect4>
4909
4910 <sect4>
4911 <title>Description</title>
4912
4913 <para>This function initiates the application's participation as a
4914 receiver within the <emphasis>NormSession</emphasis> identified by
4915 the <parameter>sessionHandle</parameter> parameter. The NORM
4916 protocol engine will begin providing the application with
4917 receiver-related <link
4918 linkend="NormEvent"><literal>NormEvent</literal></link>
4919 notifications, and, unless <link
4920 linkend="NormSetSilentReceiver"><literal>NormSetSilentReceiver</literal></link>(<constant>true</constant>)
4921 is invoked, respond to senders with appropriate protocol messages.
4922 The <parameter>bufferSpace</parameter> parameter is used to set a
4923 limit on the amount of <parameter>bufferSpace</parameter> allocated
4924 by the receiver per active <emphasis>NormSender</emphasis> within
4925 the session. The appropriate <parameter>bufferSpace</parameter> to
4926 use is a function of expected network delay*bandwidth product and
4927 packet loss characteristics. A discussion of trade-offs associated
4928 with NORM transmit and receiver buffer space selection is provided
4929 later in this document. An insufficient
4930 <parameter>bufferSpace</parameter> allocation will result in
4931 potentially inefficient protocol operation, even though reliable
4932 operation may be maintained. In some cases of a large
4933 delay*bandwidth product and/or severe packet loss, a small
4934 <parameter>bufferSpace</parameter> allocation (coupled with the lack
4935 of explicit flow control in NORM) may result in the receiver
4936 "re-syncing" to the sender, resulting in "outages" in the reliable
4937 transmissions from a sender (this is analogous to a TCP connection
4938 timeout failure).</para>
4939 </sect4>
4940
4941 <sect4>
4942 <title>Return Values</title>
4943
4944 <para>A value of <constant>true</constant> is returned upon success
4945 and <constant>false</constant> upon failure. The reasons failure may
4946 occur include limited system resources or that the network sockets
4947 required for session communication failed to open or properly
4948 configure.</para>
4949 </sect4>
4950 </sect3>
4951
4952 <sect3 id="NormStopReceiver">
4953 <title>NormStopReceiver()</title>
4954
4955 <sect4>
4956 <title>Synopsis</title>
4957
4958 <programlisting>#include &lt;normApi.h&gt;
4959
4960 void <link linkend="NormStopReceiver"><literal>NormStopReceiver</literal></link>(<link
4961 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
4962 unsigned int gracePeriod = 0);</programlisting>
4963 </sect4>
4964
4965 <sect4>
4966 <title>Description</title>
4967
4968 <para>This function ends the application's participation as a
4969 receiver in the <emphasis>NormSession</emphasis> specified by the
4970 session parameter. By default, all receiver-related protocol
4971 activity is immediately halted and all receiver-related resources
4972 are freed (except for those which have been specifically retained
4973 (see <link
4974 linkend="NormNodeRetain"><literal>NormNodeRetain()</literal></link>
4975 and <link
4976 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>).
4977 However, and optional <parameter>gracePeriod</parameter> parameter
4978 is provided to allow the receiver an opportunity to inform the group
4979 of its intention. This is applicable when the local receiving
4980 <emphasis>NormNode</emphasis> has been designated as an active
4981 congestion control representative (i.e. current limiting receiver
4982 (CLR) or potential limiting receiver (PLR)). In this case, a
4983 non-zero <parameter>gracePeriod</parameter> value provides an
4984 opportunity for the receiver to respond to the applicable sender(s)
4985 so the sender will not expect further congestion control feedback
4986 from this receiver. The <parameter>gracePeriod</parameter> integer
4987 value is used as a multiplier with the largest sender GRTT to
4988 determine the actual time period for which the receiver will linger
4989 in the group to provide such feedback (i.e. <literal>"graceTime" =
4990 (<parameter>gracePeriod</parameter> * GRTT)</literal>). During this
4991 time, the receiver will not generate any requests for repair or
4992 other protocol actions aside from response to applicable congestion
4993 control probes. When the receiver is removed from the current list
4994 of receivers in the sender congestion control probe messages (or the
4995 <parameter>gracePeriod</parameter> expires, whichever comes first),
4996 the NORM protocol engine will post a
4997 <literal>NORM_LOCAL_RECEIVER_CLOSED</literal> event for the
4998 applicable session, and related resources are then freed.</para>
4999 </sect4>
5000
5001 <sect4>
5002 <title>Return Values</title>
5003
5004 <para>This function has no return values.</para>
5005 </sect4>
5006 </sect3>
5007
5008 <sect3 id="NormSetRxCacheLimit">
5009 <title>NormSetRxCacheLimit()</title>
5010
5011 <sect4>
5012 <title>Synopsis</title>
5013
5014 <programlisting>#include &lt;normApi.h&gt;
5015
5016 void <link linkend="NormSetRxCacheLimit"><literal>NormSetRxCacheLimit</literal></link>(<link
5017 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
5018 unsigned short countMax);</programlisting>
5019 </sect4>
5020
5021 <sect4>
5022 <title>Description</title>
5023
5024 <para>This function sets a limit on the number of outstanding
5025 (pending) <emphasis>NormObjects</emphasis> for which a receiver will
5026 keep state on a per-sender basis. Note that the value
5027 <parameter>countMax</parameter> sets a limit on the maximum
5028 consecutive range of objects that can be pending. The default value
5029 (when this function is not called) of
5030 <parameter>countMax</parameter> is <constant>256</constant>. This
5031 should be sufficient for most bulk transfer usage, but if small
5032 object sizes (e.g. small <constant>NORM_OBJECT_DATA</constant>
5033 messages) are being transferred, it may be useful to raise this
5034 limit in cases of high transmission speeds or large
5035 &lt;delay*bandwidth, loss&gt; network conditions. If the receiver
5036 cache limit is set too small (i.e. for high speed or large
5037 &lt;delay*bandwidth&gt; operation), the receiver may not maintain
5038 reliable reception or impact session throughput when flow control is
5039 enabled (see <link
5040 linkend="NormSetFlowControl"><literal>NormSetFlowControl()</literal></link>).
5041 The maximum allowed value of <parameter>countMax</parameter> is
5042 <constant>16,384.</constant></para>
5043
5044 <para>If this value is changed after <link
5045 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
5046 has been called, it will only affect newly-detected remote senders,
5047 so this should typically be called before NORM receiver operation is
5048 initiated.</para>
5049 </sect4>
5050
5051 <sect4>
5052 <title>Return Values</title>
5053
5054 <para>This function has no return value.</para>
5055 </sect4>
5056 </sect3>
5057
5058 <sect3 id="NormSetRxSocketBuffer">
5059 <title>NormSetRxSocketBuffer()</title>
5060
5061 <sect4>
5062 <title>Synopsis</title>
5063
5064 <programlisting>#include &lt;normApi.h&gt;
5065
5066 bool <link linkend="NormSetRxSocketBuffer"><literal>NormSetRxSocketBuffer</literal></link>(<link
5067 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
5068 unsigned int bufferSize);</programlisting>
5069 </sect4>
5070
5071 <sect4>
5072 <title>Description</title>
5073
5074 <para>This function allows the application to set an alternative,
5075 non-default buffer size for the UDP socket used by the specified
5076 NORM <parameter>sessionHandle</parameter> for packet reception. This
5077 may be necessary for high speed NORM sessions where the UDP receive
5078 socket buffer becomes a bottleneck when the NORM protocol engine
5079 (which is running as a user-space process) doesn't get to service
5080 the receive socket quickly enough resulting in packet loss when the
5081 socket buffer overflows. The <parameter>bufferSize</parameter>
5082 parameter specifies the socket buffer size in bytes. Different
5083 operating systems and sometimes system configurations allow
5084 different ranges of socket buffer sizes to be set. Note that a call
5085 to <link
5086 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
5087 (or <link
5088 linkend="NormStartSender"><literal>NormStartSender()</literal></link>)
5089 must have been previously made for this call to succeed (i.e., the
5090 socket must be already open).</para>
5091 </sect4>
5092
5093 <sect4>
5094 <title>Return Values</title>
5095
5096 <para>This function returns <constant>true</constant> upon success
5097 and <constant>false</constant> upon failure. Possible reasons for
5098 failure include, 1) the specified session is not valid, 2) that NORM
5099 "receiver" (or "sender") operation has not yet been started for the
5100 given session, or 3) an invalid <parameter>bufferSize</parameter>
5101 specification was given.</para>
5102 </sect4>
5103 </sect3>
5104
5105 <sect3 id="NormSetSilentReceiver">
5106 <title>NormSetSilentReceiver()</title>
5107
5108 <sect4>
5109 <title>Synopsis</title>
5110
5111 <programlisting>#include &lt;normApi.h&gt;
5112
5113 void <link linkend="NormSetSilentReceiver"><literal>NormSetSilentReceiver</literal></link>(<link
5114 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
5115 bool silent,
5116 INT32 maxDelay = -1);</programlisting>
5117 </sect4>
5118
5119 <sect4>
5120 <title>Description</title>
5121
5122 <para>This function provides the option to configure a NORM receiver
5123 application as a "silent receiver". This mode of receiver operation
5124 dictates that the host does not generate any protocol messages while
5125 operating as a receiver within the specified
5126 <parameter>sessionHandle</parameter>. Setting the
5127 <parameter>silent</parameter> parameter to <constant>true</constant>
5128 enables silent receiver operation while setting it to
5129 <constant>false</constant> results in normal protocol operation
5130 where feedback is provided as needed for reliability and protocol
5131 operation. Silent receivers are dependent upon proactive FEC
5132 transmission (see <link
5133 linkend="NormSetAutoParity"><literal>NormSetAutoParity()</literal></link>)
5134 or using repair information requested by other non-silent receivers
5135 within the group to achieve reliable transfers.</para>
5136
5137 <para>The optional <parameter>maxDelay</parameter> parameter is most
5138 applicable for reception of the
5139 <literal>NORM_OBJECT_STREAM</literal> type. The default value of
5140 <parameter>maxDelay</parameter> <literal>=</literal>
5141 <constant>-1</constant> corresponds to normal operation where source
5142 data segments for incompletely-received FEC coding blocks (or
5143 transport objects) are passed to the application only when imposed
5144 buffer constraints (either the <literal>NORM_OBJECT_STREAM</literal>
5145 buffer size (see <link
5146 linkend="NormStreamOpen"><literal>NormStreamOpen()</literal></link>)
5147 or the FEC receive buffer limit (see <link
5148 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>)
5149 require. Thus, the default behavior (<parameter>maxDelay</parameter>
5150 <literal>=</literal> <constant>-1</constant>), causes the receiver
5151 to buffer received FEC code blocks for as long as possible (within
5152 buffer constraints as newer data arrives) before allowing the
5153 application to read the data. Hence, the receive latency (delay) can
5154 be quite long depending upon buffer size settings, transmission
5155 rate, etc. When the <constant>maxDelay</constant> parameter is set
5156 to a non-negative value, the value determines the maximum number of
5157 FEC coding blocks (according to a NORM sender's current transmit
5158 position) the receiver will cache an incompletely-received FEC block
5159 before giving the application the (incomplete) set of received
5160 source segments. For example, a value of
5161 <parameter>maxDelay</parameter> <literal>=</literal>
5162 <constant>0</constant> will provide the receive application with any
5163 data from the previous FEC block as soon as a subsequent FEC block
5164 is begun reception. However, this provide no protection against the
5165 possibility of out-of-order delivery of packets by the network.
5166 Therefore, if lower latency operation is desired when using silent
5167 receivers, a minimum <parameter>maxDelay</parameter> value of
5168 <constant>1</constant> is recommended. For
5169 <literal>NORM_OBJECT_FILE</literal> and
5170 <literal>NORM_OBJECT_DATA</literal>, the only impact of a
5171 non-negative <parameter>maxDelay</parameter> value is that previous
5172 transport objects will be immediately aborted when subsequent object
5173 begin reception. Thus, it is not usually recommended to apply a
5174 non-negative <parameter>maxDelay</parameter> value when
5175 <literal>NORM_OBJECT_STREAM</literal> is not being used.</para>
5176 </sect4>
5177
5178 <sect4>
5179 <title>Return Values</title>
5180
5181 <para>This function has no return values.</para>
5182 </sect4>
5183 </sect3>
5184
5185 <sect3 id="NormSetDefaultUnicastNack">
5186 <title>NormSetDefaultUnicastNack()</title>
5187
5188 <sect4>
5189 <title>Synopsis</title>
5190
5191 <programlisting>#include &lt;normApi.h&gt;
5192
5193 void <link linkend="NormSetDefaultUnicastNack"><literal>NormSetDefaultUnicastNack</literal></link>(<link
5194 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
5195 bool enable);</programlisting>
5196 </sect4>
5197
5198 <sect4>
5199 <title>Description</title>
5200
5201 <para>This function controls the default behavior determining the
5202 destination of receiver feedback messages generated while
5203 participating in the session. If the <parameter>enable</parameter>
5204 parameter is true, "unicast NACKing" is enabled for new remote
5205 senders while it is disabled for state equal to false. The NACKing
5206 behavior for current remote senders is not affected. When "unicast
5207 NACKing" is disabled (default), NACK messages are sent to the
5208 session address (usually a multicast address) and port, but when
5209 "unicast NACKing" is enabled, receiver feedback messages are sent to
5210 the unicast address (and port) based on the source address of sender
5211 messages received. For unicast NORM sessions, it is recommended that
5212 "unicast NACKing" be enabled. Note that receiver feedback messages
5213 subject to potential "unicast NACKing" include NACK-messages as well
5214 as some ACK messages such as congestion control feedback. Explicitly
5215 solicited ACK messages, such as those used to satisfy sender
5216 watermark acknowledgement requests (see <link
5217 linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>)
5218 are always unicast to the applicable sender. (<emphasis>TBD -
5219 provide API option so that all messages are multicast.</emphasis>)
5220 The default session-wide behavior for unicast NACKing can be
5221 overridden via the <link
5222 linkend="NormNodeSetUnicastNack"><literal>NormNodeSetUnicastNack()</literal></link>
5223 function for individual remote senders.</para>
5224 </sect4>
5225
5226 <sect4>
5227 <title>Return Values</title>
5228
5229 <para>This function has no return values.</para>
5230 </sect4>
5231 </sect3>
5232
5233 <sect3 id="NormNodeSetUnicastNack">
5234 <title>NormNodeSetUnicastNack()</title>
5235
5236 <sect4>
5237 <title>Synopsis</title>
5238
5239 <programlisting>#include &lt;normApi.h&gt;
5240
5241 void <link linkend="NormNodeSetUnicastNack"><literal>NormNodeSetUnicastNack</literal></link>(<link
5242 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> senderNode,
5243 bool enable);</programlisting>
5244 </sect4>
5245
5246 <sect4>
5247 <title>Description</title>
5248
5249 <para>This function controls the destination address of receiver
5250 feedback messages generated in response to a specific remote NORM
5251 sender corresponding to the <parameter>senderNode</parameter>
5252 parameter. If <parameter>enable</parameter> is
5253 <constant>true</constant>, "unicast NACKing" is enabled while it is
5254 disabled for <parameter>enable</parameter> equal to
5255 <constant>false</constant>. See the description of <link
5256 linkend="NormSetDefaultUnicastNack"><literal>NormSetDefaultUnicastNack()</literal></link>
5257 for details on "unicast NACKing" behavior.</para>
5258 </sect4>
5259
5260 <sect4>
5261 <title>Return Values</title>
5262
5263 <para>This function has no return values.</para>
5264 </sect4>
5265 </sect3>
5266
5267 <sect3 id="NormSetDefaultSyncPolicy">
5268 <title>NormSetDefaultSyncPolicy()</title>
5269
5270 <sect4>
5271 <title>Synopsis</title>
5272
5273 <programlisting>#include &lt;normApi.h&gt;
5274
5275 void <link linkend="NormSetDefaultSyncPolicy"><literal>NormSetDefaultSyncPolicy</literal></link>(<link
5276 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
5277 <link linkend="NormSyncPolicy"><literal>NormSyncPolicy</literal></link> syncPolicy);</programlisting>
5278 </sect4>
5279
5280 <sect4>
5281 <title>Description</title>
5282
5283 <para>This function sets the default "synchronization policy" used
5284 when beginning (or restarting) reception of objects from a remote
5285 sender (i.e., "syncing" to the sender) for the given
5286 <parameter>sessionHandle</parameter>. The "synchronization policy"
5287 is the behavior observed by the receiver with regards to what
5288 objects it attempts to reliably receive (via transmissions of
5289 Negative Acknowledgements to the sender(s) or group as needed).
5290 There are currently two synchronization policy types defined:</para>
5291
5292 <informaltable frame="all">
5293 <tgroup cols="2">
5294 <tbody>
5295 <row>
5296 <entry><para><literal>NORM_SYNC_CURRENT</literal></para></entry>
5297
5298 <entry><para>Attempt reception of "current" and new objects
5299 only. (default)</para></entry>
5300 </row>
5301
5302 <row>
5303 <entry><para><literal>NORM_SYNC_ALL</literal></para></entry>
5304
5305 <entry><para>Attempt recovery and reliable reception of all
5306 objects held in sender transmit object cache and newer
5307 objects.</para></entry>
5308 </row>
5309 </tbody>
5310 </tgroup>
5311 </informaltable>
5312
5313 <para>The behavior of a receiver using the default
5314 <constant>NORM_SYNC_CURRENT</constant> policy is to attempt reliable
5315 reception only for the first received "current" and newer (with
5316 respect to the ordinal NORM object transport identifiers used by the
5317 protocol) objects from a given NORM sender. Additionally, reliable
5318 reception is only attempted when receiving a non-repair
5319 <literal>NORM_DATA</literal> message (or optionally a NORM positive
5320 acknowledgement request) from the <emphasis>first</emphasis> forward
5321 error correction (FEC) encoding block of the given object. This
5322 somewhat conservative synchronization behavior helps prevent
5323 late-joining (or otherwise "flaky" with respect to group membership)
5324 receivers from penalizing other receivers in the group by causing
5325 the sender to "rewind" and transmit older object content to satisfy
5326 the late joiner instead of moving forward with transmission of new
5327 content. For large scale, loosely-organized multicast applications,
5328 the <constant>NORM_SYNC_CURRENT</constant> policy is typically
5329 recommended.</para>
5330
5331 <para>The <constant>NORM_SYNC_ALL</constant> policy allows newly
5332 joining receivers much more aggressive behavior as they will
5333 immediately NACK for all objects from the "current" object backwards
5334 through the entire range of objects set by the <link
5335 linkend="NormSetRxCacheLimit"><literal>NormSetRxCacheLimit()</literal></link>
5336 function. This behavior depends upon the sender to issue an
5337 appropriate <literal>NORM_CMD(SQUELCH)</literal> response (if
5338 applicable) to align (i.e. "synchronize") the new receiver with its
5339 current transmit object cache (similar to a "repair window"). This
5340 synchronization behavior may be useful for unicast uses of NORM or
5341 other applications where the group membership is more carefully
5342 managed and it is important that all content (including older
5343 content) is received. Note that the sender transmit cache bounds
5344 (see <link
5345 linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>)
5346 and the receiver receive cache limit (see <link
5347 linkend="NormSetRxCacheLimit"><literal>NormSetRxCacheLimit()</literal></link>)
5348 settings will limit how far back onto the sender transmission
5349 history that transmitted objects can be reliably recovered from the
5350 "current" transmission point when the receiver begins
5351 reception.</para>
5352
5353 <para>When this function is not invoked, the
5354 <constant>NORM_SYNC_CURRENT</constant> behavior is observed as the
5355 default receiver synchronization policy. This call SHOULD be made
5356 before <link
5357 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
5358 is called.</para>
5359 </sect4>
5360
5361 <sect4>
5362 <title>Return Values</title>
5363
5364 <para>This function has no return values.</para>
5365 </sect4>
5366 </sect3>
5367
5368 <sect3 id="NormSetDefaultNackingMode">
5369 <title>NormSetDefaultNackingMode()</title>
5370
5371 <sect4>
5372 <title>Synopsis</title>
5373
5374 <programlisting>#include &lt;normApi.h&gt;
5375
5376 void <link linkend="NormSetDefaultNackingMode"><literal>NormSetDefaultNackingMode</literal></link>(<link
5377 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
5378 <link linkend="NormNackingMode"><literal>NormNackingMode</literal></link> nackingMode);</programlisting>
5379 </sect4>
5380
5381 <sect4>
5382 <title>Description</title>
5383
5384 <para>This function sets the default "nacking mode" used when
5385 receiving objects for the given
5386 <parameter>sessionHandle</parameter>. This allows the receiver
5387 application some control of its degree of participation in the
5388 repair process. By limiting receivers to only request repair of
5389 objects in which they are really interested in receiving, some
5390 overall savings in unnecessary network loading might be realized for
5391 some applications and users. Available nacking modes include:</para>
5392
5393 <informaltable frame="all">
5394 <tgroup cols="2">
5395 <tbody>
5396 <row>
5397 <entry><para><literal>NORM_NACK_NONE</literal></para></entry>
5398
5399 <entry><para>Do not transmit any repair requests for the
5400 newly received object.</para></entry>
5401 </row>
5402
5403 <row>
5404 <entry><para><literal>NORM_NACK_INFO_ONLY</literal></para></entry>
5405
5406 <entry><para>Transmit repair requests for
5407 <literal>NORM_INFO</literal> content only as
5408 needed.</para></entry>
5409 </row>
5410
5411 <row>
5412 <entry><para><literal>NORM_NACK_NORMAL</literal></para></entry>
5413
5414 <entry><para>Transmit repair requests for entire object as
5415 needed.</para></entry>
5416 </row>
5417 </tbody>
5418 </tgroup>
5419 </informaltable>
5420
5421 <para>This function specifies the default behavior with respect to
5422 any new sender or object. This default behavior may be overridden
5423 for specific sender nodes or specific object using <link
5424 linkend="NormNodeSetNackingMode"><literal>NormNodeSetNackingMode()</literal></link>
5425 or <link
5426 linkend="NormObjectSetNackingMode"><literal>NormObjectSetNackingMode()</literal></link>,
5427 respectively. The receiver application's use of
5428 <literal>NORM_NACK_NONE</literal> essentially disables a guarantee
5429 of reliable reception, although the receiver may still take
5430 advantage of sender repair transmissions in response to other
5431 receivers' requests. When the sender provides,
5432 <literal>NORM_INFO</literal> content for transmitted objects, the
5433 <literal>NORM_NACK_INFO_ONLY</literal> mode may allows the receiver
5434 to reliably receive object context information from which it may
5435 choose to "upgrade" its <parameter>nackingMode</parameter> for the
5436 specific object via the <link
5437 linkend="NormObjectSetNackingMode"><literal>NormObjectSetNackingMode()</literal></link>
5438 call. Similarly, the receiver may changes its default
5439 <parameter>nackingMode</parameter> with respect to specific senders
5440 via the <link
5441 linkend="NormNodeSetNackingMode"><literal>NormNodeSetNackingMode()</literal></link>
5442 call. The default "default <parameter>nackingMode</parameter>" when
5443 this call is not made is <literal>NORM_NACK_NORMAL</literal>.</para>
5444 </sect4>
5445
5446 <sect4>
5447 <title>Return Values</title>
5448
5449 <para>This function has no return values.</para>
5450 </sect4>
5451 </sect3>
5452
5453 <sect3 id="NormNodeSetNackingMode">
5454 <title>NormNodeSetNackingMode()</title>
5455
5456 <sect4>
5457 <title>Synopsis</title>
5458
5459 <programlisting>#include &lt;normApi.h&gt;
5460
5461 void <link linkend="NormNodeSetNackingMode"><literal>NormNodeSetNackingMode</literal></link>(<link
5462 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle,
5463 <link linkend="NormNackingMode"><literal>NormNackingMode</literal></link> nackingMode);</programlisting>
5464 </sect4>
5465
5466 <sect4>
5467 <title>Description</title>
5468
5469 <para>This function sets the default "nacking mode" used for
5470 receiving new objects from a specific sender as identified by the
5471 <parameter>nodeHandle</parameter> parameter. This overrides the
5472 default <parameter>nackingMode</parameter> set for the receive
5473 session. See <link
5474 linkend="NormSetDefaultNackingMode"><literal>NormSetDefaultNackingMode()</literal></link>
5475 for a description of possible <parameter>nackingMode</parameter>
5476 parameter values and other related information.</para>
5477 </sect4>
5478
5479 <sect4>
5480 <title>Return Values</title>
5481
5482 <para>This function has no return values.</para>
5483 </sect4>
5484 </sect3>
5485
5486 <sect3 id="NormObjectSetNackingMode">
5487 <title>NormObjectSetNackingMode()</title>
5488
5489 <sect4>
5490 <title>Synopsis</title>
5491
5492 <programlisting>#include &lt;normApi.h&gt;
5493
5494 void <link linkend="NormObjectSetNackingMode"><literal>NormObjectSetNackingMode</literal></link>(<link
5495 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle,
5496 <link linkend="NormNackingMode"><literal>NormNackingMode</literal></link> nackingMode);</programlisting>
5497 </sect4>
5498
5499 <sect4>
5500 <title>Description</title>
5501
5502 <para>This function sets the "nacking mode" used for receiving a
5503 specific transport object as identified by the
5504 <parameter>objectHandle</parameter> parameter. This overrides the
5505 default nacking mode set for the applicable sender node. See <link
5506 linkend="NormSetDefaultNackingMode"><literal>NormSetDefaultNackingMode()</literal></link>
5507 for a description of possible <parameter>nackingMode</parameter>
5508 parameter values and other related information.</para>
5509 </sect4>
5510
5511 <sect4>
5512 <title>Return Values</title>
5513
5514 <para>This function has no return values.</para>
5515 </sect4>
5516 </sect3>
5517
5518 <sect3 id="NormSetDefaultRepairBoundary">
5519 <title>NormSetDefaultRepairBoundary()</title>
5520
5521 <sect4>
5522 <title>Synopsis</title>
5523
5524 <programlisting>#include &lt;normApi.h&gt;
5525
5526 void <link linkend="NormSetDefaultRepairBoundary"><literal>NormSetDefaultRepairBoundary</literal></link>(<link
5527 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
5528 <link linkend="NormRepairBoundary"><literal>NormRepairBoundary</literal></link> repairBoundary);</programlisting>
5529 </sect4>
5530
5531 <sect4>
5532 <title>Description</title>
5533
5534 <para>This function allows the receiver application to customize,
5535 for a given <parameter>sessionHandle</parameter>, at what points the
5536 receiver initiates the NORM NACK repair process during protocol
5537 operation. Normally, the NORM receiver initiates NACKing for repairs
5538 at the FEC code block and transport object boundaries. For smaller
5539 block sizes, the NACK repair process is often/quickly initiated and
5540 the repair of an object will occur, as needed, during the
5541 transmission of the object. This default operation corresponds to
5542 <parameter>repairBoundary</parameter> equal to
5543 <literal>NORM_BOUNDARY_BLOCK</literal>. Using this function, the
5544 application may alternatively, setting
5545 <parameter>repairBoundary</parameter> equal to
5546 <literal>NORM_BOUNDARY_OBJECT</literal>, cause the protocol to defer
5547 NACK process initiation until the current transport object has been
5548 completely transmitted.</para>
5549 </sect4>
5550
5551 <sect4>
5552 <title>Return Values</title>
5553
5554 <para>This function has no return values.</para>
5555 </sect4>
5556 </sect3>
5557
5558 <sect3 id="NormNodeSetRepairBoundary">
5559 <title>NormNodeSetRepairBoundary()</title>
5560
5561 <sect4>
5562 <title>Synopsis</title>
5563
5564 <programlisting>#include &lt;normApi.h&gt;
5565
5566 void <link linkend="NormNodeSetRepairBoundary"><literal>NormNodeSetRepairBoundary</literal></link>(<link
5567 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle,
5568 <link linkend="NormRepairBoundary"><literal>NormRepairBoundary</literal></link> repairBoundary);</programlisting>
5569 </sect4>
5570
5571 <sect4>
5572 <title>Description</title>
5573
5574 <para>This function allows the receiver application to customize,
5575 for the specific remote sender referenced by the
5576 <parameter>nodeHandle</parameter> parameter, at what points the
5577 receiver initiates the NORM NACK repair process during protocol
5578 operation. See the description of <link
5579 linkend="NormSetDefaultRepairBoundary"><literal>NormSetDefaultRepairBoundary()</literal></link>
5580 for further details on the impact of setting the NORM receiver
5581 repair boundary and possible values for the
5582 <parameter>repairBoundary</parameter> parameter.</para>
5583 </sect4>
5584
5585 <sect4>
5586 <title>Return Values</title>
5587
5588 <para>This function has no return values.</para>
5589 </sect4>
5590 </sect3>
5591
5592 <sect3 id="NormSetDefaultRxRobustFactor">
5593 <title>NormSetDefaultRxRobustFactor()</title>
5594
5595 <sect4>
5596 <title>Synopsis</title>
5597
5598 <programlisting>#include &lt;normApi.h&gt;
5599
5600 void <link linkend="NormSetDefaultRxRobustFactor"><literal>NormSetDefaultRxRobustFactor</literal></link>(<link
5601 linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
5602 int rxRobustFactor);</programlisting>
5603 </sect4>
5604
5605 <sect4>
5606 <title>Description</title>
5607
5608 <para>This routine controls how persistently NORM receivers will
5609 maintain state for sender(s) and continue to request repairs from
5610 the sender(s) even when packet reception has ceased. The
5611 <parameter>rxRobustFactor</parameter> value determines how many
5612 times a NORM receiver will self-initiate NACKing (repair requests)
5613 upon cessation of packet reception from a sender. The default value
5614 is <constant>20</constant>. Setting
5615 <parameter>rxRobustFactor</parameter> to <constant>-1</constant>
5616 will make the NORM receiver infinitely persistent (i.e., it will
5617 continue to NACK indefinitely as long as it is missing data
5618 content). It is important to note that the <link
5619 linkend="NormSetTxRobustFactor"><literal>NormSetTxRobustFactor()</literal></link>
5620 also affects receiver operation in setting the time interval that is
5621 used to gauge that sender packet transmission has ceased (i.e., the
5622 sender inactivity timeout). This "timeout" interval is a equal of
5623 (<literal><constant>2</constant> * GRTT *
5624 <parameter>txRobustFactor</parameter></literal>). Thus the overall
5625 timeout before a NORM receiver quits NACKing is
5626 (<literal><parameter>rxRobustFactor</parameter> *
5627 <constant>2</constant> * GRTT *
5628 <parameter>txRobustFactor</parameter></literal>).</para>
5629
5630 <para>The <link
5631 linkend="NormNodeSetRxRobustFactor"><literal>NormNodeSetRxRobustFactor()</literal></link>
5632 function can be used to control this behavior on a per-sender basis.
5633 When a new remote sender is detected, the default
5634 <parameter>rxRobustFactor</parameter> set here is used. Again, the
5635 default value is <constant>20</constant>.</para>
5636 </sect4>
5637
5638 <sect4>
5639 <title>Return Values</title>
5640
5641 <para>This function has no return values.</para>
5642 </sect4>
5643 </sect3>
5644
5645 <sect3 id="NormNodeSetRxRobustFactor">
5646 <title>NormNodeSetRxRobustFactor()</title>
5647
5648 <sect4>
5649 <title>Synopsis</title>
5650
5651 <programlisting>#include &lt;normApi.h&gt;
5652
5653 void <link linkend="NormNodeSetRxRobustFactor"><literal>NormNodeSetRxRobustFactor</literal></link>(<link
5654 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle,
5655 int rxRobustFactor);</programlisting>
5656 </sect4>
5657
5658 <sect4>
5659 <title>Description</title>
5660
5661 <para>This routine sets the <parameter>rxRobustFactor</parameter> as
5662 described in <link
5663 linkend="NormSetDefaultRxRobustFactor"><literal>NormSetDefaultRxRobustFactor()</literal></link>
5664 for an individual remote sender identified by the
5665 <parameter>nodeHandle</parameter> parameter. See the description of
5666 <link
5667 linkend="NormSetDefaultRxRobustFactor"><literal>NormSetDefaultRxRobustFactor()</literal></link>
5668 for details</para>
5669 </sect4>
5670
5671 <sect4>
5672 <title>Return Values</title>
5673
5674 <para>This function has no return values.</para>
5675 </sect4>
5676 </sect3>
5677
5678 <sect3 id="NormStreamRead">
5679 <title>NormStreamRead()</title>
5680
5681 <sect4>
5682 <title>Synopsis</title>
5683
5684 <programlisting>#include &lt;normApi.h&gt;
5685
5686 bool <link linkend="NormStreamRead"><literal>NormStreamRead</literal></link>(<link
5687 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle,
5688 char* buffer
5689 unsigned int* numBytes);</programlisting>
5690 </sect4>
5691
5692 <sect4>
5693 <title>Description</title>
5694
5695 <para>This function can be used by the receiver application to read
5696 any available data from an incoming NORM stream. NORM receiver
5697 applications "learn" of available NORM streams via
5698 <literal>NORM_RX_OBJECT_NEW</literal> notification events. The
5699 <parameter>streamHandle</parameter> parameter here must correspond
5700 to a valid <link
5701 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
5702 value provided during such a prior
5703 <literal>NORM_RX_OBJECT_NEW</literal> notification. The
5704 <parameter>buffer</parameter> parameter must be a pointer to an
5705 array where the received data can be stored of a length as
5706 referenced by the <parameter>numBytes</parameter> pointer. On
5707 successful completion, the <parameter>numBytes</parameter> storage
5708 will be modified to indicate the actual number of bytes copied into
5709 the provided <parameter>buffer</parameter>. If the
5710 <parameter>numBytes</parameter> storage is modified to a zero value,
5711 this indicates that no stream data was currently available for
5712 reading.</para>
5713
5714 <para>Note that <link
5715 linkend="NormStreamRead"><literal>NormStreamRead()</literal></link>
5716 is never a blocking call and only returns failure
5717 (<constant>false</constant>) when a break in the integrity of the
5718 received stream occurs. The <literal>NORM_RX_OBJECT_UPDATE</literal>
5719 provides an indication to when there is stream data available for
5720 reading. When such notification occurs, the application should
5721 repeatedly read from the stream until the
5722 <parameter>numBytes</parameter> storage is set to zero, even if a
5723 <constant>false</constant> value is returned. Additional
5724 <literal>NORM_RX_OBJECT_UPDATE</literal> notifications might not be
5725 posted until the application has read all available data.</para>
5726 </sect4>
5727
5728 <sect4>
5729 <title>Return Values</title>
5730
5731 <para>This function normally returns a value of
5732 <constant>true</constant>. However, if a break in the integrity of
5733 the reliable received stream occurs (or the stream has been ended by
5734 the sender), a value of <constant>false</constant> is returned to
5735 indicate the break. Unless the stream has been ended (and the
5736 receiver application will receive
5737 <literal>NORM_RX_OBJECT_COMPLETED</literal> notification for the
5738 stream in that case), the application may continue to read from the
5739 stream as the NORM protocol will automatically "resync" to streams,
5740 even if network conditions are sufficiently poor that breaks in
5741 reliability occur. If such a "break" and "resync" occurs, the
5742 application may be able to leverage other NORM API calls such as
5743 <link
5744 linkend="NormStreamSeekMsgStart"><literal>NormStreamSeekMsgStart()</literal></link>
5745 or <link
5746 linkend="NormStreamGetReadOffset"><literal>NormStreamGetReadOffset()</literal></link>
5747 if needed to recover its alignment with received stream content.
5748 This depends upon the nature of the application and its stream
5749 content.</para>
5750 </sect4>
5751 </sect3>
5752
5753 <sect3 id="NormStreamSeekMsgStart">
5754 <title>NormStreamSeekMsgStart()</title>
5755
5756 <sect4>
5757 <title>Synopsis</title>
5758
5759 <programlisting>#include &lt;normApi.h&gt;
5760
5761 bool <link linkend="NormStreamSeekMsgStart"><literal>NormStreamSeekMsgStart</literal></link>(<link
5762 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle);</programlisting>
5763 </sect4>
5764
5765 <sect4>
5766 <title>Description</title>
5767
5768 <para>This function advances the read offset of the receive stream
5769 referenced by the <parameter>streamHandle</parameter> parameter to
5770 align with the next available message boundary. Message boundaries
5771 are defined by the sender application using the <link
5772 linkend="NormStreamMarkEom"><literal>NormStreamMarkEom()</literal></link>
5773 call. Note that any received data prior to the next message boundary
5774 is discarded by the NORM protocol engine and is not available to the
5775 application (i.e., there is currently no "rewind" function for a
5776 NORM stream). Also note this call cannot be used to skip messages.
5777 Once a valid message boundary is found, the application must read
5778 from the stream using <link
5779 linkend="NormStreamRead"><literal>NormStreamRead()</literal></link>
5780 to further advance the read offset. The current offset (in bytes)
5781 for the stream can be retrieved via <link
5782 linkend="NormStreamGetReadOffset"><literal>NormStreamGetReadOffset()</literal></link>.</para>
5783 </sect4>
5784
5785 <sect4>
5786 <title>Return Values</title>
5787
5788 <para>This function returns a value of <constant>true</constant>
5789 when start-of-message is found. The next call to <link
5790 linkend="NormStreamRead"><literal>NormStreamRead()</literal></link>
5791 will retrieve data aligned with the message start. If no new message
5792 boundary is found in the buffered receive data for the stream, the
5793 function returns a value of <constant>false</constant>. In this
5794 case, the application should defer repeating a call to this function
5795 until a subsequent <literal>NORM_RX_OBJECT_UPDATE</literal>
5796 notification is posted.</para>
5797 </sect4>
5798 </sect3>
5799
5800 <sect3 id="NormStreamGetReadOffset">
5801 <title>NormStreamGetReadOffset()</title>
5802
5803 <sect4>
5804 <title>Synopsis</title>
5805
5806 <programlisting>#include &lt;normApi.h&gt;
5807
5808 unsigned long <link linkend="NormStreamGetReadOffset"><literal>NormStreamGetReadOffset</literal></link>(<link
5809 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle);</programlisting>
5810 </sect4>
5811
5812 <sect4>
5813 <title>Description</title>
5814
5815 <para>This function retrieves the current read offset value for the
5816 receive stream indicated by the <parameter>streamHandle</parameter>
5817 parameter. Note that for very long-lived streams, this value may
5818 wrap. Thus, in general, applications should not be highly dependent
5819 upon the stream offset, but this feature may be valuable for certain
5820 applications which associate some application context with stream
5821 position.</para>
5822 </sect4>
5823
5824 <sect4>
5825 <title>Return Values</title>
5826
5827 <para>This function returns the current read offset in bytes. The
5828 return value is undefined for sender streams. There is no error
5829 result.</para>
5830 </sect4>
5831 </sect3>
5832 </sect2>
5833
5834 <sect2>
5835 <title>NORM Object Functions</title>
5836
5837 <para>The functions described in this section may be used for sender or
5838 receiver purposes to manage transmission and reception of NORM transport
5839 objects. In most cases, the receiver will be the typical user of these
5840 functions to retrieve additional information on newly-received objects.
5841 All of these functions require a valid <link
5842 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
5843 argument which specifies the applicable object. Note that <link
5844 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
5845 values obtained from a <link
5846 linkend="NormEvent"><literal>NormEvent</literal></link> notification may
5847 be considered valid only until a subsequent call to <link
5848 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>,
5849 unless explicitly retained by the application (see <link
5850 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>).
5851 <link
5852 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
5853 values obtained as a result of <link
5854 linkend="NormFileEnqueue"><literal>NormFileEnqueue()</literal></link>,
5855 <link
5856 linkend="NormDataEnqueue"><literal>NormDataEnqueue()</literal></link>,
5857 or <link
5858 linkend="NormStreamOpen"><literal>NormStreamOpen()</literal></link>
5859 calls can be considered valid only until a corresponding
5860 <literal>NORM_TX_OBJECT_PURGED</literal> notification is posted or the
5861 object is dequeued using <link
5862 linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>,
5863 unless, again, otherwise explicitly retained (see <link
5864 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>).</para>
5865
5866 <sect3 id="NormObjectGetType">
5867 <title>NormObjectGetType()</title>
5868
5869 <sect4>
5870 <title>Synopsis</title>
5871
5872 <programlisting>#include &lt;normApi.h&gt;
5873
5874 <link linkend="NormObjectType"><literal>NormObjectType</literal></link> <link
5875 linkend="NormObjectGetType"><literal>NormObjectGetType</literal></link>(<link
5876 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
5877 </sect4>
5878
5879 <sect4>
5880 <title>Description</title>
5881
5882 <para>This function can be used to determine the object type
5883 (<literal>(NORM_OBJECT_DAT</literal>,
5884 <literal>NORM_OBJECT_FILE</literal>, or
5885 <literal>NORM_OBJECT_STREAM</literal>) for the NORM transport object
5886 identified by the <parameter>objectHandle</parameter> parameter. The
5887 <parameter>objectHandle</parameter> must refer to a current, valid
5888 transport object.</para>
5889 </sect4>
5890
5891 <sect4>
5892 <title>Return Values</title>
5893
5894 <para>This function returns the NORM object type. Valid NORM object
5895 types include <literal>NORM_OBJECT_DATA</literal>,
5896 <literal>NORM_OBJECT_FILE</literal>, or
5897 <literal>NORM_OBJECT_STREAM</literal>. A type value of
5898 <literal>NORM_OBJECT_NONE</literal> will be returned for an
5899 <parameter>objectHandle</parameter> value of
5900 <literal>NORM_OBJECT_INVALID</literal>.</para>
5901 </sect4>
5902 </sect3>
5903
5904 <sect3 id="NormObjectHasInfo">
5905 <title>NormObjectHasInfo()</title>
5906
5907 <sect4>
5908 <title>Synopsis</title>
5909
5910 <programlisting>#include &lt;normApi.h&gt;
5911
5912 bool <link linkend="NormObjectHasInfo"><literal>NormObjectHasInfo</literal></link>(<link
5913 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
5914 </sect4>
5915
5916 <sect4>
5917 <title>Description</title>
5918
5919 <para>This function can be used to determine if the sender has
5920 associated any <literal>NORM_INFO</literal> content with the
5921 transport object specified by the
5922 <parameter>objectHandle</parameter> parameter. This can even be used
5923 before the <literal>NORM_INFO</literal> content is delivered to the
5924 receiver and a <literal>NORM_RX_OBJECT_INFO</literal> notification
5925 is posted.</para>
5926 </sect4>
5927
5928 <sect4>
5929 <title>Return Values</title>
5930
5931 <para>A value of <constant>true</constant> is returned if
5932 <literal>NORM_INFO</literal> is (or will be) available for the
5933 specified transport object. A value of <constant>false</constant> is
5934 returned otherwise.</para>
5935 </sect4>
5936 </sect3>
5937
5938 <sect3 id="NormObjectGetInfoLength">
5939 <title>NormObjectGetInfoLength()</title>
5940
5941 <sect4>
5942 <title>Synopsis</title>
5943
5944 <programlisting>#include &lt;normApi.h&gt;
5945
5946 unsigned short <link linkend="NormObjectGetInfoLength"><literal>NormObjectGetInfoLength</literal></link>(<link
5947 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
5948 </sect4>
5949
5950 <sect4>
5951 <title>Description</title>
5952
5953 <para>This function can be used to determine the length of currently
5954 available <literal>NORM_INFO</literal> content (if any) associated
5955 with the transport object referenced by the
5956 <parameter>objectHandle</parameter> parameter.</para>
5957 </sect4>
5958
5959 <sect4>
5960 <title>Return Values</title>
5961
5962 <para>The length of the <literal>NORM_INFO</literal> content, in
5963 bytes, of currently available for the specified transport object is
5964 returned. A value of <constant>0</constant> is returned if no
5965 <literal>NORM_INFO</literal> content is currently available or
5966 associated with the object.</para>
5967 </sect4>
5968 </sect3>
5969
5970 <sect3 id="NormObjectGetInfo">
5971 <title>NormObjectGetInfo()</title>
5972
5973 <sect4>
5974 <title>Synopsis</title>
5975
5976 <programlisting>#include &lt;normApi.h&gt;
5977
5978 unsigned short <link linkend="NormObjectGetInfo"><literal>NormObjectGetInfo</literal></link>(<link
5979 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle,
5980 char* buffer,
5981 unsigned short bufferLen);</programlisting>
5982 </sect4>
5983
5984 <sect4>
5985 <title>Description</title>
5986
5987 <para>This function copies any <literal>NORM_INFO</literal> content
5988 associated (by the sender application) with the transport object
5989 specified by <parameter>objectHandle</parameter> into the provided
5990 memory space referenced by the buffer parameter. The
5991 <parameter>bufferLen</parameter> parameter indicates the length of
5992 the buffer space in bytes. If the provided
5993 <parameter>bufferLen</parameter> is less than the actual
5994 <literal>NORM_INFO</literal> length, a partial copy will occur. The
5995 actual length of <literal>NORM_INFO</literal> content available for
5996 the specified object is returned. However, note that until a
5997 <literal>NORM_RX_OBJECT_INFO</literal> notification is posted to the
5998 receive application, no <literal>NORM_INFO</literal> content is
5999 available and a zero result will be returned, even if
6000 <literal>NORM_INFO</literal> content may be subsequently available.
6001 The <link
6002 linkend="NormObjectHasInfo"><literal>NormObjectHasInfo()</literal></link>
6003 call can be used to determine if any <literal>NORM_INFO</literal>
6004 content will ever be available for a specified transport object
6005 (i.e., determine if the sender has associated any
6006 <literal>NORM_INFO</literal> with the object in question).</para>
6007 </sect4>
6008
6009 <sect4>
6010 <title>Return Values</title>
6011
6012 <para>The actual length of currently available
6013 <literal>NORM_INFO</literal> content for the specified transport
6014 object is returned. This function can be used to determine the
6015 length of <literal>NORM_INFO</literal> content for the object even
6016 if a NULL buffer value and zero <parameter>bufferLen</parameter> is
6017 provided. A zero value is returned if <literal>NORM_INFO</literal>
6018 content has not yet been received (or is non-existent) for the
6019 specified object.</para>
6020 </sect4>
6021 </sect3>
6022
6023 <sect3 id="NormObjectGetSize">
6024 <title>NormObjectGetSize()</title>
6025
6026 <sect4>
6027 <title>Synopsis</title>
6028
6029 <programlisting>#include &lt;normApi.h&gt;
6030
6031 <link linkend="NormSize"><literal>NormSize</literal></link> <link
6032 linkend="NormObjectGetSize"><literal>NormObjectGetSize</literal></link>(<link
6033 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
6034 </sect4>
6035
6036 <sect4>
6037 <title>Description</title>
6038
6039 <para>This function can be used to determine the size (in bytes) of
6040 the transport object specified by the
6041 <parameter>objectHandle</parameter> parameter. NORM can support
6042 large object sizes for the <literal>NORM_OBJECT_FILE</literal> type,
6043 so typically the NORM library is built with any necessary, related
6044 macros defined such that operating system large file support is
6045 enabled (e.g., "<literal>#define
6046 <constant>_FILE_OFFSET_BITS</constant>
6047 <constant>64</constant></literal>" or equivalent). The <link
6048 linkend="NormSize"><literal>NormSize</literal></link> type is
6049 defined accordingly, so the application should be built with the
6050 same large file support configuration.</para>
6051
6052 <para>For objects of type <literal>NORM_OBJECT_STREAM</literal>, the
6053 size returned here corresponds to the stream buffer size set by the
6054 sender application when opening the referenced stream object.</para>
6055 </sect4>
6056
6057 <sect4>
6058 <title>Return Values</title>
6059
6060 <para>A size of the data content of the specified object, in bytes,
6061 is returned. Note that it may be possible that some objects have
6062 zero data content, but do have <literal>NORM_INFO</literal> content
6063 available.</para>
6064 </sect4>
6065 </sect3>
6066
6067 <sect3 id="NormObjectGetBytesPending">
6068 <title>NormObjectGetBytesPending()</title>
6069
6070 <sect4>
6071 <title>Synopsis</title>
6072
6073 <programlisting>#include &lt;normApi.h&gt;
6074
6075 <link linkend="NormSize"><literal>NormSize</literal></link> <link
6076 linkend="NormObjectGetBytesPending"><literal>NormObjectGetBytesPending</literal></link>(<link
6077 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
6078 </sect4>
6079
6080 <sect4>
6081 <title>Description</title>
6082
6083 <para>This function can be used to determine the progress of
6084 reception of the NORM transport object identified by the
6085 <parameter>objectHandle</parameter> parameter. This function
6086 indicates the number of bytes that are pending reception (I.e., when
6087 the object is completely received, "bytes pending" will equal ZERO).
6088 This function is not necessarily applicable to objects of type
6089 <literal>NORM_OBJECT_STREAM</literal> which do not have a finite
6090 size. Note it is possible that this function might also be useful to
6091 query the "transmit pending" status of sender objects, but it does
6092 not account for pending FEC repair transmissions and thus may not
6093 produce useful results for this purpose.</para>
6094 </sect4>
6095
6096 <sect4>
6097 <title>Return Values</title>
6098
6099 <para>A number of object source data bytes pending reception (or
6100 transmission) is returned.</para>
6101 </sect4>
6102 </sect3>
6103
6104 <sect3 id="NormObjectCancel">
6105 <title>NormObjectCancel()</title>
6106
6107 <sect4>
6108 <title>Synopsis</title>
6109
6110 <programlisting>#include &lt;normApi.h&gt;
6111
6112 void <link linkend="NormObjectCancel"><literal>NormObjectCancel</literal></link>(<link
6113 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
6114 </sect4>
6115
6116 <sect4>
6117 <title>Description</title>
6118
6119 <para>This function immediately cancels the transmission of a local
6120 sender transport object or the reception of a specified object from
6121 a remote sender as specified by the
6122 <parameter>objectHandle</parameter> parameter. The
6123 <parameter>objectHandle</parameter> must refer to a currently valid
6124 NORM transport object. Any resources used by the transport object in
6125 question are immediately freed unless the object has been otherwise
6126 retained by the application via the <link
6127 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
6128 call. Unless the application has retained the object in such
6129 fashion, the object in question should be considered invalid and the
6130 application must not again reference the
6131 <parameter>objectHandle</parameter> after this call is made.</para>
6132
6133 <para>If the canceled object is a sender object not completely
6134 received by participating receivers, the receivers will be informed
6135 of the object's cancellation via the NORM protocol
6136 <literal>NORM_CMD</literal>(SQUELCH) message in response to any
6137 NACKs requesting repair or retransmission of the applicable object.
6138 In the case of receive objects, the NORM receiver will not make
6139 further requests for repair of the indicated object, but
6140 furthermore, will acknowledge the object as completed with respect
6141 to any associated positive acknowledgement requests (see <link
6142 linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>).</para>
6143 </sect4>
6144
6145 <sect4>
6146 <title>Return Values</title>
6147
6148 <para>This function has no return value.</para>
6149 </sect4>
6150 </sect3>
6151
6152 <sect3 id="NormObjectRetain">
6153 <title>NormObjectRetain()</title>
6154
6155 <sect4>
6156 <title>Synopsis</title>
6157
6158 <programlisting>#include &lt;normApi.h&gt;
6159
6160 void <link linkend="NormObjectRetain"><literal>NormObjectRetain</literal></link>(<link
6161 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
6162 </sect4>
6163
6164 <sect4>
6165 <title>Description</title>
6166
6167 <para>This function "retains" the
6168 <parameter>objectHandle</parameter> and any state associated with it
6169 for further use by the application even when the NORM protocol
6170 engine may no longer require access to the associated transport
6171 object. Normally, the application is guaranteed that a given <link
6172 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
6173 is valid only while it is being actively transported by NORM (i.e.,
6174 for sender objects, from the time an object is created by the
6175 application until it is canceled by the application or purged (see
6176 the <literal>NORM_TX_OBJECT_PURGED</literal> notification) by the
6177 protocol engine, or, for receiver objects, from the time of the
6178 object's <literal>NORM_RX_OBJECT_NEW</literal> notification until
6179 its reception is canceled by the application or a
6180 <literal>NORM_RX_OBJECT_COMPLETED</literal> or
6181 <literal>NORM_RX_OBJECT_ABORTED</literal> notification is posted).
6182 Note that an application may refer to a given object after any
6183 related notification until the application makes a subsequent call
6184 to <link
6185 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>.</para>
6186
6187 <para>When the application makes a call to <link
6188 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
6189 for a given <parameter>objectHandle</parameter>, the application may
6190 use that <parameter>objectHandle</parameter> value in any NORM API
6191 calls until the application makes a call to <link
6192 linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>
6193 for the given object. Note that the application MUST make a
6194 corresponding call to <link
6195 linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>
6196 for each call it has made to <link
6197 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
6198 in order to free any system resources (i.e., memory) used by that
6199 object. Also note that retaining a receive object also automatically
6200 retains any state associated with the <link
6201 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
6202 corresponding to the remote sender of that receive object so that
6203 the application may use NORM node API calls for the value returned
6204 by <link
6205 linkend="NormObjectGetSender"><literal>NormObjectGetSender()</literal></link>
6206 as needed.</para>
6207 </sect4>
6208
6209 <sect4>
6210 <title>Return Values</title>
6211
6212 <para>This function has no return value.</para>
6213 </sect4>
6214 </sect3>
6215
6216 <sect3 id="NormObjectRelease">
6217 <title>NormObjectRelease()</title>
6218
6219 <sect4>
6220 <title>Synopsis</title>
6221
6222 <programlisting>#include &lt;normApi.h&gt;
6223
6224 void <link linkend="NormObjectRelease"><literal>NormObjectRelease</literal></link>(<link
6225 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
6226 </sect4>
6227
6228 <sect4>
6229 <title>Description</title>
6230
6231 <para>This function complements the <link
6232 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
6233 call by immediately freeing any resources associated with the given
6234 <parameter>objectHandle</parameter>, assuming the underlying NORM
6235 protocol engine no longer requires access to the corresponding
6236 transport object. Note the NORM protocol engine retains/releases
6237 state for associated objects for its own needs and thus it is very
6238 unsafe for an application to call <link
6239 linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>
6240 for an <parameter>objectHandle</parameter> for which it has not
6241 previously explicitly retained via <link
6242 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>.</para>
6243 </sect4>
6244
6245 <sect4>
6246 <title>Return Values</title>
6247
6248 <para>This function has no return value.</para>
6249 </sect4>
6250 </sect3>
6251
6252 <sect3 id="NormFileGetName">
6253 <title>NormFileGetName()</title>
6254
6255 <sect4>
6256 <title>Synopsis</title>
6257
6258 <programlisting>#include &lt;normApi.h&gt;
6259
6260 bool <link linkend="NormFileGetName"><literal>NormFileGetName</literal></link>(<link
6261 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle,
6262 char* nameBuffer,
6263 unsigned int bufferLen);</programlisting>
6264 </sect4>
6265
6266 <sect4>
6267 <title>Description</title>
6268
6269 <para>This function copies the name, as a
6270 <constant>NULL</constant>-terminated string, of the file object
6271 specified by the <parameter>objectHandle</parameter> parameter into
6272 the <parameter>nameBuffer</parameter> of length
6273 <parameter>bufferLen</parameter> bytes provided by the application.
6274 The <parameter>objectHandle</parameter> parameter must refer to a
6275 valid <link
6276 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
6277 for an object of type <literal>NORM_OBJECT_FILE</literal>. If the
6278 actual name is longer than the provided
6279 <parameter>bufferLen</parameter>, a partial copy will occur. Note
6280 that the file name consists of the entire path name of the specified
6281 file object and the application should give consideration to
6282 operating system file path lengths when providing the
6283 <parameter>nameBuffer</parameter>.</para>
6284 </sect4>
6285
6286 <sect4>
6287 <title>Return Values</title>
6288
6289 <para>This function returns <constant>true</constant> upon success
6290 and <constant>false</constant> upon failure. Possible failure
6291 conditions include the <parameter>objectHandle</parameter> does not
6292 refer to an object of type
6293 <literal>NORM_OBJECT_FILE</literal>.</para>
6294 </sect4>
6295 </sect3>
6296
6297 <sect3 id="NormFileRename">
6298 <title>NormFileRename()</title>
6299
6300 <sect4>
6301 <title>Synopsis</title>
6302
6303 <programlisting>#include &lt;normApi.h&gt;
6304
6305 bool <link linkend="NormFileRename"><literal>NormFileRename</literal></link>(<link
6306 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle,
6307 const char* fileName);</programlisting>
6308 </sect4>
6309
6310 <sect4>
6311 <title>Description</title>
6312
6313 <para>This function renames the file used to store content for the
6314 <literal>NORM_OBJECT_FILE</literal> transport object specified by
6315 the <parameter>objectHandle</parameter> parameter. This allows
6316 receiver applications to rename (or move) received files as needed.
6317 NORM uses temporary file names for received files until the
6318 application explicitly renames the file. For example, sender
6319 applications may choose to use the <literal>NORM_INFO</literal>
6320 content associated with a file object to provide name and/or typing
6321 information to receivers. The <parameter>fileName</parameter>
6322 parameter must be a <constant>NULL</constant>-terminated string
6323 which should specify the full desired path name to be used. NORM
6324 will attempt to create sub-directories as needed to satisfy the
6325 request. Note that existing files of the same name may be
6326 overwritten.</para>
6327 </sect4>
6328
6329 <sect4>
6330 <title>Return Values</title>
6331
6332 <para>This function returns true upon success and false upon
6333 failure. Possible failure conditions include the case where the
6334 <parameter>objectHandle</parameter> does not refer to an object of
6335 type <literal>NORM_OBJECT_FILE</literal> and where NORM was unable
6336 to successfully create any needed directories and/or the file
6337 itself.</para>
6338 </sect4>
6339 </sect3>
6340
6341 <sect3 id="NormDataAccessData">
6342 <title>NormDataAccessData()</title>
6343
6344 <sect4>
6345 <title>Synopsis</title>
6346
6347 <programlisting>#include &lt;normApi.h&gt;
6348
6349 const char* <link linkend="NormDataAccessData"><literal>NormDataAccessData</literal></link>(<link
6350 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
6351 </sect4>
6352
6353 <sect4>
6354 <title>Description</title>
6355
6356 <para>This function allows the application to access the data
6357 storage area associated with a transport object of type
6358 <literal>NORM_OBJECT_DATA</literal>. For example, the application
6359 may use this function to copy the received data content for its own
6360 use. Alternatively, the application may establish "ownership" for
6361 the allocated memory space using the <link
6362 linkend="NormDataDetachData"><literal>NormDataDetachData()</literal></link>
6363 function if it is desired to avoid the copy.</para>
6364
6365 <para>If the object specified by the
6366 <parameter>objectHandle</parameter> parameter has no data content
6367 (or is not of type <literal>NORM_OBJECT_DATA</literal>), a NULL
6368 value may be returned. The application MUST NOT attempt to modify
6369 the memory space used by <literal>NORM_OBJECT_DATA</literal> objects
6370 during the time an associated <parameter>objectHandle</parameter> is
6371 valid. The length of data storage area can be determined with a call
6372 to <link
6373 linkend="NormObjectGetSize"><literal>NormObjectGetSize()</literal></link>
6374 for the same <parameter>objectHandle</parameter> value.</para>
6375 </sect4>
6376
6377 <sect4>
6378 <title>Return Values</title>
6379
6380 <para>This function returns a pointer to the data storage area for
6381 the specified transport object. A NULL value may be returned if the
6382 object has no associated data content or is not of type
6383 <literal>NORM_OBJECT_DATA</literal>.</para>
6384 </sect4>
6385 </sect3>
6386
6387 <sect3 id="NormDataDetachData">
6388 <title>NormDataDetachData()</title>
6389
6390 <sect4>
6391 <title>Synopsis</title>
6392
6393 <programlisting>#include &lt;normApi.h&gt;
6394
6395 char* <link linkend="NormDataDetachData"><literal>NormDataDetachData</literal></link>(<link
6396 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
6397 </sect4>
6398
6399 <sect4>
6400 <title>Description</title>
6401
6402 <para>This function allows the application to disassociate data
6403 storage allocated by the NORM protocol engine for a receive object
6404 from the <literal>NORM_OBJECT_DATA</literal> transport object
6405 specified by the <parameter>objectHandle</parameter> parameter. It
6406 is important that this function is called after the NORM protocol
6407 engine has indicated it is finished with the data object (i.e.,
6408 after a <literal>NORM_TX_OBJECT_PURGED</literal>,
6409 <literal>NORM_RX_OBJECT_COMPLETED</literal>, or
6410 <literal>NORM_RX_OBJECT_ABORTED</literal> notification event). But
6411 the application must call <link
6412 linkend="NormDataDetachData"><literal>NormDataDetachData()</literal></link>
6413 before a call is made to <link
6414 linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>
6415 or <link
6416 linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>
6417 for the object if it plans to access the data content afterwards.
6418 Otherwise, the NORM protocol engine will free the applicable memory
6419 space when the associated <literal>NORM_OBJECT_DATA</literal>
6420 transport object is deleted and the application will be unable to
6421 access the received data unless it has previously copied the
6422 content.</para>
6423
6424 <para>Once the application has used this call to "detach" the data
6425 content, it is the application's responsibility to subsequently free
6426 the data storage space as needed.</para>
6427 </sect4>
6428
6429 <sect4>
6430 <title>Return Values</title>
6431
6432 <para>This function returns a pointer to the data storage area for
6433 the specified transport object. A <constant>NULL</constant> value
6434 may be returned if the object has no associated data content or is
6435 not of type <literal>NORM_OBJECT_DATA</literal>.</para>
6436 </sect4>
6437 </sect3>
6438
6439 <sect3 id="NormObjectGetSender">
6440 <title>NormObjectGetSender()</title>
6441
6442 <sect4>
6443 <title>Synopsis</title>
6444
6445 <programlisting>#include &lt;normApi.h&gt;
6446
6447 <link linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> <link
6448 linkend="NormObjectGetSender"><literal>NormObjectGetSender</literal></link>(<link
6449 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
6450 </sect4>
6451
6452 <sect4>
6453 <title>Description</title>
6454
6455 <para>This function retrieves the <link
6456 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
6457 corresponding to the remote sender of the transport object
6458 associated with the given <parameter>objectHandle</parameter>
6459 parameter. Note that the returned <link
6460 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
6461 value is only valid for the same period that the
6462 <parameter>objectHandle</parameter> is valid. The returned <link
6463 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
6464 may optionally be retained for further use by the application using
6465 the <link
6466 linkend="NormNodeRetain"><literal>NormNodeRetain()</literal></link>
6467 function call. The returned value can be used in the NORM Node
6468 Functions described later in this document.</para>
6469 </sect4>
6470
6471 <sect4>
6472 <title>Return Values</title>
6473
6474 <para>This function returns the <link
6475 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
6476 corresponding to the remote sender of the transport object
6477 associated with the given <parameter>objectHandle</parameter>
6478 parameter. A value of <literal>NORM_NODE_INVALID</literal> is
6479 returned if the specified <parameter>objectHandle</parameter>
6480 references a locally originated, sender object.</para>
6481 </sect4>
6482 </sect3>
6483 </sect2>
6484
6485 <sect2>
6486 <title>NORM Node Functions</title>
6487
6488 <para>The functions described in this section may be used for NORM
6489 sender or receiver (most typically receiver) purposes to retrieve
6490 additional information about a remote <emphasis>NormNode</emphasis>,
6491 given a valid <link
6492 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>. Note
6493 that, unless specifically retained (see <link
6494 linkend="NormNodeRetain"><literal>NormNodeRetain()</literal></link>), a
6495 <link linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
6496 provided in a <link
6497 linkend="NormEvent"><literal>NormEvent</literal></link> notification
6498 should be considered valid only until a subsequent call to <link
6499 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
6500 is made. <link
6501 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> values
6502 retrieved using <link
6503 linkend="NormObjectGetSender"><literal>NormObjectGetSender()</literal></link>
6504 can be considered valid for the same period of time as the corresponding
6505 <link
6506 linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> is
6507 valid.</para>
6508
6509 <sect3 id="NormNodeGetId">
6510 <title>NormNodeGetId()</title>
6511
6512 <sect4>
6513 <title>Synopsis</title>
6514
6515 <programlisting>#include &lt;normApi.h&gt;
6516
6517 <link linkend="NormNodeId"><literal>NormNodeId</literal></link> <link
6518 linkend="NormNodeGetId"><literal>NormNodeGetId</literal></link>(<link
6519 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle);</programlisting>
6520 </sect4>
6521
6522 <sect4>
6523 <title>Description</title>
6524
6525 <para>This function retrieves the <link
6526 linkend="NormNodeId"><literal>NormNodeId</literal></link> identifier
6527 for the remote participant referenced by the given
6528 <parameter>nodeHandle</parameter> value. The <link
6529 linkend="NormNodeId"><literal>NormNodeId</literal></link> is a
6530 32-bit value used within the NORM protocol to uniquely identify
6531 participants within a NORM session. The participants identifiers are
6532 assigned by the application or derived (by the NORM API code) from
6533 the host computers default IP address.</para>
6534 </sect4>
6535
6536 <sect4>
6537 <title>Return Values</title>
6538
6539 <para>This function returns the <link
6540 linkend="NormNodeId"><literal>NormNodeId</literal></link> value
6541 associated with the specified <parameter>nodeHandle</parameter>. In
6542 the case <parameter>nodeHandle</parameter> is equal to
6543 <literal>NORM_NODE_INVALID</literal>, the return value will be
6544 <literal>NORM_NODE_NONE</literal>.</para>
6545 </sect4>
6546 </sect3>
6547
6548 <sect3 id="NormNodeGetAddress">
6549 <title>NormNodeGetAddress()</title>
6550
6551 <sect4>
6552 <title>Synopsis</title>
6553
6554 <programlisting>#include &lt;normApi.h&gt;
6555
6556 bool <link linkend="NormNodeGetAddress"><literal>NormNodeGetAddress</literal></link>(<link
6557 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle,
6558 char* addrBuffer,
6559 unsigned int* bufferLen,
6560 unsigned short* port = NULL);</programlisting>
6561 </sect4>
6562
6563 <sect4>
6564 <title>Description</title>
6565
6566 <para>This function retrieves the current network source address
6567 detected for packets received from remote NORM sender referenced by
6568 the <parameter>nodeHandle</parameter> parameter. The
6569 <parameter>addrBuffer</parameter> must be a pointer to storage of
6570 <parameter>bufferLen</parameter> bytes in length in which the
6571 referenced sender node's address will be returned. Optionally, the
6572 remote sender source port number (see <link
6573 linkend="NormSetTxPort"><literal>NormSetTxPort()</literal></link>)
6574 is also returned if the optional port pointer to storage parameter
6575 is provided in the call. Note that in the case of Network Address
6576 Translation (NAT) or other firewall activities, the source address
6577 detected by the NORM receiver may not be the original address of the
6578 original NORM sender.</para>
6579 </sect4>
6580
6581 <sect4>
6582 <title>Return Values</title>
6583
6584 <para>A value of <constant>true</constant> is returned upon success
6585 and <constant>false</constant> upon failure. An invalid
6586 <parameter>nodeHandle</parameter> parameter value would lead to such
6587 failure.</para>
6588 </sect4>
6589 </sect3>
6590
6591 <sect3 id="NormNodeGetGrtt">
6592 <title>NormNodeGetGrtt()</title>
6593
6594 <sect4>
6595 <title>Synopsis</title>
6596
6597 <programlisting>#include &lt;normApi.h&gt;
6598
6599 double <link linkend="NormNodeGetId"><literal>NormNodeGetGrtt</literal></link>(<link
6600 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle);</programlisting>
6601 </sect4>
6602
6603 <sect4>
6604 <title>Description</title>
6605
6606 <para>This function retrieves the advertised estimate of group
6607 round-trip timing (GRTT) for the remote sender referenced by the
6608 given <parameter>nodeHandle</parameter> value. Newly-starting
6609 senders that have been participating as a receiver within a group
6610 may wish to use this function to provide a more accurate startup
6611 estimate of GRTT (see <link
6612 linkend="NormSetGrttEstimate"><literal>NormSetGrttEstimate()</literal></link>)
6613 prior to a call to <link
6614 linkend="NormStartSender"><literal>NormStartSender()</literal></link>.
6615 Applications may use this information for other purpose as well.
6616 Note that the <literal>NORM_GRTT_UPDATED</literal> event is posted
6617 (see <link
6618 linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>)
6619 by the NORM protocol engine to indicate when changes in the local
6620 sender or remote senders' GRTT estimate occurs.</para>
6621 </sect4>
6622
6623 <sect4>
6624 <title>Return Values</title>
6625
6626 <para>This function returns the remote sender's advertised GRTT
6627 estimate in units of seconds. A value of <constant>-1.0</constant>
6628 is returned upon failure. An invalid
6629 <parameter>nodeHandle</parameter> parameter value will lead to such
6630 failure.</para>
6631 </sect4>
6632 </sect3>
6633
6634 <sect3 id="NormNodeGetCommand">
6635 <title>NormNodeGetCommand()</title>
6636
6637 <sect4>
6638 <title>Synopsis</title>
6639
6640 <programlisting>#include &lt;normApi.h&gt;
6641
6642 bool <link linkend="NormNodeGetCommand"><literal>NormNodeGetCommand</literal></link>(<link
6643 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle,
6644 char* buffer,
6645 unsigned int* buflen);</programlisting>
6646 </sect4>
6647
6648 <sect4>
6649 <title>Description</title>
6650
6651 <para>This function retrieves the content of an application-defined
6652 command that was received from a remote sender associated with the
6653 given <parameter>nodeHandle</parameter>. This call should be made in
6654 response to the <constant>NORM_RX_CMD_NEW</constant> notification.
6655 This notification is issued for each command received. However the
6656 application may use this call to poll for received commands if
6657 desired. Additionally, the received command length can be "queried"
6658 by setting the value referenced by the <parameter>buflen</parameter>
6659 parameter to <constant>ZERO</constant>. Upon return, this value
6660 referenced by the <parameter>buflen</parameter> parameter is
6661 adjusted to reflect the command length. Then a subsequent call to
6662 <link
6663 linkend="NormNodeGetCommand"><literal>NormNodeGetCommand()</literal></link>
6664 can be made with an appropriately-sized buffer to retrieve the
6665 received command content. The command size will be less than or
6666 equal to the NORM segment size configured for the given remote
6667 sender.</para>
6668
6669 <para>Note that if a rapid succession of commands are sent it is
6670 possible that the commands may be delivered to the receivers
6671 out-of-order. Also, when repetition is requested (i.e., if
6672 <parameter>robust</parameter> is set to <constant>true</constant>)
6673 the receiver may receive duplicate copies of the same command. It is
6674 up to the application to provide any needed mechanism for detecting
6675 and/or filtering duplicate command reception.</para>
6676 </sect4>
6677
6678 <sect4>
6679 <title>Return Values</title>
6680
6681 <para>This function returns <constant>true</constant> upon
6682 successful retrieval of command content. A return value of
6683 <constant>false</constant> indicates that either no command was
6684 available or the provided buffer size (<parameter>buflen</parameter>
6685 parameter) was inadequate. The value referenced by the
6686 <parameter>buflen</parameter> parameter is adjusted to indicate the
6687 actual command length (in bytes) upon return.</para>
6688 </sect4>
6689 </sect3>
6690
6691 <sect3 id="NormNodeFreeBuffers">
6692 <title>NormNodeFreeBuffers()</title>
6693
6694 <sect4>
6695 <title>Synopsis</title>
6696
6697 <programlisting>#include &lt;normApi.h&gt;
6698
6699 void <link linkend="NormNodeFreeBuffers"><literal>NormNodeFreeBuffers</literal></link>(<link
6700 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle);</programlisting>
6701 </sect4>
6702
6703 <sect4>
6704 <title>Description</title>
6705
6706 <para>This function releases memory resources that were allocated
6707 for a remote sender. For example, the receiver application may wish
6708 to free memory resources when receiving a
6709 <constant>NORM_REMOTE_SENDER_INACTIVE</constant> notification for a
6710 given remote sender when multiple senders may be providing content.
6711 The NORM protocol engine allocates memory for reliable transport
6712 buffering on a per sender basis according to the limit set in the
6713 <link
6714 linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
6715 call. These buffering resources comprise the majority of the state
6716 allocated for a given remote sender. For NORM applications with
6717 possibly multiple senders active at different times, this function
6718 can be used to manage to amount of memory allocated for reliable
6719 reception. If a sender becomes "active" again after a call to <link
6720 linkend="NormNodeFreeBuffers"><literal>NormNodeFreeBuffers()</literal></link>,
6721 new memory resources will be allocated. Note that state for any
6722 pending (uncompleted) objects will be dropped when this function is
6723 called and the receiver may request retransmission and repair of
6724 content if the sender once again becomes "active". The application
6725 SHOULD call <link
6726 linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>
6727 for any pending objects <emphasis>before</emphasis> calling <link
6728 linkend="NormNodeFreeBuffers"><literal>NormNodeFreeBuffers()</literal></link>
6729 if it wishes to never receive those pending objects. Alternatively,
6730 a call to <link
6731 linkend="NormNodeDelete"><literal>NormNodeDelete()</literal></link>
6732 will completely eliminate all state for a given remote sender and,
6733 if that sender becomes "active" again, it will be treated as a
6734 completely new sender.</para>
6735 </sect4>
6736
6737 <sect4>
6738 <title>Return Values</title>
6739
6740 <para>This function has no return value.</para>
6741 </sect4>
6742 </sect3>
6743
6744 <sect3 id="NormNodeDelete">
6745 <title>NormNodeDelete()</title>
6746
6747 <sect4>
6748 <title>Synopsis</title>
6749
6750 <programlisting>#include &lt;normApi.h&gt;
6751
6752 void <link linkend="NormNodeDelete"><literal>NormNodeDelete</literal></link>(<link
6753 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle);</programlisting>
6754 </sect4>
6755
6756 <sect4>
6757 <title>Description</title>
6758
6759 <para>This function can be used by a NORM receiver application to
6760 completely remove the state associated with a remote sender for the
6761 given <parameter>nodeHandle</parameter>. For example, when a
6762 <constant>NORM_REMOTE_SENDER_INACTIVE</constant> notification occurs
6763 for a given sender, the application may wish to completely free
6764 <emphasis>all</emphasis> associated resources. Note this is distinct
6765 from the <link
6766 linkend="NormNodeFreeBuffers"><literal>NormNodeFreeBuffers()</literal></link>
6767 call where only the buffering resources are freed and other state
6768 pertaining to the sender is kept. If the deleted sender again
6769 becomes "active", it will be treated as a brand new sender. Unless
6770 explicitly retained with a call to <link
6771 linkend="NormNodeRetain"><literal>NormNodeRetain()</literal></link>,
6772 the <parameter>nodeHandle</parameter> should be considered invalid
6773 after this call is made. Additionally, any
6774 <type>NormObjectHandle</type> values for pending objects from this
6775 sender are also invalidated (unless otherwise retained), although
6776 <constant>NORM_RX_OBJECT_ABORTED</constant> notifications may be
6777 issued for those pending objects.</para>
6778 </sect4>
6779
6780 <sect4>
6781 <title>Return Values</title>
6782
6783 <para>This function has no return value.</para>
6784 </sect4>
6785 </sect3>
6786
6787 <sect3 id="NormNodeRetain">
6788 <title>NormNodeRetain()</title>
6789
6790 <sect4>
6791 <title>Synopsis</title>
6792
6793 <programlisting>#include &lt;normApi.h&gt;
6794
6795 void <link linkend="NormNodeRetain"><literal>NormNodeRetain</literal></link>(<link
6796 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle);</programlisting>
6797 </sect4>
6798
6799 <sect4>
6800 <title>Description</title>
6801
6802 <para>In the same manner as the <link
6803 linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
6804 function, this function allows the application to retain state
6805 associated with a given <parameter>nodeHandle</parameter> value even
6806 when the underlying NORM protocol engine might normally free the
6807 associated state and thus invalidate the <link
6808 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>.
6809 If the application uses this function, it must make a corresponding
6810 call to <link
6811 linkend="NormNodeRelease"><literal>NormNodeRelease()</literal></link>
6812 when finished with the node information to avoid a memory leak
6813 condition. <link
6814 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
6815 values (unless retained) are valid from the time of a
6816 <literal>NORM_REMOTE_SENDER_NEW</literal> notification until a
6817 complimentary <literal>NORM_REMOTE_SENDER_PURGED</literal>
6818 notification. During that interval, the application will receive
6819 <literal>NORM_REMOTE_SENDER_ACTIVE</literal> and
6820 <literal>NORM_REMOTE_SENDER_INACTIVE</literal> notifications
6821 according to the sender's message transmission activity within the
6822 session.</para>
6823
6824 <para>It is important to note that, if the NORM protocol engine
6825 posts a <literal>NORM_REMOTE_SENDER_PURGED</literal> notification
6826 for a given <link
6827 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>,
6828 the NORM protocol engine could possibly, subsequently establish a
6829 new, different <link
6830 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
6831 value for the same remote sender (i.e., one of equivalent <link
6832 linkend="NormNodeId"><literal>NormNodeId</literal></link>) if it
6833 again becomes active in the session. A new <link
6834 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
6835 may likely be established even if the application has retained the
6836 previous <link
6837 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
6838 value. Therefore, to the application, it might appear that two
6839 different senders with the same <link
6840 linkend="NormNodeId"><literal>NormNodeId</literal></link> are
6841 participating if these notifications are not carefully monitored.
6842 This behavior is contingent upon how the application has configured
6843 the NORM protocol engine to manage resources when there is potential
6844 for a large number of remote senders within a session (related APIs
6845 are TBD). For example, the application may wish to control which
6846 specific remote senders for which it keeps state (or limit the
6847 memory resources used for remote sender state, etc) and the NORM API
6848 may be extended in the future to control this behavior.</para>
6849 </sect4>
6850
6851 <sect4>
6852 <title>Return Values</title>
6853
6854 <para>This function has no return value.</para>
6855 </sect4>
6856 </sect3>
6857
6858 <sect3 id="NormNodeRelease">
6859 <title>NormNodeRelease()</title>
6860
6861 <sect4>
6862 <title>Synopsis</title>
6863
6864 <programlisting>#include &lt;normApi.h&gt;
6865
6866 void <link linkend="NormNodeRelease"><literal>NormNodeRelease</literal></link>(<link
6867 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle);</programlisting>
6868 </sect4>
6869
6870 <sect4>
6871 <title>Description</title>
6872
6873 <para>In complement to the <link
6874 linkend="NormNodeRetain"><literal>NormNodeRetain()</literal></link>
6875 function, this API call releases the specified
6876 <parameter>nodeHandle</parameter> so that the NORM protocol engine
6877 may free associated resources as needed. Once this call is made, the
6878 application should no longer reference the specified <link
6879 linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>,
6880 unless it is still valid.</para>
6881 </sect4>
6882
6883 <sect4>
6884 <title>Return Values</title>
6885
6886 <para>This function has no return value.</para>
6887 </sect4>
6888 </sect3>
6889 </sect2>
6890
6891 <sect2>
6892 <title>NORM Debugging Functions</title>
6893
6894 <para>This section describes some additional function calls that are
6895 available to set debugging output options and control other aspects of
6896 the NORM implementation.</para>
6897
6898 <sect3 id="NormSetDebugLevel">
6899 <title>NormSetDebugLevel()</title>
6900
6901 <sect4>
6902 <title>Synopsis</title>
6903
6904 <programlisting>#include &lt;normApi.h&gt;
6905
6906 void <link linkend="NormSetDebugLevel"><literal>NormSetDebugLevel</literal></link>(unsigned int level);</programlisting>
6907 </sect4>
6908
6909 <sect4>
6910 <title>Description</title>
6911
6912 <para>This function controls the verbosity of NORM debugging output.
6913 Higher values of level result in more detailed output. The highest
6914 level of debugging is 12. The debug output consists of text written
6915 to STDOUT by default but may be directed to a log file using the
6916 <link
6917 linkend="NormOpenDebugLog"><literal>NormOpenDebugLog()</literal></link>
6918 function.</para>
6919 </sect4>
6920
6921 <sect4>
6922 <title>Return Values</title>
6923
6924 <para>This function has no return value.</para>
6925 </sect4>
6926 </sect3>
6927
6928 <sect3 id="NormOpenDebugLog">
6929 <title>NormOpenDebugLog()</title>
6930
6931 <sect4>
6932 <title>Synopsis</title>
6933
6934 <programlisting>#include &lt;normApi.h&gt;
6935
6936 bool <link linkend="NormOpenDebugLog"><literal>NormOpenDebugLog</literal></link>(NormInstanceHandle instance, const char* fileName);</programlisting>
6937 </sect4>
6938
6939 <sect4>
6940 <title>Description</title>
6941
6942 <para>This function allows NORM debug output to be directed to a
6943 file instead of the default <constant>STDERR</constant>.</para>
6944 </sect4>
6945
6946 <sect4>
6947 <title>Return Values</title>
6948
6949 <para>The function returns <constant>true</constant> on success. If
6950 the specified file cannot be opened a value of
6951 <constant>false</constant> is returned.</para>
6952 </sect4>
6953 </sect3>
6954
6955 <sect3 id="NormCloseDebugLog">
6956 <title>NormCloseDebugLog()</title>
6957
6958 <sect4>
6959 <title>Synopsis</title>
6960
6961 <programlisting>#include &lt;normApi.h&gt;
6962
6963 bool <link linkend="NormCloseDebugLog"><literal>NormCloseDebugLog</literal></link>(NormInstanceHandle instance);</programlisting>
6964 </sect4>
6965
6966 <sect4>
6967 <title>Description</title>
6968
6969 <para>TBD</para>
6970 </sect4>
6971
6972 <sect4>
6973 <title>Return Values</title>
6974
6975 <para>TBD</para>
6976 </sect4>
6977 </sect3>
6978
6979 <sect3 id="NormOpenDebugPipe">
6980 <title>NormOpenDebugPipe()</title>
6981
6982 <sect4>
6983 <title>Synopsis</title>
6984
6985 <programlisting>#include &lt;normApi.h&gt;
6986
6987 bool <link linkend="NormOpenDebugPipe"><literal>NormOpenDebugPipe</literal></link>(NormInstanceHandle instance, const char* pipeName);</programlisting>
6988 </sect4>
6989
6990 <sect4>
6991 <title>Description</title>
6992
6993 <para>TBD</para>
6994 </sect4>
6995
6996 <sect4>
6997 <title>Return Values</title>
6998
6999 <para>TBD</para>
7000 </sect4>
7001 </sect3>
7002
7003 <sect3 id="NormCloseDebugPipe">
7004 <title>NormCloseDebugPipe()</title>
7005
7006 <sect4>
7007 <title>Synopsis</title>
7008
7009 <programlisting>#include &lt;normApi.h&gt;
7010
7011 bool <link linkend="NormCloseDebugPipe"><literal>NormCloseDebugPipe</literal></link>(NormInstanceHandle instance);</programlisting>
7012 </sect4>
7013
7014 <sect4>
7015 <title>Description</title>
7016
7017 <para>TBD</para>
7018 </sect4>
7019
7020 <sect4>
7021 <title>Return Values</title>
7022
7023 <para>TBD</para>
7024 </sect4>
7025 </sect3>
7026 </sect2>
7027 </sect1>
7028 </article>