File: NormDeveloperGuide.xml

package info (click to toggle)
norm 1.5.9%2Bdfsg-2
links: PTS, VCS
area: main
in suites: bookworm, bullseye
size: 9,664 kB
sloc: cpp: 123,494; xml: 7,536; tcl: 5,460; makefile: 3,441; python: 1,898; java: 1,750; ansic: 642; sh: 21; csh: 8
file content (7028 lines) | stat: -rw-r--r-- 345,925 bytes
parent folder | download | duplicates (4)
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article>
  <articleinfo>
    <title><inlinemediaobject>
        <imageobject>
          <imagedata align="center" fileref="NormLogo.gif" scale="50"/>
        </imageobject>
      </inlinemediaobject> NORM Developer's Guide (version 1.5b5)</title>

    <titleabbrev>NORM Developer's Guide</titleabbrev>

    <abstract>
      <para>This document describes an application programming interface (API)
      for the <ulink url="http://norm.pf.itd.nrl.navy.mil/">Nack-Oriented
      Reliable Multicast (NORM)</ulink> protocol implementation developed by
      the Protocol Engineering and Advance Networking (<ulink
      url="http://cs.itd.nrl.navy.mil/">PROTEAN</ulink>) Research Group of the
      United States <ulink url="http://www.nrl.navy.mil/">Naval Research
      Laboratory</ulink> (NRL). The NORM protocol provides general purpose
      reliable data transport for applications wishing to use Internet
      Protocol (IP) Multicast services for group data delivery. NORM can also
      support unicast (point-to-point) data communication and may be used for
      such when deemed appropriate. The current NORM protocol specification is
      given in the <ulink url="http://www.ietf.org/">Internet Engineering Task
      Force</ulink> (IETF) <ulink
      url="http://norm.pf.itd.nrl.navy.mil/rfc3940.pdf">RFC 3940</ulink>. This
      document is currently a reference guide to the NORM API of the NRL
      reference implementation. More tutorial material may be include in a
      future version of this document or a separate developer's tutorial may
      be created at a later date.</para>
    </abstract>
  </articleinfo>

  <sect1>
    <title>Background</title>

    <para>This document describes an application programming interface (API)
    for the <ulink url="http://norm.pf.itd.nrl.navy.mil/">Nack-Oriented
    Reliable Multicast (NORM)</ulink> protocol implementation developed by the
    Protocol Engineering and Advance Networking (<ulink
    url="http://cs.itd.nrl.navy.mil/">PROTEAN</ulink>) Research Group of the
    United States <ulink url="http://www.nrl.navy.mil/">Naval Research
    Laboratory</ulink> (NRL). The NORM protocol provides general purpose
    reliable data transport for applications wishing to use Internet Protocol
    (IP) Multicast services for group data delivery. NORM can also support
    unicast (point-to-point) data communication and may be used for such when
    deemed appropriate. The current NORM protocol specification is given in
    the <ulink url="http://www.ietf.org/">Internet Engineering Task
    Force</ulink> (IETF) <ulink
    url="http://norm.pf.itd.nrl.navy.mil/rfc5740.pdf">RFC 5740</ulink>.</para>

    <para>The NORM protocol is designed to provide end-to-end reliable
    transport of bulk data objects or streams over generic IP multicast
    routing and forwarding services. NORM uses a selective, negative
    acknowledgement (NACK) mechanism for transport reliability and offers
    additional protocol mechanisms to conduct reliable multicast sessions with
    limited "a priori" coordination among senders and receivers. A congestion
    control scheme is specified to allow the NORM protocol to fairly share
    available network bandwidth with other transport protocols such as
    Transmission Control Protocol (TCP). It is capable of operating with both
    reciprocal multicast routing among senders and receivers and with
    asymmetric connectivity (possibly a unicast return path) from the senders
    to receivers. The protocol offers a number of features to allow different
    types of applications or possibly other higher-level transport protocols
    to utilize its service in different ways. The protocol leverages the use
    of FEC-based repair and other proven reliable multicast transport
    techniques in its design.</para>

    <para>The NRL NORM library attempts to provide a general useful capability
    for development of reliable multicast applications for bulk file or other
    data delivery as well as support of stream-based transport with possible
    real-time delivery requirements. The API allows access to many NORM
    protocol parameters and control functions to tailor performance for
    specific applications. While default parameters, where provided, can be
    useful to a potential wide range of requirements, the many different
    possible group communication paradigms dictate different needs for
    different applications. Even with NORM, the developer should have a
    thorough understanding of the specific application's group communication
    needs.</para>
  </sect1>

  <sect1>
    <title>Overview</title>

    <para>The NORM API has been designed to provide simple, straightforward
    access to and control of NORM protocol state and functions. Functions are
    provided to create and initialize instances of the NORM API and associated
    transport sessions (<emphasis>NormSessions</emphasis>). Subsequently, NORM
    data transmission (<emphasis>NormSender</emphasis>) operation can be
    activated and the application can queue various types of data
    (<emphasis>NormObjects</emphasis>) for reliable transport. Additionally or
    alternatively, NORM reception (<emphasis>NormReceiver</emphasis>)
    operation can also be enabled on a per-session basis and the protocol
    implementation alerts the application of receive events.</para>

    <para>By default, the NORM API will create an operating system thread in
    which the NORM protocol engine runs. This allows user application code and
    the underlying NORM code to execute somewhat independently of one another.
    The NORM protocol thread notifies the application of various protocol
    events through a thread-safe event dispatching mechanism and API calls are
    provided to allow the application to control NORM operation. (Note: API
    mechanisms for lower-level, non-threaded control and execution of the NORM
    protocol engine code may also be provided in the future.)</para>

    <para>The NORM API operation can be roughly summarized with the following
    categories of functions:</para>

    <orderedlist>
      <listitem>
        <para>API Initialization</para>
      </listitem>

      <listitem>
        <para>Session Creation and Control</para>
      </listitem>

      <listitem>
        <para>Data Transport</para>
      </listitem>

      <listitem>
        <para>API Event Notification</para>
      </listitem>
    </orderedlist>

    <para>Note the order of these categories roughly reflects the order of
    function calls required to use NORM in an application. The first step is
    to create and initialize, as needed, at least one instance of the NORM
    API. Then one or more NORM transport sessions (where a "session"
    corresponds to data exchanges on a given multicast group (or unicast
    address) and host port number) may be created and controlled. Applications
    may participate as senders and/or receivers within a NORM session. NORM
    senders transmit data to the session destination address (usually an IP
    multicast group) while receivers are notified of incoming data. The NORM
    API provides and event notification scheme to notify the application of
    significant sender and receiver events. There are also a number support
    functions provided for the application to control and monitor its
    participation within a NORM transport session.</para>

    <sect2>
      <title>API Initialization</title>

      <para>The NORM API requires that an application explicitly create at
      least one instance of the NORM protocol engine that is subsequently used
      as a conduit for further NORM API calls. By default, the NORM protocol
      engine runs in its own operating system thread and interacts with the
      application in a thread-safe manner through the API calls and event
      dispatching mechanism.</para>

      <para>In general, only a single thread should access the <link
      linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
      API call for a given <emphasis>NormInstance</emphasis>. This function
      serves as the conduit for delivering NORM protocol engine events to the
      application. A NORM application can be designed to be single-threaded,
      even with multiple active NormSessions, but also multiple API instances
      can be created (see <link
      linkend="NormCreateInstance"><literal>NormCreateInstance()</literal></link>)
      as needed for applications with specific requirements for accessing and
      controlling participation in multiple <emphasis>NormSessions</emphasis>
      from separate operating system multiple threads. Or, alternatively, a
      single <emphasis>NormInstance</emphasis> could be used, with a "master
      thread" serving as an intermediary between the <link
      linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
      function, demultiplexing and dispatching events as appropriate to other
      "child threads" that are created to handle
      "per-<emphasis>NormSession</emphasis>" input/output. The advantage of
      this alternative approach is that the end result would be one NORM
      protocol engine thread plus one "master thread" plus one "child thread"
      per <emphasis>NormSession</emphasis> instead of two threads (protocol
      engine plus application thread) per <emphasis>NormSession</emphasis> if
      such multi-threaded operation is needed by the application.</para>
    </sect2>

    <sect2>
      <title>Session Creation and Control</title>

      <para>Once an API instance has been successfully created, the
      application may then create NORM transport session instances as needed.
      The application can participate in each session as a sender and/or
      receiver of data. If an application is participating as a sender, it may
      enqueue data transport objects for transmission. The control of
      transmission is largely left to the senders and API calls are provided
      to control transmission rate, FEC parameters, etc. Applications
      participating as receivers will be notified via the NORM API's event
      dispatching mechanism of pending and completed reliable reception of
      data along with other significant events. Additionally, API controls for
      some optional NORM protocol mechanisms, such as positive acknowledgment
      collection, are also provided.</para>

      <para>Note when multiple senders are involved, receivers allocate system
      resources (buffer space) for each active sender. With a very large
      number of concurrently active senders, this may translate to significant
      memory allocation on receiver nodes. Currently, the API allows the
      application to control how much buffer space is allocated for each
      active sender (NOTE: In the future, API functions may be provided limit
      the number of active senders monitored and/or provide the application
      with finer control over receive buffer allocation, perhaps on a per
      sender basis).</para>
    </sect2>

    <sect2>
      <title>Data Transport</title>

      <para>The NORM protocol supports transport of three basic types of data
      content. These include the types <literal>NORM_OBJECT_FILE</literal> and
      <literal>NORM_OBJECT_DATA</literal> which represent predetermined,
      fixed-size application data content. The only differentiation with
      respect to these two types is the implicit "hint" to the receiver to use
      non-volatile (i.e. file system) storage or memory. This "hint" lets the
      receiver allocate appropriate storage space with no other information on
      the incoming data. The NORM implementation reads/writes data for the
      <literal>NORM_OBJECT_FILE</literal> type directly from/to file storage,
      while application memory space is accessed for the
      <literal>NORM_OBJECT_DATA</literal> type. The third data content type,
      <literal>NORM_OBJECT_STREAM</literal>, represents unbounded, possibly
      persistent, streams of data content. Using this transport paradigm,
      traditional, byte-oriented streaming transport service (e.g. similar to
      that provided by a TCP socket) can be provided. Additionally, NORM has
      provisions for application-defined message-oriented transport where
      receivers can recover message boundaries without any "handshake" with
      the sender. Stream content is buffered by the NORM implementation for
      transmission/retransmission and as it is received.</para>

      <sect3>
        <title>Data Transmission</title>

        <para>The behavior of data transport operation is largely placed in
        the control of the NORM sender(s). NORM senders controls their data
        transmission rate, forward error correction (FEC) encoding settings,
        and parameters controlling feedback from the receiver group. Multiple
        senders may operate in a session, each with independent transmission
        parameters. NORM receivers learn needed parameter values from fields
        in NORM message headers.</para>

        <para>NORM transport "objects" (file, data, or stream) are queued for
        transmission by NORM senders. NORM senders may also cancel
        transmission of objects at any time. The NORM sender controls the
        transmission rate either manually (fixed transmission rate) or
        automatically when NORM congestion control operation is enabled. The
        NORM congestion control mechanism is designed to be "friendly" to
        other data flows on the network, fairly sharing available
        bandwidth.<link
        linkend="NormSetAutoParity"><literal>NormSetAutoParity()</literal></link>)
        to achieve reliable transfer) receive object transmission before any
        extensive repair process that may be required to satisfy other
        receivers with poor network connectivity. The repair boundary can also
        be set for individual remote senders using the <link
        linkend="NormNodeSetRepairBoundary"><literal>NormNodeSetRepairBoundary()</literal></link>
        function.<literal>NORM_OBJECT_FILE</literal> objects. This function
        must be called before any file objects may be received and thus should
        be called before any calls to <link
        linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
        are made. However, note that the cache directory may be changed even
        during active NORM reception. In this case, the new specified
        directory path will be used for subsequently-received files. Any files
        received before a directory path change will remain in the previous
        cache location. Note that the <link
        linkend="NormFileRename"><literal>NormFileRename()</literal></link>
        function may be used to rename, and thus potentially move, received
        files after reception has begun.</para>

        <para>By default, the NORM sender transmits application-enqueued data
        content, providing repair transmissions (usually in the form of FEC
        messages) only when requested by NACKs from the receivers. However,
        the application may also configure NORM to proactively send some
        amount of FEC content along with the original data content to create a
        "robust" transmission that, in some cases, may be reliably received
        without any NACKing activity. This can allow for some degree of
        reliable protocol operation even without receiver feedback available.
        NORM senders may also requeue (within the limits of "transmit cache"
        settings) objects for repeat transmission, and receivers may combine
        together multiple transmissions to reliably receive content.
        Additionally, hybrid proactive/reactive FEC repair operation is
        possible with the receiver NACK process as a "backup" for when network
        packet loss exceeds the repair capability of the proactive FEC
        settings.</para>

        <para>The NRL NORM implementation also supports optional collection of
        positive acknowledgment from a subset of the receiver group at
        application-determined positions during data transmission. The NORM
        API allows the application to specify the receiver subset ("acking
        node list") and set "watermark" points for which positive
        acknowledgement is collected. This process can provide the application
        with explicit flow control for an application-determined critical set
        of receivers in the group.</para>

        <para>For a NORM application to perform data transmission, it must
        first create a session using <link
        linkend="NormCreateSession"><literal>NormCreateSession()</literal></link>
        and make a call to <link
        linkend="NormStartSender"><literal>NormStartSender()</literal></link>
        before sending actual user data. The functions <link
        linkend="NormFileEnqueue"><literal>NormFileEnqueue()</literal></link>,
        <link
        linkend="NormDataEnqueue"><literal>NormDataEnqueue()</literal></link>,
        and <link
        linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
        are available for the application to pass data to the NORM protocol
        engine for transmission. Note that to use <link
        linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>,
        a "sender stream" must first be created using <link
        linkend="NormStreamOpen"><literal>NormStreamOpen()</literal></link>.
        In the case of <link
        linkend="NormFileEnqueue"><literal>NormFileEnqueue()</literal></link>
        and <link
        linkend="NormDataEnqueue"><literal>NormDataEnqueue()</literal></link>,
        the NORM protocol engine directly accesses the application file or
        memory space to refer to the transmitted content and does not make its
        own copy of this data.</para>

        <para>The calls to enqueue transport objects or write to a stream may
        be called at any time, but the <literal>NORM_TX_QUEUE_EMPTY</literal>
        and <literal>NORM_TX_QUEUE_VACANCY</literal> notification events (see
        <link
        linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>)
        provide useful cues for when these functions may be successfully
        called. Typically, an application might catch both
        <literal>NORM_TX_QUEUE_EMPTY</literal> and
        <literal>NORM_TX_QUEUE_VACANCY</literal> event types as cues for
        enqueuing additional transport objects or writing to a stream.
        However, an application may choose to cue off of
        <literal>NORM_TX_QUEUE_EMPTY</literal> only if it wishes to provide
        the "freshest" data to NORM for transmission. The advantage of
        additionally using <literal>NORM_TX_QUEUE_VACANCY</literal> is that if
        the application uses this cue to fill up NORM transport object or
        stream buffers, it can keep the NORM stream busy sending data and
        realize the highest possible transmission rate when attempting very
        high speed communication (Otherwise, the NORM protocol engine may
        experience some "dead air time" waiting for the application thread to
        respond to a <literal>NORM_TX_QUEUE_EMPTY</literal> event). Note the
        sender application can control buffer depths as needed with the <link
        linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>
        and <link
        linkend="NormStreamOpen"><literal>NormStreamOpen()</literal></link>
        calls. Additionally, it is possible for applications to configure the
        transmit object "cache" (see <link
        linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>)
        and use the <link
        linkend="NormRequeueObject"><literal>NormRequeueObject()</literal></link>
        call (for objects that have not yet received a
        <parameter>NORM_TX_OBJECT_PURGED</parameter> notification) to effect a
        sort of "data carousel" operation with repeated transmission of the
        cached objects. The <parameter>NORM_TX_OBJECT_SENT</parameter>
        notification can be used a cue to properly control the "requeue"
        cycle(s).</para>

        <para>The NORM implementation provides a form of timer-based flow
        control that limits how quickly sender applications may enqueue new
        objects or stream data for transmission. The <link
        linkend="NormSetFlowControl"><literal>NormSetFlowControl()</literal></link>
        call is provided to control this behavior, including the option to
        disable it. This timer-based mechanism is a type of "soft" flow
        control by allowing receivers "sufficient" time to request repair of
        pending data the sender has enqueued. A more explicit form of flow
        control using the optional "watermark flushing" mechanism is described
        below.</para>

        <para>Another cue that can be leveraged by the sender application to
        determine when it is appropriate to enqueue (or write) additional data
        for transmission is the <literal>NORM_TX_WATERMARK_COMPLETED</literal>
        event. This event is posted when the flushing or explicit positive
        acknowledgment collection process has completed for a "watermark"
        point in transmission that was set by the sender (see <link
        linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
        and <link
        linkend="NormAddAckingNode"><literal>NormAddAckingNode()</literal></link>).
        A list of <link
        linkend="NormNodeId"><literal>NormNodeId</literal></link> values can
        be supplied from which explicit acknowledgement is expected and/or the
        <link linkend="NormNodeId"><literal>NormNodeId</literal></link>
        <literal>NORM_NODE_NONE</literal> can be set (using <link
        linkend="NormAddAckingNode"><literal>NormAddAckingNode()</literal></link>)
        for completion of a NACK-based version of the watermark flushing
        procedure. This flushing process can be used as a flow control
        mechanism for NORM applications. Note this is distinct from NORM's
        congestion control mechanism that, while it provides network-friendly
        transmission rate control, does guarantee flow control to receiving
        nodes.<literal>NORM_NODE_NONE</literal> can be set (using <link
        linkend="NormAddAckingNode"><literal>NormAddAckingNode()</literal></link>)
        for completion of a NACK-based version of the watermark flushing
        procedure. This flushing process can be used as a flow control
        mechanism for NORM applications. Note this is distinct from NORM's
        congestion control mechanism that, while it provides network-friendly
        transmission rate control, does guarantee flow control to receiving
        nodes.</para>
      </sect3>

      <sect3>
        <title>Data Reception</title>

        <para>NORM receiver applications learn of active senders and their
        corresponding pending and completed data transfers, etc via the API
        event dispatching mechanism. By default, NORM receivers use NACK
        messages to request repair of transmitted content from the originating
        sender as needed to achieve reliable transfer. Some API functions are
        available to provide some additional control over the NACKing
        behavior, such as initially NACKing for <literal>NORM_INFO</literal>
        content only or even to the extent of disabling receiver feedback
        (silent receiver or emission-controlled (EMCON) operation) entirely.
        Otherwise, the parameters and operation of reliable data transmission
        are left to sender applications and receivers learn of sender
        parameters in NORM protocol message headers and are instructed by
        <literal>NORM_CMD</literal> messages from the sender(s).</para>

        <para>With respect to the NORM API, the receiver application is
        informed of new senders and receive data objects via the the
        <parameter>NORM_REMOTE_SENDER_NEW</parameter> and
        <parameter>NORM_RX_OBJECT_NEW</parameter> notifications, respectfully.
        Additionally, object reception progress is indicated with the
        <parameter>NORM_RX_OBJECT_UPDATED</parameter> notification and this
        also serves as an indicator for the
        <parameter>NORM_OBJECT_STREAM</parameter> type that the receive
        application should make calls to <link
        linkend="NormStreamRead"><literal>NormStreamRead()</literal></link> to
        read newly received stream content. NORM sender status is also
        conveyed via the <parameter>NORM_REMOTE_SENDER_ACTIVE</parameter> and
        NORM_REMOTE_SENDER_INACTIVE notifications. For example, the receiver
        application may use the
        <parameter>NORM_REMOTE_SENDER_INACTIVE</parameter> as a cue to make
        calls to <link
        linkend="NormNodeFreeBuffers"><literal>NormNodeFreeBuffers()</literal></link>
        and/or <link
        linkend="NormNodeDelete"><literal>NormNodeDelete()</literal></link> to
        free memory resources allocated for buffering received content for the
        given sender. The amount of memory allocated <emphasis>per
        sender</emphasis> is set in the <link
        linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
        call.</para>
      </sect3>
    </sect2>

    <sect2>
      <title>API Event Notification</title>

      <para>An asynchronous event dispatching mechanism is provided to notify
      the application of significant NORM protocol events. The centerpiece of
      this is the <link
      linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
      function that can be used to retrieve the next NORM protocol engine
      event in the form of a <link
      linkend="NormEvent"><literal>NormEvent</literal></link> structure. This
      function will typically block until a <link
      linkend="NormEvent"><literal>NormEvent</literal></link> occurs. However,
      non-blocking operation may be achieved by using the <link
      linkend="NormGetDescriptor"><literal>NormGetDescriptor()</literal></link>
      call to get a <link
      linkend="NormDescriptor"><type>NormDescriptor</type></link> (file
      descriptor) value (Unix <type>int</type> or Win32 <type>HANDLE</type>)
      suitable for use in a asynchronous I/O monitoring functions such as the
      Unix <function>select()</function> or Win32
      <function>MsgWaitForMultipleObjects()</function> system calls. The a
      <link linkend="NormDescriptor"><type>NormDescriptor</type></link> will
      be signaled when a <link
      linkend="NormEvent"><literal>NormEvent</literal></link> is available.
      For Win32 platforms, dispatching of a user-defined Windows message for
      NORM event notification is also planned for a future update to the NORM
      API.</para>
    </sect2>
  </sect1>

  <sect1>
    <title>Build Notes</title>

    <para>To build applications that use the NORM library, a path to the
    "normApi.h" header file must be provided and the linker step needs to
    reference the NORM library file ("<filename>libnorm.a</filename>" for Unix
    platforms and "<filename>Norm.lib</filename>" for Win32 platforms). NORM
    also depends upon the NRL Protean Protocol Prototyping toolkit "Protokit"
    library (a.k.a "Protolib") (static library files
    "<filename>libProtokit.a</filename>" for Unix and
    "<filename>Protokit.lib</filename>" for Win32). Shared or
    dynamically-linked versions of these libraries may also be built from the
    NORM source code or provided. Depending upon the platform, some additional
    library dependencies may be required to support the needs of NORM and/or
    Protokit. These are described below.</para>

    <para>The "makefiles" directory contains Unix Makefiles for various
    platforms the "win32" and "wince" sub-directories there contain Microsoft
    Visual C++ (VC++) and Embedded VC++ project files for building the NORM
    implementation. Additionally, a "waf" (Python-based build tool) build
    option is supported that can be used to build and install the NORM library
    code on the supported platforms. Finally, Python and Java bindings to the
    NORM API are included and "src/python" and "src/java" directories contain
    the code for these and the "makefiles/java" directory contains Makefiles
    to build the NORM Java JNI bindings. Note the "waf" tool can also be used
    to build the Java and Python bindings.</para>

    <sect2>
      <title>Unix Platforms</title>

      <para>NORM has been built and tested on Linux (various architectures),
      MacOS (BSD), Solaris, and IRIX (SGI) platforms. The code should be
      readily portable to other Unix platforms.</para>

      <para>To support IPv6 operation, the NORM and the Protokit library must
      be compiled with the "<constant>HAVE_IPV6</constant>" macro defined.
      This is default in the NORM and Protokit Makefiles for platforms that
      support IPv6. It is important that NORM and Protokit be built with this
      macro defined the same. With NORM, it is recommended that "large file
      support" options be enabled when possible.</para>

      <para>The NORM API uses threading so that the NORM protocol engine may
      run independent of the application. Thus the "POSIX Threads" library
      must be included ("-pthread") in the linking step. MacOS/BSD also
      requires the addition of the "-lresolv" (resolver) library and Solaris
      requires the dynamic loader, network/socket, and resolver libraries
      ("-lnsl -lsocket -lresolv") to achieve successful compilation. The
      Makefiles in the NORM source code distribution are a reference for these
      requirements. Note that MacOS 9 and earlier are not supported.</para>

      <para>Additionally, it is critical that the
      _<constant>FILE_OFFSET_BITS</constant> macro be consistently defined for
      the NORM library build and the application build using the library. The
      distributed NORM Makefiles have
      <constant>-D_FILE_OFFSET_BITS=64</constant> set in the compilation to
      enable "large file support". Applications built using NORM should have
      the same compilation option set to operate correctly (The definition of
      the <link linkend="NormSize"><literal>NormSize</literal></link> type in
      "<filename>normApi.h</filename>" depends upon this compilation
      flag).</para>
    </sect2>

    <sect2>
      <title>Win32/WiNCE Platforms</title>

      <para>NORM has been built using Microsoft's Visual C++ (6.0 and .NET)
      and Embedded VC++ 4.2 environments. In addition to proper macro
      definitions (e.g., HAVE_IPV6, etc) that are included in the respective
      "Protokit" and "NORM" project files, it is important that common code
      generation settings be used when building the NORM application. The NORM
      and Protokit projects are built with the "Multi-threading DLL" library
      usage set. The NORM API requires multi-threading support. This is a
      critical setting and numerous compiler and linker errors will result if
      this is not properly set for your application project.</para>

      <para>NORM and Protokit also depend on the Winsock 2.0
      ("<filename>ws2_32.lib</filename>" (or "<filename>ws2.lib</filename>"
      (WinCE)) and the IP Helper API ("<filename>iphlpapi.lib</filename>")
      libraries and these must be included in the project "Link"
      attributes.</para>

      <para>An additional note is that a bug in VC++ 6.0 and earlier compilers
      (includes embedded VC++ 4.x compilers) prevent compilation of
      Protokit-based code with debugging capabilities enabled. However, this
      has been resolved in VC++ .NET and is hoped to be resolved in the future
      for the WinCE build tools.</para>

      <para>Operation on Windows NT4 (and perhaps other older Windows
      operating systems) requires that the compile time macro
      <constant>WINVER=0x0400</constant> defined. This is because the version
      of the IP Helper API library (<filename>iphlpapi.lib</filename>) used by
      <emphasis>Protolib</emphasis> (and hence NORM) for this system doesn't
      support some of the functions defined for this library. This may be
      related to IPv6 support issues so it may be possible that the Protolib
      build could be tweaked to provide a single binary executable suitable
      for IPv4 operation only across a large range of Windows
      platforms.</para>
    </sect2>
  </sect1>

  <sect1>
    <title>API Reference</title>

    <para>This section provides a reference to the NORM API variable types,
    constants and functions.</para>

    <sect2>
      <title>API Variable Types and Constants</title>

      <para>The NORM API defines and enumerates a number of supporting
      variable types and values which are used in different function calls.
      The variable types are described here.</para>

      <sect3 id="NormInstanceHandle">
        <title>NormInstanceHandle</title>

        <para>The <link
        linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link>
        type is returned when a NORM API instance is created (see <link
        linkend="NormCreateInstance"><literal>NormCreateInstance()</literal></link>).
        This handle can be subsequently used for API calls which require
        reference to a specific NORM API instance. By default, each NORM API
        instance instantiated creates an operating system thread for protocol
        operation. Note that multiple NORM transport sessions may be created
        for a single API instance. In general, it is expected that
        applications will create a single NORM API instance, but some
        multi-threaded application designs may prefer multiple corresponding
        NORM API instances. The value <literal>NORM_INSTANCE_INVALID</literal>
        corresponds to an invalid API instance.</para>
      </sect3>

      <sect3 id="NormSessionHandle">
        <title>NormSessionHandle</title>

        <para>The <link
        linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>
        type is used to reference NORM transport sessions which have been
        created using the <link
        linkend="NormCreateSession"><literal>NormCreateSession()</literal></link>
        API call. Multiple <link
        linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>
        values may be associated with a given <link
        linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link>.
        The special value <literal>NORM_SESSION_INVALID</literal> is used to
        refer to invalid session references.</para>
      </sect3>

      <sect3 id="NormSessionId">
        <title>NormSessionId</title>

        <para>The <link
        linkend="NormSessionId"><literal>NormSessionId</literal></link> type
        is used by applications to uniquely identify their instance of
        participation as a sender within a <emphasis>NormSession</emphasis>.
        This type is a parameter to the <link
        linkend="NormStartSender"><literal>NormStartSender()</literal></link>
        function. Robust applications can use different <link
        linkend="NormSessionId"><literal>NormSessionId</literal></link> values
        when initiating sender operation so that receivers can discriminate
        when a sender has terminated and restarted (whether intentional or due
        to system failure). For example, an application could cache its prior
        <link linkend="NormSessionId"><literal>NormSessionId</literal></link>
        value in non-volatile storage which could then be recovered and
        incremented (for example) upon system restart to produce a new value.
        The <link
        linkend="NormSessionId"><literal>NormSessionId</literal></link> value
        is used for the value of the instance_id field in NORM protocol sender
        messages (see the NORM protocol specification) and receivers use this
        field to detect sender restart within a
        <emphasis>NormSession</emphasis>.</para>
      </sect3>

      <sect3 id="NormNodeHandle">
        <title>NormNodeHandle</title>

        <para>The <link
        linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> type
        is used to reference state kept by the NORM implementation with
        respect to other participants within a
        <emphasis>NormSession</emphasis>. Most typically, the <link
        linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> is
        used by receiver applications to dereference information about remote
        senders of data as needed. The special value
        <literal>NORM_NODE_INVALID</literal> corresponds to an invalid
        reference.</para>
      </sect3>

      <sect3 id="NormNodeId">
        <title>NormNodeId</title>

        <para>The <link
        linkend="NormNodeId"><literal>NormNodeId</literal></link> type
        corresponds to a 32-bit numeric value which should uniquely identify a
        participant (node) in a given <emphasis>NormSession</emphasis>. The
        <link
        linkend="NormNodeGetId"><literal>NormNodeGetId()</literal></link>
        function can be used to retrieve this value given a valid <link
        linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>. The
        special value <literal>NORM_NODE_NONE</literal> corresponds to an
        invalid (or null) node while the value
        <literal>NORM_NODE_ANY</literal> serves as a wild card value for some
        functions.</para>
      </sect3>

      <sect3 id="NormObjectHandle">
        <title>NormObjectHandle</title>

        <para>The <link
        linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
        type is used to reference state kept for data transport objects being
        actively transmitted or received. The state kept for NORM transport
        objects is temporary, but the NORM API provides a function to
        persistently retain state associated with a sender or receiver <link
        linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
        (see <link
        linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>)
        if needed. For sender objects, unless explicitly retained, the <link
        linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
        can be considered valid until the referenced object is explicitly
        canceled (see <link
        linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>)
        or purged from the sender transmission queue (see the event
        <literal>NORM_TX_OBJECT_PURGED</literal>). For receiver objects, these
        handles should be treated as valid only until a subsequent call to
        <link
        linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
        unless, again, specifically retained. The special value
        <literal>NORM_OBJECT_INVALID</literal> corresponds to an invalid
        transport object reference.</para>
      </sect3>

      <sect3 id="NormObjectType">
        <title>NormObjectType</title>

        <para>The <link
        linkend="NormObjectType"><literal>NormObjectType</literal></link> type
        is an enumeration of possible NORM data transport object types. As
        previously mentioned, valid types include:</para>

        <orderedlist>
          <listitem>
            <para><literal>NORM_OBJECT_FILE</literal></para>
          </listitem>

          <listitem>
            <para><literal>NORM_OBJECT_DATA</literal>, and</para>
          </listitem>

          <listitem>
            <para><literal>NORM_OBJECT_STREAM</literal></para>
          </listitem>
        </orderedlist>

        <para>Given a <link
        linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>,
        the application may determine an object's type using the <link
        linkend="NormObjectGetType"><literal>NormObjectGetType()</literal></link>
        function call. A special <link
        linkend="NormObjectType"><literal>NormObjectType</literal></link>
        value, <literal>NORM_OBJECT_NONE</literal>, indicates an invalid
        object type.</para>
      </sect3>

      <sect3 id="NormSize">
        <title>NormSize</title>

        <para>The <link linkend="NormSize"><literal>NormSize</literal></link>
        is the type used for <emphasis>NormObject</emphasis> size information.
        For example, the <link
        linkend="NormObjectGetSize"><literal>NormObjectGetSize()</literal></link>
        function returns a value of type <link
        linkend="NormSize"><literal>NormSize</literal></link>. The range of
        <link linkend="NormSize"><literal>NormSize</literal></link> values
        depends upon the operating system and NORM library compilation
        settings. With "large file support" enabled, as is the case with
        distributed NORM library "Makefiles", the <link
        linkend="NormSize"><literal>NormSize</literal></link> type is a 64-bit
        integer. However, some platforms may support only 32-bit object
        sizes.</para>
      </sect3>

      <sect3 id="NormObjectTransportId">
        <title>NormObjectTransportId</title>

        <para>The <link
        linkend="NormObjectTransportId"><literal>NormObjectTransportId</literal></link>
        type is a 16-bit numerical value assigned to
        <emphasis>NormObjects</emphasis> by senders during active transport.
        These values are temporarily unique with respect to a given sender
        within a <emphasis>NormSession</emphasis> and may be "recycled" for
        use for future transport objects. NORM sender nodes assign these
        values in a monotonically increasing fashion during the course of a
        session as part of protocol operation. Typically, the application
        should not need access to these values, but an API call such as
        <function>NormObjectGetTransportId()</function>
        (<emphasis>TBD</emphasis>) may be provided to retrieve these values if
        needed. (Note this type may be deprecated; i.e., it may not be needed
        at since the <link
        linkend="NormRequeueObject"><function>NormRequeueObject()</function></link>
        function is implemented using handles only, but _some_ applications
        requiring persistence even after a system reboot may need the ability
        to recall previous transport ids?)</para>
      </sect3>

      <sect3 id="NormEventType">
        <title>NormEventType</title>

        <para>The <link
        linkend="NormEventType"><literal>NormEventType</literal></link> is an
        enumeration of NORM API events. "Events" are used by the NORM API to
        signal the application of significant NORM protocol operation events
        (e.g., receipt of a new receive object, etc). A description of
        possible <link
        linkend="NormEventType"><literal>NormEventType</literal></link> values
        and their interpretation is given below. The function call <link
        linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
        is used to retrieve events from the NORM protocol engine.</para>
      </sect3>

      <sect3 id="NormEvent">
        <title>NormEvent</title>

        <para>The <link
        linkend="NormEvent"><literal>NormEvent</literal></link> type is a
        structure used to describe significant NORM protocol events. This
        structure is defined as follows:</para>

        <para><programlisting>typedef struct
{
    NormEventType     type;
    <link linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session; 
    <link linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>    node;
    <link linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>  object;
} <link linkend="NormEvent"><literal>NormEvent</literal></link>;</programlisting></para>

        <para>The <parameter>type</parameter> field indicates the <link
        linkend="NormEventType"><literal>NormEventType</literal></link> and
        determines how the other fields should be interpreted. Note that not
        all <link
        linkend="NormEventType"><literal>NormEventType</literal></link> fields
        are relevant to all events. The <parameter>session</parameter>,
        <parameter>node</parameter>, and <parameter>object</parameter> fields
        indicate the applicable <link
        linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>,
        <link
        linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>, and
        <link
        linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>,
        respectively, to which the event applies. NORM protocol events are
        made available to the application via the <link
        linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
        function call.</para>
      </sect3>

      <sect3 id="NormDescriptor">
        <title>NormDescriptor</title>

        <para>The <link
        linkend="NormDescriptor"><literal>NormDescriptor</literal></link> type
        can provide a reference to a corresponding file descriptor (Unix
        <type>int</type> or Win32 <type>HANDLE</type>) for the
        <emphasis>NormInstance</emphasis>. For a given <link
        linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link>,
        the <link
        linkend="NormGetDescriptor"><literal>NormGetDescriptor()</literal></link>
        function can be used to retrieve a <link
        linkend="NormDescriptor"><literal>NormDescriptor</literal></link>
        value that may, in turn, used in appropriate system calls (e.g.
        <function>select()</function> or
        <function>MsgWaitForMultipleObjects()</function>) to asynchronously
        monitor the NORM protocol engine for notification events (see <link
        linkend="NormEvent"><literal>NormEvent</literal></link>
        description).</para>
      </sect3>

      <sect3 id="NormFlushMode">
        <title>NormFlushMode</title>

        <para>The <link
        linkend="NormFlushMode"><literal>NormFlushMode</literal></link> type
        consists of the following enumeration:</para>

        <para><programlisting>enum <link linkend="NormFlushMode"><literal>NormFlushMode</literal></link>
<literal>{
    NORM_FLUSH_NON</literal>E<literal>,
    NORM_FLUSH_PASSIV</literal>E<literal>,
    NORM_FLUSH_ACTIV</literal>E
};</programlisting></para>

        <para>The use and interpretation of these values is given in the
        descriptions of <link
        linkend="NormStreamFlush"><literal>NormStreamFlush()</literal></link>
        and <link
        linkend="NormStreamSetAutoFlush"><literal>NormStreamSetAutoFlush()</literal></link>
        functions.</para>
      </sect3>

      <sect3 id="NormProbingMode">
        <title>NormProbingMode</title>

        <para>The <link
        linkend="NormProbingMode"><literal>NormProbingMode</literal></link>
        type consists of the following enumeration:</para>

        <para><programlisting>enum <link linkend="NormProbingMode"><literal>NormProbingMode</literal></link>
{
    <literal>NORM_PROBE_NON</literal>E<literal>,
    NORM_PROBE_PASSIV</literal>E<literal>,
    NORM_PROBE_ACTIV</literal>E
};</programlisting></para>

        <para>The use and interpretation of these values is given in the
        description of <link
        linkend="NormSetGrttProbingMode"><literal>NormSetGrttProbingMode()</literal></link>
        function.</para>
      </sect3>

      <sect3 id="NormSyncPolicy">
        <title>NormSyncPolicy</title>

        <para>The <link
        linkend="NormSyncPolicy"><literal>NormSyncPolicy</literal></link> type
        consists of the following enumeration:</para>

        <para><programlisting>enum <link linkend="NormSyncPolicy"><literal>NormSyncPolicy</literal></link>
{
    <literal>NORM_SYNC_CURRENT</literal><literal>,
    NORM_</literal>SYNC_ALL<literal>
};</literal></programlisting></para>

        <para>The use and interpretation of these values is given in the
        descriptions of the <link
        linkend="NormSetDefaultSyncPolicy"><literal>NormSetDefaultSyncPolicy()</literal></link>
        function.</para>
      </sect3>

      <sect3 id="NormNackingMode">
        <title>NormNackingMode</title>

        <para>The <link
        linkend="NormNackingMode"><literal>NormNackingMode</literal></link>
        type consists of the following enumeration:</para>

        <para><programlisting>enum <link linkend="NormNackingMode"><literal>NormNackingMode</literal></link>
{
    <literal>NORM_NACK_NON</literal>E<literal>,
    NORM_NACK_INFO_ONL</literal>Y,
    <literal>NORM_NACK_NORMAL
};</literal></programlisting></para>

        <para>The use and interpretation of these values is given in the
        descriptions of the <link
        linkend="NormSetDefaultNackingMode"><literal>NormSetDefaultNackingMode()</literal></link>,
        <link
        linkend="NormNodeSetNackingMode"><literal>NormNodeSetNackingMode()</literal></link>
        and <link
        linkend="NormObjectSetNackingMode"><literal>NormObjectSetNackingMode()</literal></link>
        functions.</para>
      </sect3>

      <sect3 id="NormRepairBoundary">
        <title>NormRepairBoundary</title>

        <para>The <link
        linkend="NormRepairBoundary"><literal>NormRepairBoundary</literal></link>
        types consists of the following enumeration:</para>

        <para><programlisting>enum <link linkend="NormRepairBoundary"><literal>NormRepairBoundary</literal></link>
{<literal>
    NORM_BOUNDARY_BLOC</literal>K,
    N<literal>ORM_BOUNDARY_OBJECT
};</literal></programlisting></para>

        <para>The interpretation of these values is given in the descriptions
        of the <link
        linkend="NormSetDefaultRepairBoundary"><literal>NormSetDefaultRepairBoundary()</literal></link>
        and <link
        linkend="NormNodeSetRepairBoundary"><literal>NormNodeSetRepairBoundary()</literal></link>
        functions.</para>
      </sect3>

      <sect3 id="NormAckingStatus">
        <title>NormAckingStatus</title>

        <para>The <link
        linkend="NormAckingStatus"><literal>NormAckingStatus</literal></link>
        consist of the following enumeration:</para>

        <para><programlisting>enum <link linkend="NormAckingStatus"><literal>NormAckingStatus</literal></link>
{
    <literal>NORM_ACK_INVALID</literal>,<literal> 
    NORM_ACK_FAILUR</literal>E<literal>,
    NORM_ACK_PENDIN</literal>G,
    <literal>NORM_ACK_SUCCES</literal>S
};</programlisting></para>

        <para>The interpretation of these values is given in the descriptions
        of the <link
        linkend="NormGetAckingStatus"><literal>NormGetAckingStatus()</literal></link>
        function.</para>
      </sect3>
    </sect2>

    <sect2>
      <title>API Initialization and Operation</title>

      <para>The first step in using the NORM API is to create an "instance" of
      the NORM protocol engine. Note that multiple instances may be created by
      the application if necessary, but generally only a single instance is
      required since multiple <emphasis>NormSessions</emphasis> may be managed
      under a single NORM API instance.</para>

      <sect3 id="NormCreateInstance">
        <title>NormCreateInstance()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

<link linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link> <link
              linkend="NormCreateInstance"><literal>NormCreateInstance</literal></link>(bool <parameter>priorityBoost</parameter> = false);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function creates an instance of a NORM protocol engine
          and is the necessary first step before any other API functions may
          be used. With the instantiation of the NORM protocol engine, an
          operating system thread is created for protocol execution. The
          returned <link
          linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link>
          value may be used in subsequent API calls as needed, such <link
          linkend="NormCreateSession"><literal>NormCreateSession()</literal></link>,
          etc. The optional <parameter>priorityBoost</parameter> parameter,
          when set to a value of true, specifies that the NORM protocol engine
          thread be run with higher priority scheduling. On Win32 platforms,
          this corresponds to
          <constant>THREAD_PRIORITY_TIME_CRITICAL</constant> and on Unix
          systems with the <function>sched_setscheduler()</function> API, an
          attempt to get the maximum allowed <constant>SCHED_FIFO</constant>
          priority is made. The use of this option should be carefully
          evaluated since, depending upon the application's scheduling
          priority and NORM API usage, this may have adverse effects instead
          of a guaranteed performance increase!</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A value of <literal>NORM_INSTANCE_INVALID</literal> is
          returned upon failure. The function will only fail if system
          resources are unavailable to allocate the instance and/or create the
          corresponding thread.</para>
        </sect4>
      </sect3>

      <sect3 id="NormDestroyInstance">
        <title>NormDestroyInstance()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormDestroyInstance"><literal>NormDestroyInstance</literal></link>(<link
              linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link> instanceHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>The <link
          linkend="NormDestroyInstance"><literal>NormDestroyInstance()</literal></link>
          function immediately shuts down and destroys the NORM protocol
          engine instance referred to by the
          <parameter>instanceHandle</parameter> parameter. The application
          should make no subsequent references to the indicated <link
          linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link>
          or any other API handles or objects associated with it. However, the
          application is still responsible for releasing any object handles it
          has retained (see <link
          linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
          and <link
          linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>).</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The function has no return value.</para>
        </sect4>
      </sect3>

      <sect3 id="NormStopInstance">
        <title>NormStopInstance()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormStopInstance"><literal>NormStopInstance</literal></link>(<link
              linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link> instanceHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function immediately stops the NORM protocol engine
          thread corresponding to the given
          <parameter>instanceHandle</parameter> parameter. It also posts a
          "dummy" notification event so that if another thread is blocked on a
          call to <link
          linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>,
          that thread will be released. Hence, for some multi-threaded uses of
          the NORM API, this function may be useful as a preliminary step to
          safely coordinate thread shutdown before a call is made to <link
          linkend="NormDestroyInstance"><literal>NormDestroyInstance()</literal></link>.
          After <link
          linkend="NormStopInstance"><literal>NormStopInstance()</literal></link>
          is called and any pending events posted prior to its call have been
          retrieved, <link
          linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
          will return a value of <constant>false</constant>.</para>

          <para>When this function is invoked, state for any
          <emphasis>NormSessions</emphasis> associated with the given instance
          is "frozen". The complementary function, <link
          linkend="NormRestartInstance"><literal>NormRestartInstance()</literal></link>
          can be subsequently used to "unfreeze" and resume NORM protocol
          operation (a new thread is created and started).</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The function has no return value.</para>
        </sect4>
      </sect3>

      <sect3 id="NormRestartInstance">
        <title>NormRestartInstance()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormRestartInstance"><literal>NormRestartInstance</literal></link>(<link
              linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link> instanceHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function creates and starts an operating system thread to
          resume NORM protocol engine operation for the given
          <parameter>instanceHandle</parameter> that was previously stopped by
          a call to <link
          linkend="NormStopInstance"><literal>NormStopInstance()</literal></link>.
          It is not expected that this function will be used often, but there
          may be special application cases where "freezing" and later resuming
          NORM protocol operation may be useful.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The function returns <constant>true</constant> when the NORM
          protocol engine thread is successfully restarted, and
          <constant>false</constant> otherwise.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetCacheDirectory">
        <title>NormSetCacheDirectory()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormSetCacheDirectory"><literal>NormSetCacheDirectory</literal></link>(<link
              linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link>    instanceHandle,
                           const char*           cachePath);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets the directory path used by receivers to
          cache newly-received <constant>NORM_OBJECT_FILE</constant> content.
          The <parameter>instanceHandle</parameter> parameter specifies the
          NORM protocol engine instance (all <emphasis>NormSessions</emphasis>
          associated with that <parameter>instanceHandle</parameter> share the
          same cache path) and the <parameter>cachePath</parameter> is a
          string specifying a valid (and writable) directory path.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The function returns <constant>true</constant> on success and
          <constant>false</constant> on failure. The failure conditions are
          that the indicated directory does not exist or the process does not
          have permissions to write.</para>
        </sect4>
      </sect3>

      <sect3 id="NormGetNextEvent">
        <title>NormGetNextEvent()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormGetNextEvent"><literal>NormGetNextEvent</literal></link>(<link
              linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link> instanceHandle,
                      <link linkend="NormEvent"><literal>NormEvent*</literal></link>         theEvent);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function retrieves the next available NORM protocol event
          from the protocol engine. The <parameter>instanceHandle</parameter>
          parameter specifies the applicable NORM protocol engine, and the
          <parameter>theEvent</parameter> parameter must be a valid pointer to
          a <link linkend="NormEvent"><literal>NormEvent</literal></link>
          structure capable of receiving the NORM event information. For
          expected reliable protocol operation, the application should make
          every attempt to retrieve and process NORM notification events in a
          timely manner.</para>

          <para>Note that this is currently the only blocking call in the NORM
          API. But non-blocking operation may be achieved by using the <link
          linkend="NormGetDescriptor"><literal>NormGetDescriptor()</literal></link>
          function to obtain a descriptor (<type>int</type> for Unix or
          <type>HANDLE</type> for WIN32) suitable for asynchronous
          input/output (I/O) notification using such system calls the Unix
          <function>select()</function> or Win32
          <function>WaitForMultipleObjects()</function> calls. The descriptor
          is signaled when a notification event is pending and a call to <link
          linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
          will not block.<link
          linkend="NormGetNextEvent"><literal>NormGetNextEvent</literal></link></para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The function returns <constant>true</constant> when a <link
          linkend="NormEvent"><type>NormEvent</type></link> is successfully
          retrieved, and <constant>false</constant> otherwise. Note that a
          return value of <constant>false</constant> does
          <emphasis>not</emphasis> indicate an error or signify end of NORM
          operation.</para>
        </sect4>

        <sect4>
          <title>NORM Notification Event Types</title>

          <para>The following table enumerates the possible <link
          linkend="NormEvent"><literal>NormEvent</literal></link> values and
          describes how these notifications should be interpreted as they are
          retrieved by the application via the <link
          linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
          function call.</para>

          <informaltable frame="all">
            <tgroup cols="2">
              <colspec colnum="1" colwidth="1*"/>

              <colspec colnum="2" colwidth="2.5*"/>

              <tbody>
                <row>
                  <entry nameend="c2" namest="c1"><para><emphasis
                  role="bold">Sender Notifications:</emphasis></para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_TX_QUEUE_VACANCY</literal></para></entry>

                  <entry><para>This event indicates that there is room for
                  additional transmit objects to be enqueued, or, if the
                  handle of <literal>NORM_OBJECT_STREAM</literal> is given in
                  the corresponding event "object" field, the application may
                  successfully write to the indicated stream object. Note this
                  event is not dispatched until a call to <link
                  linkend="NormFileEnqueue"><literal>NormFileEnqueue()</literal></link>,
                  <link
                  linkend="NormDataEnqueue"><literal>NormDataEnqueue()</literal></link>,
                  or <link
                  linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
                  fails because of a filled transmit cache or stream
                  buffer.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_TX_QUEUE_EMPTY</literal></para></entry>

                  <entry><para>This event indicates the NORM protocol engine
                  has no new data pending transmission and the application may
                  enqueue additional objects for transmission. If the handle
                  of a sender <literal>NORM_OBJECT_STREAM</literal> is given
                  in the corresponding event "object" field, this indicates
                  the stream transmit buffer has been emptied and the sender
                  application may write to the stream (Use of
                  <literal>NORM_TX_QUEUE_VACANCY</literal> may be preferred
                  for this purpose since it allows the application to keep the
                  NORM protocol engine busier sending data, resulting in
                  higher throughput when attempting very high transfer
                  rates).</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_TX_FLUSH_COMPLETED</literal></para></entry>

                  <entry><para>This event indicates that the flushing process
                  the NORM sender observes when it no longer has data ready
                  for transmission has completed. The completion of the
                  flushing process is a reasonable indicator (with a
                  sufficient NORM "robust factor" value) that the receiver set
                  no longer has any pending repair requests. Note the use of
                  NORM's optional positive acknowledgement feature is more
                  deterministic in this regards, but this notification is
                  useful when there are non-acking (NACK-only) receivers. The
                  default NORM robust factor of 20 (20 flush messages are sent
                  at end-of-transmission) provides a high assurance of
                  reliable transmission, even with packet loss rates of
                  50%.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_TX_WATERMARK_COMPLETED</literal></para></entry>

                  <entry><para>This event indicates that the flushing process
                  initiated by a prior application call to <link
                  linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
                  has completed The posting of this event indicates the
                  appropriate time for the application to make a call <link
                  linkend="NormGetAckingStatus"><literal>NormGetAckingStatus()</literal></link>
                  to determine the results of the watermark flushing
                  process.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_TX_OBJECT_SENT</literal></para></entry>

                  <entry><para>This event indicates that the transport object
                  referenced by the event's "object" field has completed at
                  least one pass of total transmission. Note that this does
                  not guarantee that reliable transmission has yet completed;
                  only that the entire object content has been transmitted.
                  Depending upon network behavior, several rounds of NACKing
                  and repair transmissions may be required to complete
                  reliable transfer.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_TX_OBJECT_PURGED</literal></para></entry>

                  <entry><para>This event indicates that the NORM protocol
                  engine will no longer refer to the transport object
                  identified by the event's "object' field. Typically, this
                  will occur when the application has enqueued more objects
                  than space available within the set sender transmit cache
                  bounds (see <link
                  linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>).
                  Posting of this notification means the application is free
                  to free any resources (memory, files, etc) associated with
                  the indicated "object". After this event, the given "object"
                  handle (<link
                  linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>)
                  is no longer valid unless it is specifically retained by the
                  application.<link
                  linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link></para></entry>
                </row>

                <row>
                  <entry><literal>NORM_TX_CMD_SENT</literal></entry>

                  <entry>This event indicates that an application-defined
                  command previously enqueued with a call to <link
                  linkend="NormSendCommand"><literal>NormSendCommand()</literal></link>
                  has been transmitted, including any repetition.</entry>
                </row>

                <row>
                  <entry><literal>NORM_TX_RATE_CHANGED</literal></entry>

                  <entry>This event indicates that NORM Congestion Control
                  operation has adjusted the transmission rate. The <link
                  linkend="NormGetTxRate"><literal>NormGetTxRate()</literal></link>
                  call may be used to retrieve the new corresponding
                  transmission rate. Note that if <link
                  linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>
                  was called with its <parameter>adjustRate</parameter>
                  parameter set to <constant>false</constant>, then no actual
                  rate change has occurred and the rate value returned by
                  <link
                  linkend="NormGetTxRate"><literal>NormGetTxRate()</literal></link>
                  reflects a "suggested" rate and not the actual transmission
                  rate.</entry>
                </row>

                <row>
                  <entry><para><literal>NORM_LOCAL_SENDER_CLOSED</literal></para></entry>

                  <entry><para>This event is posted when the NORM protocol
                  engine completes the "graceful shutdown" of its
                  participation as a sender in the indicated "session" (see
                  <link
                  linkend="NormStopSender"><literal>NormStopSender()</literal></link>).</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_CC_ACTIVE</literal></para></entry>

                  <entry><para>This event indicates that congestion control
                  feedback from receivers has begun to be received (This also
                  implies that receivers in the group are actually present and
                  can be used as a cue to begin data transmission.). Note that
                  congestion control must be enabled (see <link
                  linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>)
                  for this event to be posted. Congestion control feedback can
                  be assumed to be received until a
                  <literal>NORM_CC_INACTIVE</literal> event is
                  posted.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_CC_INACTIVE</literal></para></entry>

                  <entry><para>This event indicates there has been no recent
                  congestion control feedback received from the receiver set
                  and that the local NORM sender has reached its minimum
                  transmit rate. Applications may wish to refrain from new
                  data transmission until a <literal>NORM_CC_ACTIVE</literal>
                  event is posted. This notification is only posted when
                  congestion control operation is enabled (see <link
                  linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>)
                  and a previous <literal>NORM_CC_ACTIVE</literal> event has
                  occurred.</para></entry>
                </row>

                <row>
                  <entry nameend="c2" namest="c1"><para><emphasis
                  role="bold">Receiver
                  Notifications:</emphasis></para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_REMOTE_SENDER_NEW</literal></para></entry>

                  <entry><para>This event is posted when a receiver first
                  receives messages from a specific remote NORM sender. This
                  marks the beginning of the interval during which the
                  application may reference the provided "node" handle (<link
                  linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>).</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_REMOTE_SENDER_ACTIVE</literal></para></entry>

                  <entry><para>This event is posted when a previously inactive
                  (or new) remote <anchor id="OLE_LINK5"/> <anchor
                  id="OLE_LINK4"/>sender is detected operating as an active
                  sender within the session.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_REMOTE_SENDER_INACTIVE</literal></para></entry>

                  <entry><para>This event is posted after a significant period
                  of inactivity (no sender messages received) of a specific
                  NORM sender within the session. The NORM protocol engine
                  frees buffering resources allocated for this sender when it
                  becomes inactive.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_REMOTE_SENDER_PURGED</literal></para></entry>

                  <entry><para>This event is posted when the NORM protocol
                  engine frees resources for, and thus invalidates the
                  indicated "node" handle.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_RX_OBJECT_NEW</literal></para></entry>

                  <entry><para>This event is posted when reception of a new
                  transport object begins and marks the beginning of the
                  interval during which the specified "object" (<link
                  linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>)
                  is valid.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_RX_OBJECT_INFO</literal></para></entry>

                  <entry><para>This notification is posted when the
                  <literal>NORM_INFO</literal> content for the indicated
                  "object" is received.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_RX_OBJECT_UPDATED</literal></para></entry>

                  <entry><para>This event indicates that the identified
                  receive "object" has newly received data
                  content.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_RX_OBJECT_COMPLETED</literal></para></entry>

                  <entry><para>This event is posted when a receive object is
                  completely received, including available
                  <literal>NORM_INFO</literal> content. Unless the application
                  specifically retains the "object" handle, the indicated
                  <link
                  linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
                  becomes invalid and must no longer be
                  referenced.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_RX_OBJECT_ABORTED</literal></para></entry>

                  <entry><para>This notification is posted when a pending
                  receive object's transmission is aborted by the remote
                  sender. Unless the application specifically retains the
                  "object" handle, the indicated <link
                  linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
                  becomes invalid and must no longer be
                  referenced.</para></entry>
                </row>

                <row>
                  <entry><constant>NORM_RX_CMD_NEW</constant></entry>

                  <entry>This event indicates that an application-defined
                  command has been received from a remote sender. The
                  <type>NormEvent</type> node element indicates the
                  <type>NormNodeHandle</type> value associated with the given
                  sender. The <link
                  linkend="NormNodeGetCommand"><literal>NormNodeGetCommand()</literal></link>
                  call can be used to retrieve the received command
                  content.</entry>
                </row>

                <row>
                  <entry nameend="c2" namest="c1"><para><emphasis
                  role="bold">Miscellaneous
                  Notifications:</emphasis></para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_GRTT_UPDATED</literal></para></entry>

                  <entry><para>This notification indicates that either the
                  local sender estimate of GRTT has changed, or that a remote
                  sender's estimate of GRTT has changed. The "sender" member
                  of the <link
                  linkend="NormEvent"><literal>NormEvent</literal></link> is
                  set to <literal>NORM_NODE_INVALID</literal> if the local
                  sender's GRTT estimate has changed or to the <link
                  linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
                  of the remote sender that has updated its estimate of
                  GRTT.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_EVENT_INVALID</literal></para></entry>

                  <entry><para>This <link
                  linkend="NormEventType"><literal>NormEventType</literal></link>
                  indicates an invalid or "null" notification which should be
                  ignored.</para></entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function generally blocks the thread of application
          execution until a <link
          linkend="NormEvent"><literal>NormEvent</literal></link> is available
          and returns <constant>true</constant> when a <link
          linkend="NormEvent"><literal>NormEvent</literal></link> is
          available. However, there are some exceptional cases when the
          function may immediately return even when no event is pending. In
          these cases, the return value is <constant>false</constant>
          indicating the <link
          linkend="NormEvent"><literal>NormEvent</literal></link> should be
          ignored.</para>

          <para><emphasis>Win32 Note: A future version of this API will
          provide an option to have a user-defined Window message posted when
          a NORM API event is pending. (Also some event filtering calls may be
          provided (e.g. avoid the potentially numerous
          <literal>NORM_RX_OBJECT_UPDATED</literal> events if not needed by
          the application)).</emphasis></para>
        </sect4>
      </sect3>

      <sect3 id="NormGetDescriptor">
        <title>NormGetDescriptor()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

<link linkend="NormDescriptor"><literal>NormDescriptor</literal></link> <link
              linkend="NormGetDescriptor"><literal>NormGetDescriptor</literal></link>(<link
              linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link> instance);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function is used to retrieve a <link
          linkend="NormDescriptor"><literal>NormDescriptor</literal></link>
          (Unix <type>int</type> file descriptor or Win32 <type>HANDLE</type>)
          suitable for asynchronous I/O notification to avoid blocking calls
          to <link
          linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>.
          A <link
          linkend="NormDescriptor"><literal>NormDescriptor</literal></link> is
          available for each protocol engine instance created using <link
          linkend="NormCreateInstance">NormCreateInstance()</link>. The
          descriptor returned is suitable for use as an input (or "read")
          descriptor which is signaled when a NORM protocol event is ready for
          retrieval via <link
          linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>.
          Hence, a call to <link
          linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
          will not block when the descriptor has been signaled. The Unix
          <function>select()</function> or Win32
          <function>WaitForMultipleObjects()</function> system calls can be
          used to detect when the <link
          linkend="NormDescriptor"><literal>NormDescriptor</literal></link> is
          signaled. Note that for Unix <function>select()</function> call
          usage, the NORM descriptor should be treated as a "read"
          descriptor.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A <link
          linkend="NormDescriptor"><type>NormDescriptor</type></link> value is
          returned which is valid until a call to <link
          linkend="NormDestroyInstance"><literal>NormDestroyInstance()</literal></link>
          is made. Upon error, a value of
          <literal>NORM_DESCRIPTOR_INVALID</literal> is returned.</para>
        </sect4>
      </sect3>
    </sect2>

    <sect2>
      <title>Session Creation and Control Functions</title>

      <para>Whether participating in a NORM protocol session as a sender,
      receiver, or both, there are some common API calls used to instantiate a
      <emphasis>NormSession</emphasis> and set some common session parameters.
      Functions are provided to control network socket and multicast
      parameters. Additionally, a "user data" value may be associated with a
      <link
      linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>
      for programming convenience when dealing with multiple sessions.</para>

      <sect3 id="NormCreateSession">
        <title>NormCreateSession()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h<link
              linkend="NormSessionHandle"><literal>
NormSessionHandle</literal></link> <link linkend="NormCreateSession"><literal>NormCreateSession</literal></link>(<link
              linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link>       instance,
                                    const char*              address,
                                    unsigned short           port,
                                    <link linkend="NormNodeId"><literal>NormNodeId</literal></link>               localId);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function creates a NORM protocol session
          (<emphasis>NormSession</emphasis>) using the
          <parameter>address</parameter> (multicast or unicast) and
          <parameter>port</parameter> parameters provided. While session state
          is allocated and initialized, active session participation does not
          begin until a call is made to <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          and/or <link
          linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
          to join the specified multicast group (if applicable) and start
          protocol operation. The following parameters are required in this
          function call:</para>

          <informaltable frame="all">
            <tgroup cols="2">
              <colspec colnum="1" colwidth="1*"/>

              <colspec colnum="2" colwidth="5*"/>

              <tbody>
                <row>
                  <entry><para><literal>instance</literal></para></entry>

                  <entry><para>This must be a valid <link
                  linkend="NormInstanceHandle"><literal>NormInstanceHandle</literal></link>
                  previously obtained with a call to <link
                  linkend="NormCreateInstance"><literal>NormCreateInstance()</literal></link>.</para></entry>
                </row>

                <row>
                  <entry><para><literal>address</literal></para></entry>

                  <entry><para>This points to a string containing an IP
                  address (e.g. dotted decimal IPv4 address (or IPv6 address)
                  or name resolvable to a valid IP address. The specified
                  address (along with the port number) determines the
                  destination of NORM messages sent. For multicast sessions,
                  NORM senders and receivers must use a common multicast
                  address and port number. For unicast sessions, the sender
                  and receiver must use a common port number, but specify the
                  other node's IP address as the session address (Although
                  note that receiver-only unicast nodes who are providing
                  unicast feedback to senders will not generate any messages
                  to the session IP address and the address parameter value is
                  thus inconsequential for this special case).</para></entry>
                </row>

                <row>
                  <entry><para><literal>port</literal></para></entry>

                  <entry><para>This must be a valid, unused port number
                  corresponding to the desired NORM session address. See the
                  address parameter description for more
                  details.</para></entry>
                </row>

                <row>
                  <entry><para><literal>localId</literal></para></entry>

                  <entry><para>The <parameter>localId</parameter> parameter
                  specifies the <link
                  linkend="NormNodeId"><literal>NormNodeId</literal></link>
                  that should be used to identify the application's presence
                  in the <emphasis>NormSession</emphasis>. All participant's
                  in a <emphasis>NormSession</emphasis> should use unique
                  <parameter>localId</parameter> values. The application may
                  specify a value of <literal>NORM_NODE_ANY</literal> or
                  <literal>NORM_NODE_ANY</literal> for the
                  <parameter>localId</parameter> parameter. In this case, the
                  NORM implementation will attempt to pick an identifier based
                  on the host computer's "default" IP address (based on the
                  computer's default host name). Note there is a chance that
                  this approach may not provide unique node identifiers in
                  some situations and the NORM protocol does not currently
                  provide a mechanism to detect or resolve <link
                  linkend="NormNodeId"><literal>NormNodeId</literal></link>
                  collisions. Thus, the application should explicitly specify
                  the <parameter>localId</parameter> unless there is a high
                  degree of confidence that the default IP address will
                  provide a unique identifier.</para></entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The returned <link
          linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>
          value is valid until a call to <link
          linkend="NormDestroySession"><literal>NormDestroySession()</literal></link>
          is made. A value of <literal>NORM_SESSION_INVALID</literal> is
          returned upon error.</para>
        </sect4>
      </sect3>

      <sect3 id="NormDestroySession">
        <title>NormDestroySession()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormDestroySession"><literal>NormDestroySession</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function immediately terminates the application's
          participation in the <emphasis>NormSession</emphasis> identified by
          the <parameter>sessionHandle</parameter> parameter and frees any
          resources used by that session. An exception to this is that the
          application is responsible for releasing any explicitly retained
          <link
          linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
          values (See <link
          linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
          and <link
          linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>).</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no returned values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetUserData">
        <title>NormSetUserData()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetUserData"><literal>NormSetUserData</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                     const void*       userData);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function allows the application to attach a value to the
          previously-created <emphasis>NormSession</emphasis> instance
          specified by the <parameter>sessionHandle</parameter> parameter.
          This value is not used or interpreted by NORM, but is available to
          the application for use at the programmer's discretion. The set
          <parameter>userData</parameter> value can be later retrieved using
          the <link
          linkend="NormGetUserData"><literal>NormGetUserData()</literal></link>
          function call.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no returned values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormGetUserData">
        <title>NormGetUserData()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

const void* <link linkend="NormGetUserData"><literal>NormGetUserData</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function retrieves the "user data" value set for the
          specified <parameter>sessionHandle</parameter> with a prior call to
          <link
          linkend="NormSetUserData"><literal>NormSetUserData()</literal></link>.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns the user data value set for the
          specified session. If no user data value has been previously set, a
          NULL (i.e., <literal>(<type>const void*</type>)0)</literal> value is
          returned.</para>
        </sect4>
      </sect3>

      <sect3 id="NormGetLocalNodeId">
        <title>NormGetLocalNodeId()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

<link linkend="NormNodeId"><literal>NormNodeId</literal></link> <link
              linkend="NormGetLocalNodeId"><literal>NormGetLocalNodeId</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function retrieves the <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link> value used
          for the application's participation in the
          <emphasis>NormSession</emphasis> identified by the
          <parameter>sessionHandle</parameter> parameter. The value may have
          been explicitly set during the <link
          linkend="NormCreateSession"><literal>NormCreateSession()</literal></link>
          call or may have been automatically derived using the host
          computer's "default" IP network address.</para>
        </sect4>

        <sect4>
          <title>Return Valuess</title>

          <para>The returned value indicates the <emphasis>NormNode</emphasis>
          identifier used by the NORM protocol engine for the local
          application's participation in the specified
          <emphasis>NormSession</emphasis>.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetTxPort">
        <title>NormSetTxPort()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormSetTxPort"><literal>NormSetTxPort</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                   unsigned short    txPort,
                   bool              enableReuse = false,
                   const char*       txBindAddress = (const char*)0);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function is used to force NORM to use a specific port
          number for UDP packets sent for the specified
          <parameter>sessionHandle</parameter>. Additionally, it can
          optionally enable reuse of the specified port number and/or specify
          a specific source address binding that is used for packet
          transmission. By default, NORM uses separate port numbers for packet
          transmission and session packet reception (the receive port is
          specified as part of the <link
          linkend="NormCreateSession"><literal>NormCreateSession()</literal></link>
          call), allowing the operating system to pick a freely available port
          for transmission. This call allows the application to pick a
          specific port number for transmission, and furthermore allows the
          application to even specify the same port number for transmission as
          is used for reception. However, the use of separate transmit/receive
          ports allows NORM to discriminate when unicast feedback is occurring
          and thus it is not generally recommended that the transmit port be
          set to the same value as the session receive port.</para>

          <para>The <parameter>enableReuse</parameter> parameter, when set to
          <constant>true</constant>, allows that the specified port may be
          reused for multiple sessions, but care must be taken when enabling
          this option. The <parameter>txBindAddress</parameter> parameter
          allows specification of a specific source address binding for packet
          transmission. The specified address MUST be a valid unicast IP
          address assigned and configured for the host system. Additionally,
          the address specified must be compatible with multicast routing
          and/or the interfaces specified in any calls to <link
          linkend="NormSetMulticastInterface"><literal>NormSetMulticastInterface()</literal></link>
          for the given session when IP multicast is used.</para>

          <para>When the <parameter>txPort</parameter> is set equal to the
          session port number and a <parameter>txBindAddress</parameter> is
          not specified or set equal to the session address, a single socket
          is used for both transmission and reception. If the same port number
          is desired for both packet transmission and reception,
          <emphasis>and</emphasis> a specific source address binding is set,
          then the <parameter>enableReuse</parameter> parameter MUST be (and
          is automatically) set to <constant>true</constant> for successful
          operation. In this case, the receive socket is bound to session
          address if it is multicast and the transmit socket is bound to the
          specified <parameter>txAddress</parameter> although both are bound
          to the same port number.</para>

          <para>Note this call MUST be made <emphasis>before</emphasis> any
          calls to <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          or <link
          linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
          for the given session to work as described.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns <constant>true</constant> upon success
          and <constant>false</constant> upon failure. Failure will occur if a
          <parameter>txBindAddress</parameter> is provided that does not
          correspond to a valid, configured IP address for the local host
          system.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetTxOnly">
        <title>NormSetTxOnly()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormStopSender"><literal>NormSetTxOnly</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                   bool              txOnly,
                   bool              connectToSessionAddress = false);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function limits the <emphasis>NormSession</emphasis> to
          perform NORM sender functions only. It also limits the underlying
          NORM UDP socket usage to open only a single transmit socket
          (tx_socket) and does <emphasis>not</emphasis> open or bind a receive
          socket for the given session address or port number. Thus, if this
          property is set, any NORM receivers MUST enable unicast feedback via
          a call to the <link
          linkend="NormSetDefaultUnicastNack">NormSetDefaultUnicastNack()</link>
          or appropriate <link
          linkend="NormNodeSetUnicastNack">NormNodeSetUnicastNack()</link>
          function in order for their feedback messages (NACKs and ACKs) to be
          received by this sender. The purpose of this function is to allow
          NORM sender sessions to be created as separate process from a
          corresponding NORM receiver session for the same session address and
          port number. By default (when this call is not made), a
          <emphasis>NormSession</emphasis>, even when acting as only a sender
          (see<link linkend="NormStartSender"> NormStartSender()</link>) opens
          two separate UDP sockets including a "receive" socket bound to the
          session port number and a "transmit" socket used for message
          transmission and reception of unicast feedback messages when
          receivers are so configured.</para>

          <para>The optional <parameter>connectToSessionAddress</parameter>
          parameter, when set to <constant>true</constant>, causes the
          underlying NORM code to "<function>connect()</function>" the UDP
          socket to the session (remote receiver) address and port number. If
          the corresponding NORM remote receiver instance uses <link
          linkend="NormSetTxPort">NormSetTxPort()</link> to set its transmit
          port to the same as the session port number, the result is a unique
          binding between this "tx only" sender instance and the remote NORM
          receiver instance. With proper use of <link
          linkend="NormSetRxPortReuse">NormSetRxPortReuse()</link>, this
          allows multiple senders to be properly associated (i.e., binded with
          respect to UDP socket packet demultiplexing) with multiple receivers
          on a single host (all using the same session port number). Note the
          NORM receiver MUST also use the <link
          linkend="NormSetDefaultUnicastNack">NormSetDefaultUnicastNack()</link>
          call so that its feedback messages are directed to the "tx only"
          sender address/port. The motivation for this API call is to allow
          systems have NORM sender and receiver instances in separate
          processes supporting a set (e.g. a mesh) of unicast connections to
          other hosts. The only constraint is that the senders uses a "tx
          port" number that is different from the "rx port" number. This
          enables firewall configurations that only open a pair of UDP ports
          and allow for connection among an arbitrary number of hosts. This
          option is really only relevant for unicast NORM sessions.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetRxPortReuse">
        <title>NormSetRxPortReuse()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetRxPortReuse"><literal>NormSetRxPortReuse</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session,
                        bool              enableReuse,
                        const char*       rxBindAddress = (const char*)0,
                        const char*       senderAddress = (const char*)0,
                        UINT16            senderPort = 0);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function allows the user to control the port reuse and
          binding behavior for the receive socket used for the given NORM
          <parameter>sessionHandle</parameter>. When the
          <parameter>enablReuse</parameter> parameter is set to
          <constant>true</constant>, reuse of the
          <emphasis>NormSession</emphasis> port number by multiple NORM
          instances or sessions is enabled.</para>

          <para>If the optional <parameter>rxBindAddress</parameter> is
          supplied (an IP address or host name in string form), the socket
          will bind() to the given address when it is opened in a call to
          NormStartReceiver() or NormStartSender(). The
          <parameter>rxBindAddress</parameter> MUST be the session multicast
          address (if it is a multicast session) or a valid local unicast
          address in the case of NORM unicast operation. This binding limits
          the socket to receive only packets destined for the specified
          <parameter>rxBindAddress</parameter>. This allows multiple NORM
          sessions to reuse the same port number, but use different multicast
          addresses (or allow for multiple NORM sessions for multiple local
          unicast addresses).</para>

          <para>The optional <parameter>senderAddress</parameter> and
          <parameter>senderPort</parameter> parameters can be used to
          connect() the underlying NORM receive socket to specific
          address/port. This limits the socket to receiving only packets from
          the specified
          <parameter>senderAddress</parameter>/<parameter>senderPort</parameter>.
          This, with receive port reuse enabled, allows for multiple NORM
          receiver instances to be listening to different NORM senders and
          have proper UDP socket demultiplexing occur. Note that it is also
          possible to have single NORM receiver receive transmissions from
          multiple senders, but in some cases it may be desirable for separate
          NORM processes or threads to be used to handle reception from
          separate senders. Thus, this socket binding option is
          provided.</para>

          <para>When this call is not made in any form, the default socket
          binding to IP address INADDR_ANY (equivalent to when this call is
          made and <parameter>rxBindAddress</parameter> is set to
          <constant>NULL</constant>) allows the
          <emphasis>NormSession</emphasis> receive socket to receive any
          multicast or unicast transmissions to the session port number
          provided in the call to <link
          linkend="NormCreateSession"><literal>NormCreateSession()</literal></link>.
          This allows a NORM receiver to receive from senders sending to a
          multicast session address or the receiver's unicast address. As
          mentioned, enabling port reuse and binding the session destination
          address allows multiple NORM sessions on the same port number, but
          participating in different multicast groups.</para>

          <para>Note this call MUST be made <emphasis>before</emphasis> any
          calls to <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          or <link
          linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
          for the given <parameter>sessionHandle</parameter> to
          succeed.</para>

          <para>This call could also be used in conjunction with <link
          linkend="NormSetMulticastInterface"><literal>NormSetMulticastInterface()</literal></link>
          so that multiple <emphasis>NormSessions</emphasis>, using the same
          port and multicast address, could separately cover multiple network
          interfaces (and some sort of application-layer bridging of reliable
          multicast could be realized if desired).</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetMulticastInterface">
        <title>NormSetMulticastInterface()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormSetMulticastInterface"><literal>NormSetMulticastInterface</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session,
                               const char*       interfaceName);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function specifies which host network interface is used
          for IP Multicast transmissions and group membership. This should be
          called <emphasis>before</emphasis> any call to <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          or <link
          linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
          is made so that the IP multicast group is joined on the proper host
          interface. However, if a call to <link
          linkend="NormSetMulticastInterface"><literal>NormSetMulticastInterface()</literal></link>
          is made after either of these function calls, the call will not
          affect the group membership interface, but only dictate that a
          possibly different network interface is used for transmitted NORM
          messages. Thus, the code:</para>

          <para><programlisting><link linkend="NormSetMulticastInterface"><literal>NormSetMulticastInterface</literal></link>(session, "interface1");
<link linkend="NormStartReceiver"><literal>NormStartReceiver</literal></link>(session, ...);<link
                linkend="NormSetMulticastInterface"><literal>
NormSetMulticastInterface</literal></link>(session, "interface2");</programlisting></para>

          <para>will result in NORM group membership (i.e. multicast
          reception) being managed on "<literal>interface1</literal>" while
          NORM multicast transmissions are made via
          "<literal>interface2</literal>".</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A return value of <constant>true</constant> indicates success
          while a return value of <constant>false</constant> indicates that
          the specified interface was invalid. This function will always
          return <constant>true</constant> if made before calls to <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          or <link
          linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>.
          However, those calls may fail if an invalid interface was specified
          with the call described here.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetMulticastInterface">
        <title>NormSetSSM()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormSetMulticastInterface"><literal>NormSetSSM</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session,
                const char*       sourceAddress);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets the source address for Source-Specific
          Multicast (SSM) operation. This should be called
          <emphasis>before</emphasis> any call to <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          or <link
          linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
          is made so that the proper group join is done. The receiver
          application MUST also use the <link
          linkend="NormSetDefaultUnicastNack"><literal>NormSetDefaultUnicastNack()</literal></link>
          call so that feedback traffic is directed back to appropriate
          sender.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A return value of <constant>true</constant> indicates success
          while a return value of <constant>false</constant> indicates that
          the specified source address was invalid. Note that if a valid IP
          address is specified but is improper for SSM (e.g., an IP multicast
          address) the later calls to <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          or <link
          linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
          may fail.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetTTL">
        <title>NormSetTTL()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormSetTTL"><literal>NormSetTTL</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session,
                unsigned char     ttl);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function specifies the time-to-live
          (<parameter>ttl</parameter>) for IP Multicast datagrams generated by
          NORM for the specified <parameter>sessionHandle</parameter>. The IP
          TTL field limits the number of router "hops" that a generated
          multicast packet may traverse before being dropped. For example, if
          TTL is equal to one, the transmissions will be limited to the local
          area network (LAN) of the host computers network interface. Larger
          TTL values should be specified to span large networks. Also note
          that some multicast router configurations use artificial "TTL
          threshold" values to constrain some multicast traffic to an
          administrative boundary. In these cases, the NORM TTL setting must
          also exceed the router "TTL threshold" in order for the NORM traffic
          to be allowed to exit the administrative area.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A return value of <constant>true</constant> indicates success
          while a return value of <constant>false</constant> indicates that
          the specified <parameter>ttl</parameter> could not be set. This
          function will always return <constant>true</constant> if made before
          calls to <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          or <link
          linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>.
          However, those calls may fail if the desired
          <parameter>ttl</parameter> value cannot be set.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetTOS">
        <title>NormSetTOS()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormSetTOS"><literal>NormSetTOS</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>       sessionHandle,
                unsigned char           tos);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function specifies the type-of-service
          (<parameter>tos</parameter>) field value used in IP Multicast
          datagrams generated by NORM for the specified
          <parameter>sessionHandle</parameter>. The IP TOS field value can be
          used as an indicator that a "flow" of packets may merit special
          Quality-of-Service (QoS) treatment by network devices. Users should
          refer to applicable QoS information for their network to determine
          the expected interpretation and treatment (if any) of packets with
          explicit TOS marking.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A return value of <constant>true</constant> indicates success
          while a return value of <constant>false</constant> indicates that
          the specified <parameter>tos</parameter> could not be set. This
          function will always return <constant>true</constant> if made before
          calls to <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          or <link
          linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>.
          However, those calls may fail if the desired
          <parameter>tos</parameter> value cannot be set.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetLoopback">
        <title>NormSetLoopback()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetLoopback"><literal>NormSetLoopback</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                     bool              loopbackEnable);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function enables or disables loopback operation for the
          indicated NORM <parameter>sessionHandle</parameter>. If
          <parameter>loopbackEnable</parameter> is set to
          <constant>true</constant>, loopback operation is enabled which
          allows the application to receive its own message traffic. Thus, an
          application which is both actively receiving and sending may receive
          its own transmissions. Note it is expected that this option would be
          principally be used for test purposes and that applications would
          generally not need to transfer data to themselves. If
          <parameter>loopbackEnable</parameter> is false, the application is
          prevented from receiving its own NORM message transmissions. By
          default, loopback operation is disabled when a
          <emphasis>NormSession</emphasis> is created.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetFragmentation">
        <title>NormSetFragmentation()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormSetFragmentation"><literal>NormSetFragmentation</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                          bool              fragmentation);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets an underlying socket option that enables or
          disables IP datagram fragmentation by network intermediate systems
          according to whether the <parameter>fragmentation</parameter>
          parameter is set to a value of <constant>true</constant> or
          <constant>false</constant>, respectively. If set to
          <constant>true</constant> to enable fragmentation, the DF (don't
          fragment) bit of the headers of NORM UDP/IP packets sent will be
          cleared. Otherwise the DF bit is set and packets will not be
          fragmented by network devices if they exceed a link Maximum
          Transmission Unit (MTU) and will instead be dropped. For IP
          Multicast destinations, some operating systems may always set the DF
          bit of transmitted packets, regardless of the setting here and the
          underlying socket option status. Typically, the DF bit is set (i.e.,
          fragmentation disabled) by default on most operating systems.</para>

          <para>This call is not currently functional on the Mac OSX system
          that does not support the needed
          <constant>IP_MTU_DISCOVER</constant> or
          <constant>IP_DONTFRAG</constant> socket options.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns <constant>true</constant> upon success
          and <constant>false</constant> upon failure.</para>
        </sect4>
      </sect3>
    </sect2>

    <sect2>
      <title><anchor id="_NORM_Sender_Functions"/>NORM Sender
      Functions</title>

      <para>The functions described in this section apply only to NORM sender
      operation. Applications may participate strictly as senders or as
      receivers, or may act as both in the context of a NORM protocol session.
      The NORM sender is responsible for most parameters pertaining to its
      transmission of data. This includes transmission rate, data segmentation
      sizes, FEC coding parameters, stream buffer sizes, etc.</para>

      <sect3 id="NormStartSender">
        <title>NormStartSender()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormStartSender"><literal>NormStartSender</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>        sessionHandle,
                     <link linkend="NormSessionId"><literal>NormSessionId</literal></link>            instanceId,
                     unsigned long            bufferSpace,
                     unsigned short           segmentSize,
                     unsigned char            blockSize,
                     unsigned char            numParity);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>The application's participation as a sender within a specified
          <emphasis>NormSession</emphasis> begins when this function is
          called. This includes protocol activity such as congestion control
          and/or group round-trip timing (GRTT) feedback collection and
          application API activity such as posting of sender-related <link
          linkend="NormEvent"><literal>NormEvent</literal></link>
          notifications. The parameters required for this function call
          include:</para>

          <informaltable frame="all">
            <tgroup cols="2">
              <colspec colnum="1" colwidth="1*"/>

              <colspec colnum="2" colwidth="5*"/>

              <tbody>
                <row>
                  <entry><para><parameter>sessionHandle</parameter></para></entry>

                  <entry><para>This must be a valid <link
                  linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>
                  previously obtained with a call to <link
                  linkend="NormCreateSession"><literal>NormCreateSession()</literal></link>.</para></entry>
                </row>

                <row>
                  <entry><para><parameter>instanceId</parameter></para></entry>

                  <entry><para>Application-defined value used as the
                  <constant>instance_id</constant> field of NORM sender
                  messages for the application's participation within a
                  session. Receivers can detect when a sender has terminated
                  and restarted if the application uses different
                  <parameter>instanceId</parameter> values when initiating
                  sender operation. For example, a robust application could
                  cache previous <parameter>instanceId</parameter> values in
                  non-volatile storage and gracefully recover (without
                  confusing receivers) from a total system shutdown and reboot
                  by using a new <parameter>instanceId</parameter> value upon
                  restart.</para></entry>
                </row>

                <row>
                  <entry><para><parameter>bufferSpace</parameter></para></entry>

                  <entry><para>This specifies the maximum memory space (in
                  bytes) the NORM protocol engine is allowed to use to buffer
                  any sender calculated FEC segments and repair state for the
                  session. The optimum <parameter>bufferSpace</parameter>
                  value is function of the network topology bandwidth*delay
                  product and packet loss characteristics. If the
                  <parameter>bufferSpace</parameter> limit is too small, the
                  protocol may operate less efficiently as the sender is
                  required to possibly recalculate FEC parity segments and/or
                  provide less efficient repair transmission strategies
                  (resort to explicit repair) when state is dropped due to
                  constrained buffering resources. However, note the protocol
                  will still provide reliable transfer. A large
                  <parameter>bufferSpace</parameter> allocation is safer at
                  the expense of possibly committing more memory
                  resources.</para></entry>
                </row>

                <row>
                  <entry><para><parameter>segmentSize</parameter></para></entry>

                  <entry><para>This parameter sets the maximum payload size
                  (in bytes) of NORM sender messages (not including any NORM
                  message header fields). A sender's
                  <parameter>segmentSize</parameter> value is also used by
                  receivers to limit the payload content of some feedback
                  messages (e.g. <literal>NORM_NACK</literal> message content,
                  etc.) generated in response to that sender. Note different
                  senders within a <emphasis>NormSession</emphasis> may use
                  different segmentSize values. Generally, the appropriate
                  segment size to use is dependent upon the types of networks
                  forming the multicast topology, but applications may choose
                  different values for other purposes. Note that application
                  designers MUST account for the size of NORM message headers
                  when selecting a <parameter>segmentSize</parameter>. For
                  example, the <literal>NORM_DATA</literal> message header for
                  a <literal>NORM_OBJECT_STREAM</literal> with full header
                  extensions is 48 bytes in length. In this case, the UDP
                  payload size of these messages generated by NORM would be up
                  to (48 + <parameter>segmentSize</parameter>)
                  bytes.</para></entry>
                </row>

                <row>
                  <entry><para><parameter>blockSize</parameter></para></entry>

                  <entry><para>This parameter sets the number of source symbol
                  segments (packets) per coding block, for the systematic
                  Reed-Solomon FEC code used in the current NORM
                  implementation. For traditional systematic block code
                  "(n,k)" nomenclature, the <parameter>blockSize</parameter>
                  value corresponds to "k". NORM logically segments transport
                  object data content into coding blocks and the
                  <parameter>blockSize</parameter> parameter determines the
                  number of source symbol segments (packets) comprising a
                  single coding block where each source symbol segment is up
                  to <parameter>segmentSize</parameter> bytes in length.. A
                  given block's parity symbol segments are calculated using
                  the corresponding set of source symbol segments. The maximum
                  <parameter>blockSize</parameter> allowed by the 8-bit
                  Reed-Solomon codes in NORM is <constant>255</constant>, with
                  the further limitation that
                  (<parameter>blockSize</parameter> +
                  <parameter>numParity</parameter>) &lt;=
                  <constant>255</constant>.</para></entry>
                </row>

                <row>
                  <entry><para><parameter>numParity</parameter></para></entry>

                  <entry><para>This parameter sets the maximum number of
                  parity symbol segments (packets) the sender is willing to
                  calculate per FEC coding block. The parity symbol segments
                  for a block are calculated from the corresponding
                  <parameter>blockSize</parameter> source symbol segments. In
                  the "<literal>(n,k)</literal>" nomenclature mention above,
                  the <parameter>numParity</parameter> value corresponds to
                  "<literal>n - k</literal>". A property of the Reed-Solomon
                  FEC codes used in the current NORM implementation is that
                  one parity segment can fill any one erasure (missing segment
                  (packet)) for a coding block. For a given
                  <parameter>blockSize</parameter>, the maximum numParity
                  value is (<constant>255</constant> -
                  <parameter>blockSize</parameter>). However, note that
                  computational complexity increases significantly with
                  increasing <parameter>numParity</parameter> values and
                  applications may wish to be conservative with respect to
                  <parameter>numParity</parameter> selection, given
                  anticipated network packet loss conditions and group size
                  scalability concerns. Additional FEC code options may be
                  provided for this NORM implementation in the future with
                  different parameters, capabilities, trade-offs, and
                  computational requirements.</para></entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>

          <para>These parameters are currently immutable with respect to a
          sender's participation within a <emphasis>NormSession</emphasis>.
          Sender operation must be stopped (see <link
          linkend="NormStopSender"><literal>NormStopSender()</literal></link>)
          and restarted with another call to <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          if these parameters require alteration. The API may be extended in
          the future to support additional flexibility here, if required. For
          example, the NORM protocol "<parameter>intance_id</parameter>" field
          may possibly be leveraged to permit a node to establish multiple
          virtual presences as a sender within a
          <emphasis>NormSession</emphasis> in the future. This would allow the
          sender to provide multiple concurrent streams of transport, with
          possibly different FEC and other parameters if appropriate within
          the context of a single <emphasis>NormSession</emphasis>. Again,
          this extended functionality is not yet supported in this
          implementation.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A value of <constant>true</constant> is returned upon success
          and <constant>false</constant> upon failure. The reasons failure may
          occur include limited system resources or that the network sockets
          required for communication failed to open or properly configure.
          (<emphasis>TBD - Provide a <function>NormGetError</function>(<link
          linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>
          <parameter>sessionHandle</parameter>) function to retrieve a more
          specific error indication for this and other
          functions.</emphasis>)</para>
        </sect4>
      </sect3>

      <sect3 id="NormStopSender">
        <title>NormStopSender()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormStopSender"><literal>NormStopSender</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                    bool              graceful = false);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function terminates the application's participation in a
          <emphasis>NormSession</emphasis> as a sender. By default, the sender
          will immediately exit the session identified by the
          <parameter>sessionHandle</parameter> parameter without notifying the
          receiver set of its intention. However a "graceful shutdown" option,
          enabled by setting the <parameter>graceful</parameter> parameter to
          true, is provided to terminate sender operation gracefully,
          notifying the receiver set its pending exit with appropriate
          protocol messaging. A <link
          linkend="NormEvent"><literal>NormEvent</literal></link>,
          <literal>NORM_LOCAL_SENDER_CLOSED</literal>, is dispatched when the
          graceful shutdown process has completed.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetTxRate">
        <title>NormSetTxRate()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetTxRate"><literal>NormSetTxRate</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                   double            rate);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets the transmission
          <parameter>rate</parameter> (in bits per second (bps)) limit used
          for <emphasis>NormSender</emphasis> transmissions for the given
          <parameter>sessionHandle</parameter>. For fixed-rate transmission of
          <literal>NORM_OBJECT_FILE</literal> or
          <literal>NORM_OBJECT_DATA</literal>, this limit determines the data
          rate at which NORM protocol messages and data content are sent. For
          <literal>NORM_OBJECT_STREAM</literal> transmissions, this is the
          maximum rate allowed for transmission (i.e. if the application
          writes to the stream at a lower rate, a lower average NORM
          transmission rate will occur). Note that the application will need
          to consider the overhead of NORM protocol headers when determining
          an appropriate transmission rate for its purposes. When NORM
          congestion control is enabled (see <link
          linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>),
          the <parameter>rate</parameter> set here will be set, but congestion
          control operation, if enabled, may quickly readjust the transmission
          rate.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormGetTxRate">
        <title>NormGetTxRate()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

double <link linkend="NormGetTxRate"><literal>NormGetTxRate</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function retrieves the current sender transmission rate
          in units of bits per second (bps) for the given
          <parameter>sessionHandle</parameter>. When NORM congestion control
          is enabled (see <link
          linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>),
          this reflects the current rate set (or suggested) by NORM congestion
          control operation. Otherwise, this returns the rate that was set
          with the <literal><link
          linkend="NormSetTxRate">NormSetTxRate()</link></literal>
          call.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns the sender transmission rate in units of
          bits per second (bps).</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetTxSocketBuffer">
        <title>NormSetTxSocketBuffer()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormSetTxSocketBuffer"><literal>NormSetTxSocketBuffer</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                           unsigned int      bufferSize);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function can be used to set a non-default socket buffer
          size for the UDP socket used by the specified NORM
          <parameter>sessionHandle</parameter> for data transmission. The
          <parameter>bufferSize</parameter> parameter specifies the desired
          socket buffer size in bytes. Large transmit socket buffer sizes may
          be necessary to achieve high transmission rates when NORM, as a
          user-space process, is unable to precisely time its packet
          transmissions. Similarly, NORM receivers may need to set large
          receive socket buffer sizes to achieve successful, sustained high
          data rate reception (see <link
          linkend="NormSetRxSocketBuffer"><literal>NormSetRxSocketBuffer()</literal></link>).
          Typically, it is more important to set the receive socket buffer
          size (see <link
          linkend="NormSetRxSocketBuffer"><literal>NormSetRxSocketBuffer()</literal></link>)
          as this maintains reliability (i.e. by avoiding receive socket
          buffer overflow) at high data rates while setting a larger transmit
          socket buffer size allows higher average transmission rates to be
          achieved.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns <constant>true</constant> upon success
          and <constant>false</constant> upon failure. Possible failure modes
          include an invalid <parameter>sessionHandle</parameter> parameter, a
          call to <link
          linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
          or <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          has not yet been made for the session, or an invalid
          <parameter>bufferSize</parameter> was given. Note some operating
          systems may require additional system configuration to use
          non-standard socket buffer sizes.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetFlowControl">
        <title>NormSetFlowControl()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetFlowControl"><literal>NormSetFlowControl</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                        double            flowControlFactor);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function controls a scaling factor that is used for
          sender timer-based flow control for the the specified NORM
          <parameter>sessionHandle</parameter>. Timer-based flow control works
          by preventing the NORM sender application from enqueueing new
          transmit objects or stream data that would purge "old" objects or
          stream data when there has been recent NACK activity for those old
          objects or data. If the <parameter>flowControlFactor</parameter> is
          set to <constant>ZERO</constant>, then the flow control mechanism is
          effectively disabled. Larger
          <parameter>flowControlFactor</parameter> values enforce more robust
          flow control by forcing the sender to maintain state longer, but
          then larger transmit buffer, stream buffer, transmit cache bounds
          and receive cache limits (see <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>,
          <link
          linkend="NormStreamOpen"><literal>NormStreamOpen()</literal></link>,
          <link
          linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>,
          and <link
          linkend="NormSetRxCacheLimit"><literal>NormSetRxCacheLimit()</literal></link>,
          respectively) may be needed to maintain throughput in larger
          &lt;delay*bandwidth, loss&gt; conditions. Effectively, a larger
          <parameter>flowControlFactor</parameter> can favor reliability over
          throughput when buffer-constrained.</para>

          <para>The <parameter>flowControlFactor</parameter> is used to
          compute a delay time for when a sender buffered object (or block of
          stream data) may be released (i.e. purged) after transmission or
          applicable NACKs reception. The delay time function is:</para>

          <para><programlisting>flowControlDelay = flowControlFactor * GRTT * (backoffFactor + 1)</programlisting></para>

          <para>where the "<literal>GRTT</literal>" is the sender's advertised
          GRTT estimate and the <literal>backoffFactor</literal> is the
          sender's configured timer-based feedback scaling factor.</para>

          <para>The default value (when this function is not called) of the
          <parameter>flowControlFactor</parameter> is
          <constant>2.0</constant>. Note that a NORM application can also
          implement more explicit, deterministic flow control through use of
          the <link
          linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
          API call, potentially even requiring positive acknowledgement of
          older data before enqueueing new data. Note that using the <link
          linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
          API call with a <constant>NORM_NODE_NONE</constant> member in acking
          node list to force a "full" watermark flush is somewhat equivalent
          to timer-based flow control with a
          <parameter>flowControlFactor</parameter> equal to <literal>2.0 *
          txRobustFactor</literal>.</para>

          <para>If such explicit flow control is implemented by the
          application, then a reduced <parameter>flowControlFactor</parameter>
          (or even <constant>ZERO</constant>) may be used. If "push mode" is
          enabled for a <constant>NORM_OBJECT_STREAM</constant> (see <link
          linkend="NormStreamSetPushEnable"><literal>NormStreamSetPushEnable()</literal></link>),
          then flow control has no effect for the stream.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetCongestionControl">
        <title>NormSetCongestionControl()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetCongestionControl"><literal>NormSetCongestionControl</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                              bool              enable,
                              bool              adjustRate = true);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function enables (or disables) the NORM sender congestion
          control operation for the session designated by the
          <parameter>sessionHandle</parameter> parameter. For best operation,
          this function should be called before the call to <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          is made, but congestion control operation can be dynamically
          enabled/disabled during the course of sender operation. If the value
          of the <parameter>enable</parameter> parameter is
          <constant>true</constant>, congestion control operation is enabled
          while it is disabled for enable equal to <constant>false</constant>.
          When congestion control operation is enabled, the NORM sender
          automatically adjusts its transmission rate based on feedback from
          receivers. If bounds on transmission rate have been set (see <link
          linkend="NormSetTxRateBounds"><literal>NormSetTxRateBounds()</literal></link>)
          the rate adjustment will remain within the set bounds. The
          application will be notified of any changes to the sender
          transmission rate via a <link
          linkend="NormEvent"><literal>NormEvent</literal></link> of type
          <constant>NORM_TX_RATE_CHANGED</constant>.</para>

          <para>The rate set by <link
          linkend="NormSetTxRate"><literal>NormSetTxRate()</literal></link>
          has no effect when congestion control operation is enabled,
          <emphasis>unless</emphasis> the <parameter>adjustRate</parameter>
          parameter here is set to <constant>false</constant>. When the
          <parameter>adjustRate</parameter> parameter is set to
          <constant>false</constant>, the NORM Congestion Control operates as
          usual, with feedback collected from the receiver set and the
          "current limiting receiver" identified, except that no actual
          adjustment is made to the sender's transmission rate. I.e., the
          transmission rate that was set by <literal><link
          linkend="NormSetTxRate">NormSetTxRate()</link></literal> is observed
          by the sender regardless of the feedback received. The
          <constant>NORM_TX_RATE_CHANGED</constant> notification will still
          occur as if the rate were being adjusted and the value returned by
          <link
          linkend="NormGetTxRate"><literal>NormGetTxRate()</literal></link>
          reflects the rate that would have been used had the
          <parameter>adjustRate</parameter> parameter been enabled even though
          no actual rate change has occurred. The purpose of this variation of
          NORM Congestion Control operation is to allow applications to get a
          "suggested" rate from the NORM-CC mechanism. But, it is important to
          note that this "suggested" rate may or may not be appropriate since
          the operation of the NORM-CC algorithm is somewhat dependent on the
          associated NORM sender load on the network. For example, the
          "suggested" rate may be artificially high if the sender application
          has not been correspondingly setting the rate and actively
          transmitting data at that rate. This optional mode of operation is
          provided for EXPERIMENTAL purposes and is NOT RECOMMENDED for
          typical use of NORM.</para>

          <para>NORM's congestion algorithm provides rate adjustment to fairly
          compete for available network bandwidth with other TCP, NORM, or
          similarly governed traffic flows.</para>

          <para>(<emphasis>TBD - Describe the
          <function>NormSetEcnSupport()</function> function as this
          experimental option matures.</emphasis>)</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetTxRateBounds">
        <title>NormSetTxRateBounds()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormSetTxRateBounds"><literal>NormSetTxRateBounds</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                               double            rateMin,
                               double            rateMax);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets the range of sender transmission rates
          within which the NORM congestion control algorithm is allowed to
          operate for the given <parameter>sessionHandle</parameter>. By
          default, the NORM congestion control algorithm operates with no
          lower or upper bound on its rate adjustment. This function allows
          this to be limited where <parameter>rateMin</parameter> corresponds
          to the minimum transmission rate (bps) and
          <parameter>rateMax</parameter> corresponds to the maximum
          transmission rate. One or both of these parameters may be set to
          values less than zero to remove one or both bounds. For example, the
          call "<link
          linkend="NormSetTxRateBounds"><literal>NormSetTxRateBounds</literal></link><literal>(session,
          -1.0, 64000.0)</literal>" will set an upper limit of 64 kbps for the
          sender transmission rate with no lower bound. These rate bounds
          apply only when congestion control operation is enabled (see <link
          linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>).
          If the current congestion control rate falls outside of the
          specified bounds, the sender transmission rate will be adjusted to
          stay within the set bounds.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns <constant>true</constant> upon success.
          If both <parameter>rateMin</parameter> and
          <parameter>rateMax</parameter> are greater than or equal to zero,
          but (<parameter>rateMax</parameter> <literal>&lt;</literal>
          <parameter>rateMin</parameter>), the rate bounds will remain unset
          or unchanged and the function will return
          <constant>false</constant>.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetTxCacheBounds">
        <title>NormSetTxCacheBounds()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                                <link linkend="NormSize"><literal>NormSize</literal></link>          sizeMax,
                                unsigned int      countMin,
                                unsigned int      countMax);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets limits that define the number and total
          size of pending transmit objects a NORM sender will allow to be
          enqueued by the application. Setting these bounds to large values
          means the NORM protocol engine will keep history and state for
          previously transmitted objects for a larger interval of time
          (depending upon the transmission rate) when the application is
          actively enqueueing additional objects in response to
          <literal>NORM_TX_QUEUE_EMPTY</literal> notifications. This can allow
          more time for receivers suffering degraded network conditions to
          make repair requests before the sender "purges" older objects from
          its "transmit cache" when new objects are enqueued. A
          <literal>NORM_TX_OBJECT_PURGED</literal> notification is issued when
          the enqueuing of a new transmit object causes the NORM transmit
          cache to overflow, indicating the NORM sender no longer needs to
          reference the designated old transmit object and the application is
          free to release related resources as needed.</para>

          <para>The <parameter>sizeMax</parameter> parameter sets the maximum
          total size, in bytes, of enqueued objects allowed, providing the
          constraints of the <parameter>countMin</parameter> and
          <parameter>countMax</parameter> parameters are met. The
          <parameter>countMin</parameter> parameter sets the minimum number of
          objects the application may enqueue, regardless of the objects'
          sizes and the <parameter>sizeMax</parameter> value. For example, the
          default <parameter>sizeMax</parameter> value is 20 Mbyte and the
          default <parameter>countMin</parameter> is 8, thus allowing the
          application to always have at least 8 pending objects enqueued for
          transmission if it desires, even if their total size is greater than
          20 Mbyte. Similarly, the <parameter>countMax</parameter> parameter
          sets a ceiling on how many objects may be enqueued, regardless of
          their total sizes with respect to the <parameter>sizeMax</parameter>
          setting. For example, the default <parameter>countMax</parameter>
          value is 256, which means the application is never allowed to have
          more than 256 objects pending transmission enqueued, even if they
          are 256 very small objects. Note that
          <parameter>countMax</parameter> must be greater than or equal to
          <parameter>countMin</parameter> and <parameter>countMin</parameter>
          is recommended to be at least two.</para>

          <para>Note that in the case of <literal>NORM_OBJECT_FILE</literal>
          objects, some operating systems impose limits (e.g. 256) on how many
          open files a process may have at one time and it may be appropriate
          to limit the <parameter>countMax</parameter> value accordingly. In
          other cases, a large <parameter>countMin</parameter> or
          <parameter>countMax</parameter> may be desired to allow the NORM
          sender to act as virtual cache of files or other data available for
          reliable transmission. Future iterations of the NRL NORM
          implementation may support alternative NORM receiver "group join"
          policies that would allow the receivers to request transmission of
          cached content.</para>

          <para>The utility of the <link
          linkend="NormRequeueObject"><literal>NormRequeueObject()</literal></link>
          API call also depends on the parameters set by this function. The
          <link
          linkend="NormRequeueObject"><literal>NormRequeueObject()</literal></link>
          call will only succeed when the given
          <parameter>objectHandle</parameter> corresponds to an object
          maintained in the NORM senders "transmit cache".</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return value.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetAutoParity">
        <title>NormSetAutoParity()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetAutoParity"><literal>NormSetAutoParity</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                       unsigned char     autoParity);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets the quantity of proactive "auto parity"
          <literal>NORM_DATA</literal> messages sent at the end of each FEC
          coding block. By default (i.e., <parameter>autoParity</parameter>
          <literal>=</literal> <constant>0</constant>), FEC content is sent
          only in response to repair requests (NACKs) from receivers. But, by
          setting a non-zero value for <parameter>autoParity</parameter>, the
          sender can automatically accompany each coding block of transport
          object source data segments (<literal>(NORM_DATA</literal> messages)
          with the set number of FEC segments. The number of source symbol
          messages (segments) per FEC coding block is determined by the
          <parameter>blockSize</parameter> parameter used when <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          was called for the given
          <parameter>sessionHandle</parameter>.</para>

          <para>The use of proactively-sent "auto parity" may eliminate the
          need for any receiver NACKing to achieve reliable transfer in
          networks with low packet loss. However, note that the quantity of
          "auto parity" set adds overhead to transport object transmission. In
          networks with a predictable level of packet loss and potentially
          large round-trip times, the use of "auto parity" may allow lower
          latency in the reliable delivery process. Also, its use may
          contribute to a smaller amount of receiver feedback as only
          receivers with exceptional packet loss may need to NACK for
          additional repair content.</para>

          <para>The value of <parameter>autoParity</parameter> set must be
          less than or equal to the <parameter>numParity</parameter> parameter
          set when <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          was called for the given
          <parameter>sessionHandle</parameter>.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormGetGrttEstimate">
        <title>NormGetGrttEstimate()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

double <link linkend="NormGetGrttEstimate"><literal>NormGetGrttEstimate</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function returns the sender's current estimate(in
          seconds) of group round-trip timing (GRTT) for the given NORM
          session. This function may be useful for applications to leverage
          for other purposes the assessment of round-trip timing made by the
          NORM protocol engine. For example, an application may scale its own
          timeouts based on connectivity delays among participants in a NORM
          session. Note that the <literal>NORM_GRTT_UPDATED</literal> event is
          posted (see <link
          linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>)
          by the NORM protocol engine to indicate when changes in the local
          sender or remote senders' GRTT estimate occurs.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns the current sender group round-trip
          timing (GRTT) estimate (in units of seconds). A value of
          <constant>-1.0</constant> is returned if an invalid session value is
          provided.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetGrttEstimate">
        <title>NormSetGrttEstimate()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetGrttEstimate"><literal>NormSetGrttEstimate</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                         double            grtt);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets the sender's estimate of group round-trip
          time (GRTT) (in units of seconds) for the given NORM
          <parameter>sessionHandle</parameter>. This function is expected to
          most typically used to initialize the sender's GRTT estimate prior
          to the call to <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          when the application has a priori confidence that the default
          initial GRTT value of 0.5 second is inappropriate. The sender GRTT
          estimate will be updated during normal sender protocol operation
          after sender startup or if this call is made while sender operation
          is active. For experimental purposes (or very special application
          needs), this API provides a mechanism to control or disable the
          sender GRTT update process (see <link
          linkend="NormSetGrttProbingMode"><literal>NormSetGrttProbingMode()</literal></link>).
          The <parameter>grtt</parameter> value (in seconds) will be limited
          to the maximum GRTT as set (see <link
          linkend="NormSetGrttMax"><literal>NormSetGrttMax()</literal></link>)
          or the default maximum of 10 seconds.</para>

          <para>The sender GRTT is advertised to the receiver group and is
          used to scale various NORM protocol timers. The default NORM GRTT
          estimation process dynamically measures round-trip timing to
          determine an appropriate operating value. An overly-large GRTT
          estimate can introduce additional latency into the reliability
          process (resulting in a larger virtual delay*bandwidth product for
          the protocol and potentially requiring more buffer space to maintain
          reliability). An overly-small GRTT estimate may introduce the
          potential for feedback implosion, limiting the scalability of group
          size.</para>

          <para>Also note that the advertised GRTT estimate can also be
          limited by transmission rate. When the sender transmission rate is
          low, the GRTT is also governed to a lower bound of the nominal
          packet transmission interval (i.e., <literal>1/txRate</literal>).
          This maintains the "event driven" nature of the NORM protocol with
          respect to receiver reception of NORM sender data and
          commands.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetGrttMax">
        <title>NormSetGrttMax()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetGrttMax"><literal>NormSetGrttMax</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                    double            grttMax);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets the sender's maximum advertised GRTT value
          for the given NORM <parameter>sessionHandle</parameter>. The
          <parameter>grttMax</parameter> parameter, in units of seconds,
          limits the GRTT used by the group for scaling protocol timers,
          regardless of larger measured round trip times. The default maximum
          for the NRL NORM library is 10 seconds. See the <link
          linkend="NormSetGrttEstimate"><literal>NormSetGrttEstimate()</literal></link>
          function description for the purpose of the NORM GRTT measurement
          process.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetGrttProbingMode">
        <title>NormSetGrttProbingMode()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetGrttProbingMode"><literal>NormSetGrttProbingMode</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                            <link linkend="NormProbingMode"><literal>NormProbingMode</literal></link>   probingMode);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets the sender's mode of probing for round trip
          timing measurement responses from the receiver set for the given
          NORM <parameter>sessionHandle</parameter>. Possible values for the
          <parameter>probingMode</parameter> parameter include
          <literal>NORM_PROBE_NONE</literal>,
          <literal>NORM_PROBE_PASSIVE</literal>, and
          <literal>NORM_PROBE_ACTIVE</literal>. The default probing mode is
          <literal>NORM_PROBE_ACTIVE</literal>. In this mode, the receiver set
          explicitly acknowledges NORM sender GRTT probes
          (<literal>(NORM_C</literal><literal><literal>M</literal>D(CC)</literal>
          messages) with <literal>NORM_ACK</literal> responses that are
          group-wise suppressed. Note that NORM receivers also will include
          their response to GRTT probing piggy-backed on any
          <literal>NORM_NACK</literal> messages sent in this mode as well to
          minimize feedback.</para>

          <para>Note that the <literal>NORM_PROBE_ACTIVE</literal> probing
          mode is required and automatically set when NORM congestion control
          operation is enabled (see <link
          linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>).
          Thus, when congestion control is enabled, the <link
          linkend="NormSetGrttProbingMode"><literal>NormSetGrttProbingMode()</literal></link>
          function has no effect.</para>

          <para>If congestion control operation is not enabled, the NORM
          application may elect to reduce the volume of feedback traffic by
          setting the <parameter>probingMode</parameter> to
          <literal>NORM_PROBE_PASSIVE</literal>. Here, the NORM sender still
          transmits <literal>NORM_CMD</literal><literal>(CC)</literal> probe
          messages multiplexed with its data transmission, but the receiver
          set does not explicitly acknowledge these probes. Instead the
          receiver set is limited to opportunistically piggy-backing responses
          when <literal>NORM_NACK</literal> messages are generated. Note that
          this may, in some cases, introduce some opportunity for bursts of
          large volume receiver feedback when the sender's estimate of GRTT is
          incorrect due to the reduced probing feedback. But, in some
          controlled network environments, this option for passive probing may
          provide some benefits in reducing protocol overhead.</para>

          <para>Finally, the <parameter>probingMode</parameter> can be set to
          <literal>NORM_PROBE_NONE</literal> to eliminate the overhead (and
          benefits) of NORM GRTT measurement entirely. In this case, the
          sender application must explicitly set its estimate of GRTT using
          the <link
          linkend="NormSetGrttEstimate"><literal>NormSetGrttEstimate()</literal></link>
          function. See this function for a description of the purpose of the
          NORM GRTT measurement.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetGrttProbingInterval">
        <title>NormSetGrttProbingInterval()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetGrttProbingInterval"><literal>NormSetGrttProbingInterval</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                                double            intervalMin,
                                double            intervalMax);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function controls the sender GRTT measurement and
          estimation process for the given NORM
          <parameter>sessionHandle</parameter>. The NORM sender multiplexes
          periodic transmission of <literal>NORM_CMD</literal>(CC) messages
          with its ongoing data transmission or when data transmission is
          idle. When NORM congestion control operation is enabled, these
          probes are sent once per RTT of the current limiting receiver (with
          respect to congestion control rate). In this case the
          <parameter>intervalMin</parameter> and
          <parameter>intervalMax</parameter> parameters (in units of seconds)
          control the rate at which the sender's estimate of GRTT is updated.
          At session start, the estimate is updated at
          <parameter>intervalMin</parameter> and the update interval time is
          doubled until <parameter>intervalMax</parameter> is reached. This
          dynamic allows for a rapid initial estimation of GRTT and a slower,
          steady-state update of GRTT. When congestion control is disabled and
          NORM GRTT probing is enabled (<literal>(NORM_PROBE_ACTIVE</literal>
          or <literal>NORM_PROBE_PASSIVE</literal>) the
          <parameter>intervalMin</parameter> and
          <parameter>intervalMax</parameter> values also determine the rate at
          which <literal>NORM_CMD</literal>(CC) probes are transmitted by the
          sender. Thus by setting larger values for
          <parameter>intervalMin</parameter> and
          <parameter>intervalMax</parameter>, the NORM sender application can
          reduce the overhead of the GRTT measurement process. However, this
          also reduces the ability of NORM to adapt to changes in GRTT.</para>

          <para>The default NORM GRTT <parameter>intervalMin</parameter> and
          <parameter>intervalMax</parameter> values, i.e., when this call is
          not made, are <constant>1.0</constant> second and
          <constant>30.0</constant> seconds, respectively.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetBackoffFactor">
        <title>NormSetBackoffFactor()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetBackoffFactor"><literal>NormSetBackoffFactor</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                          double            backoffFactor);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets the sender's "backoff factor" for the given
          <parameter>sessionHandle</parameter>. The
          <parameter>backoffFactor</parameter> (in units of seconds) is used
          to scale various timeouts related to the NACK repair process. The
          sender advertises its <parameter>backoffFactor</parameter> setting
          to the receiver group in NORM protocol message headers. The default
          <parameter>backoffFactor</parameter> for NORM sessions is
          <constant>4.0</constant> seconds. The
          <parameter>backoffFactor</parameter> is used to determine the
          maximum time that receivers may delay NACK transmissions (and other
          feedback messages) as part of NORM's probabilistic feedback
          suppression technique. For example, the maximum NACK delay time is
          <parameter>backoffFactor</parameter><literal>*GRTT</literal>. Thus a
          large <literal>backoffFactor</literal> value introduces latency into
          the NORM repair process. However, a small backoffFactor value causes
          feedback suppression to be less effective and increases the risk of
          feedback implosion for large receiver group sizes.</para>

          <para>The default setting of <constant>4.0</constant> provides
          reasonable feedback suppression for moderate to large group sizes
          when multicast feedback is possible. The NORM specification
          recommends a <literal>backoffFactor</literal> value of
          <constant>6.0</constant> when unicast feedback is used. However, for
          demanding applications (with respect to repair latency) when group
          sizes are modest, a small (even <constant>0.0</constant>)
          <literal>backoffFactor</literal> value can be specified to reduce
          the latency of reliable data delivery.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetGroupSize">
        <title>NormSetGroupSize()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetGroupSize"><literal>NormSetGroupSize</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                      unsigned int      groupSize);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets the sender's estimate of receiver group
          size for the given <parameter>sessionHandle</parameter>. The sender
          advertises its <parameter>groupSize</parameter> setting to the
          receiver group in NORM protocol message headers that, in turn, use
          this information to shape the distribution curve of their random
          timeouts for the timer-based, probabilistic feedback suppression
          technique used in the NORM protocol. Note that the
          <parameter>groupSize</parameter> estimate does not have to be very
          accurate and values within an order of magnitude of the actual group
          size tend to produce acceptable performance.</para>

          <para>The default <parameter>groupSize</parameter> setting in NORM
          is <constant>1,000</constant> and thus can work well for a wide
          range of actual receiver group sizes. The penalty of an overly large
          estimate is statistically a little more latency in reliable data
          delivery with respect to the round trip time and some potential for
          excess feedback. A substantial underestimation of
          <parameter>groupSize</parameter> increases the risk of feedback
          implosion. Currently, the NORM implementation does not attempt to
          automatically measure <parameter>groupSize</parameter> from receiver
          feedback. Applications could add their own mechanism for this
          (perhaps keeping explicit track of group membership), or it is
          possible that future versions of the NRL NORM implementation may
          have some provision for automatic <parameter>groupSize</parameter>
          estimation by the sender based on receiver feedback messages.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetTxRobustFactor">
        <title>NormSetTxRobustFactor()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetTxRobustFactor"><literal>NormSetTxRobustFactor</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                           int               txRobustFactor);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This routine sets the "robustness factor" used for various
          NORM sender functions. These functions include the number of
          repetitions of "robustly-transmitted" NORM sender commands such as
          <literal><literal>NORM_CMD</literal>(FLUSH)</literal> or similar
          application-defined commands, and the number of attempts that are
          made to collect positive acknowledgement from receivers. These
          commands are distinct from the NORM reliable data transmission
          process, but play a role in overall NORM protocol operation. The
          default <parameter>txRobustFactor</parameter> value is
          <constant>20</constant>. This relatively large value makes the NORM
          sender end-of-transmission flushing and positive acknowledgement
          collection functions somewhat immune from packet loss. However, for
          some applications, the default value may make the NORM protocol more
          "chatty" than desired (particularly if flushing is invoked often).
          In other situations where the network connectivity may be
          intermittent or extremely lossy, it may be useful to actually
          increase this value. The default value (<constant>20</constant>) is
          expected to provide reasonable operation across a wide range of
          network conditions and application types. Since this value is not
          communicated among NORM participants as part of the protocol
          operation, it is important that applications consistently set this
          value among all applications participating in a NORM session.</para>

          <para>Setting <parameter>txRobustFactor</parameter> to a value of
          <constant>-1</constant> makes the redundant transmission of these
          commands continue indefinitely until completion. For example, with
          positive acknowledgement collection, the request process will
          continue indefinitely until all recipients requested acknowledge or
          the request is canceled by the application. Similarly, flushing
          commands would be transmitted repeatedly until data transmission is
          resumed. Typically, setting <parameter>txRobustFactor</parameter> to
          <constant>-1</constant> is not recommended.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormFileEnqueue">
        <title>NormFileEnqueue()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

<link linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> <link
              linkend="NormFileEnqueue"><literal>NormFileEnqueue</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>      sessionHandle,
                                 const char*            filename,
                                 const char*            infoPtr = NULL,
                                 unsigned int           infoLen = 0);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function enqueues a file for transmission within the
          specified NORM <parameter>sessionHandle</parameter>. Note that <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          must have been previously called before files or any transport
          objects may be enqueued and transmitted. The
          <parameter>fileName</parameter> parameter specifies the path to the
          file to be transmitted. The NORM protocol engine read and writes
          directly from/to file system storage for file transport, potentially
          providing for a very large virtual "repair window" as needed for
          some applications. While relative paths with respect to the "current
          working directory" may be used, it is recommended that full paths be
          used when possible. The optional <parameter>infoPtr</parameter> and
          <parameter>infoLen</parameter> parameters are used to associate
          <literal>NORM_INFO</literal> content with the sent transport object.
          The maximum allowed <parameter>infoLen</parameter> corresponds to
          the <parameter>segmentSize</parameter> used in the prior call to
          <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>.
          The use and interpretation of the <literal>NORM_INFO</literal>
          content is left to the application's discretion. Example usage of
          <literal>NORM_INFO</literal> content for
          <literal>NORM_OBJECT_FILE</literal> might include file name,
          creation date, MIME-type or other information which will enable NORM
          receivers to properly handle the file when reception is
          complete.</para>

          <para>The application is allowed to enqueue multiple transmit
          objects within in the "transmit cache" bounds (see <link
          linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>)
          and enqueued objects are transmitted (and repaired as needed) within
          the limits determined by automated congestion control (see <link
          linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>)
          or fixed rate (see <literal><link
          linkend="NormSetTxRate">NormSetTxRate()</link></literal>)
          parameters.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A <link
          linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
          is returned which the application may use in other NORM API calls as
          needed. This handle can be considered valid until the application
          explicitly cancels the object's transmission (see <link
          linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>)
          or a <literal>NORM_TX_OBJECT_PURGED</literal> event is received for
          the given object. Note the application may use the <link
          linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
          method if it wishes to refer to the object after the
          <literal>NORM_TX_OBJECT_PURGED</literal> notification. In this case,
          the application, when finished with the object, must use <link
          linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>
          to free any resources used or else a memory leak condition will
          result. A value of <literal>NORM_OBJECT_INVALID</literal> is return
          upon error. Possible failure conditions include the specified
          session is not operating as a NormSender, insufficient memory
          resources were available, or the "transmit cache" limits have been
          reached and all previously enqueued NORM transmit objects are
          pending transmission. Also the call will fail if the
          <parameter>infoLen</parameter> parameter exceeds the local
          <emphasis>NormSender</emphasis> <parameter>segmentSize</parameter>
          limit.</para>
        </sect4>
      </sect3>

      <sect3 id="NormDataEnqueue">
        <title>NormDataEnqueue()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

<link linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> <link
              linkend="NormDataEnqueue"><literal>NormDataEnqueue</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>      sessionHandle,
                                 const char*            dataPtr,
                                 unsigned int           dataLen,
                                 const char*            infoPtr = NULL,
                                 unsigned int           infoLen = 0);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function enqueues a segment of application memory space
          for transmission within the specified NORM
          <parameter>sessionHandle</parameter>. Note that <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          MUST have been previously called before files or any transport
          objects may be enqueued and transmitted. The
          <parameter>dataPtr</parameter> parameter must be a valid pointer to
          the area of application memory to be transmitted and the
          <parameter>dataLen</parameter> parameter indicates the quantity of
          data to transmit. The NORM protocol engine read and writes directly
          from/to application memory space so it is important that the
          application does not modify (or deallocate) the memory space during
          the time the NORM protocol engine may access this area. After
          calling <link
          linkend="NormDataEnqueue"><literal>NormDataEnqueue()</literal></link>
          for a specific application "dataPtr" memory space, the application
          MUST NOT deallocate (or change the contents of) that memory space
          until a <literal>NORM_TX_OBJECT_PURGED</literal> notification is
          received for the given object or the application itself explicitly
          cancels the object's transmission (see <link
          linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>).</para>

          <para>The optional <parameter>infoPtr</parameter> and
          <parameter>infoLen</parameter> parameters are used to associate
          <literal>NORM_INFO</literal> content with the sent transport object.
          The maximum allowed <parameter>infoLen</parameter> corresponds to
          the <parameter>segmentSize</parameter> used in the prior call to
          <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>.
          The use and interpretation of the <literal>NORM_INFO</literal>
          content is left to the application's discretion. Example usage of
          <literal>NORM_INFO</literal> content for
          <literal>NORM_OBJECT_DATA</literal> might include
          application-defined data typing or other information which will
          enable NORM receiver applications to properly interpret the received
          data when reception is complete. Of course, it is possible that the
          application may embed such typing information in the object data
          content itself. This is left to the application's discretion.</para>

          <para>The application is allowed to enqueue multiple transmit
          objects within in the "transmit cache" bounds (see <link
          linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>)
          and enqueued objects are transmitted (and repaired as needed) within
          the limits determined by automated congestion control (see <link
          linkend="NormSetCongestionControl"><literal>NormSetCongestionControl()</literal></link>)
          or fixed rate (see <literal><link
          linkend="NormSetTxRate">NormSetTxRate()</link></literal>)
          parameters.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A <link
          linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
          is returned which the application may use in other NORM API calls as
          needed. This handle can be considered valid until the application
          explicitly cancels the object's transmission (see <link
          linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>)
          or a <literal>NORM_TX_OBJECT_PURGED</literal> event is received for
          the given object. Note the application may use the <link
          linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
          method if it wishes to refer to the object after the
          <literal>NORM_TX_OBJECT_PURGED</literal> notification. In this case,
          the application, when finished with the object, must use <link
          linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>
          to free any resources used or else a memory leak condition will
          result. A value of <literal>NORM_OBJECT_INVALID</literal> is return
          upon error. Possible failure conditions include the specified
          session is not operating as a NormSender, insufficient memory
          resources were available, or the "transmit cache" limits have been
          reached and all previously enqueued NORM transmit objects are
          pending transmission. Also the call will fail if the
          <parameter>infoLen</parameter> parameter exceeds the local
          <emphasis>NormSender</emphasis> <parameter>segmentSize</parameter>
          limit.</para>
        </sect4>
      </sect3>

      <sect3 id="NormRequeueObject">
        <title>NormRequeueObject()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool NormRequeueObject(<link linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                      <link linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>  objectHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function allows the application to resend (or reset
          transmission of) a <literal>NORM_OBJECT_FILE</literal> or
          <literal>NORM_OBJECT_DATA</literal> transmit object that was
          previously enqueued for the indicated
          <parameter>sessionHandle</parameter>. This function is useful for
          applications sending to silent (non-NACKing) receivers as it enables
          the receivers to take advantage of multiple retransmissions of
          objects (including any auto-parity set, see <link
          linkend="NormSetAutoParity"><literal>NormSetAutoParity()</literal></link>)
          to more robustly receive content. The
          <parameter>objectHandle</parameter> parameter must be a valid
          transmit <link
          linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
          that has not yet been "purged" from the sender's transmit queue.
          Upon success, the specified object will be fully retransmitted using
          the same NORM object transport identifier as was used on its initial
          transmission. This call may be made at any time to restart
          transmission of a previously-enqueued object, but the
          <literal>NORM_TX_OBJECT_SENT</literal> or
          <literal>NORM_TX_FLUSH_COMPLETED</literal> notifications can serve
          as good cues for an appropriate time to resend an object. If
          multiple objects are re-queued, they will be resent in order of
          their initial enqueueing.</para>

          <para>The transmit cache bounds set by <link
          linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>
          determine the number of previously-sent objects retained in the
          sender's transmit queue and that are thus eligible to be requeued
          for retransmission. An object may be requeued via this call multiple
          times, but each distinct requeue should be done after an indication
          such as <literal>NORM_TX_OBJECT_SENT</literal> or
          <literal>NORM_TX_FLUSH_COMPLETED</literal> for the given object.
          Otherwise, the object will simply be reset from its current
          transmission point to transmit from the beginning (i.e. restart).
          Note that the object type <literal>NORM_OBJECT_STREAM</literal>
          cannot currently be requeued.</para>

          <para>(TBD - should a "numRepeats" parameter be added to this
          function?)</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A value of <constant>true</constant> is returned upon success
          and a value of <constant>false</constant> is returned upon failure.
          Possible reasons for failure include an invalid
          <parameter>objectHandle</parameter> was provided (i.e. a
          non-transmit object or transmit object that has been "purged" from
          the transmit queue (see <literal>NORM_TX_OBJECT_PURGED</literal>))
          or the provided object was of type
          <literal>NORM_OBJECT_STREAM</literal>.</para>
        </sect4>
      </sect3>

      <sect3 id="NormStreamOpen">
        <title>NormStreamOpen()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

<link linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> <link
              linkend="NormStreamOpen"><literal>NormStreamOpen</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>      sessionHandle,
                                unsigned int           bufferSize,
                                const char*            infoPtr = NULL,
                                unsigned int           infoLen = 0);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function opens a <literal>NORM_OBJECT_STREAM</literal>
          sender object and enqueues it for transmission within the indicated
          <parameter>sessionHandle</parameter>. NORM streams provide reliable,
          in-order delivery of data content written to the stream by the
          sender application. Note that no data is sent until subsequent calls
          to <link
          linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
          are made unless <literal>NORM_INFO</literal> content is specified
          for the stream with the <parameter>infoPtr</parameter> and
          <parameter>infoLen</parameter> parameters. Example usage of
          <literal>NORM_INFO</literal> content for
          <literal>NORM_OBJECT_STREAM</literal> might include
          application-defined data typing or other information which will
          enable NORM receiver applications to properly interpret the received
          stream as it is being received. The NORM protocol engine buffers
          data written to the stream for original transmission and repair
          transmissions as needed to achieve reliable transfer. The
          <parameter>bufferSize</parameter> parameter controls the size of the
          stream's "repair window" which limits how far back the sender will
          "rewind" to satisfy receiver repair requests.</para>

          <para>NORM, as a NACK-oriented protocol, currently lacks a mechanism
          for receivers to explicitly feedback flow control status to the
          sender unless the sender application specifically leverages NORM's
          optional positive-acknowledgement (ACK) features. Thus, the
          <parameter>bufferSize</parameter> selection plays an important role
          in reliable delivery of NORM stream content. Generally, a larger
          <parameter>bufferSize</parameter> value is safer with respect to
          reliability, but some applications may wish to limit how far the
          sender rewinds to repair receivers with poor connectivity with
          respect to the group at large. Such applications may set a smaller
          <parameter>bufferSize</parameter> to avoid the potential for large
          latency in data delivery (i.e. favor peak delivery latency over full
          reliability). This may result in breaks in the reliable delivery of
          stream data to some receivers, but this form of quasi-reliability
          while limiting latency may be useful for some types of applications
          (e.g. reliable real-time messaging, video or sensor or media data
          transport). Note that NORM receivers can quickly, automatically
          "resync" to the sender after such breaks if the application
          leverages the application message boundary recovery features of NORM
          (see <link
          linkend="NormStreamMarkEom"><literal>NormStreamMarkEom()</literal></link>).</para>

          <para>Note that the current implementation of NORM is designed to
          support only one active stream per session, and that any
          <literal>NORM_OBJECT_DATA</literal> or
          <literal>NORM_OBJECT_FILE</literal> objects enqueued for
          transmission will not begin transmission until an active stream is
          closed. Applications requiring multiple streams or concurrent
          file/data transfer SHOULD generally instantiate multiple
          <emphasis>NormSessions</emphasis> as needed.</para>

          <para>Note there is no corresponding "open" call for receiver
          streams. Receiver <literal>NORM_OBJECT_STREAMs</literal> are
          automatically opened by the NORM protocol engine and the receiver
          applications is notified of new streams via the
          <literal>NORM_RX_OBJECT_NEW</literal> notification (see <link
          linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>).</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A <link
          linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
          is returned which the application may use in other NORM API calls as
          needed. This handle can be considered valid until the application
          explicitly cancels the object's transmission (see <link
          linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>)
          or a <literal>NORM_TX_OBJECT_PURGED</literal> event is received for
          the given object. Note the application may use the <link
          linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
          method if it wishes to refer to the object after the
          <literal>NORM_TX_OBJECT_PURGED</literal> notification. In this case,
          the application, when finished with the object, must use <link
          linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>
          to free any resources used or else a memory leak condition will
          result. A value of <literal>NORM_OBJECT_INVALID</literal> is return
          upon error. Possible failure conditions include the specified
          session is not operating as a <emphasis>NormSender</emphasis>,
          insufficient memory resources were available, or the "transmit
          cache" bounds have been reached and all previously enqueued NORM
          transmit objects are pending transmission. Also the call will fail
          if the <parameter>infoLen</parameter> parameter exceeds the local
          <emphasis>NormSender</emphasis> <parameter>segmentSize</parameter>
          limit.</para>
        </sect4>
      </sect3>

      <sect3 id="NormStreamClose">
        <title>NormStreamClose()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormStreamClose"><literal>NormStreamClose</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle,
                     bool             graceful = false);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function halts transfer of the stream specified by the
          <parameter>streamHandle</parameter> parameter and releases any
          resources used unless the associated object has been explicitly
          retained by a call to <link
          linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>.
          No further calls to <link
          linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
          will be successful for the given
          <parameter>streamHandle</parameter>. The optional graceful
          parameter, when set to a value of true, may be used by NORM senders
          to initiate "graceful" shutdown of a transmit stream. In this case,
          the sender application will be notified that stream has (most
          likely) completed reliable transfer via the
          <literal>NORM_TX_OBJECT_PURGED</literal> notification upon
          completion of the graceful shutdown process. When the
          <parameter>graceful</parameter> option is set to
          <constant>true</constant>, receivers are notified of the stream end
          via an "stream end" stream control code in
          <literal>NORM_DATA</literal> message and will receive a
          <literal>NORM_RX_OBJECT_COMPLETED</literal> notification after all
          received stream content has been read. Otherwise, the stream is
          immediately terminated, regardless of receiver state. In this case,
          this function is equivalent to the <link
          linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>
          routine and may be used for sender or receiver streams. So, it is
          expected this function (<link
          linkend="NormStreamClose"><literal>NormStreamClose()</literal></link>)
          will typically be used for transmit streams by NORM senders.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormStreamWrite">
        <title>NormStreamWrite()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

unsigned int <link linkend="NormStreamWrite"><literal>NormStreamWrite</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle 
                             const char*      buffer,
                             unsigned int     numBytes);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function enqueues data for transmission within the NORM
          stream specified by the <parameter>streamHandle</parameter>
          parameter. The <parameter>buffer</parameter> parameter must be a
          pointer to the data to be enqueued and the
          <parameter>numBytes</parameter> parameter indicates the length of
          the data content. Note this call does not block and will return
          immediately. The return value indicates the number of bytes copied
          from the provided buffer to the internal stream transmission
          buffers. Calls to this function will be successful unless the
          stream's transmit buffer space is fully occupied with data pending
          original or repair transmission if the stream's "push mode" is set
          to false (default, see <link
          linkend="NormStreamSetPushEnable"><literal>NormStreamSetPushEnable()</literal></link>
          for details). If the stream's "push mode" is set to true, a call to
          <link
          linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
          will always result in copying of application data to the stream at
          the cost of previously enqueued data pending transmission (original
          or repair) being dropped by the NORM protocol engine. While NORM
          NACK-based reliability does not provide explicit flow control, there
          is some degree of implicit flow control in limiting writing new data
          to the stream against pending repairs. Other flow control strategies
          are possible using the <link
          linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
          function.<link
          linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
          function.</para>

          <para>The <link
          linkend="NormEvent"><literal>NormEvent</literal></link> values
          <literal>NORM_TX_QUEUE_EMPTY</literal> and
          <literal>NORM_TX_QUEUE_VACANCY</literal> are posted with the <link
          linkend="NormEvent"><literal>NormEvent</literal></link><parameter>::object</parameter>
          field set to a valid sender stream <link
          linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
          to indicate when the stream is ready for writing via this function.
          Note that the <literal>NORM_TX_QUEUE_VACANCY</literal> event type is
          posted only after the stream's transmit buffer has been completely
          filled. Thus, the application must make a call to <link
          linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
          that copies less than the requested <parameter>numBytes</parameter>
          value (return value less than <parameter>numBytes</parameter>)
          before additional <literal>NORM_TX_QUEUE_VACANCY</literal> events
          are posted for the given <parameter>streamHandle</parameter> (i.e.,
          the event type is not re-posted until the application has again
          filled the available stream transmit buffer space). By cueing off of
          <literal>NORM_TX_QUEUE_EMPTY</literal>, the application can write
          its "freshest" available data to the stream, but by cueing off of
          <literal>NORM_TX_QUEUE_VACANCY</literal>, an application can keep
          the NORM protocol engine busiest, to achieve the maximum possible
          throughput at high data rates.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns the number of bytes of data successfully
          enqueued for NORM stream transmission. If the underlying send stream
          buffer is full, this function may return zero or a value less than
          the requested <parameter>numBytes</parameter>.</para>
        </sect4>
      </sect3>

      <sect3 id="NormStreamFlush">
        <title>NormStreamFlush()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormStreamFlush"><literal>NormStreamFlush</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle,
                     bool             eom = false,
                     <link linkend="NormFlushMode"><literal>NormFlushMode</literal></link>    flushMode = <literal>NORM_FLUSH_PASSIVE</literal>);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function causes an immediate "flush" of the transmit
          stream specified by the <parameter>streamHandle</parameter>
          parameter. Normally, unless <link
          linkend="NormStreamSetAutoFlush"><literal>NormStreamSetAutoFlush()</literal></link>
          has been invoked, the NORM protocol engine buffers data written to a
          stream until it has accumulated a sufficient quantity to generate a
          <literal>NORM_DATA</literal> message with a full payload (as
          designated by the <parameter>segmentSize</parameter> parameter of
          the <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>
          call). This results in most efficient operation with respect to
          protocol overhead. However, for some NORM streams, the application
          may not wish wait for such accumulation when critical data has been
          written to a stream. The default stream "flush" operation invoked
          via <link
          linkend="NormStreamFlush"><literal>NormStreamFlush()</literal></link>
          for <parameter>flushMode</parameter> equal to
          <literal>NORM_FLUSH_PASSIVE</literal> causes NORM to immediately
          transmit all enqueued data for the stream (subject to session
          transmit rate limits), even if this results in
          <literal>NORM_DATA</literal> messages with "small" payloads. If the
          optional <parameter>flushMode</parameter> parameter is set to
          <literal>NORM_FLUSH_ACTIVE</literal>, the application can achieve
          reliable delivery of stream content up to the current write position
          in an even more proactive fashion. In this case, the sender
          additionally, actively transmits <literal>NORM_CMD</literal>(FLUSH)
          messages after any enqueued stream content has been sent. This
          immediately prompt receivers for repair requests which reduces
          latency of reliable delivery, but at a cost of some additional
          messaging. Note any such "active" flush activity will be terminated
          upon the next subsequent write to the stream. If
          <parameter>flushMode</parameter> is set to
          <literal>NORM_FLUSH_NONE</literal>, this call has no effect other
          than the optional end-of-message marking described here.</para>

          <para>The optional <parameter>eom</parameter> parameter, when set to
          <constant>true</constant>, allows the sender application to mark an
          end-of-message indication (see <link
          linkend="NormStreamMarkEom"><literal>NormStreamMarkEom()</literal></link>)
          for the stream and initiate flushing in a single function call. The
          end-of-message indication causes NORM to embed the appropriate
          message start byte offset in the <literal>NORM_DATA</literal>
          message generated following a subsequent write to the stream with
          the <literal>NORM_FLAGS_MSG_START</literal> flag. This mechanism
          provide a means for automatic application message boundary recovery
          when receivers join or re-sync to a sender mid-stream.</para>

          <para>Note that frequent flushing, particularly for
          <literal>NORM_FLUSH_ACTIVE</literal> operation, may result in more
          NORM protocol activity than usual, so care must be taken in
          application design and deployment when scalability to large group
          sizes is expected.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormStreamSetAutoFlush">
        <title>NormStreamSetAutoFlush()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormStreamSetAutoFlush"><literal>NormStreamSetAutoFlush</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle
                            <link linkend="NormFlushMode"><literal>NormFlushMode</literal></link>    flushMode);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets "automated flushing" for the NORM transmit
          stream indicated by the <parameter>streamHandle</parameter>
          parameter. By default, a NORM transmit stream is "flushed" only when
          explicitly requested by the application (see <link
          linkend="NormStreamFlush"><literal>NormStreamFlush()</literal></link>).
          However, to simplify programming, the NORM API allows that automated
          flushing be enabled such that the "flush" operation occurs every
          time the full requested buffer provided to a <link
          linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
          call is successfully enqueued. This may be appropriate for messaging
          applications where the provided buffers corresponds to an
          application messages requiring immediate, full transmission. This
          may make the NORM protocol perhaps more "chatty" than its typical
          "bulk transfer" form of operation, but can provide a useful
          capability for some applications.</para>

          <para>Possible values for the <parameter>flushMode</parameter>
          parameter include <literal>NORM_FLUSH_NONE</literal>,
          <literal>NORM_FLUSH_PASSIVE</literal>, and
          <literal>NORM_FLUSH_ACTIVE</literal>. The default setting for a NORM
          stream is <literal>NORM_FLUSH_NONE</literal> where no flushing
          occurs unless explicitly requested via <link
          linkend="NormStreamFlush"><literal>NormStreamFlush()</literal></link>.
          By setting the automated <parameter>flushMode</parameter> to
          <literal>NORM_FLUSH_PASSIVE</literal>, the only action taken is to
          immediately transmit any data that has been written to the stream,
          even if "runt" <literal>NORM_DATA</literal> messages (with payloads
          less than the <emphasis>NormSender</emphasis>
          <parameter>segmentSize</parameter> parameter) are generated as a
          result. If <literal>NORM_FLUSH_ACTIVE</literal> is specified, the
          automated flushing operation is further augmented with the
          additional transmission of
          <literal>NORM_C</literal><literal><literal>MD</literal>(FLUSH)</literal>
          messages to proactively excite the receiver group for repair
          requests.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormStreamSetPushEnable">
        <title>NormStreamSetPushEnable()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormStreamSetPushEnable"><literal>NormStreamSetPushEnable</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle,
                             bool             pushEnable);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function controls how the NORM API behaves when the
          application attempts to enqueue new stream data for transmission
          when the associated stream's transmit buffer is fully occupied with
          data pending original or repair transmission. By default
          (<parameter>pushEnable</parameter> <literal>=</literal>
          <constant>false</constant>), a call to <link
          linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
          will return a zero value under this condition, indicating it was
          unable to enqueue the new data. However, if
          <parameter>pushEnable</parameter> is set to
          <constant>true</constant> for a given
          <parameter>streamHandle</parameter>, the NORM protocol engine will
          discard the oldest buffered stream data (even if it is pending
          repair transmission or has never been transmitted) as needed to
          enqueue the new data. Thus a call to <link
          linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
          will never fail to copy data. This behavior may be desirable for
          applications where it is more important to quickly delivery new data
          than to reliably deliver older data written to a stream. The default
          behavior for a newly opened stream corresponds to
          <parameter>pushEnable</parameter> equals <constant>false</constant>.
          This limits the rate to which an application can write new data to
          the stream to the current transmission rate and status of the
          reliable repair process.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormStreamHasVacancy">
        <title>NormStreamHasVacancy()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormStreamHasVacancy"><literal>NormStreamHasVacancy</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> <parameter>streamHandle</parameter>);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function can be used to query whether the transmit
          stream, specified by the <parameter>streamHandle</parameter>
          parameter, has buffer space available so that the application may
          successfully make a call to <link
          linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>.
          Normally, a call to <link
          linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
          itself can be used to make this determination, but this function can
          be useful when "push mode" has been enabled (see the description of
          the <link
          linkend="NormStreamSetPushEnable"><literal>NormStreamSetPushEnable()</literal></link>
          function) and the application wants to avoid overwriting data
          previously written to the stream that has not yet been transmitted.
          Note that when "push mode" is enabled, a call to <link
          linkend="NormStreamWrite"><literal>NormStreamWrite()</literal></link>
          will always succeed, overwriting previously-enqueued data if
          necessary. Normally, this function will return true after a
          <literal>NORM_TX_QUEUE_VACANCY</literal> notification has been
          received for a given NORM stream object.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns a value of <constant>true</constant>
          when there is transmit buffer space to which the application may
          write and <constant>false</constant> otherwise.</para>
        </sect4>
      </sect3>

      <sect3 id="NormStreamMarkEom">
        <title>NormStreamMarkEom()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormStreamMarkEom"><literal>NormStreamMarkEom</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> <parameter>streamHandle</parameter>);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function allows the application to indicate to the NORM
          protocol engine that the last data successfully written to the
          stream indicated by <parameter>streamHandle</parameter> corresponded
          to the end of an application-defined message boundary. The
          end-of-message indication given here will cause the NORM protocol
          engine to embed the appropriate message start byte offset in the
          <constant>NORM_DATA</constant> message generated that contains the
          data for the subsequent application call to NormStreamWrite(). Use
          of this end-of-message marking enables NORM receivers to
          automatically re-sync to application-defined message boundaries when
          joining (or re-joining) a NORM session already in progress.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetWatermark">
        <title>NormSetWatermark()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormSetWatermark"><literal>NormSetWatermark</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                      <link linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>  objectHandle, 
                      bool              overrideFlush = true);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function specifies a "watermark" transmission point at
          which NORM sender protocol operation should perform a flushing
          process and/or positive acknowledgment collection for a given
          <parameter>sessionHandle</parameter>. For
          <literal>NORM_OBJECT_FILE</literal> and
          <literal>NORM_OBJECT_DATA</literal> transmissions, the positive
          acknowledgement collection will begin when the specified object has
          been completely transmitted. The <parameter>objectHandle</parameter>
          parameter must be a valid handle to a previously-created sender
          object (see <link
          linkend="NormFileEnqueue"><literal>NormFileEnqueue()</literal></link>,
          <link
          linkend="NormDataEnqueue"><literal>NormDataEnqueue()</literal></link>,
          or <link
          linkend="NormStreamOpen"><literal>NormStreamOpen()</literal></link>).
          For <literal>NORM_OBJECT_STREAM</literal> transmission, the positive
          acknowledgment collection begins immediately, using the current
          position (offset of most recent data written) of the sender stream
          as a reference.</para>

          <para>The functions <link
          linkend="NormAddAckingNode"><literal>NormAddAckingNode()</literal></link>
          and <link
          linkend="NormRemoveAckingNode"><literal>NormRemoveAckingNode()</literal></link>
          are used to manage the list of <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link> values
          corresponding to NORM receivers that are expected to explicitly
          acknowledge the watermark flushing messages transmitted by the
          sender. Note that the <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link>
          <literal>NORM_NODE_NONE</literal> may be included in the list.
          Inclusion of <literal>NORM_NODE_NONE</literal> forces the watermark
          flushing process to proceed through a full
          <literal>NORM_ROBUST_FACTOR</literal> number of rounds before
          completing, prompting any receivers that have not completed reliable
          reception to the given watermark point to NACK for any repair needs.
          If NACKs occur, the flushing process is reset and repeated until
          completing with no NACKs for data through the given watermark
          transmission point are received. Thus, even without explicit
          positive acknowledgment, the sender can use this process (by adding
          <literal>NORM_NODE_NONE</literal> to the session's list of "acking
          nodes") for a high level of assurance that the receiver set is
          "happy" (completed reliable data reception) through the given object
          (or stream transmission point).</para>

          <para>The event <literal>NORM_TX_WATERMARK_COMPLETED</literal> is
          posted for the given session when the flushing process or positive
          acknowledgment collection has completed. The process completes as
          soon as all listed receivers have responded unless
          <literal>NORM_NODE_NONE</literal> is included in the "acking node"
          list. The sender application may use the function <link
          linkend="NormGetAckingStatus"><literal>NormGetAckingStatus()</literal></link>
          to determine the degree of success of the flushing process in
          general or for individual <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link>
          values.</para>

          <para>The flushing is conducted concurrently with ongoing data
          transmission and does not impede the progress of reliable data
          transfer. Thus the sender may still enqueue
          <emphasis>NormObjects</emphasis> for transmission (or write to the
          existing stream) and the positive acknowledgement collection and
          flushing procedure will be multiplexed with the ongoing data
          transmission. However, the sender application may wish to defer from
          or limit itself in sending more data until a
          <literal>NORM_TX_WATERMARK_COMPLETED</literal> event is received for
          the given session. This provides a form of sender-&gt;receiver(s)
          flow control which does not exist in NORM's default protocol
          operation. If a subsequent call is made to <link
          linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
          before the current acknowledgement request has completed, the
          pending acknowledgment request is canceled and the new one
          begins.</para>

          <para>The optional <parameter>overrideFlush</parameter> parameter,
          when set to <constant>true</constant>, causes the watermark
          acknowledgment process that is established with this function call
          to potentially fully supersede the usual NORM end-of-transmission
          flushing process that occurs. If
          <parameter>overrideFlush</parameter> is set and the "watermark"
          transmission point corresponds to the last transmission that will
          result from data enqueued by the sending application, then the
          watermark flush completion will terminate the usual flushing
          process. I.e., if positive acknowledgement of watermark is received
          from the full "acking node list", then no further flushing is
          conducted. Thus, the <parameter>overrideFlush</parameter> parameter
          should only be set when the "acking node list" contains a complete
          list of intended recipients. This is useful for small receiver
          groups (or unicast operation) to reduce the "chattiness" of NORM's
          default end-of-transmission flush process. Note that once the
          watermark flush is completed and further data enqueued and
          transmitted, the normal default end-of-transmission behavior will be
          resumed unless another "watermark" is set with
          <parameter>overrideFlush</parameter> enabled. Thus, as long as new
          watermarks are established by successive use of this API call, this
          effectively "morphs" NORM into a protocol driven by positive
          acknowledgement behavior.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The function returns <constant>true</constant> upon successful
          establishment of the watermark point. The function may return
          <constant>false</constant> upon failure.</para>
        </sect4>
      </sect3>

      <sect3 id="NormCancelWatermark">
        <title>NormCancelWatermark()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormCancelWatermark"><literal>NormCancelWatermark</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function cancels any "watermark" acknowledgement request
          that was previously set via the <link
          linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
          function for the given <parameter>sessionHandle</parameter>. The
          status of any NORM receivers that may have acknowledged prior to
          cancellation can be queried using the <link
          linkend="NormGetAckingStatus"><literal>NormGetAckingStatus()</literal></link>
          function even after <link
          linkend="NormCancelWatermark"><literal>NormCancelWatermark()</literal></link>
          is called. Typically, applications should wait until a event has
          been posted, but in some special cases it may be useful to terminate
          the acknowledgement collection process early.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormAddAckingNode">
        <title>NormAddAckingNode()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormAddAckingNode"><literal>NormAddAckingNode</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                       <link linkend="NormNodeId"><literal>NormNodeId</literal></link>        nodeId);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>When this function is called, the specified
          <parameter>nodeId</parameter> is added to the list of <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link> values
          (i.e., the "acking node" list) used when NORM sender operation
          performs positive acknowledgement (ACK) collection for the specified
          <parameter>sessionHandle</parameter>. The optional NORM positive
          acknowledgement collection occurs when a specified transmission
          point (see <link
          linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>)
          is reached or for specialized protocol actions such as
          positively-acknowledged application-defined commands.</para>

          <para>Additionally the special value of
          <parameter>nodeId</parameter> equal to
          <literal>NORM_NODE_NONE</literal> may be set to force the watermark
          flushing process through a full
          <literal>NORM_ROBUST_FACTOR</literal> number of rounds regardless of
          actual acking nodes. Otherwise the flushing process is terminated
          when all of the nodes in the acking node list have responded.
          Setting a "watermark" and forcing a full flush process with the
          special <literal>NORM_NODE_NONE</literal> value of
          <parameter>nodeId</parameter> enables the resultant
          <literal>NORM_TX_WATERMARK_COMPLETED</literal> notification to be a
          indicator with high (but not absolute) assurance that the receiver
          set has completed reliable reception of content up through the
          "watermark" transmission point. This provides a form of scalable
          reliable multicast "flow control" for NACK-based operation without
          requiring explicit positive acknowledgement from all group members.
          Note that the use of the <literal>NORM_NODE_NONE</literal> value may
          be mixed with other <parameter>nodeId</parameter> for a mix of
          positive acknowledgement collection from some nodes and a measure of
          assurance for the group at large.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The function returns <constant>true</constant> upon success
          and <constant>false</constant> upon failure. The only failure
          condition is that insufficient memory resources were available. If a
          specific <parameter>nodeId</parameter> is added more than once, this
          has no effect.</para>
        </sect4>
      </sect3>

      <sect3 id="NormRemoveAckingNode">
        <title>NormRemoveAckingNode()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormRemoveAckingNode"><literal>NormRemoveAckingNode</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                          <link linkend="NormNodeId"><literal>NormNodeId</literal></link>        nodeId);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function deletes the specified
          <parameter>nodeId</parameter> from the list of <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link> values
          used when NORM sender operation performs positive acknowledgement
          (ACK) collection for the specified
          <parameter>sessionHandle</parameter>. Note that if the special
          <parameter>nodeId</parameter> value
          "<literal>NORM_NODE_NONE"</literal> has been added to the list, it
          too must be explicitly removed to change the watermark flushing
          behavior if desired.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormGetNextAckingNode">
        <title>NormGetNextAckingNode()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

NormNodeId <link linkend="NormRemoveAckingNode"><literal>NormGetNextAckingNode</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session, bool reset = false);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function iteratively retrieves the <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link> values in
          the "acking node" list maintained by a NORM sender (see <link
          linkend="NormAddAckingNode"><literal>NormAddAckingNode()</literal></link>)
          for the given <parameter>sessionHandle</parameter>. If the optional
          <parameter>reset</parameter> parameter is set to a value of
          <constant>true</constant>, the first <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link> value in
          the list is returned and subsequent calls to <link
          linkend="NormGetNextAckingNode"><literal>NormGetNextAckingNode()</literal></link>with
          the <parameter>reset</parameter> parameter set to its default
          <constant>false</constant> value will iteratively return the
          remaining <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link> values
          contained in the list. A value of
          <constant>NORM_NODE_NONE</constant> is returned when the end of the
          list is reached.</para>

          <para>The "acking node" list is populated with application calls to
          <link
          linkend="NormAddAckingNode"><literal>NormAddAckingNode()</literal></link>
          or auto-populated if that optional behavior is set for a
          NormSession. Note that this API does not enable the programmer to
          check if the <constant>NORM_NODE_NONE</constant> value itself is
          contained in the list. The programmer should keep track of that by
          other means.</para>

          <para>The following code example illustrates how to use this call to
          iterate through the set of stored <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link> values and
          get the current "acking status" for each:</para>

          <para><programlisting>NormNodeId nextNodeId = NormGetNextAckingNode(session, true);
while(NORM_NODE_NONE != nextNodeId)
{
    NormAckingStatus ackingStatus = NormGetAckingStatus(session, nextNodeId);
    printf("ACKing node id = %lu acking status = %d\n", nextNodeId, (int)ackingStatus);
}</programlisting>As noted below, a good time to check the acking status of
          the receiver set is after a
          <constant>NORM_TX_WATERMARK_COMPLETED</constant> notification has
          occurred.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The function iteratively returns <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link> values
          from the given session's local sender "acking node" list. A value of
          <constant>NORM_NODE_NONE</constant> is returned when the end of the
          list is reached.</para>
        </sect4>
      </sect3>

      <sect3 id="NormGetAckingStatus">
        <title>NormGetAckingStatus()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

<link linkend="NormAckingStatus"><literal>NormAckingStatus</literal></link> <link
              linkend="NormGetAckingStatus"><literal>NormGetAckingStatus</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                                     <link linkend="NormNodeId"><literal>NormNodeId</literal></link>        nodeId = <literal>NORM_NODE_ANY</literal>);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function queries the status of the watermark flushing
          process and/or positive acknowledgment collection initiated by a
          prior call to <link
          linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>
          for the given <parameter>sessionHandle</parameter>. In general, it
          is expected that applications will invoke this function after the
          corresponding <literal>NORM_TX_WATERMARK_COMPLETED</literal> event
          has been posted. Setting the default parameter value
          <parameter>nodeId</parameter> = <literal>NORM_NODE_ANY</literal>
          returns a "status" indication for the overall process. Also,
          individual <parameter>nodeId</parameter> values may be queried using
          the <link linkend="NormNodeId"><literal>NormNodeId</literal></link>
          values of receivers that were included in previous calls to <link
          linkend="NormAddAckingNode"><literal>NormAddAckingNode()</literal></link>
          to populate the sender session's acking node list.</para>

          <para>If the flushing/acknowledgment process is being used for
          application flow control, the sender application may wish to reset
          the watermark and flushing process (using <link
          linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>)
          if the response indicates that some nodes have failed to respond.
          However, note that the flushing/acknowledgment process itself does
          elicit NACKs from receivers as needed and is interrupted and reset
          by any repair response that occurs. Thus, even by the time the
          flushing process has completed (and
          <literal>NORM_TX_WATERMARK_COMPLETED</literal> is posted) once, this
          is an indication that the NORM protocol has made a valiant attempt
          to deliver the content. Resetting the watermark process can increase
          robustness, but it may be in vain to repeat this process multiple
          times when likely network connectivity has been lost or expected
          receivers have failed (dropped out, shut down, etc).</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>Possible return values include:</para>

          <informaltable frame="all">
            <tgroup cols="2">
              <tbody>
                <row>
                  <entry><para><literal>NORM_ACK_INVALID</literal></para></entry>

                  <entry><para>The given <parameter>sessionHandle</parameter>
                  is invalid or the given <parameter>nodeId</parameter> is not
                  in the sender's acking list.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_ACK_FAILURE</literal></para></entry>

                  <entry><para>The positive acknowledgement collection process
                  did not receive acknowledgment from every listed receiver
                  (<parameter>nodeId</parameter> =
                  <literal>NORM_NODE_ANY</literal>) or the identified
                  <parameter>nodeId</parameter> did not
                  respond.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_ACK_PENDING</literal></para></entry>

                  <entry><para>The flushing process at large has not yet
                  completed (<parameter>nodeId</parameter> =
                  <literal>NORM_NODE_ANY</literal>) or the given individual
                  <parameter>nodeId</parameter> is still being queried for
                  response.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_ACK_SUCCESS</literal></para></entry>

                  <entry><para>All receivers (<parameter>nodeId</parameter> =
                  <literal>NORM_NODE_ANY</literal>) responded with positive
                  acknowledgement or the given specific
                  <parameter>nodeId</parameter> did
                  acknowledge.</para></entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>
        </sect4>
      </sect3>

      <sect3 id="NormSendCommand">
        <title>NormSendCommand()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormSendCommand"><literal>NormSendCommand</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session,
                     const char*       cmdBuffer,
                     unsigned int      cmdLength,
                     bool              robust = false); </programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function enqueues a NORM application-defined command for
          transmission. The <parameter>cmdBuffer</parameter> parameter points
          to a buffer containing the application-defined command content that
          will be contained in the <literal>NORM_CMD(APPLICATION)</literal>
          message payload. The <parameter>cmdLength</parameter> indicates the
          length of this content (in bytes) and MUST be less than or equal to
          the <parameter>segmentLength</parameter> value for the given
          <parameter>session</parameter> (see <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>).
          The NORM command transmission will be multiplexed with any NORM data
          transmission. The command is NOT delivered reliably, but can be
          optionally transmitted with repetition (once per GRTT) according to
          the NORM transmit robust factor value (see <link
          linkend="NormSetTxRobustFactor"><literal>NormSetTxRobustFactor()</literal></link>)
          for the given session if the <parameter>robust</parameter> parameter
          is set to <constant>true</constant>. The command transmission is
          subject to any congestion control or set rate limits for the NORM
          session. Once the command has been transmitted (with repetition if
          <parameter>robust</parameter> is set to <constant>true</constant>),
          a <constant>NORM_TX_CMD_SENT</constant> notification is issued. An
          application can only enqueue a <emphasis>single</emphasis> command
          at a time (i.e. the <constant>NORM_TX_CMD_SENT</constant>
          notification must occur before another command can be sent). The
          <link
          linkend="NormCancelCommand"><literal>NormCancelCommand()</literal></link>
          call is available to terminate command transmission if needed. Note
          that if a rapid succession of commands are sent it is possible that
          the commands may be delivered to the receivers out-of-order. Also,
          when repetition is requested (i.e., if <parameter>robust</parameter>
          is set to <constant>true</constant>) the receiver may receive
          duplicate copies of the same command. It is up to the application to
          provide any needed mechanism for detecting and/or filtering
          duplicate command reception.</para>

          <para>The application-defined command feature allows NORM
          applications to provide some out-of-band (with respect to reliable
          data delivery) signaling to support session management or other
          functions. The reception of these "atomic" commands is relatively
          stateless (as compared to reliable data delivery) and thus it is
          possible for many senders within a group to send commands without
          extreme resource burden on receivers (i.e. other participants).
          Again, this "light-weight" signaling mechanism may be used to
          provide ancillary communication for the group. In the future, an
          additional API mechanism will be provided to support
          application-defined positive acknowledgement requests that could
          conceivably be used to help guarantee command delivery if
          desired.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The function returns <constant>true</constant> upon success.
          The function may fail, returning <constant>false</constant>, if the
          session is not set for sender operation (see <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>),
          the <parameter>cmdLength</parameter> exceeds the configured session
          <parameter>segmentLength</parameter>, or a previously-enqueued
          command has not yet been sent.</para>
        </sect4>
      </sect3>

      <sect3 id="NormCancelCommand">
        <title>NormCancelCommand()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormCancelCommand"><literal>NormCancelCommand</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> session);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function terminates any pending
          <literal>NORM_CMD(APPLICATION)</literal> transmission that was
          previously initiated with the <link
          linkend="NormSendCommand"><literal>NormSendCommand()</literal></link>
          call. Due to the asynchrony of the NORM protocol engine thread and
          the application, it is possible that the command may have been
          already sent but the <link
          linkend="NormCancelCommand"><literal>NormCancelCommand()</literal></link>
          call will ensure a <constant>NORM_TX_CMD_SENT</constant>
          notification is <emphasis>not</emphasis> issued for that prior
          command.</para>

          <para>The application-defined command feature allows NORM
          applications to provide some out-of-band (with respect to reliable
          data delivery) signaling to support session management or other
          functions. The reception of these "atomic" commands is relatively
          stateless (as compared to reliable data delivery) and thus it is
          possible for many senders within a group to send commands without
          extreme resource burden on receivers (i.e. other participants).
          Again, this "light-weight" signaling mechanism may be used to
          provide ancillary communication for the group. In the future, an
          additional API mechanism will be provided to support
          application-defined positive acknowledgement requests that could
          conceivably be used to help guarantee command delivery if
          desired.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The function has not return value.</para>
        </sect4>
      </sect3>
    </sect2>

    <sect2>
      <title>NORM Receiver Functions</title>

      <sect3 id="NormStartReceiver">
        <title>NormStartReceiver()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormStartReceiver"><literal>NormStartReceiver</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                       unsigned long     bufferSpace);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function initiates the application's participation as a
          receiver within the <emphasis>NormSession</emphasis> identified by
          the <parameter>sessionHandle</parameter> parameter. The NORM
          protocol engine will begin providing the application with
          receiver-related <link
          linkend="NormEvent"><literal>NormEvent</literal></link>
          notifications, and, unless <link
          linkend="NormSetSilentReceiver"><literal>NormSetSilentReceiver</literal></link>(<constant>true</constant>)
          is invoked, respond to senders with appropriate protocol messages.
          The <parameter>bufferSpace</parameter> parameter is used to set a
          limit on the amount of <parameter>bufferSpace</parameter> allocated
          by the receiver per active <emphasis>NormSender</emphasis> within
          the session. The appropriate <parameter>bufferSpace</parameter> to
          use is a function of expected network delay*bandwidth product and
          packet loss characteristics. A discussion of trade-offs associated
          with NORM transmit and receiver buffer space selection is provided
          later in this document. An insufficient
          <parameter>bufferSpace</parameter> allocation will result in
          potentially inefficient protocol operation, even though reliable
          operation may be maintained. In some cases of a large
          delay*bandwidth product and/or severe packet loss, a small
          <parameter>bufferSpace</parameter> allocation (coupled with the lack
          of explicit flow control in NORM) may result in the receiver
          "re-syncing" to the sender, resulting in "outages" in the reliable
          transmissions from a sender (this is analogous to a TCP connection
          timeout failure).</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A value of <constant>true</constant> is returned upon success
          and <constant>false</constant> upon failure. The reasons failure may
          occur include limited system resources or that the network sockets
          required for session communication failed to open or properly
          configure.</para>
        </sect4>
      </sect3>

      <sect3 id="NormStopReceiver">
        <title>NormStopReceiver()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormStopReceiver"><literal>NormStopReceiver</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                      unsigned int      gracePeriod = 0);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function ends the application's participation as a
          receiver in the <emphasis>NormSession</emphasis> specified by the
          session parameter. By default, all receiver-related protocol
          activity is immediately halted and all receiver-related resources
          are freed (except for those which have been specifically retained
          (see <link
          linkend="NormNodeRetain"><literal>NormNodeRetain()</literal></link>
          and <link
          linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>).
          However, and optional <parameter>gracePeriod</parameter> parameter
          is provided to allow the receiver an opportunity to inform the group
          of its intention. This is applicable when the local receiving
          <emphasis>NormNode</emphasis> has been designated as an active
          congestion control representative (i.e. current limiting receiver
          (CLR) or potential limiting receiver (PLR)). In this case, a
          non-zero <parameter>gracePeriod</parameter> value provides an
          opportunity for the receiver to respond to the applicable sender(s)
          so the sender will not expect further congestion control feedback
          from this receiver. The <parameter>gracePeriod</parameter> integer
          value is used as a multiplier with the largest sender GRTT to
          determine the actual time period for which the receiver will linger
          in the group to provide such feedback (i.e. <literal>"graceTime" =
          (<parameter>gracePeriod</parameter> * GRTT)</literal>). During this
          time, the receiver will not generate any requests for repair or
          other protocol actions aside from response to applicable congestion
          control probes. When the receiver is removed from the current list
          of receivers in the sender congestion control probe messages (or the
          <parameter>gracePeriod</parameter> expires, whichever comes first),
          the NORM protocol engine will post a
          <literal>NORM_LOCAL_RECEIVER_CLOSED</literal> event for the
          applicable session, and related resources are then freed.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetRxCacheLimit">
        <title>NormSetRxCacheLimit()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetRxCacheLimit"><literal>NormSetRxCacheLimit</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                         unsigned short    countMax);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets a limit on the number of outstanding
          (pending) <emphasis>NormObjects</emphasis> for which a receiver will
          keep state on a per-sender basis. Note that the value
          <parameter>countMax</parameter> sets a limit on the maximum
          consecutive range of objects that can be pending. The default value
          (when this function is not called) of
          <parameter>countMax</parameter> is <constant>256</constant>. This
          should be sufficient for most bulk transfer usage, but if small
          object sizes (e.g. small <constant>NORM_OBJECT_DATA</constant>
          messages) are being transferred, it may be useful to raise this
          limit in cases of high transmission speeds or large
          &lt;delay*bandwidth, loss&gt; network conditions. If the receiver
          cache limit is set too small (i.e. for high speed or large
          &lt;delay*bandwidth&gt; operation), the receiver may not maintain
          reliable reception or impact session throughput when flow control is
          enabled (see <link
          linkend="NormSetFlowControl"><literal>NormSetFlowControl()</literal></link>).
          The maximum allowed value of <parameter>countMax</parameter> is
          <constant>16,384.</constant></para>

          <para>If this value is changed after <link
          linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
          has been called, it will only affect newly-detected remote senders,
          so this should typically be called before NORM receiver operation is
          initiated.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return value.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetRxSocketBuffer">
        <title>NormSetRxSocketBuffer()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormSetRxSocketBuffer"><literal>NormSetRxSocketBuffer</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                           unsigned int      bufferSize);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function allows the application to set an alternative,
          non-default buffer size for the UDP socket used by the specified
          NORM <parameter>sessionHandle</parameter> for packet reception. This
          may be necessary for high speed NORM sessions where the UDP receive
          socket buffer becomes a bottleneck when the NORM protocol engine
          (which is running as a user-space process) doesn't get to service
          the receive socket quickly enough resulting in packet loss when the
          socket buffer overflows. The <parameter>bufferSize</parameter>
          parameter specifies the socket buffer size in bytes. Different
          operating systems and sometimes system configurations allow
          different ranges of socket buffer sizes to be set. Note that a call
          to <link
          linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
          (or <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>)
          must have been previously made for this call to succeed (i.e., the
          socket must be already open).</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns <constant>true</constant> upon success
          and <constant>false</constant> upon failure. Possible reasons for
          failure include, 1) the specified session is not valid, 2) that NORM
          "receiver" (or "sender") operation has not yet been started for the
          given session, or 3) an invalid <parameter>bufferSize</parameter>
          specification was given.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetSilentReceiver">
        <title>NormSetSilentReceiver()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetSilentReceiver"><literal>NormSetSilentReceiver</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                           bool              silent,
                           INT32             maxDelay = -1);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function provides the option to configure a NORM receiver
          application as a "silent receiver". This mode of receiver operation
          dictates that the host does not generate any protocol messages while
          operating as a receiver within the specified
          <parameter>sessionHandle</parameter>. Setting the
          <parameter>silent</parameter> parameter to <constant>true</constant>
          enables silent receiver operation while setting it to
          <constant>false</constant> results in normal protocol operation
          where feedback is provided as needed for reliability and protocol
          operation. Silent receivers are dependent upon proactive FEC
          transmission (see <link
          linkend="NormSetAutoParity"><literal>NormSetAutoParity()</literal></link>)
          or using repair information requested by other non-silent receivers
          within the group to achieve reliable transfers.</para>

          <para>The optional <parameter>maxDelay</parameter> parameter is most
          applicable for reception of the
          <literal>NORM_OBJECT_STREAM</literal> type. The default value of
          <parameter>maxDelay</parameter> <literal>=</literal>
          <constant>-1</constant> corresponds to normal operation where source
          data segments for incompletely-received FEC coding blocks (or
          transport objects) are passed to the application only when imposed
          buffer constraints (either the <literal>NORM_OBJECT_STREAM</literal>
          buffer size (see <link
          linkend="NormStreamOpen"><literal>NormStreamOpen()</literal></link>)
          or the FEC receive buffer limit (see <link
          linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>)
          require. Thus, the default behavior (<parameter>maxDelay</parameter>
          <literal>=</literal> <constant>-1</constant>), causes the receiver
          to buffer received FEC code blocks for as long as possible (within
          buffer constraints as newer data arrives) before allowing the
          application to read the data. Hence, the receive latency (delay) can
          be quite long depending upon buffer size settings, transmission
          rate, etc. When the <constant>maxDelay</constant> parameter is set
          to a non-negative value, the value determines the maximum number of
          FEC coding blocks (according to a NORM sender's current transmit
          position) the receiver will cache an incompletely-received FEC block
          before giving the application the (incomplete) set of received
          source segments. For example, a value of
          <parameter>maxDelay</parameter> <literal>=</literal>
          <constant>0</constant> will provide the receive application with any
          data from the previous FEC block as soon as a subsequent FEC block
          is begun reception. However, this provide no protection against the
          possibility of out-of-order delivery of packets by the network.
          Therefore, if lower latency operation is desired when using silent
          receivers, a minimum <parameter>maxDelay</parameter> value of
          <constant>1</constant> is recommended. For
          <literal>NORM_OBJECT_FILE</literal> and
          <literal>NORM_OBJECT_DATA</literal>, the only impact of a
          non-negative <parameter>maxDelay</parameter> value is that previous
          transport objects will be immediately aborted when subsequent object
          begin reception. Thus, it is not usually recommended to apply a
          non-negative <parameter>maxDelay</parameter> value when
          <literal>NORM_OBJECT_STREAM</literal> is not being used.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetDefaultUnicastNack">
        <title>NormSetDefaultUnicastNack()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetDefaultUnicastNack"><literal>NormSetDefaultUnicastNack</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                               bool              enable);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function controls the default behavior determining the
          destination of receiver feedback messages generated while
          participating in the session. If the <parameter>enable</parameter>
          parameter is true, "unicast NACKing" is enabled for new remote
          senders while it is disabled for state equal to false. The NACKing
          behavior for current remote senders is not affected. When "unicast
          NACKing" is disabled (default), NACK messages are sent to the
          session address (usually a multicast address) and port, but when
          "unicast NACKing" is enabled, receiver feedback messages are sent to
          the unicast address (and port) based on the source address of sender
          messages received. For unicast NORM sessions, it is recommended that
          "unicast NACKing" be enabled. Note that receiver feedback messages
          subject to potential "unicast NACKing" include NACK-messages as well
          as some ACK messages such as congestion control feedback. Explicitly
          solicited ACK messages, such as those used to satisfy sender
          watermark acknowledgement requests (see <link
          linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>)
          are always unicast to the applicable sender. (<emphasis>TBD -
          provide API option so that all messages are multicast.</emphasis>)
          The default session-wide behavior for unicast NACKing can be
          overridden via the <link
          linkend="NormNodeSetUnicastNack"><literal>NormNodeSetUnicastNack()</literal></link>
          function for individual remote senders.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormNodeSetUnicastNack">
        <title>NormNodeSetUnicastNack()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormNodeSetUnicastNack"><literal>NormNodeSetUnicastNack</literal></link>(<link
              linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> senderNode,
                            bool           enable);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function controls the destination address of receiver
          feedback messages generated in response to a specific remote NORM
          sender corresponding to the <parameter>senderNode</parameter>
          parameter. If <parameter>enable</parameter> is
          <constant>true</constant>, "unicast NACKing" is enabled while it is
          disabled for <parameter>enable</parameter> equal to
          <constant>false</constant>. See the description of <link
          linkend="NormSetDefaultUnicastNack"><literal>NormSetDefaultUnicastNack()</literal></link>
          for details on "unicast NACKing" behavior.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetDefaultSyncPolicy">
        <title>NormSetDefaultSyncPolicy()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetDefaultSyncPolicy"><literal>NormSetDefaultSyncPolicy</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                              <link linkend="NormSyncPolicy"><literal>NormSyncPolicy</literal></link>   syncPolicy);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets the default "synchronization policy" used
          when beginning (or restarting) reception of objects from a remote
          sender (i.e., "syncing" to the sender) for the given
          <parameter>sessionHandle</parameter>. The "synchronization policy"
          is the behavior observed by the receiver with regards to what
          objects it attempts to reliably receive (via transmissions of
          Negative Acknowledgements to the sender(s) or group as needed).
          There are currently two synchronization policy types defined:</para>

          <informaltable frame="all">
            <tgroup cols="2">
              <tbody>
                <row>
                  <entry><para><literal>NORM_SYNC_CURRENT</literal></para></entry>

                  <entry><para>Attempt reception of "current" and new objects
                  only. (default)</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_SYNC_ALL</literal></para></entry>

                  <entry><para>Attempt recovery and reliable reception of all
                  objects held in sender transmit object cache and newer
                  objects.</para></entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>

          <para>The behavior of a receiver using the default
          <constant>NORM_SYNC_CURRENT</constant> policy is to attempt reliable
          reception only for the first received "current" and newer (with
          respect to the ordinal NORM object transport identifiers used by the
          protocol) objects from a given NORM sender. Additionally, reliable
          reception is only attempted when receiving a non-repair
          <literal>NORM_DATA</literal> message (or optionally a NORM positive
          acknowledgement request) from the <emphasis>first</emphasis> forward
          error correction (FEC) encoding block of the given object. This
          somewhat conservative synchronization behavior helps prevent
          late-joining (or otherwise "flaky" with respect to group membership)
          receivers from penalizing other receivers in the group by causing
          the sender to "rewind" and transmit older object content to satisfy
          the late joiner instead of moving forward with transmission of new
          content. For large scale, loosely-organized multicast applications,
          the <constant>NORM_SYNC_CURRENT</constant> policy is typically
          recommended.</para>

          <para>The <constant>NORM_SYNC_ALL</constant> policy allows newly
          joining receivers much more aggressive behavior as they will
          immediately NACK for all objects from the "current" object backwards
          through the entire range of objects set by the <link
          linkend="NormSetRxCacheLimit"><literal>NormSetRxCacheLimit()</literal></link>
          function. This behavior depends upon the sender to issue an
          appropriate <literal>NORM_CMD(SQUELCH)</literal> response (if
          applicable) to align (i.e. "synchronize") the new receiver with its
          current transmit object cache (similar to a "repair window"). This
          synchronization behavior may be useful for unicast uses of NORM or
          other applications where the group membership is more carefully
          managed and it is important that all content (including older
          content) is received. Note that the sender transmit cache bounds
          (see <link
          linkend="NormSetTxCacheBounds"><literal>NormSetTxCacheBounds()</literal></link>)
          and the receiver receive cache limit (see <link
          linkend="NormSetRxCacheLimit"><literal>NormSetRxCacheLimit()</literal></link>)
          settings will limit how far back onto the sender transmission
          history that transmitted objects can be reliably recovered from the
          "current" transmission point when the receiver begins
          reception.</para>

          <para>When this function is not invoked, the
          <constant>NORM_SYNC_CURRENT</constant> behavior is observed as the
          default receiver synchronization policy. This call SHOULD be made
          before <link
          linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
          is called.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetDefaultNackingMode">
        <title>NormSetDefaultNackingMode()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetDefaultNackingMode"><literal>NormSetDefaultNackingMode</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                               <link linkend="NormNackingMode"><literal>NormNackingMode</literal></link>   nackingMode);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets the default "nacking mode" used when
          receiving objects for the given
          <parameter>sessionHandle</parameter>. This allows the receiver
          application some control of its degree of participation in the
          repair process. By limiting receivers to only request repair of
          objects in which they are really interested in receiving, some
          overall savings in unnecessary network loading might be realized for
          some applications and users. Available nacking modes include:</para>

          <informaltable frame="all">
            <tgroup cols="2">
              <tbody>
                <row>
                  <entry><para><literal>NORM_NACK_NONE</literal></para></entry>

                  <entry><para>Do not transmit any repair requests for the
                  newly received object.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_NACK_INFO_ONLY</literal></para></entry>

                  <entry><para>Transmit repair requests for
                  <literal>NORM_INFO</literal> content only as
                  needed.</para></entry>
                </row>

                <row>
                  <entry><para><literal>NORM_NACK_NORMAL</literal></para></entry>

                  <entry><para>Transmit repair requests for entire object as
                  needed.</para></entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>

          <para>This function specifies the default behavior with respect to
          any new sender or object. This default behavior may be overridden
          for specific sender nodes or specific object using <link
          linkend="NormNodeSetNackingMode"><literal>NormNodeSetNackingMode()</literal></link>
          or <link
          linkend="NormObjectSetNackingMode"><literal>NormObjectSetNackingMode()</literal></link>,
          respectively. The receiver application's use of
          <literal>NORM_NACK_NONE</literal> essentially disables a guarantee
          of reliable reception, although the receiver may still take
          advantage of sender repair transmissions in response to other
          receivers' requests. When the sender provides,
          <literal>NORM_INFO</literal> content for transmitted objects, the
          <literal>NORM_NACK_INFO_ONLY</literal> mode may allows the receiver
          to reliably receive object context information from which it may
          choose to "upgrade" its <parameter>nackingMode</parameter> for the
          specific object via the <link
          linkend="NormObjectSetNackingMode"><literal>NormObjectSetNackingMode()</literal></link>
          call. Similarly, the receiver may changes its default
          <parameter>nackingMode</parameter> with respect to specific senders
          via the <link
          linkend="NormNodeSetNackingMode"><literal>NormNodeSetNackingMode()</literal></link>
          call. The default "default <parameter>nackingMode</parameter>" when
          this call is not made is <literal>NORM_NACK_NORMAL</literal>.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormNodeSetNackingMode">
        <title>NormNodeSetNackingMode()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormNodeSetNackingMode"><literal>NormNodeSetNackingMode</literal></link>(<link
              linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>  nodeHandle,
                            <link linkend="NormNackingMode"><literal>NormNackingMode</literal></link> nackingMode);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets the default "nacking mode" used for
          receiving new objects from a specific sender as identified by the
          <parameter>nodeHandle</parameter> parameter. This overrides the
          default <parameter>nackingMode</parameter> set for the receive
          session. See <link
          linkend="NormSetDefaultNackingMode"><literal>NormSetDefaultNackingMode()</literal></link>
          for a description of possible <parameter>nackingMode</parameter>
          parameter values and other related information.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormObjectSetNackingMode">
        <title>NormObjectSetNackingMode()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormObjectSetNackingMode"><literal>NormObjectSetNackingMode</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle,
                              <link linkend="NormNackingMode"><literal>NormNackingMode</literal></link>  nackingMode);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function sets the "nacking mode" used for receiving a
          specific transport object as identified by the
          <parameter>objectHandle</parameter> parameter. This overrides the
          default nacking mode set for the applicable sender node. See <link
          linkend="NormSetDefaultNackingMode"><literal>NormSetDefaultNackingMode()</literal></link>
          for a description of possible <parameter>nackingMode</parameter>
          parameter values and other related information.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetDefaultRepairBoundary">
        <title>NormSetDefaultRepairBoundary()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetDefaultRepairBoundary"><literal>NormSetDefaultRepairBoundary</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link>  sessionHandle,
                                  <link linkend="NormRepairBoundary"><literal>NormRepairBoundary</literal></link> repairBoundary);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function allows the receiver application to customize,
          for a given <parameter>sessionHandle</parameter>, at what points the
          receiver initiates the NORM NACK repair process during protocol
          operation. Normally, the NORM receiver initiates NACKing for repairs
          at the FEC code block and transport object boundaries. For smaller
          block sizes, the NACK repair process is often/quickly initiated and
          the repair of an object will occur, as needed, during the
          transmission of the object. This default operation corresponds to
          <parameter>repairBoundary</parameter> equal to
          <literal>NORM_BOUNDARY_BLOCK</literal>. Using this function, the
          application may alternatively, setting
          <parameter>repairBoundary</parameter> equal to
          <literal>NORM_BOUNDARY_OBJECT</literal>, cause the protocol to defer
          NACK process initiation until the current transport object has been
          completely transmitted.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormNodeSetRepairBoundary">
        <title>NormNodeSetRepairBoundary()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormNodeSetRepairBoundary"><literal>NormNodeSetRepairBoundary</literal></link>(<link
              linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>     nodeHandle,
                               <link linkend="NormRepairBoundary"><literal>NormRepairBoundary</literal></link> repairBoundary);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function allows the receiver application to customize,
          for the specific remote sender referenced by the
          <parameter>nodeHandle</parameter> parameter, at what points the
          receiver initiates the NORM NACK repair process during protocol
          operation. See the description of <link
          linkend="NormSetDefaultRepairBoundary"><literal>NormSetDefaultRepairBoundary()</literal></link>
          for further details on the impact of setting the NORM receiver
          repair boundary and possible values for the
          <parameter>repairBoundary</parameter> parameter.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormSetDefaultRxRobustFactor">
        <title>NormSetDefaultRxRobustFactor()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetDefaultRxRobustFactor"><literal>NormSetDefaultRxRobustFactor</literal></link>(<link
              linkend="NormSessionHandle"><literal>NormSessionHandle</literal></link> sessionHandle,
                                  int               rxRobustFactor);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This routine controls how persistently NORM receivers will
          maintain state for sender(s) and continue to request repairs from
          the sender(s) even when packet reception has ceased. The
          <parameter>rxRobustFactor</parameter> value determines how many
          times a NORM receiver will self-initiate NACKing (repair requests)
          upon cessation of packet reception from a sender. The default value
          is <constant>20</constant>. Setting
          <parameter>rxRobustFactor</parameter> to <constant>-1</constant>
          will make the NORM receiver infinitely persistent (i.e., it will
          continue to NACK indefinitely as long as it is missing data
          content). It is important to note that the <link
          linkend="NormSetTxRobustFactor"><literal>NormSetTxRobustFactor()</literal></link>
          also affects receiver operation in setting the time interval that is
          used to gauge that sender packet transmission has ceased (i.e., the
          sender inactivity timeout). This "timeout" interval is a equal of
          (<literal><constant>2</constant> * GRTT *
          <parameter>txRobustFactor</parameter></literal>). Thus the overall
          timeout before a NORM receiver quits NACKing is
          (<literal><parameter>rxRobustFactor</parameter> *
          <constant>2</constant> * GRTT *
          <parameter>txRobustFactor</parameter></literal>).</para>

          <para>The <link
          linkend="NormNodeSetRxRobustFactor"><literal>NormNodeSetRxRobustFactor()</literal></link>
          function can be used to control this behavior on a per-sender basis.
          When a new remote sender is detected, the default
          <parameter>rxRobustFactor</parameter> set here is used. Again, the
          default value is <constant>20</constant>.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormNodeSetRxRobustFactor">
        <title>NormNodeSetRxRobustFactor()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormNodeSetRxRobustFactor"><literal>NormNodeSetRxRobustFactor</literal></link>(<link
              linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle,
                               int            rxRobustFactor);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This routine sets the <parameter>rxRobustFactor</parameter> as
          described in <link
          linkend="NormSetDefaultRxRobustFactor"><literal>NormSetDefaultRxRobustFactor()</literal></link>
          for an individual remote sender identified by the
          <parameter>nodeHandle</parameter> parameter. See the description of
          <link
          linkend="NormSetDefaultRxRobustFactor"><literal>NormSetDefaultRxRobustFactor()</literal></link>
          for details</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return values.</para>
        </sect4>
      </sect3>

      <sect3 id="NormStreamRead">
        <title>NormStreamRead()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormStreamRead"><literal>NormStreamRead</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle,
                    char*            buffer
                    unsigned int*    numBytes);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function can be used by the receiver application to read
          any available data from an incoming NORM stream. NORM receiver
          applications "learn" of available NORM streams via
          <literal>NORM_RX_OBJECT_NEW</literal> notification events. The
          <parameter>streamHandle</parameter> parameter here must correspond
          to a valid <link
          linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
          value provided during such a prior
          <literal>NORM_RX_OBJECT_NEW</literal> notification. The
          <parameter>buffer</parameter> parameter must be a pointer to an
          array where the received data can be stored of a length as
          referenced by the <parameter>numBytes</parameter> pointer. On
          successful completion, the <parameter>numBytes</parameter> storage
          will be modified to indicate the actual number of bytes copied into
          the provided <parameter>buffer</parameter>. If the
          <parameter>numBytes</parameter> storage is modified to a zero value,
          this indicates that no stream data was currently available for
          reading.</para>

          <para>Note that <link
          linkend="NormStreamRead"><literal>NormStreamRead()</literal></link>
          is never a blocking call and only returns failure
          (<constant>false</constant>) when a break in the integrity of the
          received stream occurs. The <literal>NORM_RX_OBJECT_UPDATE</literal>
          provides an indication to when there is stream data available for
          reading. When such notification occurs, the application should
          repeatedly read from the stream until the
          <parameter>numBytes</parameter> storage is set to zero, even if a
          <constant>false</constant> value is returned. Additional
          <literal>NORM_RX_OBJECT_UPDATE</literal> notifications might not be
          posted until the application has read all available data.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function normally returns a value of
          <constant>true</constant>. However, if a break in the integrity of
          the reliable received stream occurs (or the stream has been ended by
          the sender), a value of <constant>false</constant> is returned to
          indicate the break. Unless the stream has been ended (and the
          receiver application will receive
          <literal>NORM_RX_OBJECT_COMPLETED</literal> notification for the
          stream in that case), the application may continue to read from the
          stream as the NORM protocol will automatically "resync" to streams,
          even if network conditions are sufficiently poor that breaks in
          reliability occur. If such a "break" and "resync" occurs, the
          application may be able to leverage other NORM API calls such as
          <link
          linkend="NormStreamSeekMsgStart"><literal>NormStreamSeekMsgStart()</literal></link>
          or <link
          linkend="NormStreamGetReadOffset"><literal>NormStreamGetReadOffset()</literal></link>
          if needed to recover its alignment with received stream content.
          This depends upon the nature of the application and its stream
          content.</para>
        </sect4>
      </sect3>

      <sect3 id="NormStreamSeekMsgStart">
        <title>NormStreamSeekMsgStart()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormStreamSeekMsgStart"><literal>NormStreamSeekMsgStart</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function advances the read offset of the receive stream
          referenced by the <parameter>streamHandle</parameter> parameter to
          align with the next available message boundary. Message boundaries
          are defined by the sender application using the <link
          linkend="NormStreamMarkEom"><literal>NormStreamMarkEom()</literal></link>
          call. Note that any received data prior to the next message boundary
          is discarded by the NORM protocol engine and is not available to the
          application (i.e., there is currently no "rewind" function for a
          NORM stream). Also note this call cannot be used to skip messages.
          Once a valid message boundary is found, the application must read
          from the stream using <link
          linkend="NormStreamRead"><literal>NormStreamRead()</literal></link>
          to further advance the read offset. The current offset (in bytes)
          for the stream can be retrieved via <link
          linkend="NormStreamGetReadOffset"><literal>NormStreamGetReadOffset()</literal></link>.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns a value of <constant>true</constant>
          when start-of-message is found. The next call to <link
          linkend="NormStreamRead"><literal>NormStreamRead()</literal></link>
          will retrieve data aligned with the message start. If no new message
          boundary is found in the buffered receive data for the stream, the
          function returns a value of <constant>false</constant>. In this
          case, the application should defer repeating a call to this function
          until a subsequent <literal>NORM_RX_OBJECT_UPDATE</literal>
          notification is posted.</para>
        </sect4>
      </sect3>

      <sect3 id="NormStreamGetReadOffset">
        <title>NormStreamGetReadOffset()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

unsigned long <link linkend="NormStreamGetReadOffset"><literal>NormStreamGetReadOffset</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> streamHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function retrieves the current read offset value for the
          receive stream indicated by the <parameter>streamHandle</parameter>
          parameter. Note that for very long-lived streams, this value may
          wrap. Thus, in general, applications should not be highly dependent
          upon the stream offset, but this feature may be valuable for certain
          applications which associate some application context with stream
          position.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns the current read offset in bytes. The
          return value is undefined for sender streams. There is no error
          result.</para>
        </sect4>
      </sect3>
    </sect2>

    <sect2>
      <title>NORM Object Functions</title>

      <para>The functions described in this section may be used for sender or
      receiver purposes to manage transmission and reception of NORM transport
      objects. In most cases, the receiver will be the typical user of these
      functions to retrieve additional information on newly-received objects.
      All of these functions require a valid <link
      linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
      argument which specifies the applicable object. Note that <link
      linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
      values obtained from a <link
      linkend="NormEvent"><literal>NormEvent</literal></link> notification may
      be considered valid only until a subsequent call to <link
      linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>,
      unless explicitly retained by the application (see <link
      linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>).
      <link
      linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
      values obtained as a result of <link
      linkend="NormFileEnqueue"><literal>NormFileEnqueue()</literal></link>,
      <link
      linkend="NormDataEnqueue"><literal>NormDataEnqueue()</literal></link>,
      or <link
      linkend="NormStreamOpen"><literal>NormStreamOpen()</literal></link>
      calls can be considered valid only until a corresponding
      <literal>NORM_TX_OBJECT_PURGED</literal> notification is posted or the
      object is dequeued using <link
      linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>,
      unless, again, otherwise explicitly retained (see <link
      linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>).</para>

      <sect3 id="NormObjectGetType">
        <title>NormObjectGetType()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

<link linkend="NormObjectType"><literal>NormObjectType</literal></link> <link
              linkend="NormObjectGetType"><literal>NormObjectGetType</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function can be used to determine the object type
          (<literal>(NORM_OBJECT_DAT</literal>,
          <literal>NORM_OBJECT_FILE</literal>, or
          <literal>NORM_OBJECT_STREAM</literal>) for the NORM transport object
          identified by the <parameter>objectHandle</parameter> parameter. The
          <parameter>objectHandle</parameter> must refer to a current, valid
          transport object.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns the NORM object type. Valid NORM object
          types include <literal>NORM_OBJECT_DATA</literal>,
          <literal>NORM_OBJECT_FILE</literal>, or
          <literal>NORM_OBJECT_STREAM</literal>. A type value of
          <literal>NORM_OBJECT_NONE</literal> will be returned for an
          <parameter>objectHandle</parameter> value of
          <literal>NORM_OBJECT_INVALID</literal>.</para>
        </sect4>
      </sect3>

      <sect3 id="NormObjectHasInfo">
        <title>NormObjectHasInfo()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormObjectHasInfo"><literal>NormObjectHasInfo</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function can be used to determine if the sender has
          associated any <literal>NORM_INFO</literal> content with the
          transport object specified by the
          <parameter>objectHandle</parameter> parameter. This can even be used
          before the <literal>NORM_INFO</literal> content is delivered to the
          receiver and a <literal>NORM_RX_OBJECT_INFO</literal> notification
          is posted.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A value of <constant>true</constant> is returned if
          <literal>NORM_INFO</literal> is (or will be) available for the
          specified transport object. A value of <constant>false</constant> is
          returned otherwise.</para>
        </sect4>
      </sect3>

      <sect3 id="NormObjectGetInfoLength">
        <title>NormObjectGetInfoLength()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

unsigned short <link linkend="NormObjectGetInfoLength"><literal>NormObjectGetInfoLength</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function can be used to determine the length of currently
          available <literal>NORM_INFO</literal> content (if any) associated
          with the transport object referenced by the
          <parameter>objectHandle</parameter> parameter.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The length of the <literal>NORM_INFO</literal> content, in
          bytes, of currently available for the specified transport object is
          returned. A value of <constant>0</constant> is returned if no
          <literal>NORM_INFO</literal> content is currently available or
          associated with the object.</para>
        </sect4>
      </sect3>

      <sect3 id="NormObjectGetInfo">
        <title>NormObjectGetInfo()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

unsigned short <link linkend="NormObjectGetInfo"><literal>NormObjectGetInfo</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>         objectHandle,
                                 char*                    buffer,
                                 unsigned short           bufferLen);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function copies any <literal>NORM_INFO</literal> content
          associated (by the sender application) with the transport object
          specified by <parameter>objectHandle</parameter> into the provided
          memory space referenced by the buffer parameter. The
          <parameter>bufferLen</parameter> parameter indicates the length of
          the buffer space in bytes. If the provided
          <parameter>bufferLen</parameter> is less than the actual
          <literal>NORM_INFO</literal> length, a partial copy will occur. The
          actual length of <literal>NORM_INFO</literal> content available for
          the specified object is returned. However, note that until a
          <literal>NORM_RX_OBJECT_INFO</literal> notification is posted to the
          receive application, no <literal>NORM_INFO</literal> content is
          available and a zero result will be returned, even if
          <literal>NORM_INFO</literal> content may be subsequently available.
          The <link
          linkend="NormObjectHasInfo"><literal>NormObjectHasInfo()</literal></link>
          call can be used to determine if any <literal>NORM_INFO</literal>
          content will ever be available for a specified transport object
          (i.e., determine if the sender has associated any
          <literal>NORM_INFO</literal> with the object in question).</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The actual length of currently available
          <literal>NORM_INFO</literal> content for the specified transport
          object is returned. This function can be used to determine the
          length of <literal>NORM_INFO</literal> content for the object even
          if a NULL buffer value and zero <parameter>bufferLen</parameter> is
          provided. A zero value is returned if <literal>NORM_INFO</literal>
          content has not yet been received (or is non-existent) for the
          specified object.</para>
        </sect4>
      </sect3>

      <sect3 id="NormObjectGetSize">
        <title>NormObjectGetSize()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

<link linkend="NormSize"><literal>NormSize</literal></link> <link
              linkend="NormObjectGetSize"><literal>NormObjectGetSize</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function can be used to determine the size (in bytes) of
          the transport object specified by the
          <parameter>objectHandle</parameter> parameter. NORM can support
          large object sizes for the <literal>NORM_OBJECT_FILE</literal> type,
          so typically the NORM library is built with any necessary, related
          macros defined such that operating system large file support is
          enabled (e.g., "<literal>#define
          <constant>_FILE_OFFSET_BITS</constant>
          <constant>64</constant></literal>" or equivalent). The <link
          linkend="NormSize"><literal>NormSize</literal></link> type is
          defined accordingly, so the application should be built with the
          same large file support configuration.</para>

          <para>For objects of type <literal>NORM_OBJECT_STREAM</literal>, the
          size returned here corresponds to the stream buffer size set by the
          sender application when opening the referenced stream object.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A size of the data content of the specified object, in bytes,
          is returned. Note that it may be possible that some objects have
          zero data content, but do have <literal>NORM_INFO</literal> content
          available.</para>
        </sect4>
      </sect3>

      <sect3 id="NormObjectGetBytesPending">
        <title>NormObjectGetBytesPending()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

<link linkend="NormSize"><literal>NormSize</literal></link> <link
              linkend="NormObjectGetBytesPending"><literal>NormObjectGetBytesPending</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function can be used to determine the progress of
          reception of the NORM transport object identified by the
          <parameter>objectHandle</parameter> parameter. This function
          indicates the number of bytes that are pending reception (I.e., when
          the object is completely received, "bytes pending" will equal ZERO).
          This function is not necessarily applicable to objects of type
          <literal>NORM_OBJECT_STREAM</literal> which do not have a finite
          size. Note it is possible that this function might also be useful to
          query the "transmit pending" status of sender objects, but it does
          not account for pending FEC repair transmissions and thus may not
          produce useful results for this purpose.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A number of object source data bytes pending reception (or
          transmission) is returned.</para>
        </sect4>
      </sect3>

      <sect3 id="NormObjectCancel">
        <title>NormObjectCancel()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormObjectCancel"><literal>NormObjectCancel</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function immediately cancels the transmission of a local
          sender transport object or the reception of a specified object from
          a remote sender as specified by the
          <parameter>objectHandle</parameter> parameter. The
          <parameter>objectHandle</parameter> must refer to a currently valid
          NORM transport object. Any resources used by the transport object in
          question are immediately freed unless the object has been otherwise
          retained by the application via the <link
          linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
          call. Unless the application has retained the object in such
          fashion, the object in question should be considered invalid and the
          application must not again reference the
          <parameter>objectHandle</parameter> after this call is made.</para>

          <para>If the canceled object is a sender object not completely
          received by participating receivers, the receivers will be informed
          of the object's cancellation via the NORM protocol
          <literal>NORM_CMD</literal>(SQUELCH) message in response to any
          NACKs requesting repair or retransmission of the applicable object.
          In the case of receive objects, the NORM receiver will not make
          further requests for repair of the indicated object, but
          furthermore, will acknowledge the object as completed with respect
          to any associated positive acknowledgement requests (see <link
          linkend="NormSetWatermark"><literal>NormSetWatermark()</literal></link>).</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return value.</para>
        </sect4>
      </sect3>

      <sect3 id="NormObjectRetain">
        <title>NormObjectRetain()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormObjectRetain"><literal>NormObjectRetain</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function "retains" the
          <parameter>objectHandle</parameter> and any state associated with it
          for further use by the application even when the NORM protocol
          engine may no longer require access to the associated transport
          object. Normally, the application is guaranteed that a given <link
          linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
          is valid only while it is being actively transported by NORM (i.e.,
          for sender objects, from the time an object is created by the
          application until it is canceled by the application or purged (see
          the <literal>NORM_TX_OBJECT_PURGED</literal> notification) by the
          protocol engine, or, for receiver objects, from the time of the
          object's <literal>NORM_RX_OBJECT_NEW</literal> notification until
          its reception is canceled by the application or a
          <literal>NORM_RX_OBJECT_COMPLETED</literal> or
          <literal>NORM_RX_OBJECT_ABORTED</literal> notification is posted).
          Note that an application may refer to a given object after any
          related notification until the application makes a subsequent call
          to <link
          linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>.</para>

          <para>When the application makes a call to <link
          linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
          for a given <parameter>objectHandle</parameter>, the application may
          use that <parameter>objectHandle</parameter> value in any NORM API
          calls until the application makes a call to <link
          linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>
          for the given object. Note that the application MUST make a
          corresponding call to <link
          linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>
          for each call it has made to <link
          linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
          in order to free any system resources (i.e., memory) used by that
          object. Also note that retaining a receive object also automatically
          retains any state associated with the <link
          linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
          corresponding to the remote sender of that receive object so that
          the application may use NORM node API calls for the value returned
          by <link
          linkend="NormObjectGetSender"><literal>NormObjectGetSender()</literal></link>
          as needed.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return value.</para>
        </sect4>
      </sect3>

      <sect3 id="NormObjectRelease">
        <title>NormObjectRelease()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormObjectRelease"><literal>NormObjectRelease</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function complements the <link
          linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
          call by immediately freeing any resources associated with the given
          <parameter>objectHandle</parameter>, assuming the underlying NORM
          protocol engine no longer requires access to the corresponding
          transport object. Note the NORM protocol engine retains/releases
          state for associated objects for its own needs and thus it is very
          unsafe for an application to call <link
          linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>
          for an <parameter>objectHandle</parameter> for which it has not
          previously explicitly retained via <link
          linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return value.</para>
        </sect4>
      </sect3>

      <sect3 id="NormFileGetName">
        <title>NormFileGetName()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormFileGetName"><literal>NormFileGetName</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle,
                     char*            nameBuffer,
                     unsigned int     bufferLen);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function copies the name, as a
          <constant>NULL</constant>-terminated string, of the file object
          specified by the <parameter>objectHandle</parameter> parameter into
          the <parameter>nameBuffer</parameter> of length
          <parameter>bufferLen</parameter> bytes provided by the application.
          The <parameter>objectHandle</parameter> parameter must refer to a
          valid <link
          linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link>
          for an object of type <literal>NORM_OBJECT_FILE</literal>. If the
          actual name is longer than the provided
          <parameter>bufferLen</parameter>, a partial copy will occur. Note
          that the file name consists of the entire path name of the specified
          file object and the application should give consideration to
          operating system file path lengths when providing the
          <parameter>nameBuffer</parameter>.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns <constant>true</constant> upon success
          and <constant>false</constant> upon failure. Possible failure
          conditions include the <parameter>objectHandle</parameter> does not
          refer to an object of type
          <literal>NORM_OBJECT_FILE</literal>.</para>
        </sect4>
      </sect3>

      <sect3 id="NormFileRename">
        <title>NormFileRename()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormFileRename"><literal>NormFileRename</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle,
                    const char*      fileName);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function renames the file used to store content for the
          <literal>NORM_OBJECT_FILE</literal> transport object specified by
          the <parameter>objectHandle</parameter> parameter. This allows
          receiver applications to rename (or move) received files as needed.
          NORM uses temporary file names for received files until the
          application explicitly renames the file. For example, sender
          applications may choose to use the <literal>NORM_INFO</literal>
          content associated with a file object to provide name and/or typing
          information to receivers. The <parameter>fileName</parameter>
          parameter must be a <constant>NULL</constant>-terminated string
          which should specify the full desired path name to be used. NORM
          will attempt to create sub-directories as needed to satisfy the
          request. Note that existing files of the same name may be
          overwritten.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns true upon success and false upon
          failure. Possible failure conditions include the case where the
          <parameter>objectHandle</parameter> does not refer to an object of
          type <literal>NORM_OBJECT_FILE</literal> and where NORM was unable
          to successfully create any needed directories and/or the file
          itself.</para>
        </sect4>
      </sect3>

      <sect3 id="NormDataAccessData">
        <title>NormDataAccessData()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

const char* <link linkend="NormDataAccessData"><literal>NormDataAccessData</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function allows the application to access the data
          storage area associated with a transport object of type
          <literal>NORM_OBJECT_DATA</literal>. For example, the application
          may use this function to copy the received data content for its own
          use. Alternatively, the application may establish "ownership" for
          the allocated memory space using the <link
          linkend="NormDataDetachData"><literal>NormDataDetachData()</literal></link>
          function if it is desired to avoid the copy.</para>

          <para>If the object specified by the
          <parameter>objectHandle</parameter> parameter has no data content
          (or is not of type <literal>NORM_OBJECT_DATA</literal>), a NULL
          value may be returned. The application MUST NOT attempt to modify
          the memory space used by <literal>NORM_OBJECT_DATA</literal> objects
          during the time an associated <parameter>objectHandle</parameter> is
          valid. The length of data storage area can be determined with a call
          to <link
          linkend="NormObjectGetSize"><literal>NormObjectGetSize()</literal></link>
          for the same <parameter>objectHandle</parameter> value.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns a pointer to the data storage area for
          the specified transport object. A NULL value may be returned if the
          object has no associated data content or is not of type
          <literal>NORM_OBJECT_DATA</literal>.</para>
        </sect4>
      </sect3>

      <sect3 id="NormDataDetachData">
        <title>NormDataDetachData()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

char* <link linkend="NormDataDetachData"><literal>NormDataDetachData</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function allows the application to disassociate data
          storage allocated by the NORM protocol engine for a receive object
          from the <literal>NORM_OBJECT_DATA</literal> transport object
          specified by the <parameter>objectHandle</parameter> parameter. It
          is important that this function is called after the NORM protocol
          engine has indicated it is finished with the data object (i.e.,
          after a <literal>NORM_TX_OBJECT_PURGED</literal>,
          <literal>NORM_RX_OBJECT_COMPLETED</literal>, or
          <literal>NORM_RX_OBJECT_ABORTED</literal> notification event). But
          the application must call <link
          linkend="NormDataDetachData"><literal>NormDataDetachData()</literal></link>
          before a call is made to <link
          linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>
          or <link
          linkend="NormObjectRelease"><literal>NormObjectRelease()</literal></link>
          for the object if it plans to access the data content afterwards.
          Otherwise, the NORM protocol engine will free the applicable memory
          space when the associated <literal>NORM_OBJECT_DATA</literal>
          transport object is deleted and the application will be unable to
          access the received data unless it has previously copied the
          content.</para>

          <para>Once the application has used this call to "detach" the data
          content, it is the application's responsibility to subsequently free
          the data storage space as needed.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns a pointer to the data storage area for
          the specified transport object. A <constant>NULL</constant> value
          may be returned if the object has no associated data content or is
          not of type <literal>NORM_OBJECT_DATA</literal>.</para>
        </sect4>
      </sect3>

      <sect3 id="NormObjectGetSender">
        <title>NormObjectGetSender()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

<link linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> <link
              linkend="NormObjectGetSender"><literal>NormObjectGetSender</literal></link>(<link
              linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> objectHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function retrieves the <link
          linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
          corresponding to the remote sender of the transport object
          associated with the given <parameter>objectHandle</parameter>
          parameter. Note that the returned <link
          linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
          value is only valid for the same period that the
          <parameter>objectHandle</parameter> is valid. The returned <link
          linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
          may optionally be retained for further use by the application using
          the <link
          linkend="NormNodeRetain"><literal>NormNodeRetain()</literal></link>
          function call. The returned value can be used in the NORM Node
          Functions described later in this document.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns the <link
          linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
          corresponding to the remote sender of the transport object
          associated with the given <parameter>objectHandle</parameter>
          parameter. A value of <literal>NORM_NODE_INVALID</literal> is
          returned if the specified <parameter>objectHandle</parameter>
          references a locally originated, sender object.</para>
        </sect4>
      </sect3>
    </sect2>

    <sect2>
      <title>NORM Node Functions</title>

      <para>The functions described in this section may be used for NORM
      sender or receiver (most typically receiver) purposes to retrieve
      additional information about a remote <emphasis>NormNode</emphasis>,
      given a valid <link
      linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>. Note
      that, unless specifically retained (see <link
      linkend="NormNodeRetain"><literal>NormNodeRetain()</literal></link>), a
      <link linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
      provided in a <link
      linkend="NormEvent"><literal>NormEvent</literal></link> notification
      should be considered valid only until a subsequent call to <link
      linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>
      is made. <link
      linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> values
      retrieved using <link
      linkend="NormObjectGetSender"><literal>NormObjectGetSender()</literal></link>
      can be considered valid for the same period of time as the corresponding
      <link
      linkend="NormObjectHandle"><literal>NormObjectHandle</literal></link> is
      valid.</para>

      <sect3 id="NormNodeGetId">
        <title>NormNodeGetId()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

<link linkend="NormNodeId"><literal>NormNodeId</literal></link> <link
              linkend="NormNodeGetId"><literal>NormNodeGetId</literal></link>(<link
              linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function retrieves the <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link> identifier
          for the remote participant referenced by the given
          <parameter>nodeHandle</parameter> value. The <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link> is a
          32-bit value used within the NORM protocol to uniquely identify
          participants within a NORM session. The participants identifiers are
          assigned by the application or derived (by the NORM API code) from
          the host computers default IP address.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns the <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link> value
          associated with the specified <parameter>nodeHandle</parameter>. In
          the case <parameter>nodeHandle</parameter> is equal to
          <literal>NORM_NODE_INVALID</literal>, the return value will be
          <literal>NORM_NODE_NONE</literal>.</para>
        </sect4>
      </sect3>

      <sect3 id="NormNodeGetAddress">
        <title>NormNodeGetAddress()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormNodeGetAddress"><literal>NormNodeGetAddress</literal></link>(<link
              linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>          nodeHandle,
                        char*                   addrBuffer,
                        unsigned int*           bufferLen,
                        unsigned short*         port = NULL);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function retrieves the current network source address
          detected for packets received from remote NORM sender referenced by
          the <parameter>nodeHandle</parameter> parameter. The
          <parameter>addrBuffer</parameter> must be a pointer to storage of
          <parameter>bufferLen</parameter> bytes in length in which the
          referenced sender node's address will be returned. Optionally, the
          remote sender source port number (see <link
          linkend="NormSetTxPort"><literal>NormSetTxPort()</literal></link>)
          is also returned if the optional port pointer to storage parameter
          is provided in the call. Note that in the case of Network Address
          Translation (NAT) or other firewall activities, the source address
          detected by the NORM receiver may not be the original address of the
          original NORM sender.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>A value of <constant>true</constant> is returned upon success
          and <constant>false</constant> upon failure. An invalid
          <parameter>nodeHandle</parameter> parameter value would lead to such
          failure.</para>
        </sect4>
      </sect3>

      <sect3 id="NormNodeGetGrtt">
        <title>NormNodeGetGrtt()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

double <link linkend="NormNodeGetId"><literal>NormNodeGetGrtt</literal></link>(<link
              linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function retrieves the advertised estimate of group
          round-trip timing (GRTT) for the remote sender referenced by the
          given <parameter>nodeHandle</parameter> value. Newly-starting
          senders that have been participating as a receiver within a group
          may wish to use this function to provide a more accurate startup
          estimate of GRTT (see <link
          linkend="NormSetGrttEstimate"><literal>NormSetGrttEstimate()</literal></link>)
          prior to a call to <link
          linkend="NormStartSender"><literal>NormStartSender()</literal></link>.
          Applications may use this information for other purpose as well.
          Note that the <literal>NORM_GRTT_UPDATED</literal> event is posted
          (see <link
          linkend="NormGetNextEvent"><literal>NormGetNextEvent()</literal></link>)
          by the NORM protocol engine to indicate when changes in the local
          sender or remote senders' GRTT estimate occurs.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns the remote sender's advertised GRTT
          estimate in units of seconds. A value of <constant>-1.0</constant>
          is returned upon failure. An invalid
          <parameter>nodeHandle</parameter> parameter value will lead to such
          failure.</para>
        </sect4>
      </sect3>

      <sect3 id="NormNodeGetCommand">
        <title>NormNodeGetCommand()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormNodeGetCommand"><literal>NormNodeGetCommand</literal></link>(<link
              linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle,
                        char*          buffer,
                        unsigned int*  buflen);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function retrieves the content of an application-defined
          command that was received from a remote sender associated with the
          given <parameter>nodeHandle</parameter>. This call should be made in
          response to the <constant>NORM_RX_CMD_NEW</constant> notification.
          This notification is issued for each command received. However the
          application may use this call to poll for received commands if
          desired. Additionally, the received command length can be "queried"
          by setting the value referenced by the <parameter>buflen</parameter>
          parameter to <constant>ZERO</constant>. Upon return, this value
          referenced by the <parameter>buflen</parameter> parameter is
          adjusted to reflect the command length. Then a subsequent call to
          <link
          linkend="NormNodeGetCommand"><literal>NormNodeGetCommand()</literal></link>
          can be made with an appropriately-sized buffer to retrieve the
          received command content. The command size will be less than or
          equal to the NORM segment size configured for the given remote
          sender.</para>

          <para>Note that if a rapid succession of commands are sent it is
          possible that the commands may be delivered to the receivers
          out-of-order. Also, when repetition is requested (i.e., if
          <parameter>robust</parameter> is set to <constant>true</constant>)
          the receiver may receive duplicate copies of the same command. It is
          up to the application to provide any needed mechanism for detecting
          and/or filtering duplicate command reception.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function returns <constant>true</constant> upon
          successful retrieval of command content. A return value of
          <constant>false</constant> indicates that either no command was
          available or the provided buffer size (<parameter>buflen</parameter>
          parameter) was inadequate. The value referenced by the
          <parameter>buflen</parameter> parameter is adjusted to indicate the
          actual command length (in bytes) upon return.</para>
        </sect4>
      </sect3>

      <sect3 id="NormNodeFreeBuffers">
        <title>NormNodeFreeBuffers()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormNodeFreeBuffers"><literal>NormNodeFreeBuffers</literal></link>(<link
              linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function releases memory resources that were allocated
          for a remote sender. For example, the receiver application may wish
          to free memory resources when receiving a
          <constant>NORM_REMOTE_SENDER_INACTIVE</constant> notification for a
          given remote sender when multiple senders may be providing content.
          The NORM protocol engine allocates memory for reliable transport
          buffering on a per sender basis according to the limit set in the
          <link
          linkend="NormStartReceiver"><literal>NormStartReceiver()</literal></link>
          call. These buffering resources comprise the majority of the state
          allocated for a given remote sender. For NORM applications with
          possibly multiple senders active at different times, this function
          can be used to manage to amount of memory allocated for reliable
          reception. If a sender becomes "active" again after a call to <link
          linkend="NormNodeFreeBuffers"><literal>NormNodeFreeBuffers()</literal></link>,
          new memory resources will be allocated. Note that state for any
          pending (uncompleted) objects will be dropped when this function is
          called and the receiver may request retransmission and repair of
          content if the sender once again becomes "active". The application
          SHOULD call <link
          linkend="NormObjectCancel"><literal>NormObjectCancel()</literal></link>
          for any pending objects <emphasis>before</emphasis> calling <link
          linkend="NormNodeFreeBuffers"><literal>NormNodeFreeBuffers()</literal></link>
          if it wishes to never receive those pending objects. Alternatively,
          a call to <link
          linkend="NormNodeDelete"><literal>NormNodeDelete()</literal></link>
          will completely eliminate all state for a given remote sender and,
          if that sender becomes "active" again, it will be treated as a
          completely new sender.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return value.</para>
        </sect4>
      </sect3>

      <sect3 id="NormNodeDelete">
        <title>NormNodeDelete()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormNodeDelete"><literal>NormNodeDelete</literal></link>(<link
              linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function can be used by a NORM receiver application to
          completely remove the state associated with a remote sender for the
          given <parameter>nodeHandle</parameter>. For example, when a
          <constant>NORM_REMOTE_SENDER_INACTIVE</constant> notification occurs
          for a given sender, the application may wish to completely free
          <emphasis>all</emphasis> associated resources. Note this is distinct
          from the <link
          linkend="NormNodeFreeBuffers"><literal>NormNodeFreeBuffers()</literal></link>
          call where only the buffering resources are freed and other state
          pertaining to the sender is kept. If the deleted sender again
          becomes "active", it will be treated as a brand new sender. Unless
          explicitly retained with a call to <link
          linkend="NormNodeRetain"><literal>NormNodeRetain()</literal></link>,
          the <parameter>nodeHandle</parameter> should be considered invalid
          after this call is made. Additionally, any
          <type>NormObjectHandle</type> values for pending objects from this
          sender are also invalidated (unless otherwise retained), although
          <constant>NORM_RX_OBJECT_ABORTED</constant> notifications may be
          issued for those pending objects.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return value.</para>
        </sect4>
      </sect3>

      <sect3 id="NormNodeRetain">
        <title>NormNodeRetain()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormNodeRetain"><literal>NormNodeRetain</literal></link>(<link
              linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>In the same manner as the <link
          linkend="NormObjectRetain"><literal>NormObjectRetain()</literal></link>
          function, this function allows the application to retain state
          associated with a given <parameter>nodeHandle</parameter> value even
          when the underlying NORM protocol engine might normally free the
          associated state and thus invalidate the <link
          linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>.
          If the application uses this function, it must make a corresponding
          call to <link
          linkend="NormNodeRelease"><literal>NormNodeRelease()</literal></link>
          when finished with the node information to avoid a memory leak
          condition. <link
          linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
          values (unless retained) are valid from the time of a
          <literal>NORM_REMOTE_SENDER_NEW</literal> notification until a
          complimentary <literal>NORM_REMOTE_SENDER_PURGED</literal>
          notification. During that interval, the application will receive
          <literal>NORM_REMOTE_SENDER_ACTIVE</literal> and
          <literal>NORM_REMOTE_SENDER_INACTIVE</literal> notifications
          according to the sender's message transmission activity within the
          session.</para>

          <para>It is important to note that, if the NORM protocol engine
          posts a <literal>NORM_REMOTE_SENDER_PURGED</literal> notification
          for a given <link
          linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>,
          the NORM protocol engine could possibly, subsequently establish a
          new, different <link
          linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
          value for the same remote sender (i.e., one of equivalent <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link>) if it
          again becomes active in the session. A new <link
          linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
          may likely be established even if the application has retained the
          previous <link
          linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>
          value. Therefore, to the application, it might appear that two
          different senders with the same <link
          linkend="NormNodeId"><literal>NormNodeId</literal></link> are
          participating if these notifications are not carefully monitored.
          This behavior is contingent upon how the application has configured
          the NORM protocol engine to manage resources when there is potential
          for a large number of remote senders within a session (related APIs
          are TBD). For example, the application may wish to control which
          specific remote senders for which it keeps state (or limit the
          memory resources used for remote sender state, etc) and the NORM API
          may be extended in the future to control this behavior.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return value.</para>
        </sect4>
      </sect3>

      <sect3 id="NormNodeRelease">
        <title>NormNodeRelease()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormNodeRelease"><literal>NormNodeRelease</literal></link>(<link
              linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link> nodeHandle);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>In complement to the <link
          linkend="NormNodeRetain"><literal>NormNodeRetain()</literal></link>
          function, this API call releases the specified
          <parameter>nodeHandle</parameter> so that the NORM protocol engine
          may free associated resources as needed. Once this call is made, the
          application should no longer reference the specified <link
          linkend="NormNodeHandle"><literal>NormNodeHandle</literal></link>,
          unless it is still valid.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return value.</para>
        </sect4>
      </sect3>
    </sect2>

    <sect2>
      <title>NORM Debugging Functions</title>

      <para>This section describes some additional function calls that are
      available to set debugging output options and control other aspects of
      the NORM implementation.</para>

      <sect3 id="NormSetDebugLevel">
        <title>NormSetDebugLevel()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

void <link linkend="NormSetDebugLevel"><literal>NormSetDebugLevel</literal></link>(unsigned int level);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function controls the verbosity of NORM debugging output.
          Higher values of level result in more detailed output. The highest
          level of debugging is 12. The debug output consists of text written
          to STDOUT by default but may be directed to a log file using the
          <link
          linkend="NormOpenDebugLog"><literal>NormOpenDebugLog()</literal></link>
          function.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>This function has no return value.</para>
        </sect4>
      </sect3>

      <sect3 id="NormOpenDebugLog">
        <title>NormOpenDebugLog()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormOpenDebugLog"><literal>NormOpenDebugLog</literal></link>(NormInstanceHandle instance, const char* fileName);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>This function allows NORM debug output to be directed to a
          file instead of the default <constant>STDERR</constant>.</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>The function returns <constant>true</constant> on success. If
          the specified file cannot be opened a value of
          <constant>false</constant> is returned.</para>
        </sect4>
      </sect3>

      <sect3 id="NormCloseDebugLog">
        <title>NormCloseDebugLog()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormCloseDebugLog"><literal>NormCloseDebugLog</literal></link>(NormInstanceHandle instance);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>TBD</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>TBD</para>
        </sect4>
      </sect3>

      <sect3 id="NormOpenDebugPipe">
        <title>NormOpenDebugPipe()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormOpenDebugPipe"><literal>NormOpenDebugPipe</literal></link>(NormInstanceHandle instance, const char* pipeName);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>TBD</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>TBD</para>
        </sect4>
      </sect3>

      <sect3 id="NormCloseDebugPipe">
        <title>NormCloseDebugPipe()</title>

        <sect4>
          <title>Synopsis</title>

          <programlisting>#include &lt;normApi.h&gt;

bool <link linkend="NormCloseDebugPipe"><literal>NormCloseDebugPipe</literal></link>(NormInstanceHandle instance);</programlisting>
        </sect4>

        <sect4>
          <title>Description</title>

          <para>TBD</para>
        </sect4>

        <sect4>
          <title>Return Values</title>

          <para>TBD</para>
        </sect4>
      </sect3>
    </sect2>
  </sect1>
</article>