BodgeMaster
/
NORM-mirror
mirror of https://github.com/USNavalResearchLaboratory/norm.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
NORM-mirror/NormDeveloperGuide.html

3576 lines
248 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
<TITLE>NORM Developer’s Guide</TITLE>
<META NAME="GENERATOR" CONTENT="NeoOffice/J 1.1 (Unix)">
<META NAME="AUTHOR" CONTENT="Robert Adamson">
<META NAME="CREATED" CONTENT="20040824;14180000">
<META NAME="CHANGED" CONTENT="20050907;17092400">
<META NAME="DESCRIPTION" CONTENT="NORM Object Functions 42
NORM Object Functions
NORM_OBJECT_STREAM
NORM Sender Functions 19
NORM Sender Functions
">
<META NAME="KEYWORDS" CONTENT="norm object value application function ">
<STYLE>
<!--
@page { size: 8.5in 11in; margin-right: 1.25in; margin-top: 1in; margin-bottom: 0.5in }
@page:first { margin-top: 1in; margin-bottom: 1in }
P { margin-top: 0.08in; margin-bottom: 0in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
P.western { font-family: "Times"; font-size: 12pt; so-language: en-US; font-style: italic }
P.cjk { font-family: "Times"; font-size: 12pt; font-style: italic }
P.ctl { font-family: "Times"; font-size: 10pt }
H1 { margin-bottom: 0.04in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
H1.western { font-family: "Helvetica", sans-serif; font-size: 16pt; so-language: en-US }
H1.cjk { font-family: "Times"; font-size: 16pt }
H1.ctl { font-family: "Times"; font-size: 10pt; font-weight: medium }
H2 { margin-bottom: 0.04in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
H2.western { font-family: "Helvetica", sans-serif; font-size: 14pt; so-language: en-US; font-style: italic }
H2.cjk { font-family: "Times"; font-size: 14pt; font-style: italic }
H2.ctl { font-family: "Times"; font-size: 10pt; font-weight: medium }
H3 { margin-bottom: 0.04in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
H3.western { font-family: "Helvetica", sans-serif; font-size: 13pt; so-language: en-US }
H3.cjk { font-family: "Times"; font-size: 13pt }
H3.ctl { font-family: "Times"; font-size: 10pt; font-weight: medium }
H4 { margin-bottom: 0.04in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
H4.western { font-family: "Times"; font-size: 14pt; so-language: en-US }
H4.cjk { font-family: "Times"; font-size: 14pt }
H4.ctl { font-family: "Times"; font-size: 10pt; font-weight: medium }
H3.functionheading-western { border-top: 1px solid #000000; border-bottom: none; border-left: none; border-right: none; padding-top: 0.01in; padding-bottom: 0in; padding-left: 0in; padding-right: 0in; font-family: "Courier"; font-size: 13pt; so-language: en-US }
H3.functionheading-cjk { border-top: 1px solid #000000; border-bottom: none; border-left: none; border-right: none; padding-top: 0.01in; padding-bottom: 0in; padding-left: 0in; padding-right: 0in; font-family: "Times"; font-size: 13pt }
H3.functionheading-ctl { border-top: 1px solid #000000; border-bottom: none; border-left: none; border-right: none; padding-top: 0.01in; padding-bottom: 0in; padding-left: 0in; padding-right: 0in; font-family: "Times"; font-size: 10pt; font-weight: medium }
A:link { color: #0000ff }
A:visited { color: #800080 }
-->
</STYLE>
</HEAD>
<BODY LANG="en-US" TEXT="#000000" LINK="#0000ff" VLINK="#800080" DIR="LTR">
<TABLE WIDTH=590 BORDER=0 CELLPADDING=7 CELLSPACING=0 STYLE="page-break-before: always">
<COL WIDTH=191>
<COL WIDTH=371>
<TR VALIGN=TOP>
<TD WIDTH=191>
<P ALIGN=CENTER STYLE="margin-top: 0.17in; font-style: normal"><IMG SRC="NormLogo.gif" NAME="Graphic1" ALIGN=BOTTOM WIDTH=184 HEIGHT=176 BORDER=0></P>
</TD>
<TD WIDTH=371>
<P ALIGN=LEFT STYLE="margin-left: 0.86in; margin-top: 0.17in; font-style: normal">
<FONT FACE="Helvetica, sans-serif"><FONT SIZE=6 STYLE="font-size: 28pt"><B>NORM<BR>Developer’s
<BR>Guide</B></FONT></FONT></P>
</TD>
</TR>
</TABLE>
<H1 CLASS="western">Background</H1>
<P CLASS="western" STYLE="font-style: normal">This document describes
an application programming interface (API) for the Nack-Oriented
Reliable Multicast (NORM) protocol implementation developed by the
United States Naval Research Laboratory (NRL). The NORM protocol
provides general purpose reliable data transport for applications
wishing to use Internet Protocol (IP) Multicast services for group
data delivery. NORM can also support unicast (point-to-point) data
communication and may be used for such when deemed appropriate. The
current NORM protocol specification is given in the Internet
Engineering Task Force RFC 3940.</P>
<P CLASS="western" STYLE="font-style: normal">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 &quot;a
priori&quot; coordination among senders and receivers. A congestion
control scheme is specified to allow the NORM protocol fairly share
available network bandwidth with other transport protocols such as
Transmission Control Protocol (TCP). It is capable of operating with
both reciprocal multicast routing among senders and receivers and
with asymmetric connectivity (possibly a unicast return path) from
the senders to receivers. The protocol offers a number of features
to allow different types of applications or possibly other higher
level transport protocols to utilize its service in different ways.
The protocol leverages the use of FEC-based repair and other proven
reliable multicast transport techniques in its design.</P>
<P CLASS="western" STYLE="font-style: normal">The NRL NORM library
attempts to provide a general useful capability for development of
reliable multicast applications for bulk file or other data delivery
as well as support of stream-based transport with possible real-time
delivery requirements. The API allows access to many NORM protocol
parameters and control functions to tailor performance for specific
applications. While default parameters, where provided, can be
useful to a potential wide range of requirements, the many different
possible group communication paradigms dictate different needs for
different applications. Even with NORM, the developer should have a
thorough understanding of the specific application's group
communication needs.</P>
<H1 CLASS="western" ALIGN=CENTER STYLE="page-break-before: always">Table
of Contents</H1>
<DIV ID="Table of Contents1" DIR="LTR">
<P STYLE="margin-top: 0.25in; font-style: normal"><FONT FACE="Helvetica, sans-serif"><B>Overview</B></FONT></P>
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>API
Initialization</B></FONT></P>
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>Session
Creation and Control</B></FONT></P>
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>NORM
Data Transport</B></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2>NORM
Data Transmission</FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2>NORM
Data Reception</FONT></P>
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>API
Event Notification</B></FONT></P>
<P STYLE="margin-top: 0.25in; font-style: normal"><FONT FACE="Helvetica, sans-serif"><B>Build
Notes</B></FONT></P>
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>Unix
Platforms</B></FONT></P>
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>Win32/WiNCE
Platforms</B></FONT></P>
<P STYLE="margin-top: 0.25in; font-style: normal"><FONT FACE="Helvetica, sans-serif"><B>API
Reference</B></FONT></P>
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>API
Variable Types and Constants</B></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormInstanceHandle">NormInstanceHandle</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSessionHandle">NormSessionHandle</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSessionId">NormSessionId</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeId">NormNodeId</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectType">NormObjectType</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSize">NormSize</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectTransportId">NormObjectTransportId</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormEventType">NormEventType</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormEvent">NormEvent</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDescriptor">NormDescriptor</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormFlushMode">NormFlushMode</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormProbingMode">NormProbingMode</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNackingMode">NormNackingMode</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormRepairBoundary">NormRepairBoundary</A></FONT></P>
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>API
Initialization and Operation</B></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormCreateInstance()">NormCreateInstance()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDestroyInstance()">NormDestroyInstance()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetCacheDirectory()">NormSetCacheDirectory()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormGetDescriptor()">NormGetDescriptor()</A></FONT></P>
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>Session
Creation and Control</B></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormCreateSession()">NormCreateSession()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDestroySession()">NormDestroySession()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetUserData()">NormSetUserData()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormGetUserData()">NormGetUserData()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormGetLocalNodeId()">NormGetLocalNodeId()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTxPort()">NormSetTxPort()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetRxPortReuse()">NormSetRxPortReuse()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetMulticastInterface()">NormSetMulticastInterface()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTTL()">NormSetTTL()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTOS()">NormSetTOS()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetLoopback()">NormSetLoopback()</A></FONT></P>
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>NORM
Sender Functions</B></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStartSender()">NormStartSender()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStopSender()">NormStopSender()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTransmitRate()">NormSetTransmitRate()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTxSocketBuffer()">NormSetTxSocketBuffer()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetCongestionControl()">NormSetCongestionControl()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTransmitRateBounds()">NormSetTransmitRateBounds()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTransmitCacheBounds()">NormSetTransmitCacheBounds()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetAutoParity()">NormSetAutoParity()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetGrttEstimate()">NormSetGrttEstimate()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetGrttMax()">NormSetGrttMax()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetGrttProbingMode()">NormSetGrttProbingMode()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetGrttProbingInterval()">NormSetGrttProbingInterval()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormAddAckingNode()">NormAddAckingNode()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormRemoveAckingNode()">NormRemoveAckingNode()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormFileEnqueue()">NormFileEnqueue()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDataEnqueue()">NormDataEnqueue()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamOpen()">NormStreamOpen()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamClose()">NormStreamClose()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamSetAutoFlush()">NormStreamSetAutoFlush()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamSetPushEnable()">NormStreamSetPushEnable()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamHasVacancy()">NormStreamHasVacancy()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamMarkEom()">NormStreamMarkEom()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetWatermark()">NormSetWatermark()</A></FONT></P>
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>NORM
Receiver Functions</B></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStopReceiver()">NormStopReceiver()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetRxSocketBuffer()">NormSetRxSocketBuffer()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetSilentReceiver()">NormSetSilentReceiver()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetDefaultUnicastNack()">NormSetDefaultUnicastNack()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeSetUnicastNack()">NormNodeSetUnicastNack()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetDefaultNackingMode()">NormSetDefaultNackingMode()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeSetNackingMode()">NormNodeSetNackingMode()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectSetNackingMode()">NormObjectSetNackingMode()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetDefaultRepairBoundary()">NormSetDefaultRepairBoundary()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeSetRepairBoundary()">NormNodeSetRepairBoundary()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamRead()">NormStreamRead()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamSeekMsgStart()">NormStreamSeekMsgStart()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamGetReadOffset()">NormStreamGetReadOffset()</A></FONT></P>
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>NORM
Object Functions</B></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetType()">NormObjectGetType()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectHasInfo()">NormObjectHasInfo()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetInfoLength()">NormObjectGetInfoLength()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetInfo()">NormObjectGetInfo()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetSize()">NormObjectGetSize()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetBytesPending()">NormObjectGetBytesPending()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectCancel()">NormObjectCancel()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormFileGetName()">NormFileGetName()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormFileRename()">NormFileRename()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDataAccessData()">NormDataAccessData()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDataDetachData()">NormDataDetachData()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetSender()">NormObjectGetSender()</A></FONT></P>
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>NORM
Node Functions</B></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeGetId()">NormNodeGetId()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeGetAddress()">NormNodeGetAddress()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeRetain()">NormNodeRetain()</A></FONT></P>
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeRelease()">NormNodeRelease()</A></FONT></P>
</DIV>
<H1 CLASS="western" STYLE="page-break-before: always">Overview</H1>
<P CLASS="western" STYLE="font-style: normal">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 (<I>NormSessions</I>). Subsequently, NORM data
transmission (<I>NormSender</I>) operation can be activated and the
application can queue various types of data (<I>NormObjects</I>) for
reliable transport. Additionally or alternatively, NORM reception
(<I>NormReceiver</I>) operation can also be enabled on a per-session
basis and the protocol implementation alerts the application of
receive events.</P>
<P CLASS="western" STYLE="font-style: normal">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. (<I>Note:
API mechanisms for lower-level, non-threaded control and execution
of the NORM protocol engine will also be provided in the future</I>.)</P>
<P CLASS="western" STYLE="font-style: normal">The NORM API operation
can be roughly summarized with the following categories of functions:</P>
<OL>
<LI><P CLASS="western" STYLE="font-style: normal">API Initialization</P>
<LI><P CLASS="western" STYLE="font-style: normal">Session Creation
and Control</P>
<LI><P CLASS="western" STYLE="font-style: normal">Data Transport</P>
<LI><P CLASS="western" STYLE="font-style: normal">Event Notification</P>
</OL>
<P CLASS="western" STYLE="font-style: normal">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 and host
port number) may be created and controlled. Applications may
participate as senders and/or receivers within a NORM session. NORM
senders transmit data to the session destination address (usually an
IP multicast group) while receivers are notified of incoming data.
The NORM API provides and event notification scheme to notify the
application of significant sender and receiver events. There are
also a number support functions provided for the application to
control and monitor its participation within a NORM transport
session.</P>
<H2 CLASS="western">API Initialization</H2>
<P CLASS="western" STYLE="font-style: normal">The NORM API requires
that an application explicitly create at least one instance of the
NORM protocol engine which 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. In general, only the thread creating the NORM API
instance should invoke API calls referencing that instance or any
sessions or state created within that instance (<I>NOTE: This
limitation may change in the future. The current implementation is
theoretically safe for concurrent access, but this has not been fully
tested</I>). Multiple API instances may be created as needed for
applications with specific requirements for accessing and controlling
participation in multiple NORM sessions from operating system
multiple threads.</P>
<H2 CLASS="western">Session Creation and Control</H2>
<P CLASS="western" STYLE="font-style: normal">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 sender and API calls are provided to control
transmission rate, FEC parameters, etc. Applications participating
as receivers will be notified via the NORM API's event dispatching
mechanism of pending and completed reliable reception of data along
with other significant events. Additionally, API controls for some
optional NORM protocol mechanisms, such as positive acknowledgment
collection, are also provided.</P>
<P CLASS="western" STYLE="font-style: normal">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 (<I>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</I>).
</P>
<H2 CLASS="western">NORM Data Transport</H2>
<P CLASS="western" STYLE="font-style: normal">The NORM protocol
supports transport of three basic types of data content. These
include the types <FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT>
and <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT> 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
<FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT> type directly
from/to file storage, while application memory space is accessed for
the <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT> type. The
third data content type, <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>,
represents unbounded, possibly persistent, streams of data content.
Using this transport paradigm, traditional, byte-oriented streaming
transport service (e.g. similar to that provided by a TCP socket) can
be provided. Additionally, NORM has provisions for
application-defined message-oriented transport where receivers can
recover message boundaries without any “handshake” with the
sender. Stream content is buffered by the NORM implementation for
transmission/retransmission and as it is received.</P>
<H3 CLASS="western">NORM Data Transmission</H3>
<P CLASS="western" STYLE="font-style: normal">The behavior of data
transport operation is largely placed in the control of the NORM
sender(s). NORM senders controls their data transmission rate,
forward error correction (FEC) encoding settings, and parameters
controlling feedback from the receiver group. Multiple senders may
operate in a session, each with independent transmission parameters.
NORM receivers learn needed parameter values from fields in NORM
message headers.</P>
<P CLASS="western" STYLE="font-style: normal">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 &quot;friendly&quot; to other data flows
on the network, fairly sharing available bandwidth.</P>
<P CLASS="western" STYLE="font-style: normal">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 &quot;robust&quot;
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 &quot;transmit cache&quot;
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 &quot;backup&quot; for
when network packet loss exceeds the repair capability of the
proactive FEC settings.</P>
<P CLASS="western" STYLE="font-style: normal">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 (&quot;acking
node list&quot;) and set &quot;watermark&quot; points for which
positive acknowledgement is collected. This process can provide the
application with explicit flow control for an application-determined
critical set of receivers in the group.</P>
<H3 CLASS="western">NORM Data Reception</H3>
<P CLASS="western" STYLE="font-style: normal">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 NORM_INFO content only or even to the extent of
disabling receiver feedback (silent receiver operation) entirely.</P>
<H2 CLASS="western">API Event Notification</H2>
<P CLASS="western" STYLE="font-style: normal">An asynchronous event
dispatching mechanism is provided to notify the application of
significant NORM protocol events. The centerpiece of this is the
<FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT> function which can be
used to retrieve the next NORM protocol engine event in the form of a
<FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT> structure. This function will
typically block until a <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT> occurs.
However, non-blocking operation may be achieved by using the
<FONT FACE="Courier"><A HREF="#NormGetDescriptor()">NormGetDescriptor()</A></FONT> call to get a value
(file descriptor (Unix) or HANDLE (Win32) suitable for use in a
asynchronous I/O monitoring functions such as <I>select()</I> (Unix)
or <I>MsgWaitForMultipleObjects()</I> (Win32). The descriptor will
be signaled when a <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT> 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 API.</P>
<H1 CLASS="western">Build Notes</H1>
<P CLASS="western" STYLE="font-style: normal">To build applications
that use the NORM library, a path to the &quot;normApi.h&quot; header
file must be provided and the linker step needs to reference the NORM
library file (&quot;libnorm.a&quot; for Unix platforms and &quot;Norm.lib&quot;
for Win32 platforms). NORM also depends upon the NRL Protean
Protocol Prototyping toolkit &quot;Protokit&quot; library (a.k.a
&quot;Protolib&quot;) (static library files &quot;libProtokit.a&quot;
for Unix and &quot;Protokit.lib&quot; for Win32). Depending upon the
platform, some additional library dependencies may be required to
support the needs of NORM and/or Protokit. These are described
below.</P>
<H2 CLASS="western">Unix Platforms</H2>
<P CLASS="western" STYLE="font-style: normal">NORM has been built and
tested on Linux (various architectures), MacOS (BSD), Solaris, and
IRIX (SGI) platforms. The code should be readily portable to other
Unix platforms.</P>
<P CLASS="western" STYLE="font-style: normal">To support IPv6
operation, the NORM and the Protokit library must be compiled with
the &quot;HAVE_IPV6&quot; 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 &quot;large file support&quot;
options be enabled when possible.</P>
<P CLASS="western" STYLE="font-style: normal">The NORM API uses
threading so that the NORM protocol engine may run independent of the
application. Thus the &quot;POSIX Threads&quot; library must be
included (&quot;-'pthread&quot;) in the linking step. MacOS/BSD also
requires the addition of the &quot;-lresolv&quot; (resolver) library
and Solaris requires the dynamic loader, network/socket, and resolver
libraries (&quot;–lnsl –lsocket –lresolv&quot;) to achieve
successful compilation. The Makefiles in the NORM source code
distribution are a reference for these requirements. Note that MacOS
9 and earlier are not supported.</P>
<P CLASS="western" STYLE="font-style: normal">Additionally, it is
critical that the _FILE_OFFSET_BITS macro be consistently defined for
the NORM library build and the application build using the library.
The distributed NORM Makefiles have –D_FILE_OFFSET_BITS=64 set in
the compilation to enable &quot;large file support&quot;.
Applications built using NORM should have the same compilation option
set to operate correctly (The definition of the <FONT FACE="Courier"><A HREF="#NormSize">NormSize</A></FONT>
type in &quot;normApi.h&quot; depends upon this compilation flag).</P>
<H2 CLASS="western">Win32/WiNCE Platforms</H2>
<P CLASS="western" STYLE="font-style: normal">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 &quot;Protokit&quot;
and &quot;NORM&quot; 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 &quot;Multithreading
DLL&quot; library usage set. The NORM API requires multithreading
support. This is a critical setting and numerous compiler and linker
errors will result if this is not properly set for your application
project.</P>
<P CLASS="western" STYLE="font-style: normal">NORM and Protokit also
depend on the Winsock 2.0 (&quot;ws2_32.lib&quot; (or &quot;ws2.lib&quot;
(WinCE)) and the IP Helper API (&quot;iphlpapi.lib&quot;) libraries
and these must be included in the project &quot;Link&quot;
attributes.</P>
<P CLASS="western" STYLE="font-style: normal">An additional note is
that a bug in VC++ 6.0 and earlier compilers (includes embedded VC++
4.x compilers) prevent compilation of Protokit-based code with
debugging capabilities enabled. However, this has been resolved in
VC++ .NET and is hoped to be resolved in the future for the WinCE
build tools.</P>
<H1 CLASS="western">API Reference</H1>
<P CLASS="western" STYLE="font-style: normal">This section provides a
reference to the NORM API variable types, constants and functions.</P>
<H2 CLASS="western">API Variable Types and Constants</H2>
<P CLASS="western" STYLE="font-style: normal">The NORM API defines
and enumerates a number of supporting variable types and values which
are used in different function calls. The variable types are
described here.</P>
<H3 CLASS="functionheading-western"><A NAME="NormInstanceHandle">NormInstanceHandle</A></H3>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormInstanceHandle">NormInstanceHandle</A>
</FONT>type is returned when a NORM API instance is created (see
<FONT FACE="Courier"><A HREF="#NormCreateInstance()">NormCreateInstance()</A></FONT>). 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 <FONT FACE="Courier">NORM_INSTANCE_INVALID</FONT>
corresponds to an invalid API instance.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSessionHandle">NormSessionHandle</A></H3>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormSessionHandle">NormSessionHandle</A></FONT>
type is used to reference NORM transport sessions which have been
created using the <FONT FACE="Courier"><A HREF="#NormCreateSession()">NormCreateSession()</A></FONT> API
call. Multiple <FONT FACE="Courier">NormSessionHandles</FONT> may be
associated with a given <FONT FACE="Courier"><A HREF="#NormInstanceHandle">NormInstanceHandle</A></FONT>.
The special value <FONT FACE="Courier">NORM_SESSION_INVALID </FONT>is
used to refer to invalid session references.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSessionId">NormSessionId</A></H3>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormSessionId">NormSessionId</A></FONT>
type is used by applications to uniquely identify their instance of
participation as a sender within a <I>NormSession</I>. This type is
a parameter to the <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>
function. Robust applications can use different <FONT FACE="Courier"><A HREF="#NormSessionId">NormSessionId</A></FONT>
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 <FONT FACE="Courier"><A HREF="#NormSessionId">NormSessionId</A></FONT> value
in non-volatile storage which could then be recovered and incremented
(for example) upon system restart to produce a new value. The
<FONT FACE="Courier"><A HREF="#NormSessionId">NormSessionId</A></FONT> value is used for the value
of the <I>instance_id</I> field in NORM protocol sender messages (see
the NORM protocol specification) and receivers use this field to
detect sender restart within a <I>NormSession</I>.</P>
<H3 CLASS="functionheading-western"><A NAME="NormNodeHandle">NormNodeHandle</A></H3>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A>
</FONT>type is used to reference state kept by the NORM
implementation with respect to other participants within a
<I>NormSession</I>. Most typically, the <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A>
</FONT>is used by receiver applications to dereference information
about remote senders of data as needed. The special value
<FONT FACE="Courier">NORM_NODE_INVALID</FONT> corresponds to an
invalid reference.</P>
<H3 CLASS="functionheading-western"><A NAME="NormNodeId">NormNodeId</A></H3>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT>
type corresponds to a 32-bit numeric value which should uniquely
identify a participant (node) in a given <I>NormSession</I>. The
<FONT FACE="Courier"><A HREF="#NormNodeGetId()">NormNodeGetId()</A></FONT> function can be used to
retrieve this value given a valid <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>.
The special value <FONT FACE="Courier">NORM_NODE_NONE</FONT>
corresponds to an invalid (or null) node while the value
<FONT FACE="Courier">NORM_NODE_ANY</FONT> serves as a wildcard value
for some functions.</P>
<H3 CLASS="functionheading-western"><A NAME="NormObjectHandle">NormObjectHandle</A></H3>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>
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
<FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT> (see <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT>)
if needed. For sender objects, unless explicitly retained, the
<FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT> can be considered valid
until the referenced object is explicitly canceled (see
<FONT FACE="Courier"><A HREF="#NormObjectCancel()">NormObjectCancel()</A></FONT>) or purged from the
sender transmission queue (see the event <I><FONT FACE="Courier">NORM_TX_OBJECT_PURGED</FONT></I>).
For receiver objects, these handles should be treated as valid only
until a subsequent call to <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>
unless, again, specifically retained. The special value
<I><FONT FACE="Courier">NORM_OBJECT_INVALID</FONT></I> corresponds to
an invalid transport object reference.</P>
<H3 CLASS="functionheading-western"><A NAME="NormObjectType">NormObjectType</A></H3>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormObjectType">NormObjectType</A></FONT>
type is an enumeration of possible NORM data transport object types.
As previously mentioned, valid types include:</P>
<OL>
<LI><P CLASS="western"><FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT></P>
<LI><P CLASS="western" STYLE="font-style: normal"><I><FONT FACE="Courier">NORM_OBJECT_DATA</FONT></I>,
and</P>
<LI><P CLASS="western"><FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT></P>
</OL>
<P CLASS="western" STYLE="font-style: normal">Given a
<FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>, the application may
determine an object's type using the <FONT FACE="Courier"><A HREF="#NormObjectGetType()">NormObjectGetType()</A></FONT>
function call. A special <FONT FACE="Courier"><A HREF="#NormObjectType">NormObjectType</A></FONT>
value, <I><FONT FACE="Courier">NORM_OBJECT_NONE</FONT></I>, indicates
an invalid object type.
</P>
<H3 CLASS="functionheading-western"><A NAME="NormSize">NormSize</A></H3>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormSize">NormSize</A></FONT>
is the type used for <I>NormObject</I> size information. For
example, the <FONT FACE="Courier"><A HREF="#NormObjectGetSize()">NormObjectGetSize()</A></FONT> function
returns a value of type <FONT FACE="Courier"><A HREF="#NormSize">NormSize</A></FONT>. The
range of <FONT FACE="Courier"><A HREF="#NormSize">NormSize</A></FONT> values depends upon the
operating system and NORM library compilation settings. With &quot;large
file support&quot; enabled, as is the case with distributed NORM
library &quot;Makefiles&quot;, the <FONT FACE="Courier"><A HREF="#NormSize">NormSize</A></FONT>
type is a 64-bit integer. However, some platforms may support only
32-bit object sizes.</P>
<H3 CLASS="functionheading-western"><A NAME="NormObjectTransportId">NormObjectTransportId</A></H3>
<P CLASS="western" STYLE="font-style: normal">The
<FONT FACE="Courier"><A HREF="#NormObjectTransportId">NormObjectTransportId</A></FONT> type is a 16-bit
numerical value assigned to <I>NormObjects</I> by senders during
active transport. These values are temporarily unique with respect
to a given sender within a <I>NormSession</I> and may be &quot;recycled&quot;
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
<FONT FACE="Courier">NormObjectGetTransportId() </FONT>is provided to
retrieve these values if needed. (<I>Note this type may be
deprecated – it may not be needed at all if the NormObjectRequeue()
function (TBD) is implemented using handles only, but _some_
applications requiring persistence even after a system reboot may
need the ability to recall previous transport ids?</I>)</P>
<H3 CLASS="functionheading-western"><A NAME="NormEventType">NormEventType</A></H3>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormEventType">NormEventType</A></FONT>
is an enumeration of NORM API events. &quot;Events&quot; 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 <FONT FACE="Courier"><A HREF="#NormEventType">NormEventType</A></FONT>
values and their interpretation is given below. The function call
<FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT> is used to retrieve
events from the NORM protocol engine.</P>
<H3 CLASS="functionheading-western"><A NAME="NormEvent">NormEvent</A></H3>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A>
</FONT>type is a structure used to describe significant NORM protocol
events. This structure is defined as follows:</P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>typedef
struct<BR>{<BR>&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormEventType">NormEventType</A>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;type;<BR>&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session;<BR>&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormNodeHandle">NormNodeHandle</A>&nbsp;&nbsp;&nbsp;&nbsp;node;<BR>&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormObjectHandle">NormObjectHandle</A>&nbsp;&nbsp;object;<BR>}
<A HREF="#NormEvent">NormEvent</A>;</FONT></FONT></P>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier">type</FONT>
field indicates the <FONT FACE="Courier"><A HREF="#NormEventType">NormEventType</A></FONT> and
determines how the other fields should be interpreted. Note that not
all <FONT FACE="Courier"><A HREF="#NormEventType">NormEventType</A></FONT> fields are relevant to
all events. The <FONT FACE="Courier">session</FONT>, <FONT FACE="Courier">node</FONT>,
and <FONT FACE="Courier">object</FONT> fields indicate the applicable
<FONT FACE="Courier"><A HREF="#NormSessionHandle">NormSessionHandle</A></FONT>, <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>,
and <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>, respectively, to
which the event applies. NORM protocol events are made available to
the application via the <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>
function call.</P>
<H3 CLASS="functionheading-western"><A NAME="NormDescriptor">NormDescriptor</A></H3>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormDescriptor">NormDescriptor</A></FONT>
type provides reference to a file descriptor (Unix) or HANDLE
(Win32). For a given <FONT FACE="Courier"><A HREF="#NormInstanceHandle">NormInstanceHandle</A></FONT>,
the <FONT FACE="Courier"><A HREF="#NormGetDescriptor()">NormGetDescriptor()</A></FONT> function can be
used to retrieve a <A HREF="#NormDescriptor">NormDescriptor</A> value that may, in turn, used in
appropriate system calls (e.g. <I>select()</I> or
<I>MsgWaitForMultipleObjects()</I>) to asynchronously monitor the
NORM protocol engine for notification events (see <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT>
description).
</P>
<H3 CLASS="functionheading-western"><A NAME="NormFlushMode">NormFlushMode</A></H3>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormFlushMode">NormFlushMode</A></FONT>
consist of the following enumeration:</P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>enum
<A HREF="#NormFlushMode">NormFlushMode</A><BR>{<BR>&nbsp;&nbsp;&nbsp;&nbsp;NORM_FLUSH_NONE,<BR>&nbsp;&nbsp;&nbsp;&nbsp;NORM_FLUSH_PASSIVE,<BR>&nbsp;&nbsp;&nbsp;&nbsp;NORM_FLUSH_ACTIVE<BR>};</FONT></FONT></P>
<P CLASS="western" STYLE="font-style: normal">The interpretation of
these values is given in the descriptions of <FONT FACE="Courier"><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT>
and <FONT FACE="Courier"><A HREF="#NormStreamSetAutoFlush()">NormStreamSetAutoFlush()</A></FONT> functions.</P>
<H3 CLASS="functionheading-western"><A NAME="NormProbingMode">NormProbingMode</A></H3>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormProbingMode">NormProbingMode</A></FONT>
consist of the following enumeration:</P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>enum
<A HREF="#NormProbingMode">NormProbingMode</A><BR>{<BR>&nbsp;&nbsp;&nbsp;&nbsp;NORM_PROBE_NONE,<BR>&nbsp;&nbsp;&nbsp;&nbsp;NORM_PROBE_PASSIVE,<BR>&nbsp;&nbsp;&nbsp;&nbsp;NORM_PROBE_ACTIVE<BR>};</FONT></FONT></P>
<P CLASS="western" STYLE="font-style: normal">The interpretation of
these values is given in the description of <FONT FACE="Courier"><A HREF="#NormSetGrttProbingMode()">NormSetGrttProbingMode()</A></FONT>
function.</P>
<H3 CLASS="functionheading-western"><A NAME="NormNackingMode">NormNackingMode</A></H3>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormNackingMode">NormNackingMode</A></FONT>
consist of the following enumeration:</P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>enum
<A HREF="#NormNackingMode">NormNackingMode</A><BR>{<BR>&nbsp;&nbsp;&nbsp;&nbsp;NORM_NACK_NONE,<BR>&nbsp;&nbsp;&nbsp;&nbsp;NORM_NACK_INFO_ONLY,<BR>&nbsp;&nbsp;&nbsp;&nbsp;NORM_NACK_NORMAL<BR>};</FONT></FONT></P>
<P CLASS="western" STYLE="font-style: normal">The interpretation of
these values is given in the descriptions of the
<FONT FACE="Courier"><A HREF="#NormSetDefaultNackingMode()">NormSetDefaultNackingMode()</A></FONT>,
<FONT FACE="Courier"><A HREF="#NormNodeSetNackingMode()">NormNodeSetNackingMode()</A></FONT> and
<FONT FACE="Courier"><A HREF="#NormObjectSetNackingMode()">NormObjectSetNackingMode()</A></FONT> functions.</P>
<H3 CLASS="functionheading-western"><A NAME="NormRepairBoundary">NormRepairBoundary</A></H3>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormRepairBoundary">NormRepairBoundary</A></FONT>
consist of the following enumeration:</P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>enum
<A HREF="#NormRepairBoundary">NormRepairBoundary</A><BR>{<BR>&nbsp;&nbsp;&nbsp;&nbsp;NORM_BOUNDARY_BLOCK,<BR>&nbsp;&nbsp;&nbsp;&nbsp;NORM_BOUNDARY_OBJECT<BR>};</FONT></FONT></P>
<P CLASS="western" STYLE="font-style: normal">The interpretation of
these values is given in the descriptions of the
<FONT FACE="Courier"><A HREF="#NormSetDefaultRepairBoundary()">NormSetDefaultRepairBoundary()</A> </FONT>and
<FONT FACE="Courier"><A HREF="#NormNodeSetRepairBoundary()">NormNodeSetRepairBoundary()</A></FONT> functions.</P>
<H2 CLASS="western">API Initialization and Operation</H2>
<P CLASS="western" STYLE="font-style: normal">The first step in using
the NORM API is to create an &quot;instance&quot; 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 <I>NormSessions</I> may be managed under a
single NORM API instance.</P>
<H3 CLASS="functionheading-western"><A NAME="NormCreateInstance()">NormCreateInstance()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormInstanceHandle">NormInstanceHandle</A>
NormCreateInstance(bool priorityBoost = false);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">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 <FONT FACE="Courier"><A HREF="#NormInstanceHandle">NormInstanceHandle</A>
</FONT>value may be used in subsequent API calls as needed, such
<FONT FACE="Courier">NormCreateSesssion()</FONT>, etc. The optional
<FONT FACE="Courier"><U>priorityBoost</U></FONT> parameter, when set
to a value of <FONT FACE="Courier"><I>true</I></FONT>, specifies that
the NORM protocol engine thread be run with higher priority
scheduling. On Win32 platforms, this corresponds to
<FONT FACE="Courier"><I>THREAD_PRIORITY_TIME_CRITICAL</I></FONT> and
on Unix systems with the <FONT FACE="Courier">sched_setscheduler()</FONT>
API, an attempt to get the maximum allowed <FONT FACE="Courier"><I>SCHED_FIFO</I></FONT>
priority is made. The use of this option should be carefully
evaluated since, depending upon the application's scheduling priority
and NORM API usage, this may have adverse effects instead of a
guaranteed performance increase!</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">A value of
<FONT FACE="Courier">NORM_INSTANCE_INVALID</FONT> is returned upon
failure. The function will only fail if system resources are
unavailable to allocate the instance and/or create the corresponding
thread.</P>
<H3 CLASS="functionheading-western"><A NAME="NormDestroyInstance()">NormDestroyInstance()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormDestroyInstance(<A HREF="#NormInstanceHandle">NormInstanceHandle</A> instance);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">The
<FONT FACE="Courier"><A HREF="#NormDestroyInstance()">NormDestroyInstance()</A></FONT> function
immediately shuts down and destroys the NORM protocol engine instance
referred to by the <U><FONT FACE="Courier">instance</FONT></U>
parameter. The application should make no subsequent references to
the indicated <FONT FACE="Courier"><A HREF="#NormInstanceHandle">NormInstanceHandle</A></FONT> 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 <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> and
<FONT FACE="Courier"><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT>).
</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">The function has no
return value.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetCacheDirectory()">NormSetCacheDirectory()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormSetCacheDirectory(<A HREF="#NormInstanceHandle">NormInstanceHandle</A>&nbsp;instance,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const
char*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cachePath);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function sets the
directory path used by receivers to cache newly-received
<I><FONT FACE="Courier">NORM_OBJECT_FILE</FONT></I> objects. This
function must be called before any file objects may be received and
thus should be called before any calls to <FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT>
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 <FONT FACE="Courier"><A HREF="#NormFileRename()">NormFileRename()</A></FONT>
function may be used to rename, and thus potentially move, received
files after reception has begun.
</P>
<P CLASS="western" STYLE="font-style: normal">The <U><FONT FACE="Courier">instance</FONT></U>
parameter specifies the NORM protocol engine instance (all
NormSessions associated with that <U><FONT FACE="Courier">instance</FONT></U>
share the same cache path) and the <U><FONT FACE="Courier">cachePath</FONT></U>
is a string specifying a valid (and writable) directory path. The
function returns <I><FONT FACE="Courier">true</FONT></I> on success
and <I><FONT FACE="Courier">false</FONT></I> on failure. The failure
conditions are that the indicated directory does not exist or the
process does not have permissions to write.</P>
<H3 CLASS="functionheading-western"><A NAME="NormGetNextEvent()">NormGetNextEvent()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormGetNextEvent(<A HREF="#NormInstanceHandle">NormInstanceHandle</A>&nbsp;instance,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormEvent">NormEvent</A>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;theEvent);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function retrieves
the next available NORM protocol event from the protocol engine. The
<FONT FACE="Courier"><U>instance</U></FONT><U> </U>parameter
specifies the applicable NORM protocol engine, and the <FONT FACE="Courier"><U>theEvent</U></FONT><U>
</U>parameter must be a valid pointer to a <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT>
structure capable of receiving the NORM event information. For
expected reliable protocol operation, the application should make
every attempt to retrieve and process NORM notification events in a
timely manner.</P>
<P CLASS="western" STYLE="font-style: normal">Note that this is
currently the only blocking call in the NORM API. But non-blocking
operation may be achieved by using the <FONT FACE="Courier"><A HREF="#NormGetDescriptor()">NormGetDescriptor()</A></FONT>
function to obtain a descriptor (or HANDLE for WIN32) suitable for
asynchronous input/output (I/O) notification using such system calls
as <I><FONT FACE="Courier">select()</FONT></I> (UNIX) or
<I><FONT FACE="Courier">WaitForMultipleObjects()</FONT></I> (WIN32).
The descriptor is signaled when a notification event is pending and a
call to <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT> will not
block.</P>
<H4 CLASS="western">NORM Notification Event Types</H4>
<P CLASS="western" STYLE="font-style: normal">The following table
enumerates the possible <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A> </FONT>values
and describes how these notifications should be interpreted as they
are retrieved by the application via the <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>
function call.</P>
<TABLE WIDTH=590 BORDER=0 CELLPADDING=7 CELLSPACING=0>
<COL WIDTH=269>
<COL WIDTH=293>
<TR>
<TD COLSPAN=2 WIDTH=576 VALIGN=TOP>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<B>Sender Notification Event Types:</B></P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_TX_QUEUE_VACANCY</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This event indicates that there is room for additional transmit
objects to be enqueued, or, if the handle of <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>
is given in the event &quot;object&quot; field, the application
may successfully write to the indicated stream object.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_TX_QUEUE_EMPTY</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This event indicates the NORM protocol engine has no new data
pending transmission and the application may enqueue additional
objects for transmission.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_TX_FLUSH_COMPLETED</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
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 &quot;robust factor&quot; value)
that the receiver set no longer has any pending repair requests.
Note the use of NORM's optional positive acknowledgement feature
is more deterministic in this regards, but this notification is
useful when there are non-acking (NACK-only) receivers. The
default NORM robust factor of 20 (20 flush messages are sent at
end-of-transmission) provides a high assurance of reliable
transmission, even with packet loss rates of 50%.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_TX_OBJECT_SENT</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This event indicates that the transport object referenced by the
event's &quot;object&quot; field has completed at least one pass
of total transmission. Note that this does not guarantee that
reliable transmission has yet completed; only that the entire
object content has been transmitted. Depending upon network
behavior, several rounds of NACKing and repair transmissions may
be required to complete reliable transfer.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This event indicates that the NORM protocol engine will no longer
refer to the transport object identified by the event's &quot;object'
field. Typically, this will occur when the application has
enqueued more objects than space available within the set sender
transmit cache bounds (see <FONT FACE="Courier"><A HREF="#NormSetTransmitCacheBounds()">NormSetTransmitCacheBounds()</A></FONT>).
Posting of this notification means the application is free to
free any resources (memory, files, etc) associated with the
indicated &quot;object&quot;. After this event, the given
&quot;object&quot; handle (<FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>)
is no longer valid unless it is specifically retained by the
application.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_LOCAL_SERVER_CLOSED</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This event is posted when the NORM protocol engine completes the
&quot;graceful shutdown&quot; of its participation as a sender in
the indicated &quot;session&quot; (see <FONT FACE="Courier"><A HREF="#NormStopSender()">NormStopSender()</A></FONT>).</P>
</TD>
</TR>
<TR>
<TD COLSPAN=2 WIDTH=576 VALIGN=TOP>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<B>Receiver Notification Event Types:</B></P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_REMOTE_SERVER_NEW</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This notification is posted when a receiver first receives
messages from a specific remote NORM server. This marks the
beginning of the interval during which the application may
reference the provided &quot;node&quot; handle (<FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>).</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_REMOTE_SERVER_ACTIVE</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This event is posted when a previously inactive (or new) remote
server is detected operating as an active sender within the
session.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_REMOTE_SERVER_INACTIVE</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This event is posted after a significant period of inactivity (no
sender messages received) of a specific NORM sender within the
session. The NORM protocol engine frees buffering resources
allocated for this sender when it becomes inactive.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_REMOTE_SERVER_PURGED</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This event is posted when the NORM protocol engine frees resources
for, and thus invalidates the indicated &quot;node&quot; handle.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_RX_OBJECT_NEW</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This event is posted when reception of a new transport object
begins and marks the beginning of the interval during which the
specified &quot;object&quot; (<FONT FACE="Courier"><U><A HREF="#NormObjectHandle">NormObjectHandle</A></U></FONT>)
is valid.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_RX_OBJECT_INFO</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This notification is posted when the NORM_INFO content for the
indicated &quot;object&quot; is received.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_RX_OBJECT_UPDATED</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This event indicates that the identified receive &quot;object&quot;
has newly received data content.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_RX_OBJECT_COMPLETED</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This event is posted when a receive object is completely received,
including available NORM_INFO content. Unless the application
specifically retains the &quot;object&quot; handle, the indicated
<FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT> becomes invalid and
must no longer be referenced.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_RX_OBJECT_ABORTED</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This notification is posted when a pending receive object's
transmission is aborted by the remote sender. Unless the
application specifically retains the &quot;object&quot; handle,
the indicated <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT> becomes
invalid and must no longer be referenced.</P>
</TD>
</TR>
<TR>
<TD COLSPAN=2 WIDTH=576 VALIGN=TOP>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<B>Miscellaneous Notification Event Types</B></P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=269>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><I>NORM_EVENT_INVALID</I></FONT></P>
</TD>
<TD WIDTH=293>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This <A HREF="#NormEventType">NormEventType</A> indicates an invalid or &quot;null&quot;
notification which should be ignored.</P>
</TD>
</TR>
</TABLE>
<P CLASS="western" STYLE="font-style: normal"><BR>
</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function generally
blocks the thread of application execution until a <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT>
is available and returns <FONT FACE="Courier"><I>true</I></FONT> when
a <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT> 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
<FONT FACE="Courier"><I>false</I></FONT>.
</P>
<P CLASS="western">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 <FONT FACE="Courier"><I>NORM_RX_OBJECT_UPDATED</I></FONT>
events if undesired)).</P>
<H3 CLASS="functionheading-western"><A NAME="NormGetDescriptor()">NormGetDescriptor()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormDescriptor">NormDescriptor</A>
NormGetDescriptor(<A HREF="#NormInstanceHandle">NormInstanceHandle</A> instance);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function is used
to retrieve a <FONT FACE="Courier"><A HREF="#NormDescriptor">NormDescriptor</A></FONT> (integer
file descriptor (UNIX) or HANDLE (WIN32)) suitable for asynchronous
I/O notification to avoid blocking calls to <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>.
A <FONT FACE="Courier"><A HREF="#NormDescriptor">NormDescriptor</A></FONT> is available for each
protocol engine <U><FONT FACE="Courier">instance</FONT></U>. The
descriptor (or WIN32 HANDLE) is suitable for use as an input (or
&quot;read&quot;) descriptor which is signaled when a NORM protocol
event is ready for retrieval via <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>.
Hence, a call to <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT> will
not block when the descriptor has been signaled. The <I><FONT FACE="Courier">select()</FONT></I>
system call (UNIX) (or <I><FONT FACE="Courier">WaitForMultipleObjects()</FONT></I>
(WIN32)) can be used to detect when the returned <FONT FACE="Courier"><A HREF="#NormDescriptor">NormDescriptor</A></FONT>
is signaled. For the <FONT FACE="Courier">select()</FONT> call
usage, the NORM descriptor should be treated as a &quot;read&quot;
descriptor.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">A descriptor is
returned which is valid until a call to <FONT FACE="Courier"><A HREF="#NormDestroyInstance()">NormDestroyInstance()</A></FONT>
is made. Upon error, a value of <I><FONT FACE="Courier">NORM_DESCRIPTOR_INVALID</FONT></I>
is returned.</P>
<H2 CLASS="western">Session Creation and Control</H2>
<H3 CLASS="functionheading-western"><A NAME="NormCreateSession()">NormCreateSession()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormSessionHandle">NormSessionHandle</A>
NormCreateSession(<A HREF="#NormInstanceHandle">NormInstanceHandle</A>&nbsp;instance,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const
char*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;address,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
short&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;port,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormNodeId">NormNodeId</A>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;localId);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function creates a
NORM reliable multicast session (<I>NormSession</I>) using the
address parameters provided. While session state is allocated and
initialized, active session participation does not begin until a call
is made to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> and/or
<FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT> to join the specified
multicast group (if applicable) and start protocol operation. The
following parameters are required in this function call:</P>
<TABLE WIDTH=590 BORDER=0 CELLPADDING=7 CELLSPACING=0>
<COL WIDTH=101>
<COL WIDTH=461>
<TR VALIGN=TOP>
<TD WIDTH=101>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier">instance</FONT></P>
</TD>
<TD WIDTH=461>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This must be a valid <FONT FACE="Courier"><A HREF="#NormInstanceHandle">NormInstanceHandle</A></FONT>
previously obtained with a call to <FONT FACE="Courier"><A HREF="#NormCreateInstance()">NormCreateInstance()</A></FONT>.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=101>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier">address</FONT></P>
</TD>
<TD WIDTH=461>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
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 <U><FONT FACE="Courier">address</FONT></U>
(along with the <U><FONT FACE="Courier">port</FONT></U> 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 <U><FONT FACE="Courier">address</FONT></U> parameter value
is thus inconsequential for this special case).</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=101>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier">port</FONT></P>
</TD>
<TD WIDTH=461>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This must be a valid, unused port number corresponding to the
desired NORM session address. See the <U><FONT FACE="Courier">address</FONT></U>
parameter description for more details.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=101>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier">localId</FONT></P>
</TD>
<TD WIDTH=461>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
The <FONT FACE="Courier">localId</FONT> parameter specifies the
<FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> that should be used to
identify the application's presence in the <I>NormSession</I>.
All participant's in a <I>NormSession</I> should use unique
<FONT FACE="Courier">localId</FONT> values. The application may
specify a value of <I><FONT FACE="Courier">NORM_NODE_ANY </FONT></I>or
<I><FONT FACE="Courier">NORM_NODE_ANY</FONT></I> for the <FONT FACE="Courier">localId</FONT>
parameter. In this case, the NORM implementation will attempt to
pick an identifier based on the host computer's &quot;default&quot;
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 <I><A HREF="#NormNodeId">NormNodeId</A></I>
collisions. Thus, the application should explicitly specify the
<FONT FACE="Courier">localId</FONT> unless there is a high degree
of confidence that the default IP address will provide a unique
identifier.</P>
</TD>
</TR>
</TABLE>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">The returned
<FONT FACE="Courier"><A HREF="#NormSessionHandle">NormSessionHandle</A></FONT> value is valid until a
call to <FONT FACE="Courier"><A HREF="#NormDestroySession()">NormDestroySession()</A></FONT> is made. A
value of <I><FONT FACE="Courier">NORM_SESSION_INVALID</FONT></I> is
returned upon error.</P>
<H3 CLASS="functionheading-western"><A NAME="NormDestroySession()">NormDestroySession()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormDestroySession(<A HREF="#NormSessionHandle">NormSessionHandle</A> session);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function
immediately terminates the application's participation in the
<I>NormSession</I> identified by the <U><FONT FACE="Courier">session</FONT></U>
parameter and frees any resources used by that session. An exception
to this is that the application is responsible for releasing any
explicitly retained <FONT FACE="Courier">NormObjectHandles</FONT>
(See <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> and
<FONT FACE="Courier"><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT>).</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
returned values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetUserData()">NormSetUserData()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormSetUserData(<A HREF="#NormSessionHandle">NormSessionHandle</A> session, const void* userData);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function allows
the application to attach a value to the previously-created
<I>NormSession</I> instance specified by the <FONT FACE="Courier"><U>session</U></FONT>
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 <FONT FACE="Courier"><U>userData</U></FONT> value can be
later retrieved using the <FONT FACE="Courier"><A HREF="#NormGetUserData()">NormGetUserData()</A></FONT>
function call.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
returned values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormGetUserData()">NormGetUserData()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>const
void* NormGetUserData(<A HREF="#NormSessionHandle">NormSessionHandle</A> session);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function retrieves
the &quot;user data&quot; value set for the specified session with a
prior call to <FONT FACE="Courier"><A HREF="#NormSetUserData()">NormSetUserData()</A></FONT>.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function returns
the user data value set for the specified session. If no user data
value has been previously set a <FONT FACE="Courier"><I>NULL</I></FONT>
(i.e., <FONT FACE="Courier"><I>(const void*)0</I></FONT>) value is
returned.</P>
<H3 CLASS="functionheading-western"><A NAME="NormGetLocalNodeId()">NormGetLocalNodeId()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormNodeId">NormNodeId</A>
NormGetLocalNodeId(<A HREF="#NormSessionHandle">NormSessionHandle</A> session);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function retrieves
the <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> value used for the
application's participation in the <I>NormSession</I> identified by
the <FONT FACE="Courier"><U>session</U></FONT> parameter. The value
may have been explicitly set during the <FONT FACE="Courier"><A HREF="#NormCreateSession()">NormCreateSession()</A></FONT>
call or derived using the host computer's &quot;default&quot; IP
network address.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">The returned value
indicates the <I>NormNode</I> identifier used by the NORM protocol
engine for the local application's participation in the specified
<I>NormSession</I>.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetTxPort()">NormSetTxPort()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormSetTxPort(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
short txPort);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function is used
to force NORM to use a specific port number for UDP packets sent for
the specified <FONT FACE="Courier"><U>session</U></FONT>. By
default, NORM uses separate port numbers for packet transmission and
session packet reception (the receive port is specified as part of
the <FONT FACE="Courier"><A HREF="#NormCreateSession()">NormCreateSession()</A></FONT> 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 <FONT FACE="Courier"><U>session</U></FONT>
receive port.
</P>
<P CLASS="western" STYLE="font-style: normal">Note this call <I>must</I>
be made <I>before</I> any calls to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>
or <FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT> for the given
<FONT FACE="Courier"><U>session</U></FONT> to succeed.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetRxPortReuse()">NormSetRxPortReuse()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormSetRxPortReuse(<A HREF="#NormSessionHandle">NormSessionHandle</A>
session,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bool
state);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function allows
the user to control the port reuse and binding behavior for the
receive socket used for the given NORM <FONT FACE="Courier"><U>session</U></FONT>.
When the <FONT FACE="Courier"><U>state</U></FONT> parameter is set
to <FONT FACE="Courier"><I>true</I></FONT>:</P>
<OL>
<LI><P CLASS="western" STYLE="font-style: normal">Reuse of the
<I>NormSession</I> port number is enabled, and</P>
<LI><P CLASS="western" STYLE="font-style: normal">the underlying
socket is also bound (see the <FONT FACE="Courier">bind()</FONT>
system call) to the <I>NormSession</I> destination address instead
of the default behavior of binding to INADDR_ANY.
</P>
</OL>
<P CLASS="western" STYLE="font-style: normal">The default binding to
INADDR_ANY (<FONT FACE="Courier"><U>state</U></FONT> equals <FONT FACE="Courier"><I>false</I></FONT>)
allows the <I>NormSession</I> receive socket to receive any multicast
or unicast transmissions to the given port number. This allows a
NORM receiver to receive from senders sending to a multicast session
address or the receiver's unicast address. Enabling port reuse and
binding the session destination address allows multiple NORM sessions
on the same port number, but participating in different multicast
groups.</P>
<P CLASS="western" STYLE="font-style: normal">Note this call <I>must</I>
be made <I>before</I> any calls to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>
or <FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT> for the given
<FONT FACE="Courier"><U>session</U></FONT> to succeed.</P>
<P CLASS="western" STYLE="font-style: normal">This call could also be
used in conjunction with <FONT FACE="Courier"><A HREF="#NormSetMulticastInterface()">NormSetMulticastInterface()</A></FONT>
so that multiple <I>NormSessions</I>, using the same port and
multicast address, could separately cover multiple network interfaces
(and some sort of application-layer bridging of reliable multicast
could be realized if desired).</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetMulticastInterface()">NormSetMulticastInterface()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormSetMulticastInterface(<A HREF="#NormSessionHandle">NormSessionHandle</A>
session,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const
char*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;interfaceName);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function specifies
which host network interface is used for IP Multicast transmissions
and group membership. This should be called <I>before</I> any call
to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> or
<FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT> is made so that the
IP multicast group is joined on the proper host interface. However,
if a call to <FONT FACE="Courier"><A HREF="#NormSetMulticastInterface()">NormSetMulticastInterface()</A></FONT>
is made <I>after</I> either of these function calls, the call will
not affect the group membership interface, but only dictate that a
possibly different network interface is used for transmitted NORM
messages. Thus, the code:</P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>NormSetMulticastInterface(session,
&quot;interface1&quot;);<BR>NormStartReceiver(session,
...);<BR>NormSetMulticastInterface(session, &quot;interface2&quot;);</FONT></FONT></P>
<P CLASS="western" STYLE="font-style: normal">will result in NORM
group membership (i.e. multicast reception) being managed on
&quot;interface1&quot; while NORM multicast transmissions are made
via &quot;interface2&quot;.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">A return value of <FONT FACE="Courier"><I>true</I></FONT>
indicates success while a return value of <FONT FACE="Courier"><I>false</I></FONT>
indicates that the specified interface was valid. This function will
always return <FONT FACE="Courier"><I>true</I></FONT> if made before
calls to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> or
<FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT>. However, those
calls may fail if an invalid interface is specified.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetTTL()">NormSetTTL()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormSetTTL(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
char &nbsp;&nbsp;&nbsp;&nbsp;ttl);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function specifies
the time-to-live (<FONT FACE="Courier"><U>ttl</U></FONT>) for IP
Multicast datagrams generated by NORM for the specified <FONT FACE="Courier"><U>session</U></FONT>.
The IP TTL field limits the number of router &quot;hops&quot; 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 &quot;TTL
threshold&quot; values to constrain some multicast traffic to an
administrative boundary. In these cases. the NORM TTL setting must
also exceed the router &quot;TTL threshold&quot; in order for the
NORM traffic to be allowed to exit the administrative area.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">A return value of <FONT FACE="Courier"><I>true</I></FONT>
indicates success while a return value of <FONT FACE="Courier"><I>false</I></FONT>
indicates that the specified <FONT FACE="Courier"><U>ttl</U></FONT>
could not be set. This function will always return <FONT FACE="Courier"><I>true</I></FONT>
if made before calls to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>
or <FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT>. However, those
calls may fail if the desired <FONT FACE="Courier"><U>ttl</U></FONT>
value cannot be set..</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetTOS()">NormSetTOS()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormSetTOS(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
char&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;tos);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function specifies
the type-of-service (<FONT FACE="Courier"><U>tos</U></FONT>) field
value used in IP Multicast datagrams generated by NORM for the
specified <FONT FACE="Courier"><U>session</U></FONT>. The IP TOS
field value can be used as an indicator that a &quot;flow&quot; of
packets may merit special Quality-of-Service (QoS) treatment by
network devices. Users should refer to applicable QoS information
for their network to determine the expected interpretation and
treatment (if any) of packets with explicit TOS marking.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">A return value of <FONT FACE="Courier"><I>true</I></FONT>
indicates success while a return value of <FONT FACE="Courier"><I>false</I></FONT>
indicates that the specified <FONT FACE="Courier"><U>tos</U></FONT>
could not be set. This function will always return <FONT FACE="Courier"><I>true</I></FONT>
if made before calls to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>
or <FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT>. However, those
calls may fail if the desired <FONT FACE="Courier"><U>tos</U></FONT>
value cannot be set..</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetLoopback()">NormSetLoopback()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormSetLoopback(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bool&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;loopbackEnable);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function enables
or disables loopback operation for the indicated NORM <FONT FACE="Courier"><U>session</U></FONT>.
If <FONT FACE="Courier"><U>loopbackEnable</U></FONT> is set to <FONT FACE="Courier"><I>true</I></FONT>,
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 <FONT FACE="Courier"><U>loopbackEnable</U></FONT>
is <FONT FACE="Courier"><I>false</I></FONT>, the application is
prevented from receiving its own NORM message transmissions. By
default, loopback operation is disabled when a <I>NormSession</I> is
created.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H2 CLASS="western">NORM<SPAN STYLE="font-style: normal"> </SPAN>Sender
Functions</H2>
<H3 CLASS="functionheading-western"><A NAME="NormStartSender()">NormStartSender()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormStartSender(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;sessionHandle<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormSessionId">NormSessionId</A>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;sessionId<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
long&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bufferSpace<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
short&nbsp;&nbsp;&nbsp;&nbsp;segmentSize,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
char&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;blockSize,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
char&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;numParity);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">The application's
participation as a sender within a specified <I>NormSession</I>
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 <I>NormEvents</I>. The parameters required for this
function call include:</P>
<TABLE WIDTH=590 BORDER=0 CELLPADDING=7 CELLSPACING=0>
<COL WIDTH=125>
<COL WIDTH=437>
<TR VALIGN=TOP>
<TD WIDTH=125>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><U>sessionHandle</U></FONT></P>
</TD>
<TD WIDTH=437>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This must be a valid <FONT FACE="Courier"><A HREF="#NormSessionHandle">NormSessionHandle</A></FONT>
previously obtained with a call to <FONT FACE="Courier"><A HREF="#NormCreateSession()">NormCreateSession()</A></FONT>.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=125>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><U>sessionId</U></FONT></P>
</TD>
<TD WIDTH=437>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
Application-defined value used as the <I>instance_id</I> 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 <FONT FACE="Courier"><U>sessionId</U></FONT>
values when initiating sender operation. For example, a robust
application could cache previous <FONT FACE="Courier"><U>sessionId</U></FONT>
values in non-volatile storage and gracefully recover (without
confusing receivers) from a total system shutdown and reboot by
using a new <FONT FACE="Courier"><U>sessionId</U></FONT> value
upon restart.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=125>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><U>bufferSpace</U></FONT></P>
</TD>
<TD WIDTH=437>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This specifies the maximum memory space the NORM protocol engine
is allowed to use to buffer any sender calculated FEC segments and
repair state for the session. The optimum <FONT FACE="Courier"><U>bufferSpace</U></FONT>
value is function of the network topology <I>bandwidth*delay</I>
product and packet loss characteristics. If the <FONT FACE="Courier"><U>bufferSpace</U></FONT>
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 <U><FONT FACE="Courier">bufferSpace</FONT></U>
allocation is safer at the expense of possibly committing more
memory resources.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=125>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><U>segmentSize</U></FONT></P>
</TD>
<TD WIDTH=437>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This parameter sets the maximum <I>payload</I> size (in bytes) of
NORM sender messages (<I>not</I> including any NORM message header
fields). A sender's <FONT FACE="Courier">segmentSize</FONT> value
is also used by receivers to limit the payload content of some
feedback messages (e.g. NORM_NACK message content, etc.) generated
in response to that sender. Note different senders within a
<I>NormSession</I> may use different <FONT FACE="Courier">segmentSize</FONT>
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 <FONT FACE="Courier"><U>segmentSize</U></FONT>.
For example, the NORM_DATA message header for a
<I><FONT FACE="Courier">NORM_OBJECT_STREAM</FONT></I> 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 + <FONT FACE="Courier"><U>segmentSize</U></FONT>) bytes.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=125>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><U>blockSize</U></FONT></P>
</TD>
<TD WIDTH=437>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
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 &quot;<I>(n,k)</I>&quot; nomenclature, the <FONT FACE="Courier"><U>blockSize</U></FONT>
value corresponds to <I>&quot;k&quot;.</I> NORM logically
segments transport object data content into coding blocks and the
<FONT FACE="Courier"><U>blockSize</U></FONT> parameter determines
the number of source symbol segments (packets) comprising a single
coding block where each source symbol segment is up to <FONT FACE="Courier"><U>segmentSize</U></FONT>
bytes in length.. A given block's parity symbol segments are
calculated using the corresponding set of source symbol segments.
The maximum <FONT FACE="Courier"><U>blockSize</U></FONT> allowed
by the 8-bit Reed-Solomon codes in NORM is 255, with the further
limitation that (<FONT FACE="Courier"><U>blockSize</U></FONT> +
<FONT FACE="Courier"><U>numParity</U></FONT>) ≤ 255.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=125>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
<FONT FACE="Courier"><U>numParity</U></FONT></P>
</TD>
<TD WIDTH=437>
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
This parameter sets the maximum number of parity symbol segments
(packets) the sender is willing to <I>calculate</I> per FEC coding
block. The parity symbol segments for a block are calculated from
the corresponding <FONT FACE="Courier"><U>blockSize</U></FONT>
source symbol segments. In the &quot;<I>(n,k)&quot;</I>
nomenclature mention above, the <FONT FACE="Courier"><U>numParity</U></FONT>
value corresponds to &quot;<I>n-k</I>&quot;. 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 <FONT FACE="Courier"><U>blockSize</U></FONT>,
the maximum <FONT FACE="Courier"><U>numParity</U></FONT> value is
(255 – <FONT FACE="Courier"><U>blockSize</U></FONT>). However,
note that computational complexity increases significantly with
increasing <FONT FACE="Courier"><U>numParity</U></FONT> values and
applications may wish to be conservative with respect to <FONT FACE="Courier"><U>numParity</U></FONT>
selection, given anticipated network packet loss conditions and
group size scalability concerns. Additional FEC code options may
be provided for this NORM implementation in the future with
different parameters, capabilities, trade-offs, and computational
requirements.</P>
</TD>
</TR>
</TABLE>
<P CLASS="western" STYLE="font-style: normal">These parameters are
currently immutable with respect to a sender's participation within a
<I>NormSession</I>. Sender operation must be stopped (see
<FONT FACE="Courier"><A HREF="#NormStopSender()">NormStopSender()</A></FONT>) and restarted with
another call to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> 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 &quot;<I>sessionId</I>&quot; field may
possibly be leveraged to permit a node to establish multiple virtual
presences as a sender within a <I>NormSession</I> 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 <I>NormSession</I>.
Again, this extended functionality is not yet supported in this
implementation.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">A value of <FONT FACE="Courier"><I>true</I></FONT>
is returned upon success and <FONT FACE="Courier"><I>false</I></FONT>
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. <I>(TBD – Provide a
<FONT FACE="Courier">NormGetError(<A HREF="#NormSessionHandle">NormSessionHandle</A> session)</FONT>
function to retrieve a more specific error indication for this and
other functions.)</I></P>
<H3 CLASS="functionheading-western"><A NAME="NormStopSender()">NormStopSender()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormStopSender(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bool&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;graceful
= false);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function
terminates the application's participation in a <I>NormSession</I> as
a sender. By default, the sender will immediately exit the session
without notifying the receiver set of its intention. However a
&quot;graceful shutdown&quot; option is provided to terminate sender
operation gracefully, notifying the receiver set its pending exit
with appropriate protocol messaging. A <I><A HREF="#NormEvent">NormEvent</A></I>,
<FONT FACE="Courier"><I>NORM_LOCAL_SERVER_CLOSED,</I></FONT> is
dispatched when the graceful shutdown process has completed.</P>
<P CLASS="western" STYLE="font-style: normal"><I>(NOTE: The
&quot;</I><FONT FACE="Courier"><U><I>graceful</I></U></FONT><I>&quot;
parameter is currently not available, and the current behavior of
this API call corresponds to the default behavior of </I><FONT FACE="Courier"><U><I>graceful</I></U></FONT><I>
= </I><FONT FACE="Courier"><SPAN STYLE="font-style: normal">false</SPAN></FONT><I>).
The functionality described here will soon be supported in the API.</I></P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetTransmitRate()">NormSetTransmitRate()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormSetTransmitRate(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;rate);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function sets the
transmission rate limit (in bits per second (bps)) used for
<I>NormSender</I> transmissions. For fixed-rate transmission of
<FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT> or
<FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>, this limit
determines the data rate at which NORM protocol messages and data
content. For <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>
transmissions, this is the maximum rate allowed for transmission.
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
<FONT FACE="Courier"><A HREF="#NormSetCongestionControl()">NormSetCongestionControl()</A></FONT>), the rate set
here will be set, but congestion control operation may quickly
readjust the rate unless disabled.
</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetTxSocketBuffer()">NormSetTxSocketBuffer()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormSetTxSocketBuffer(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
int&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bufferSize);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function can be
used to set a non-default socket buffer size for the UDP socket used
by the specified NORM <FONT FACE="Courier"><U>session</U></FONT> for
data transmission. The <FONT FACE="Courier"><U>bufferSize</U></FONT>
parameter specifies the desired socket buffer size in bytes. Large
transmit socket buffer sizes may be necessary to achieve high
throughput 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
sustained high data rate reception (see <FONT FACE="Courier"><A HREF="#NormSetRxSocketBuffer()">NormSetRxSocketBuffer()</A></FONT>).
</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function returns
<FONT FACE="Courier"><I>true</I></FONT> upon success and <FONT FACE="Courier"><I>false</I></FONT>
upon failure. Possible failure modes include an invalid session
parameter, a call to <FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT>
or <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> has not yet been
made for the session, or an invalid <FONT FACE="Courier"><U>bufferSize</U></FONT>
was given. Note some operating systems may require additional
configuration to use non-standard socket buffer sizes.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetCongestionControl()">NormSetCongestionControl()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormSetTransmitRate(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bool&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;enable);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function enables
(or disables) the NORM sender congestion control operation for the
session designated by the <FONT FACE="Courier"><U>session</U></FONT>
parameter. For best operation, this function should be called before
the call to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> is made,
but congestion control operation can be dynamically enabled/disabled
during the course of sender operation. If the value of <FONT FACE="Courier"><U>enable</U></FONT>
is <FONT FACE="Courier"><I>true</I></FONT>, congestion control
operation is enabled while it is disabled for <FONT FACE="Courier"><U>enable</U></FONT>
equal to <FONT FACE="Courier"><I>false</I></FONT>. 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 <FONT FACE="Courier"><A HREF="#NormSetTransmitRateBounds()">NormSetTransmitRateBounds()</A></FONT>)
the rate adjustment will remain within any set bounds. The rate set
by <FONT FACE="Courier"><A HREF="#NormSetTransmitRate()">NormSetTransmitRate()</A></FONT> has no effect
when congestion control operation is enabled. NORM's congestion
algorithm provides rate adjustment to fairly compete for available
network bandwidth with other TCP, NORM, or similarly governed traffic
flows.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetTransmitRateBounds()">NormSetTransmitRateBounds()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormSetTransmitRateBounds(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;rateMin,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;rateMax);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function sets the
range of sender transmission rates within which the NORM congestion
control algorithm is allowed to operate. 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
<FONT FACE="Courier"><U>rateMin</U></FONT> corresponds to the minimum
transmission rate (bps) and <FONT FACE="Courier"><U>rateMax</U></FONT>
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 &quot;<FONT FACE="Courier">NormSetTransmitRate(</FONT><FONT FACE="Courier"><U>session</U></FONT><FONT FACE="Courier">,
</FONT><FONT FACE="Courier"><I>-1.0</I></FONT><FONT FACE="Courier">,
</FONT><FONT FACE="Courier"><I>64000.0</I></FONT><FONT FACE="Courier">)</FONT>&quot;
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<FONT FACE="Courier">
<A HREF="#NormSetCongestionControl()">NormSetCongestionControl()</A></FONT>). If the current congestion
control rate falls outside of the specified bounds, the sender
transmission rate will be adjusted to stay within the set bounds.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function returns
<FONT FACE="Courier"><I>true</I></FONT> upon success. If both
<FONT FACE="Courier"><U>rateMin</U></FONT> and <FONT FACE="Courier"><U>rateMax</U></FONT>
are greater than or equal to zero, but (<FONT FACE="Courier"><U>rateMax</U></FONT>
&lt; <FONT FACE="Courier"><U>rateMin</U></FONT>), the rate bounds
will remain unset or unchanged and the function will return <FONT FACE="Courier"><I>false</I></FONT>.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetTransmitCacheBounds()">NormSetTransmitCacheBounds()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><A NAME="OLE_LINK1"></A>
<FONT FACE="Courier"><FONT SIZE=2>void
NormSetTransmitCacheBounds(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormSize">NormSize</A>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;sizeMax,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
int&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;countMin,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
int&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;countMax);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">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 NORM_TX_QUEUE_EMPTY notifications. This can allow more time for
receivers suffering degraded network conditions to make repair
requests before the sender &quot;purges&quot; older objects from its
&quot;transmit cache&quot; when new objects are enqueued. A
NORM_TX_OBJECT_PURGED notification is issued when the enqueuing of a
new transmit object causes the NORM transmit cache to overflow,
indicating the NORM sender no longer needs to reference the
designated old transmit object and the application is free to release
related resources as needed.
</P>
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><U>sizeMax</U></FONT>
parameter sets the maximum total size, in bytes, of enqueued objects
allowed, providing the constraints of the <FONT FACE="Courier"><U>countMin</U></FONT>
and <FONT FACE="Courier"><U>countMax</U></FONT> parameters are met.
The <FONT FACE="Courier"><U>countMin</U></FONT> parameter sets the
minimum number of objects the application may enqueue, regardless of
the objects' sizes and the <FONT FACE="Courier"><U>sizeMax</U></FONT>
value. For example, the default <FONT FACE="Courier"><U>sizeMax</U></FONT>
value is 20 Mbyte and the default <FONT FACE="Courier"><U>countMin</U></FONT>
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 <FONT FACE="Courier"><U>countMax</U></FONT>
parameter sets a ceiling on how many objects may be enqueued,
regardless of their total sizes with respect to the <FONT FACE="Courier"><U>sizeMax</U></FONT>
setting. For example, the default <FONT FACE="Courier"><U>countMax</U></FONT>
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. <I>Note that </I><FONT FACE="Courier"><U><I>countMax</I></U></FONT><I>
must be greater than or equal to </I><FONT FACE="Courier"><U><I>countMin</I></U></FONT><I>
and </I><FONT FACE="Courier"><U><I>countMin</I></U></FONT><I> is
recommended to be at least two.</I></P>
<P CLASS="western" STYLE="font-style: normal">Note that in the case
of NORM_OBJECT_FILE 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 <FONT FACE="Courier"><U>countMax</U></FONT>
value accordingly. In other cases, a large <FONT FACE="Courier"><U>countMin</U></FONT>
or <FONT FACE="Courier"><U>countMax</U></FONT> 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 &quot;group
join&quot; policies that would allow the receivers to request
transmission of cached content.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return value.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetAutoParity()">NormSetAutoParity()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormSetAutoParity(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;sessionHandle,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
char&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;autoParity);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function sets the
quantity of proactive &quot;auto parity&quot; NORM_DATA messages sent
at the end of each FEC coding block. By default (i.e., <FONT FACE="Courier"><U>autoParity</U></FONT>
= 0), FEC content is sent <I>only</I> in response to repair requests
(NACKs) from receivers. But, by setting a non-zero value for
<FONT FACE="Courier"><U>autoParity</U></FONT>, the sender can
automatically accompany each coding block of transport object source
data segments (NORM_DATA messages) with the set number of FEC
segments. The number of source symbol messages (segments) per FEC
coding block is determined by the <FONT FACE="Courier"><U>blockSize</U></FONT>
parameter used when <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> was
called for the given <FONT FACE="Courier"><U>sessionHandle</U></FONT>.</P>
<P CLASS="western" STYLE="font-style: normal">The use of
proactively-sent &quot;auto parity&quot; may eliminate the need for
any receiver NACKing to achieve reliable transfer in networks with
low packet loss. However, note that the quantity of &quot;auto
parity&quot; 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 &quot;auto parity&quot; may allow
lower latency in the reliable delivery process. Also, its use may
contribute to a smaller amount of receiver feedback as only receivers
with exceptional packet loss may need to NACK for additional repair
content.</P>
<P CLASS="western" STYLE="font-style: normal">The value of <FONT FACE="Courier"><U>autoParity</U></FONT>
set must be less than or equal to the <FONT FACE="Courier"><U>numParity</U></FONT>
parameter set when <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> was
called for the given <FONT FACE="Courier"><U>sessionHandle</U></FONT>.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetGrttEstimate()">NormSetGrttEstimate()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormSetGrttEstimate(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;grtt);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function sets the
sender's estimate of group round-trip timing (GRTT) for the given
NORM <FONT FACE="Courier"><U>session</U></FONT>. This function is
expected to most typically used to initialize the sender's GRTT
estimate prior to the call to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>
when the application has <I>a priori</I> 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 <FONT FACE="Courier">NormSetGrttProbing()</FONT>).
The <FONT FACE="Courier"><U>grtt</U></FONT> value will be limited to
the maximum GRTT as set (see <FONT FACE="Courier"><A HREF="#NormSetGrttMax()">NormSetGrttMax()</A>)
</FONT>or the default maximum of 10 seconds.
</P>
<P CLASS="western" STYLE="font-style: normal">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 <I>delay*bandwidth</I> product for the protocol and
potentially requiring more buffer space to maintain reliability). An
overly-small GRTT estimate may introduce the potential for feedback
implosion, limiting the scalability of group size.
</P>
<P CLASS="western" STYLE="font-style: normal">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.,
<FONT FACE="Courier">1/txRate</FONT>). This maintains the “event
driven” nature of the NORM protocol with respect to receiver
reception of NORM sender data and commands.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetGrttMax()">NormSetGrttMax()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormSetGrttMax(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;grttMax);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function sets the
sender's maximum advertised GRTT value for the given NORM <FONT FACE="Courier"><U>session</U></FONT>.
The <FONT FACE="Courier"><U>grttMax</U></FONT> parameter, in units
of <I>seconds</I>, 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
<FONT FACE="Courier"><A HREF="#NormSetGrttEstimate()">NormSetGrttEstimate()</A></FONT> function
description for the purpose of the NORM GRTT measurement process.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetGrttProbingMode()">NormSetGrttProbingMode()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormSetGrttProbingMode(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NormProbingMode&nbsp;&nbsp;&nbsp;probingMode);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function sets the
sender's mode of probing for round trip timing measurement responses
from the receiver set for the given NORM <FONT FACE="Courier"><U>session</U></FONT>.
Possible values for the <FONT FACE="Courier"><U>probingMode</U></FONT>
parameter include <FONT FACE="Courier"><I>NORM_PROBE_NONE</I></FONT>,
<FONT FACE="Courier"><I>NORM_PROBE_PASSIVE</I></FONT>, and
<FONT FACE="Courier"><I>NORM_PROBE_ACTIVE</I></FONT>. The default
probing mode is <FONT FACE="Courier"><I>NORM_PROBE_ACTIVE</I></FONT>.
In this mode, the receiver set explicitly acknowledges NORM sender
GRTT probes (NORM_CMD(CC) messages) with NORM_ACK responses that are
group-wise suppressed. Note that NORM receivers also will include
their response to GRTT probing piggy-backed on any NORM_NACK messages
sent in this mode as well to minimize feedback.
</P>
<P CLASS="western" STYLE="font-style: normal">Note that the
<FONT FACE="Courier"><I>NORM_PROBE_ACTIVE</I></FONT> probing mode is
<I>required</I> and automatically set when NORM congestion control
operation is enabled (see <FONT FACE="Courier"><A HREF="#NormSetCongestionControl()">NormSetCongestionControl()</A></FONT>).
Thus, when congestion control is enabled, the
<FONT FACE="Courier"><A HREF="#NormSetGrttProbingMode()">NormSetGrttProbingMode()</A></FONT> function has no
effect.</P>
<P CLASS="western" STYLE="font-style: normal">If congestion control
operation is not enabled, the NORM applicaiton may elect to reduce
the volume of feedback traffic by setting the <FONT FACE="Courier"><U>probingMode</U></FONT>
to <FONT FACE="Courier"><I>NORM_PROBE_PASSIVE.</I></FONT> Here, the
NORM sender still transmits NORM_CMD(CC) probe messages multiplexed
with its data transmission, but the receiver set does not explicitly
acknowledge these probes. Instead the receiver set is limited to
piggy-backing responses when NORM_NACK messages are generated. Note
that this may, in some cases, introduce some opportunity for bursts
of large volume receiver feedback when the sender’s estimate of
GRTT is incorrect due to the reduced probing feedback. But, in some
controlled network environments, this option for passive probing may
provide some benefits in reducing protocol overhead.</P>
<P CLASS="western" STYLE="font-style: normal">Finally, the
<FONT FACE="Courier"><U>probingMode</U></FONT> can be set to
<FONT FACE="Courier"><I>NORM_PROBE_NONE</I></FONT> 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 <FONT FACE="Courier"><A HREF="#NormSetGrttEstimate()">NormSetGrttEstimate()</A></FONT> function.
See this function for a description of the purpose of the NORM GRTT
measurement.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetGrttProbingInterval()">NormSetGrttProbingInterval()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormSetGrttProbingInterval(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;intervalMin,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;intervalMax);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function controls
the sender GRTT measurement and estimation process for the given NORM
<FONT FACE="Courier"><U>session</U></FONT>. The NORM sender
multiplexes periodic transmission of NORM_CMD(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 <FONT FACE="Courier"><U>intervalMin</U></FONT>
and <FONT FACE="Courier"><U>intervalMax</U></FONT> parameters (in
units of <I>seconds</I>) control the rate at which the sender’s
estimate of GRTT is updated. At session start, the estimate is
updated at <FONT FACE="Courier"><U>intervalMin</U></FONT> and the
update interval time is doubled until <FONT FACE="Courier"><U>intervalMax</U></FONT>
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
(NORM_PROBE_ACTIVE or NORM_PROBE_PASSIVE) the <FONT FACE="Courier"><U>intervalMin</U></FONT>
and <FONT FACE="Courier"><U>intervalMax</U></FONT> values also
determine the rate at which NORM_CMD(CC) probes are transmitted by
the sender. Thus by setting larger values for <FONT FACE="Courier"><U>intervalMin</U></FONT>
and <FONT FACE="Courier"><U>intervalMax</U></FONT>, the NORM sender
application can reduce the overhead of the GRTT measurement process.
However, this also reduces the ability of NORM to adapt to changes in
GRTT.</P>
<P CLASS="western" STYLE="font-style: normal">The default NORM GRTT
<FONT FACE="Courier"><U>intervalMin</U></FONT> and <FONT FACE="Courier"><U>intervalMax</U></FONT>
values are 1.0 second and 30.0 seconds, respectively.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormAddAckingNode()">NormAddAckingNode()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormAddAckingNode(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormNodeId">NormNodeId</A>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;nodeId);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">When this function is
called, the specified <FONT FACE="Courier"><U>nodeId</U></FONT> is
added to the list of <I>NormNodes</I> used when NORM sender operation
performs positive acknowledgement (ACK) collection for the specified
<FONT FACE="Courier"><U>session</U></FONT>. The optional NORM
positive acknowledgement collection occurs when a specified
transmission point (see <FONT FACE="Courier"><A HREF="#NormSetWatermark()">NormSetWatermark()</A>)</FONT>
is reached or for specialized protocol actions such as
positively-acknowledged application-defined commands (<I>TBD</I>).</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">The function returns
<FONT FACE="Courier"><I>true</I></FONT> upon success and <FONT FACE="Courier"><I>false</I></FONT>
upon failure. The only failure condition is that insufficient memory
resources were available. If a specific <FONT FACE="Courier"><U>nodeId</U></FONT>
is added more than once, this has no effect.</P>
<H3 CLASS="functionheading-western"><A NAME="NormRemoveAckingNode()">NormRemoveAckingNode()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormRemoveAckingNode(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormNodeId">NormNodeId</A>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;nodeId);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function deletes
the specified <FONT FACE="Courier"><U>nodeId</U></FONT> from the list
of <I>NormNodes</I> used when NORM sender operation performs positive
acknowledgement (ACK) collection for the specified <FONT FACE="Courier"><U>session</U></FONT>.
</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">The function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormFileEnqueue()">NormFileEnqueue()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormObjectHandle">NormObjectHandle</A>
NormFileEnqueue(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const
char*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;filename,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const
char*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;infoPtr =
NULL,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
int&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;infoLen = 0);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function enqueues
a file for transmission within the specified NORM <FONT FACE="Courier"><U>session</U></FONT>.
Note that <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> must have
been previously called before files or any transport objects may be
enqueued and transmitted. The <FONT FACE="Courier"><U>fileName</U></FONT>
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
&quot;repair window&quot; 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 <FONT FACE="Courier"><U>infoPtr</U></FONT> and <FONT FACE="Courier"><U>infoLen</U></FONT>
parameters are used to associate NORM_INFO content with the sent
transport object. The maximum allowed <FONT FACE="Courier"><U>infoLen</U></FONT>
corresponds to the <FONT FACE="Courier"><U>segmentSize</U></FONT>
used in the prior call to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>.
The use and interpretation of the NORM_INFO content is left to the
application's discretion. Example usage of NORM_INFO content for
<FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT> might include
file name, creation date, MIME-type or other information which will
enable NORM receivers to properly handle the file when reception is
complete.</P>
<P CLASS="western" STYLE="font-style: normal">The application is
allowed to enqueue multiple transmit objects within in the &quot;transmit
cache&quot; limits (see <FONT FACE="Courier">NormSetTxCacheLimits()</FONT>)
and enqueued objects are transmitted (and repaired as needed) within
the limits determined by automated congestion control (see
<FONT FACE="Courier"><A HREF="#NormSetCongestionControl()">NormSetCongestionControl()</A></FONT>) or fixed rate
(see <FONT FACE="Courier">NormSetTxRate()</FONT>) parameters.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">A <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>
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 <FONT FACE="Courier"><A HREF="#NormObjectCancel()">NormObjectCancel()</A></FONT>)
or a <FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT> event
is received for the given object. Note the application may use the
<FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> method if it wishes to
refer to the object after the <FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT>
notification. In this case, the application, when finished with the
object, must use <FONT FACE="Courier"><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT> to
free any resources used or else a memory leak condition will result.
A value of <FONT FACE="Courier"><I>NORM_OBJECT_INVALID</I></FONT> is
return upon error. Possible failure conditions include the specified
<FONT FACE="Courier"><U>session</U></FONT> is not operating as a
<I>NormSender</I>, insufficient memory resources were available, or
the &quot;transmit cache&quot; limits have been reached and all
previously enqueued NORM transmit objects are pending transmission.
Also the call will fail if the <FONT FACE="Courier"><U>infoLen</U></FONT>
parameter exceeds the local <I>NormSender</I> <FONT FACE="Courier"><U>segmentSize</U></FONT>
limit.</P>
<H3 CLASS="functionheading-western"><A NAME="NormDataEnqueue()">NormDataEnqueue()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormObjectHandle">NormObjectHandle</A>
NormDataEnqueue(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const
char*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;dataPtr,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
int&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;dataLen,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const
char*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;infoPtr =
NULL,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
int&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;infoLen = 0);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function enqueues
a segment of application memory space for transmission within the
specified NORM <FONT FACE="Courier"><U>session</U></FONT>. Note that
<FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> must have been
previously called before files or any transport objects may be
enqueued and transmitted. The <FONT FACE="Courier"><U>dataPtr</U></FONT>
parameter must be a valid pointer to the area of application memory
to be transmitted and the <FONT FACE="Courier"><U>dataLen</U></FONT>
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 protocel engine
may access this area. The optional <FONT FACE="Courier"><U>infoPtr</U></FONT>
and <FONT FACE="Courier"><U>infoLen</U></FONT> parameters are used to
associate NORM_INFO content with the sent transport object. The
maximum allowed <FONT FACE="Courier"><U>infoLen</U></FONT>
corresponds to the <FONT FACE="Courier"><U>segmentSize</U></FONT>
used in the prior call to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>.
The use and interpretation of the NORM_INFO content is left to the
application's discretion. Example usage of NORM_INFO content for
<FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT> might include
application-defined data typing or other information which will
enable NORM receiver applications to properly interpret the received
data when reception is complete. Of course, it is possible that the
application may embed such typing information in the object data
content itself. This is left to the application's discretion.</P>
<P CLASS="western" STYLE="font-style: normal">The application is
allowed to enqueue multiple transmit objects within in the &quot;transmit
cache&quot; limits (see <FONT FACE="Courier">NormSetTxCacheLimits()</FONT>)
and enqueued objects are transmitted (and repaired as needed) within
the limits determined by automated congestion control (see
<FONT FACE="Courier"><A HREF="#NormSetCongestionControl()">NormSetCongestionControl()</A></FONT>) or fixed rate
(see <FONT FACE="Courier">NormSetTxRate()</FONT>) parameters.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">A <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>
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 <FONT FACE="Courier"><A HREF="#NormObjectCancel()">NormObjectCancel()</A></FONT>)
or a <FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT> event
is received for the given object. Note the application may use the
<FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> method if it wishes to
refer to the object after the <FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT>
notification. In this case, the application, when finished with the
object, <I>must</I> use <FONT FACE="Courier"><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT>
to free any resources used or else a memory leak condition will
result. A value of <FONT FACE="Courier"><I>NORM_OBJECT_INVALID</I></FONT>
is return upon error. Possible failure conditions include the
specified <FONT FACE="Courier"><U>session</U></FONT> is not operating
as a <I>NormSender</I>, insufficient memory resources were available,
or the &quot;transmit cache&quot; limits have been reached and all
previously enqueued NORM transmit objects are pending transmission.
Also the call will fail if the <FONT FACE="Courier"><U>infoLen</U></FONT>
parameter exceeds the local <I>NormSender</I> <FONT FACE="Courier"><U>segmentSize</U></FONT>
limit.</P>
<H3 CLASS="functionheading-western"><A NAME="NormStreamOpen()">NormStreamOpen()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormObjectHandle">NormObjectHandle</A>
NormStreamOpen(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
int&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bufferSize,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const
char*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;infoPtr =
NULL,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
int&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;infoLen = 0);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function opens a
<FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT> sender object
and enqueues it for transmission within the indicated <FONT FACE="Courier"><U>session</U></FONT>.
NormStream objects 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 <FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT>
are made unless NORM_INFO content is specified for the stream with
the <FONT FACE="Courier"><U>infoPtr</U></FONT> and <FONT FACE="Courier"><U>infoLen</U></FONT>
parameters. Example usage of NORM_INFO content for <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>
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
<FONT FACE="Courier"><U>bufferSize</U></FONT> parameter controls the
size of the stream's &quot;repair window&quot; which limits how far
back the sender will &quot;rewind&quot; to satisfy receiver repair
requests.
</P>
<P CLASS="western" STYLE="font-style: normal">NORM, as a
NACK-oriented protocol, currently lacks a mechanism for receivers to
<I>explicitly</I> feedback flow control status to the sender unless
the sender leverages NORM's optional positive acknowledgement (ACK)
features. Thus, the <FONT FACE="Courier"><U>bufferSize</U></FONT>
selection plays an important role in NORM's reliability. Generally,
a larger <FONT FACE="Courier"><U>bufferSize</U></FONT> 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 <FONT FACE="Courier"><U>bufferSize</U></FONT> to avoid the
potential for large latency in data delivery. 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 data transport). Note that NORM receivers can
&quot;resync&quot; to the sender after such breaks if the application
leverages the message boundary recovery features of NORM (see
<FONT FACE="Courier"><A HREF="#NormStreamMarkEom()">NormStreamMarkEom()</A></FONT>).</P>
<P CLASS="western" STYLE="font-style: normal">Note that the current
implementation of NORM is designed to support only one active stream
per session, and that any <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>
or <FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT> objects
enqueued for transmission will not begin transmission until an active
stream is closed. Applications requiring multiple streams or
concurrent file/data transfer should instantiate multiple
<I>NormSessions</I> as needed.</P>
<P CLASS="western" STYLE="font-style: normal">Note there is no
corresponding &quot;open&quot; call for receiver streams. Receiver
<FONT FACE="Courier"><I>NORM_OBJECT_STREAMs</I></FONT> are
automatically opened by the NORM protocol engine and the receiver
applications is notified of new streams via the <FONT FACE="Courier"><I>NORM_RX_OBJECT_NEW</I></FONT>
notification (see <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>).</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">A <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>
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 <FONT FACE="Courier"><A HREF="#NormObjectCancel()">NormObjectCancel()</A></FONT>)
or a <FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT> event
is received for the given object. Note the application may use the
<FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> method if it wishes to
refer to the object after the <FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT>
notification. In this case, the application, when finished with the
object, <I>must</I> use <FONT FACE="Courier"><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT>
to free any resources used or else a memory leak condition will
result. A value of <FONT FACE="Courier"><I>NORM_OBJECT_INVALID</I></FONT>
is return upon error. Possible failure conditions include the
specified <FONT FACE="Courier"><U>session</U></FONT> is not operating
as a <I>NormSender</I>, insufficient memory resources were available,
or the &quot;transmit cache&quot; limits have been reached and all
previously enqueued NORM transmit objects are pending transmission.
Also the call will fail if the <FONT FACE="Courier"><U>infoLen</U></FONT>
parameter exceeds the local <I>NormSender</I> <FONT FACE="Courier"><U>segmentSize</U></FONT>
limit.</P>
<H3 CLASS="functionheading-western"><A NAME="NormStreamClose()">NormStreamClose()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormStreamClose(<A HREF="#NormObjectHandle">NormObjectHandle</A>
streamHandle,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bool&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;graceful
= false);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function halts
transfer of the stream specified by the <FONT FACE="Courier"><U>streamHandle</U></FONT>
parameter and releases any resources used unless the associated
object has been explicitly retained by a call to <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT>.
No further calls to <FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT>
will be successful for the given <FONT FACE="Courier"><U>streamHandle</U></FONT>.
The optional <FONT FACE="Courier"><U>graceful</U></FONT> parameter,
when set to a value of <FONT FACE="Courier"><I>true</I></FONT>, may
be used by NORM senders to initiate &quot;graceful&quot; shutdown of
a transmit stream. In this case, the sender application will be
notified that stream has (most likely) completed reliable transfer
via the <FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT>
notification upon completion of the graceful shutdown process. When
the <FONT FACE="Courier"><U>graceful</U></FONT> option is set,
receivers are notified of the stream end via a &quot;FLAG_STREAM_END&quot;
flag in NORM_DATA message (<I>Note the NRL NORM implementation uses a
portion of the </I><FONT FACE="Courier"><I>NORM_DATA::payload_reserved</I></FONT><I>
field for this purpose and proposes that this type of funtionality be
added to subsequent versions of the NORM protocol specification</I>)
and will receive a <FONT FACE="Courier"><I>NORM_RX_OBJECT_COMPLETED</I></FONT>
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
<FONT FACE="Courier"><A HREF="#NormObjectCancel()">NormObjectCancel()</A></FONT> routine and may be
used for sender or receiver streams. So, it is expected this
function (<FONT FACE="Courier"><A HREF="#NormStreamClose()">NormStreamClose()</A></FONT>) will
typically be used for transmit streams by NORM senders.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormStreamWrite()">NormStreamWrite()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>unsigned
int
NormStreamWrite(<A HREF="#NormObjectHandle">NormObjectHandle</A>&nbsp;streamHandle<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const
char*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;buffer,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
int&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;numBytes);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function enqueues
data for transmission within the NORM stream specified by the
<FONT FACE="Courier"><U>streamHandle</U></FONT> parameter. The
<FONT FACE="Courier"><U>buffer</U></FONT> parameter must be a pointer
to the data to be enqueued and the <FONT FACE="Courier"><U>numBytes</U></FONT>
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 &quot;push mode&quot; is set to <FONT FACE="Courier"><I>false</I></FONT>
(default, see <FONT FACE="Courier">NormStreamSetPushMode()</FONT> for
details). If the stream's &quot;push mode&quot; is set to true, a
call to <FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT> 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.
</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function returns
the number of bytes of data successfully enqueued for NORM stream
transmission.</P>
<H3 CLASS="functionheading-western"><A NAME="NormStreamFlush()">NormStreamFlush()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormStreamFlush(<A HREF="#NormObjectHandle">NormObjectHandle</A>
streamHandle,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bool&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;eom
= false,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormFlushMode">NormFlushMode</A>&nbsp;&nbsp;&nbsp;&nbsp;flushMode
= NORM_FLUSH_PASSIVE);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function causes an
immediate &quot;flush&quot; of the transmit stream specified by the
<FONT FACE="Courier"><U>streamHandle</U></FONT> parameter. Normally,
unless <FONT FACE="Courier">NormSetAutoFlush()</FONT> has been
invoked, the NORM protocol engine buffers data written to a stream
until it has accumulated a sufficient quantity to generate a
NORM_DATA message with a full payload (as designated by the
<FONT FACE="Courier"><U>segmentSize</U></FONT> parameter of the
<FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> 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 &quot;flush&quot; operation invoked via
<FONT FACE="Courier"><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT> for <FONT FACE="Courier"><U>flushMode</U></FONT>
equal to <FONT FACE="Courier"><I>NORM_FLUSH_PASSIVE</I></FONT> causes
NORM to immediately transmit all enqueued data for the stream
(subject to session transmit rate limits), even if this results in
NORM_DATA messages with &quot;small&quot; payloads. If the optional
<FONT FACE="Courier"><U>flushMode</U></FONT> parameter is set to
<FONT FACE="Courier"><I>NORM_FLUSH_ACTIVE</I></FONT>, 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, <I>actively</I> transmits NORM_CMD(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 &quot;active&quot; flush activity will be
terminated upon the next subsequent write to the stream. If
<FONT FACE="Courier"><U>flushMode</U></FONT> is set to
<FONT FACE="Courier"><I>NORM_FLUSH_NONE</I></FONT>, this call has no
effect other than the optional end-of-message marking described here.</P>
<P CLASS="western" STYLE="font-style: normal">The optional <FONT FACE="Courier"><U>eom</U></FONT>
parameter, when set to <FONT FACE="Courier"><I>true</I></FONT>,
allows the sender application to mark an end-of-message indication
(see <FONT FACE="Courier"><A HREF="#NormStreamMarkEom()">NormStreamMarkEom()</A></FONT>) for the stream
and initiate flushing in a single function call. The end-of-message
indication causes NORM to mark the first NORM_DATA message generated
following a subsequent write to the stream with the
NORM_FLAGS_MSG_START flag. This mechanism provide a means for
message boundary recovery when receivers join or re-sync to a sender
mid-stream.</P>
<P CLASS="western" STYLE="font-style: normal">Note that frequent
flushing, particularly for <FONT FACE="Courier"><I>NORM_FLUSH_ACTIVE</I></FONT>
operation, may result in more NORM protocol activity than usual, so
care must be taken in application design and deployment when
scalability to large group sizes is expected.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormStreamSetAutoFlush()">NormStreamSetAutoFlush()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormStreamSetAutoFlush(<A HREF="#NormObjectHandle">NormObjectHandle</A>
streamHandle<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormFlushMode">NormFlushMode</A>&nbsp;&nbsp;&nbsp;&nbsp;flushMode);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function sets
&quot;<I>automated</I> flushing&quot; for the NORM transmit stream
indicated by the <FONT FACE="Courier"><U>streamHandle</U></FONT>
parameter. By default, a NORM transmit stream is &quot;flushed&quot;
only when explicitly requested by the application (see
<FONT SIZE=2><FONT FACE="Courier"><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT></FONT>).
However, to simplify programming, the NORM API allows that automated
flushing be enabled such that the &quot;flush&quot; operation occurs
every time the <I>full</I> requested <FONT FACE="Courier"><U>buffer</U></FONT>
provided to a <FONT SIZE=2><FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT></FONT>
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 &quot;chatty&quot; than its typical &quot;bulk
transfer&quot; form of operation, but can provide a useful capability
for some applications.
</P>
<P CLASS="western" STYLE="font-style: normal">Possible values for the
<FONT FACE="Courier"><U>flushMode</U></FONT> parameter include
<FONT FACE="Courier"><I>NORM_FLUSH_NONE</I></FONT>,
<FONT FACE="Courier"><I>NORM_FLUSH_PASSIVE</I></FONT>, and
<FONT FACE="Courier"><I>NORM_FLUSH_ACTIVE</I></FONT>. The default
setting for a NORM stream is <FONT FACE="Courier"><I>NORM_FLUSH_NONE</I></FONT>
where no flushing occurs unless explicitly requested via
<FONT SIZE=2><FONT FACE="Courier"><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT></FONT>.
By setting the automated <FONT FACE="Courier"><U>flushMode</U></FONT>
to <FONT FACE="Courier"><I>NORM_FLUSH_PASSIVE</I></FONT>, the only
action taken is to immediately transmit any data that has been
written to the stream, even if &quot;runt&quot; NORM_DATA messages
(with payloads less than the <I>NormSender</I> <FONT FACE="Courier"><U>segmentSize</U></FONT>
parameter) are generated as a result. If <FONT FACE="Courier"><I>NORM_FLUSH_ACTIVE</I></FONT>
is specified, the automated flushing operation is further augmented
with the additional transmission of NORM_CMD(FLUSH) messages to
proactively excite the receiver group for repair requests.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormStreamSetPushEnable()">NormStreamSetPushEnable()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormStreamSetPushEnable(<A HREF="#NormObjectHandle">NormObjectHandle</A>
streamHandle<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bool&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pushEnable);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">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 (<FONT FACE="Courier"><U>pushEnable</U></FONT>
== <FONT FACE="Courier"><I>false</I></FONT>), a call to
<FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT> will return a zero
value under this condition, indicating it was unable to enqueue the
new data. However, if <FONT FACE="Courier"><U>pushEnable</U></FONT>
is set to <FONT FACE="Courier"><I>true</I></FONT> for a given
<FONT FACE="Courier"><U>streamHandle</U></FONT>, 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 <FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT>
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 <FONT FACE="Courier"><U>pushEnable</U></FONT>
equals <FONT FACE="Courier"><I>false</I></FONT>. This limits the
rate to which an application can write new data to the stream to the
current transmission rate and status of the reliable repair process.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormStreamHasVacancy()">NormStreamHasVacancy()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormStreamHasVacancy(<A HREF="#NormObjectHandle">NormObjectHandle</A> streamHandle);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function can be
used to query whether the transmit stream, specified by the
<FONT FACE="Courier"><U>streamHandle</U></FONT> parameter, has buffer
space available so that the application may successfully make a call
to <FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT>. Normally, a call
to <FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT> itself can be used
to make this determination, but this function can be useful when
&quot;push mode&quot; has been enabled (see the description of the
<FONT FACE="Courier"><A HREF="#NormStreamSetPushEnable()">NormStreamSetPushEnable()</A> </FONT>function) and
the application wants to avoid overwriting data previously written to
the stream that has not yet been transmitted. Note that when &quot;push
mode&quot; is enabled, a call to <FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT>
will always succeed, overwriting previously-enqueued data if
necessary. Normally, this function will return true after a
NORM_TX_QUEUE_VACANCY notification has been received for a given NORM
stream object.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function returns a
value of <FONT FACE="Courier"><I>true</I></FONT> when there is
transmit buffer space to which the application may write and <FONT FACE="Courier"><I>false</I></FONT>
otherwise.</P>
<H3 CLASS="functionheading-western"><A NAME="NormStreamMarkEom()">NormStreamMarkEom()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormStreamMarkEom(<A HREF="#NormObjectHandle">NormObjectHandle</A> streamHandle);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function allows
the application to indicate to the NORM protocol engine that the last
data successfully written to the stream indicated by <FONT FACE="Courier"><U>streamHandle</U></FONT>
corresponded to the end of an application-defined message boundary.
If the stream is either explicitly flushed at this point (see
<FONT FACE="Courier"><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT>) or the last write had
exactly filled a <I>NormSender</I> <FONT FACE="Courier"><U>segmentSize</U></FONT>
NORM_DATA message payload, the beginning of the next write will
correspond to the beginning of a new NORM_DATA message. The
end-of-message indication given here will cause the NORM protocol
engine to flag this new message with NORM_FLAG_MSG_START which allows
receivers to recover message boundary synchronization even when
beginning reception mid-stream. Note that the marking is most
effective when explicit flushing is used which forces alignment of
application message boundaries with NORM_DATA messages. It is
anticipated that future versions of the NORM protocol specification
(and/or the NRL implementation) will provide additional, more
flexible stream control mechanisms (e.g. mid-segment message boundary
alignment) that allow for more robust message boundary recovery.</P>
<P CLASS="western" STYLE="font-style: normal">It is recommended that
the <FONT FACE="Courier"><A HREF="#NormStreamMarkEom()">NormStreamMarkEom()</A></FONT> should be used
with automated flushing modes (see <FONT FACE="Courier"><A HREF="#NormStreamSetAutoFlush()">NormStreamSetAutoFlush()</A></FONT>)
while the optional <FONT FACE="Courier"><U>eom</U></FONT> parameter
of <FONT FACE="Courier"><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT> is instead used when
explicit flushing is practiced. End-of-message marking <I>may</I> be
used when no flushing is done, but note then there is no guarantee of
message boundary to NORM_DATA message alignment unless the
application message sizes correspond to multiples of the configured
<I>NormSender</I> <FONT FACE="Courier"><U>segmentSize</U></FONT>.
Again, note future versions of NORM and this implementation may
provide more flexibility here.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetWatermark()">NormSetWatermark()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormSetWatermark(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormObjectHandle">NormObjectHandle</A>&nbsp;&nbsp;object);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function specifies
a &quot;watermark&quot; transmission point at which NORM sender
protocol operation should perform positive acknowledgment collection
for a given <FONT FACE="Courier"><U>session</U></FONT>. For
<FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT> and
<FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT> transmissions,
the positive acknowledgement collection will begin when the specified
<FONT FACE="Courier"><U>object</U></FONT> has been completely
transmitted. The object parameter must be a valid handle to a
previously-created sender object (see <FONT SIZE=2><FONT FACE="Courier">NormEnqueueFile(),</FONT></FONT>
<FONT SIZE=2><FONT FACE="Courier">NormEnqueueData()</FONT></FONT>, or
<FONT SIZE=2><FONT FACE="Courier"><A HREF="#NormStreamOpen()">NormStreamOpen()</A></FONT></FONT>).
For <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>
transmission, the positive acknowledgment collection begins
immediately, using the current position (last data written) of the
sender stream as a reference.
</P>
<P CLASS="western" STYLE="font-style: normal">As the acknowledgment
collection proceeds, <FONT FACE="Courier"><I>NORM_ACK_FAILED</I></FONT>
events will be posted for individual receiver <I>NormNodes</I> which
fail to acknowledge the request. The <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A>::node</FONT>
field contains a <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> for the
failed node and <FONT FACE="Courier"><A HREF="#NormNodeGetId()">NormNodeGetId()</A></FONT> can be
used to retrieve the failing node's <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT>.
When the sender acknowledgment collection process has completed, the
<FONT FACE="Courier"><I>NORM_ACK_COMPLETE</I></FONT> event is posted
and the application may assume that the remaining nodes (those for
which there was no <FONT FACE="Courier"><I>NORM_ACK_FAILED</I></FONT>
event) successfully acknowledged the request.</P>
<P CLASS="western" STYLE="font-style: normal">If a subsequent call is
made to <FONT FACE="Courier"><A HREF="#NormSetWatermark()">NormSetWatermark()</A></FONT> before the
prior acknowledgement request has completed, the pending
acknowledgment request is canceled and new one may begin.</P>
<P CLASS="western" STYLE="font-style: normal">Note that the sender
may still enqueue <I>NormObjects</I> for transmission (or write to
the existing stream) and the positive acknowledgement collection will
be multiplexed with the ongoing data transmission. However, the
sender application may wish to defer sending more data until a
<FONT FACE="Courier"><I>NORM_ACK_COMPLETE</I></FONT> event is
received for the <FONT FACE="Courier"><U>session</U></FONT>. This
provides a form of explicit sender-&gt;receiver(s) flow control (with
respect to the current list of &quot;acking&quot; receivers) which
does not exist in NORM's default NACK-only operation.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">The function returns
<FONT FACE="Courier"><I>true</I></FONT> upon successful establishment
of the watermark point. The function may return <FONT FACE="Courier"><I>false</I></FONT>
upon failure (<I>why would it fail? – TBD</I>).</P>
<H2 CLASS="western">NORM Receiver Functions</H2>
<H3 CLASS="functionheading-western"><A NAME="NormStartReceiver()">NormStartReceiver()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormStartReceiver(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
long&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bufferSpace);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function initiates
the application's participation as a receiver within the <I>NormSession</I>
identified by the <FONT FACE="Courier"><U>session</U></FONT>
parameter. The receiver will respond with appropriate protocol
messages (unless <FONT FACE="Courier">NormSetSilentReceiver(</FONT><FONT FACE="Courier"><I>true</I></FONT><FONT FACE="Courier">)</FONT>
is invoked) and begin providing the application with
receiver-related <I><A HREF="#NormEvent">NormEvent</A></I> notification. The <FONT FACE="Courier"><U>bufferSpace</U></FONT>
parameter is used to set a limit on the amount of <FONT FACE="Courier"><U>bufferSpace</U></FONT>
allocated by the receiver per active <I>NormSender</I> within the
session. The appropriate <FONT FACE="Courier"><U>bufferSpace</U></FONT>
to use is a function of expected network <I>delay*bandwidth</I>
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 bufferSpace
allocation will result in potentially inefficient protocol operation,
even though reliable operation may be maintained. In some cases of a
large <I>delay*bandwidth</I> product and/or severe packet loss, a
small <FONT FACE="Courier"><U>bufferSpace</U></FONT> allocation
(coupled with the lack of explicit flow control in NORM) may result
in the receiver &quot;re-syncing&quot; to the sender, resulting in
&quot;outages&quot; in the reliable transmissions from a sender (this
is similar to the conditions resulting in a TCP connection timeout
failure).
</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">A value of <FONT FACE="Courier"><I>true</I></FONT>
is returned upon success and <FONT FACE="Courier"><I>false</I></FONT>
upon failure. The reasons failure may occur include limited system
resources or that the network sockets required for session
communication failed to open or properly configure.</P>
<H3 CLASS="functionheading-western"><A NAME="NormStopReceiver()">NormStopReceiver()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormStopReceiver(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
int&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;gracePeriod = 0);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function ends the
application's participation as a receiver in the <I>NormSession</I>
specified by the <FONT FACE="Courier"><U>session</U></FONT>
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
<FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT>). However, and
optional <FONT FACE="Courier"><U>gracePeriod</U></FONT> parameter is
provided to allow the receiver an opportunity to inform the group of
its intention. This is applicable when the local receiving <I>NormNode</I>
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 <FONT FACE="Courier"><U>gracePeriod</U></FONT>
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 <FONT FACE="Courier"><U>gracePeriod</U></FONT>
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. &quot;grace time&quot; =
(<FONT FACE="Courier"><U>gracePeriod</U></FONT> * <FONT FACE="Courier"><I>GRTT</I></FONT>)).
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 <FONT FACE="Courier"><U>gracePeriod</U></FONT>
expires, whichever comes first), the NORM protocol engine will post a
<FONT FACE="Courier"><I>NORM_LOCAL_RECEIVER_CLOSED</I></FONT> event
for the applicable <FONT FACE="Courier"><U>session</U></FONT>, and
related resources are then freed.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetRxSocketBuffer()">NormSetRxSocketBuffer()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormSetRxSocketBuffer(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
int&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bufferSize);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function allows
the application to set an alternative, non-default buffer size for
the UDP socket used by the specified NORM <FONT FACE="Courier"><U>session</U></FONT>
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
<FONT FACE="Courier"><U>bufferSize</U></FONT> 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 <FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT>
(or <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>) must have been
previously made for this call to succeed (i.e., the socket must be
already open).</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function returns
<FONT FACE="Courier"><I>true</I></FONT> upon success and <FONT FACE="Courier"><I>false</I></FONT>
upon failure. Possible reasons for failure include, 1) the specified
<FONT FACE="Courier"><U>session</U></FONT> is not valid, 2) that NORM
&quot;receiver&quot; (or &quot;sender&quot;) operation has not yet
been started for the given <FONT FACE="Courier"><U>session</U></FONT>,
or 3) an invalid <FONT FACE="Courier"><U>bufferSize</U></FONT>
specification was given.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetSilentReceiver()">NormSetSilentReceiver()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormSetSilentReceiver(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bool&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;silent);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function provides
the option to configure a NORM receiver application as a &quot;silent
receiver&quot;. This mode of receiver operation dictates that the
host does not generate any protocol messages while operating as a
receiver within the specified <FONT FACE="Courier"><U>session</U></FONT>.
Setting the <FONT FACE="Courier"><U>silent</U></FONT> parameter to
<FONT FACE="Courier"><I>true</I></FONT> enables silent receiver
operation while setting it to <FONT FACE="Courier"><I>false</I></FONT>
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 <FONT FACE="Courier"><A HREF="#NormSetAutoParity()">NormSetAutoParity()</A></FONT>)
or using repair information requested by other non-silent receivers
within the group to achieve reliable transfers.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetDefaultUnicastNack()">NormSetDefaultUnicastNack()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormSetDefaultUnicastNack(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bool&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;state);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function controls
the default behavior determining the destination of receiver feedback
messages generated while participating in the session. If <FONT FACE="Courier"><I>state</I></FONT>
is true, &quot;unicast NACKing&quot; is enabled for <I>new</I> remote
senders while it is disabled for <FONT FACE="Courier"><I>state</I></FONT>
equal to false. The NACKing behavior for current remote senders is
not affected. When &quot;unicast NACKing&quot; is disabled
(default), NACK messages are sent to the session address (usually a
multicast address) and port, but &quot;unicast NACKing&quot;, when
enabled, causes receiver feedback messages to be sent to the unicast
address (and port) based on the source address of sender messages
received. For unicast NORM sessions, it is recommended that &quot;unicast
NACKing&quot; be enabled. Note that receiver feedback messages
subject to the state of &quot;unicast NACKing&quot; 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
<FONT FACE="Courier"><A HREF="#NormSetWatermark()">NormSetWatermark()</A></FONT>) are always unicast to
the applicable sender. (TBD – provide API option so that <I>all</I>
messages are multicast.) The default session-wide behavior for
unicast NACKing can be overridden via the <FONT FACE="Courier"><A HREF="#NormNodeSetUnicastNack()">NormNodeSetUnicastNack()</A></FONT>
function for individual remote senders.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormNodeSetUnicastNack()">NormNodeSetUnicastNack()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormNodeSetUnicastNack(<A HREF="#NormNodeHandle">NormNodeHandle</A> senderNode,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bool&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;state);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function controls
the the destination address of receiver feedback messages generated
in response to a specific remote NORM sender.. If <FONT FACE="Courier"><I>state</I></FONT>
is true, &quot;unicast NACKing&quot; is enabled while it is disabled
for <FONT FACE="Courier"><I>state</I></FONT> equal to false. See the
description of <FONT FACE="Courier"><A HREF="#NormSetDefaultUnicastNack()">NormSetDefaultUnicastNack()</A></FONT>
for details on 'unicast NACKing&quot; behavior.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetDefaultNackingMode()">NormSetDefaultNackingMode()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormSetDefaultNackingMode(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormNackingMode">NormNackingMode</A>&nbsp;&nbsp;&nbsp;nackingMode);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function sets the
default &quot;nacking mode&quot; used when receiving objects. 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. Available nacking modes include:</P>
<TABLE WIDTH=590 BORDER=0 CELLPADDING=7 CELLSPACING=0>
<COL WIDTH=231>
<COL WIDTH=332>
<TR VALIGN=TOP>
<TD WIDTH=231>
<P CLASS="western" STYLE="margin-left: 0.5in; font-style: normal"><FONT FACE="Courier"><I>NORM_NACK_NONE</I></FONT></P>
</TD>
<TD WIDTH=332>
<P CLASS="western" STYLE="margin-left: 0.02in; font-style: normal">
Do not transmit any repair requests for the newly received object.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=231>
<P CLASS="western" STYLE="margin-left: 0.5in; font-style: normal"><FONT FACE="Courier"><I>NORM_NACK_INFO_ONLY</I></FONT></P>
</TD>
<TD WIDTH=332>
<P CLASS="western" STYLE="margin-left: 0.02in; font-style: normal">
Transmit repair requests for NORM_INFO content only as needed.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=231>
<P CLASS="western" STYLE="margin-left: 0.5in; font-style: normal"><FONT FACE="Courier"><I>NORM_NACK_NORMAL</I></FONT></P>
</TD>
<TD WIDTH=332>
<P CLASS="western" STYLE="margin-left: 0.02in; font-style: normal">
Transmit repair requests for entire object as needed.</P>
</TD>
</TR>
</TABLE>
<P CLASS="western" STYLE="font-style: normal">This function specifies
the default behavior with respect to any <I>new</I> sender or object.
This default behavior may be overridden for specific sender nodes or
specific object using <FONT FACE="Courier"><A HREF="#NormNodeSetNackingMode()">NormNodeSetNackingMode()</A></FONT>
or <FONT FACE="Courier"><A HREF="#NormObjectSetNackingMode()">NormObjectSetNackingMode()</A></FONT>,
respectively. The receiver application's use of <FONT FACE="Courier"><I>NORM_NACK_NONE</I></FONT>
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,
NORM_INFO content for transmitted objects, the <FONT FACE="Courier"><I>NORM_NACK_INFO_ONLY</I></FONT>
mode may allows the receiver to reliably receive object context
information from which it may choose to &quot;upgrade&quot; its
nacking mode for the specific object via the
<FONT FACE="Courier"><A HREF="#NormObjectSetNackingMode()">NormObjectSetNackingMode()</A></FONT> call.
Similarly, the receiver may changes its default nacking mode with
respect to specific senders via the <FONT FACE="Courier"><A HREF="#NormNodeSetNackingMode()">NormNodeSetNackingMode()</A></FONT>
call. The default &quot;default nacking mode&quot; when this call is
not made is <FONT FACE="Courier"><I>NORM_NACK_NORMAL</I></FONT>.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormNodeSetNackingMode()">NormNodeSetNackingMode()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormNodeSetNackingMode(<A HREF="#NormNodeHandle">NormNodeHandle</A>&nbsp;&nbsp;nodeHandle,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormNackingMode">NormNackingMode</A>
nackingMode);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function sets the
default &quot;nacking mode&quot; used for receiving new objects from
a specific sender as identified by the <FONT FACE="Courier"><U>nodeHandle</U></FONT>
parameter. This overrides the default nacking mode set for the
receive session. See<FONT FACE="Courier">
<A HREF="#NormSetDefaultNackingMode()">NormSetDefaultNackingMode()</A></FONT> for a description of possible
<FONT FACE="Courier"><U>nackingMode</U></FONT> parameter values and
other related information.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormObjectSetNackingMode()">NormObjectSetNackingMode()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormObjectSetNackingMode(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormNackingMode">NormNackingMode</A>&nbsp;&nbsp;nackingMode);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function sets the
&quot;nacking mode&quot; used for receiving a specific transport
object as identified by the <FONT FACE="Courier"><U>objectHandle</U></FONT>
parameter. This overrides the default nacking mode set for the
applicable sender node. See<FONT FACE="Courier">
<A HREF="#NormSetDefaultNackingMode()">NormSetDefaultNackingMode()</A></FONT> for a description of possible
<FONT FACE="Courier"><U>nackingMode</U></FONT> parameter values and
other related information.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormSetDefaultRepairBoundary()">NormSetDefaultRepairBoundary()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormSetDefaultRepairBoundary(<A HREF="#NormSessionHandle">NormSessionHandle</A>&nbsp;&nbsp;sessionHandle,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormRepairBoundary">NormRepairBoundary</A>
repairBoundary);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function allows
the receiver application to customize, for a given <FONT FACE="Courier"><U>sessionHandle</U></FONT>,
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 <FONT FACE="Courier"><U>repairBoundary</U></FONT>
equal to <FONT FACE="Courier"><I>NORM_BOUNDARY_BLOCK</I></FONT>.
Using this function, the application may alternatively, setting
repairBoundary equal to <FONT FACE="Courier"><I>NORM_BOUNDARY_OBJECT</I></FONT>,
cause the protocol to defer NACK process initiation until the current
transport object has been completely transmitted. This mode of
operation may be useful when it is desirable to allow receivers with
high quality network connectivity (perhaps requiring only a little
(or even no) &quot;auto parity&quot; (see <FONT FACE="Courier"><A HREF="#NormSetAutoParity()">NormSetAutoParity()</A></FONT>)
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
<FONT FACE="Courier"><A HREF="#NormNodeSetRepairBoundary()">NormNodeSetRepairBoundary()</A></FONT> function.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormNodeSetRepairBoundary()">NormNodeSetRepairBoundary()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormNodeSetRepairBoundary(<A HREF="#NormNodeHandle">NormNodeHandle</A>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;nodeHandle,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#NormRepairBoundary">NormRepairBoundary</A>
repairBoundary);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function allows
the receiver application to customize, for the specific remote sender
referenced by the <FONT FACE="Courier"><U>nodeHandle</U></FONT>
parameter, at what points the receiver initiates the NORM NACK repair
process during protocol operation. See the description of
<FONT FACE="Courier"><A HREF="#NormSetDefaultRepairBoundary()">NormSetDefaultRepairBoundary()</A></FONT> for
further details on the impact of setting the NORM receiver repair
boundary and possible values for the <FONT FACE="Courier"><U>repairBoundary</U></FONT>
parameter.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return values.</P>
<H3 CLASS="functionheading-western"><A NAME="NormStreamRead()">NormStreamRead()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormStreamRead(<A HREF="#NormObjectHandle">NormObjectHandle</A>
streamHandle,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;char*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;buffer<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
int*&nbsp;&nbsp;&nbsp;&nbsp;numBytes);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function can be
used by the receiver application to read any available data from an
incoming NORM stream. NORM receiver applications &quot;learn&quot;
of available NORM streams via <FONT FACE="Courier"><I>NORM_RX_OBJECT_NEW</I></FONT>
notification events. The <FONT FACE="Courier"><U>streamHandle</U></FONT>
parameter here must correspond to a valid <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>
value provided during such a prior<FONT FACE="Courier"><I>
NORM_RX_OBJECT_NEW</I></FONT> notification. The <FONT FACE="Courier"><U>buffer</U></FONT>
parameter must be a pointer to an array where the received data can
be stored of a length as referenced by the <FONT FACE="Courier"><U>numBytes</U></FONT>
pointer. On successful completion, the <FONT FACE="Courier"><U>numBytes</U></FONT>
storage will be modified to indicate the actual number of bytes
copied into the provided <FONT FACE="Courier"><U>buffer</U></FONT>.
If the <FONT FACE="Courier"><U>numBytes</U></FONT> storage is
modified to a zero value, this indicates that no stream data was
currently available for reading.</P>
<P CLASS="western" STYLE="font-style: normal">Note that
<FONT FACE="Courier"><A HREF="#NormStreamRead()">NormStreamRead()</A></FONT> is never a blocking call
and only returns failure (<FONT FACE="Courier"><I>false</I></FONT>)
when a break in the integrity of the received stream occurs. The
<FONT FACE="Courier"><I>NORM_RX_OBJECT_UPDATE</I></FONT> provides an
indication to when there is stream data available for reading. When
such notification occurs, the application <I>should</I> repeatedly
read from the stream until the <FONT FACE="Courier"><U>numBytes</U></FONT>
storage is set to zero, even if a <FONT FACE="Courier"><I>false</I></FONT>
value is returned. Additional <FONT FACE="Courier"><I>NORM_RX_OBJECT_UPDATE</I></FONT>
notifications might not be posted until the application can has read
all available data.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function normally
returns a value of <FONT FACE="Courier"><I>true</I></FONT>. 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 <FONT FACE="Courier"><I>false</I></FONT>
is returned to indicate the break. Unless the stream has been ended
(and the receiver application will receive <FONT FACE="Courier"><I>NORM_RX_OBJECT_COMPLETED</I></FONT>
notification for the stream in that case), the application may
continue to read from the stream as the NORM protocol will
automatically &quot;resync&quot; to streams, even if network
conditions are sufficiently poor that breaks in reliability occur.
If such a &quot;break&quot; and &quot;resync&quot; occurs, the
application may be able to leverage other NORM API calls such as
<FONT FACE="Courier"><A HREF="#NormStreamSeekMsgStart()">NormStreamSeekMsgStart()</A></FONT> or
<FONT FACE="Courier">NormStreamGetOffset()</FONT> if needed to
recover its alignment with received stream content. This depends
upon the nature of the application and its stream content.</P>
<H3 CLASS="functionheading-western"><A NAME="NormStreamSeekMsgStart()">NormStreamSeekMsgStart()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormStreamSeekMsgStart(<A HREF="#NormObjectHandle">NormObjectHandle</A> streamHandle);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function advances
the read offset of the receive stream referenced by the <FONT FACE="Courier"><U>streamHandle</U></FONT>
parameter to align with the next available message boundary. Message
boundaries are defined by the sender application using the
<FONT FACE="Courier"><A HREF="#NormStreamMarkEom()">NormStreamMarkEom()</A></FONT> 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 &quot;rewind&quot; function for a NORM stream).
Also note this call cannot be used to skip messages. Once a valid
message boundary is found, the application <I>must</I> read from the
stream using <FONT FACE="Courier"><A HREF="#NormStreamRead()">NormStreamRead()</A></FONT> to further
advance the read offset. The current offset (in bytes) for the
stream can be retrieved via <FONT FACE="Courier"><A HREF="#NormStreamGetReadOffset()">NormStreamGetReadOffset()</A></FONT>.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function returns a
value of <FONT FACE="Courier"><I>true</I></FONT> when
start-of-message is found. The next call to <FONT FACE="Courier"><A HREF="#NormStreamRead()">NormStreamRead()</A></FONT>
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 <FONT FACE="Courier"><I>false</I></FONT>.
In this case, the application should defer repeating a call to this
function until a subsequent <FONT FACE="Courier"><I>NORM_RX_OBJECT_UPDATE</I></FONT>
notification is posted.</P>
<H3 CLASS="functionheading-western"><A NAME="NormStreamGetReadOffset()">NormStreamGetReadOffset()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>unsigned
long NormStreamGetReadOffset(<A HREF="#NormObjectHandle">NormObjectHandle</A> streamHandle);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function retrieves
the current read offset value for the receive stream indicated by the
<FONT FACE="Courier"><U>streamHandle</U></FONT> parameter. Note that
for very long-lived streams, this value may wrap. Thus, in general,
applications should not be highly dependent upon the stream offset,
but this feature may be valuable for certain applications which
associate some application context with stream position.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function returns
the current read offset in bytes. The return value is undefined for
sender streams. There is no error result.
</P>
<H2 CLASS="western">NORM Object Functions</H2>
<P CLASS="western" STYLE="font-style: normal">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 <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>
argument which specifies the applicable object. Note that
<FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT> values obtained from a
<FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT> notification may be considered
valid <I>only</I> until a subsequent call to <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>,
unless explicitly retained by the application (see
<FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT>). <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>
values obtained as a result of <FONT FACE="Courier"><A HREF="#NormFileEnqueue()">NormFileEnqueue()</A></FONT>,
<FONT FACE="Courier"><A HREF="#NormDataEnqueue()">NormDataEnqueue()</A></FONT>, or <FONT FACE="Courier">NormOpenStream()</FONT>
calls can be considered valid only until a corresponding
<FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT> notification
is posted or the object is dequeued using <FONT FACE="Courier">NormCancelObject()</FONT>,
unless, again, otherwise explicitly retained (see
<FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT>).</P>
<H3 CLASS="functionheading-western"><A NAME="NormObjectGetType()">NormObjectGetType()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormObjectType">NormObjectType</A>
NormObjectGetType(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function can be
used to determine the object type (<FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>,
<FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT>, or
<FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>) for the NORM
transport object identified by the <FONT FACE="Courier"><U>objectHandle</U></FONT>
parameter. The <FONT FACE="Courier"><U>objectHandle</U></FONT> <I>must</I>
refer to a current, valid transport object.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function returns
the NORM object type. Valid NORM object types include
<FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>,
<FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT>, or
<FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>. A type value
of <FONT FACE="Courier"><I>NORM_OBJECT_NONE</I></FONT> will be
returned for an objectHandle value of <FONT FACE="Courier"><I>NORM_OBJECT_INVALID</I></FONT>.</P>
<H3 CLASS="functionheading-western"><A NAME="NormObjectHasInfo()">NormObjectHasInfo()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormObjectHasInfo(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function can be
used to determine if the sender has associated any NORM_INFO content
with the transport object specified by the <FONT FACE="Courier"><U>objectHandle</U></FONT>
parameter. This can even be used <I>before</I> the NORM_INFO content
is delivered to the receiver and a <FONT FACE="Courier"><I>NORM_RX_OBJECT_INFO</I></FONT>
notification is posted.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">A value of <FONT FACE="Courier"><I>true</I></FONT>
is returned if NORM_INFO is (or will be) available for the specified
transport object. A value of <FONT FACE="Courier"><I>false</I></FONT>
is returned otherwise.</P>
<H3 CLASS="functionheading-western"><A NAME="NormObjectGetInfoLength()">NormObjectGetInfoLength()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>unsigned
short NormObjectGetInfoLength(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function can be
used to determine the length of currently available NORM_INFO content
(if any) associated with the transport object referenced by the
<FONT FACE="Courier"><U>objectHandle</U></FONT> parameter.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">The length of the
NORM_INFO content, in bytes, of currently available for the specified
transport object is returned. A value of <FONT FACE="Courier"><I>0</I></FONT>
is returned if no NORM_INFO content is currently available or
associated with the object.</P>
<H3 CLASS="functionheading-western"><A NAME="NormObjectGetInfo()">NormObjectGetInfo()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>unsigned
short NormObjectGetInfo(<A HREF="#NormObjectHandle">NormObjectHandle</A>
objectHandle,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;char*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;buffer,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
short&nbsp;&nbsp;&nbsp;bufferLen);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function copies
any NORM_INFO content associated (by the sender application) with the
transport object specified by <FONT FACE="Courier"><U>objectHandle</U></FONT>
into the provided memory space referenced by the <FONT FACE="Courier"><U>buffer</U></FONT>
parameter. The <FONT FACE="Courier"><U>bufferLen</U></FONT>
parameter indicates the length of the <FONT FACE="Courier"><U>buffer</U></FONT>
space in bytes. If the provided <FONT FACE="Courier"><U>bufferLen</U></FONT>
is less than the actual NORM_INFO length, a partial copy will occur.
The actual length of NORM_INFO content available for the specified
object is returned. However, note that until a <FONT FACE="Courier"><I>NORM_RX_OBJECT_INFO</I></FONT>
notification is posted to the receive application, no NORM_INFO
content is available and a zero result will be returned, even if
NORM_INFO content may be subsequently available. The
<FONT FACE="Courier"><A HREF="#NormObjectHasInfo()">NormObjectHasInfo()</A></FONT> call can be used to
determine if any NORM_INFO content will ever be available for a
specified transport object (i.e., determine if the sender has
associated any NORM_INFO with the object in question).</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">The actual length of
<I>currently</I> <I>available</I> NORM_INFO content for the specified
transport object is returned. This function can be used to determine
the length of NORM_INFO content for the object even if a <FONT FACE="Courier"><I>NULL</I></FONT>
<FONT FACE="Courier"><U>buffer</U></FONT> value and zero <FONT FACE="Courier"><U>bufferLen</U></FONT>
is provided. A zero value is returned if NORM_INFO content has not
yet been received (or is non-existent) for the specified object.</P>
<H3 CLASS="functionheading-western"><A NAME="NormObjectGetSize()">NormObjectGetSize()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormSize">NormSize</A>
NormObjectGetSize(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function can be
used to determine the size (in bytes) of the transport object
specified by the <FONT FACE="Courier"><U>objectHandle</U></FONT>
parameter. NORM can support large object sizes for the
<FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT> 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., &quot;<FONT FACE="Courier">#define _FILE_OFFSET_BITS
64</FONT>&quot; or equivalent). The <FONT FACE="Courier"><A HREF="#NormSize">NormSize</A></FONT>
type is defined accordingly, so the application should be built with
the same large file support configuration.</P>
<P CLASS="western" STYLE="font-style: normal">For objects of type
<FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>, the size
returned here corresponds to the stream buffer size set by the sender
application when opening the referenced stream object.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">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
NORM_INFO content available.</P>
<H3 CLASS="functionheading-western"><A NAME="NormObjectGetBytesPending()">NormObjectGetBytesPending()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormSize">NormSize</A>
NormObjectGetBytesPending(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function can be
used to determine the progress of reception of the NORM transport
object identified by the <FONT FACE="Courier"><U>objectHandle</U></FONT>
parameter. This function indicates the number of bytes that are
pending reception (I.e., when the object is completely received,
&quot;bytes pending&quot; will equal ZERO). This function is not
necessarily applicable to objects of type NORM_OBJECT_STREAM which do
not have a finite size. Note it is possible that this function might
also be useful to query the &quot;transmit pending&quot; status of
sender objects, but it does not account for pending FEC repair
transmissions and thus may not produce useful results for this
purpose.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">A number of object
source data bytes pending reception (or transmission) is returned.</P>
<H3 CLASS="functionheading-western"><A NAME="NormObjectCancel()">NormObjectCancel()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormObjectCancel(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">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 <FONT FACE="Courier"><U>objectHandle</U></FONT>
parameter. The <FONT FACE="Courier"><U>objectHandle</U></FONT> 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
<FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> 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 <FONT FACE="Courier"><U>objectHandle</U></FONT>
after this call is made.
</P>
<P CLASS="western" STYLE="font-style: normal">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 NORM_CMD(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, <I>will</I> acknowledge the object as completed with
respect to any associated positive acknowledgement requests (see
<FONT FACE="Courier"><A HREF="#NormSetWatermark()">NormSetWatermark()</A></FONT>).</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return value.</P>
<H3 CLASS="functionheading-western"><A NAME="NormObjectRetain()">NormObjectRetain()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormObjectRetain(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function &quot;retains&quot;
the <FONT FACE="Courier"><U>objectHandle</U></FONT> 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 <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT> 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
<FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT>
notification) by the protocol engine, or, for receiver objects, from
the time of the object's <FONT FACE="Courier"><I>NORM_RX_OBJECT_NEW</I></FONT>
notification until its reception is canceled by the application or a
<FONT FACE="Courier"><I>NORM_RX_OBJECT_COMPLETED</I></FONT> or
<FONT FACE="Courier"><I>NORM_RX_OBJECT_ABORTED</I></FONT>
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 <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>.
</P>
<P CLASS="western" STYLE="font-style: normal">When the application
makes a call to <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> for a
given <FONT FACE="Courier"><U>objectHandle</U></FONT>, the
application may use that <FONT FACE="Courier"><U>objectHandle</U></FONT>
value in any NORM API calls until the application makes a call to
<FONT FACE="Courier"><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT> for the given object.
Note that the application <I>MUST</I> make a corresponding call to
<FONT FACE="Courier"><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT> for each call it has
made to <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> 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 <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A>
</FONT>corresponding to the remote sender of that receive object so
that the application may use NORM node API calls for the value
returned by <FONT FACE="Courier"><A HREF="#NormObjectGetSender()">NormObjectGetSender()</A></FONT> as
needed.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return value.</P>
<H3 CLASS="functionheading-western"><A NAME="NormObjectRelease()">NormObjectRelease()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormObjectRelease(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function
complements the <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> call
by immediately freeing any resources associated with the given
<FONT FACE="Courier"><U>objectHandle</U></FONT>, 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 <FONT FACE="Courier"><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT>
for an <FONT FACE="Courier"><U>objectHandle</U></FONT> for which it
has not previously explicitly retained via <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT>.
</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return value.</P>
<H3 CLASS="functionheading-western"><A NAME="NormFileGetName()">NormFileGetName()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormFileGetName(<A HREF="#NormObjectHandle">NormObjectHandle</A>
fileHandle)<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;char*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;nameBuffer,<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;unsigned
int&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bufferLen);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function copies
the name, as a NULL-terminated string, of the file object specified
by the <FONT FACE="Courier"><U>fileHandle</U></FONT> parameter into
the <FONT FACE="Courier"><U>nameBuffer</U></FONT> of length <FONT FACE="Courier"><U>bufferLen</U></FONT>
bytes provided by the application. The <FONT FACE="Courier"><U>fileHandle</U></FONT>
parameter must refer to a valid <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>
for an object of type NORM_OBJECT_FILE. If the actual name is longer
than the provided <FONT FACE="Courier"><U>bufferLen</U></FONT>, 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 <FONT FACE="Courier"><U>nameBuffer</U></FONT>.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function returns
true upon success and false upon failure. Possible failure
conditions include the <FONT FACE="Courier"><U>fileHandle</U></FONT>
does not refer to an object of type <FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT>.</P>
<H3 CLASS="functionheading-western"><A NAME="NormFileRename()">NormFileRename()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
NormFileRename(<A HREF="#NormObjectHandle">NormObjectHandle</A> fileHandle)<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const
char*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fileName);</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function renames
the file used to store content for the <FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT>
transport object specified by the <FONT FACE="Courier"><U>fileHandle</U></FONT>
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 NORM_INFO
content associated with a file object to provide name and/or typing
information to receivers. The <FONT FACE="Courier"><U>fileName</U></FONT>
parameter must be a NULL-terminated string which should specify the
full desired path name to be used. NORM will attempt to create
sub-directories as needed to satisfy the request. Note that existing
files of the same name may be overwritten.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function returns
true upon success and false upon failure. Possible failure
conditions include the case where the <FONT FACE="Courier"><U>fileHandle</U></FONT>
does not refer to an object of type <FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT>
and where NORM was unable to successfully create any needed
directories and/or the file itself.</P>
<H3 CLASS="functionheading-western"><A NAME="NormDataAccessData()">NormDataAccessData()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>const
char* NormDataAccessData(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle)</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function allows
the application to access the data storage area associated with a
transport object of type <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>.
For example, the application may use this function to copy the
received data content for its own use. Alternatively, the
application may establish &quot;ownership&quot; for the allocated
memory space using the <FONT SIZE=2><FONT FACE="Courier"><A HREF="#NormDataDetachData()">NormDataDetachData()</A></FONT></FONT>
function if it is desired to avoid the copy.</P>
<P CLASS="western" STYLE="font-style: normal">If the object specified
by the <FONT FACE="Courier"><U>objectHandle</U></FONT> parameter has
no data content (or is not of type <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>),
a NULL value may be returned. The application MUST NOT attempt to
modify the memory space used by <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>
objects during the time an associated <FONT FACE="Courier"><U>objectHandle</U></FONT>
is valid. The length of data storage area can be determined with a
call to <FONT FACE="Courier"><A HREF="#NormObjectGetSize()">NormObjectGetSize()</A></FONT> for the same
<FONT FACE="Courier"><U>objectHandle</U></FONT> value.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">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 <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>.</P>
<H3 CLASS="functionheading-western"><A NAME="NormDataDetachData()">NormDataDetachData()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>char*
NormDataDetachData(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle)</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function allows
the application to disassociate data storage allocated by the NORM
protocol engine for a receive object from the <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>
transport object specified by the <FONT FACE="Courier"><U>objectHandle</U></FONT>
parameter. It is important that this function is called <I>after</I>
the NORM protocol engine has indicated it is finished with the data
object (i.e., after a <FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT>,
<FONT FACE="Courier"><I>NORM_RX_OBJECT_COMPLETED</I></FONT>, or
<FONT FACE="Courier"><I>NORM_RX_OBJECT_ABORTED</I></FONT>
notification event). But the application must call
<FONT FACE="Courier"><A HREF="#NormDataDetachData()">NormDataDetachData()</A></FONT> <I>before</I> a call
is made to <FONT FACE="Courier"><A HREF="#NormObjectCancel()">NormObjectCancel()</A></FONT> or
<FONT FACE="Courier"><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT> 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 <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>
transport object is deleted and the application will be unable to
access the received data unless it has previously copied the content.</P>
<P CLASS="western" STYLE="font-style: normal">Once the application
has used this call to &quot;detach&quot; the data content, it is the
application's responsibility to subsequently free the data storage
space as needed.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">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 <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>.</P>
<H3 CLASS="functionheading-western"><A NAME="NormObjectGetSender()">NormObjectGetSender()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormNodeHandle">NormNodeHandle</A>
NormObjectGetSender(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle)</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function retrieves
the <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> corresponding to the
remote sender of the transport object associated with the given
<FONT FACE="Courier"><U>objectHandle</U></FONT> parameter. Note that
the returned <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> value is only
valid for the same period that the <FONT FACE="Courier"><U>objectHandle</U></FONT>
is valid. The returned <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>
may optionally be retained for further use by the application using
the <FONT FACE="Courier"><A HREF="#NormNodeRetain()">NormNodeRetain()</A></FONT> function call. The
returned value can be used in the NORM Node Functions described later
in this document.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function returns
the <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> corresponding to the
remote sender of the transport object associated with the given
<FONT FACE="Courier"><U>objectHandle</U></FONT> parameter. A value
of NORM_NODE_INVALID is returned if the specified <FONT FACE="Courier"><U>objectHandle</U></FONT>
references a locally originated, sender object.</P>
<H2 CLASS="western">NORM Node Functions</H2>
<P CLASS="western" STYLE="font-style: normal">The functions described
in this section may be used for NORM sender or receiver (most
typically receiver) purposes to retrieve additional information about
a <I>NormNode</I>, given a valid <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>.
Note that, unless specifically retained (see <FONT FACE="Courier"><A HREF="#NormNodeRetain()">NormNodeRetain()</A></FONT>),
a <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> provided in a <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT>
notification should be considered valid only until a subsequent call
to <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT> is made.
<FONT FACE="Courier">NormNodeHandles </FONT>retrieved using
<FONT FACE="Courier"><A HREF="#NormObjectGetSender()">NormObjectGetSender()</A></FONT> can be considered
valid for the same period of time as the corresponding
<A HREF="#NormObjectHandle">NormObjectHandle</A> is valid.</P>
<H3 CLASS="functionheading-western"><A NAME="NormNodeGetId()">NormNodeGetId()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormNodeId">NormNodeId</A>
NormNodeGetId(<A HREF="#NormNodeHandle">NormNodeHandle</A> nodeHandle)</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function retrieves
the <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> identifier for the remote
participant referenced by the given <FONT FACE="Courier"><U>nodeHandle</U></FONT>
value. The <A HREF="#NormNodeId">NormNodeId</A> is a 32-bit value used within the NORM
protocol to uniquely identify participants within a NORM session.
The participants identifiers are assigned by the application or
derived (by the NORM API code) from the host computers default IP
address.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function returns
the <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> value associated with the
specified <FONT FACE="Courier"><U>nodeHandle</U></FONT>. In the case
<FONT FACE="Courier"><U>nodeHandle</U></FONT> is equal to
<FONT FACE="Courier"><I>NORM_NODE_INVALID</I></FONT>, the return
value will be <FONT FACE="Courier"><I>NORM_NODE_NONE</I></FONT>.</P>
<H3 CLASS="functionheading-western"><A NAME="NormNodeGetAddress()">NormNodeGetAddress()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormNodeId">NormNodeId</A>
NormNodeGetAddress(<A HREF="#NormNodeHandle">NormNodeHandle</A> nodeHandle)</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">This function retrieves
the <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> identifier for the remote
participant referenced by the given <FONT FACE="Courier"><U>nodeHandle</U></FONT>
value. The <A HREF="#NormNodeId">NormNodeId</A> is a 32-bit value used within the NORM
protocol to uniquely identify participants within a NORM session.
The participants identifiers are assigned by the application or
derived (by the NORM API code) from the host computers default IP
address.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function returns
the <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> value associated with the
specified <FONT FACE="Courier"><U>nodeHandle</U></FONT>. In the case
<FONT FACE="Courier"><U>nodeHandle</U></FONT> is equal to
<FONT FACE="Courier"><I>NORM_NODE_INVALID</I></FONT>, the return
value will be <FONT FACE="Courier"><I>NORM_NODE_NONE</I></FONT>.</P>
<H3 CLASS="functionheading-western"><A NAME="NormNodeRetain()">NormNodeRetain()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormNodeRetain(<A HREF="#NormNodeHandle">NormNodeHandle</A> nodeHandle)</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">In the same manner as
the <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> function, this
function allows the application to retain state associated with a
given <FONT FACE="Courier"><U>nodeHandle</U></FONT> value even when
the underlying NORM protocol engine might normally free the
associated state and thus invalidate the <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>.
If the application uses this function, it must make a corresponding
call to <FONT FACE="Courier"><A HREF="#NormNodeRelease()">NormNodeRelease()</A></FONT> when finished
with the node information to avoid a memory leak condition.
<FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> values (unless retained)
are valid from the time of a <FONT FACE="Courier"><I>NORM_REMOTE_SERVER_NEW</I></FONT>
notification until a complimentary <FONT FACE="Courier"><I>NORM_REMOTE_SERVER_PURGED</I></FONT>
notification. During that interval, the application will receive
<FONT FACE="Courier"><I>NORM_REMOTE_SERVER_ACTIVE</I></FONT> and
<FONT FACE="Courier"><I>NORM_REMOTE_SERVER_INACTIVE</I></FONT>
notifications according to the server's message transmission activity
within the session.</P>
<P CLASS="western" STYLE="font-style: normal">It is important to note
that, if the NORM protocol engine posts a <FONT FACE="Courier"><I>NORM_REMOTE_SERVER_PURGED</I></FONT>
notification for a given <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>,
the NORM protocol engine could possibly, subsequently establish a
new, different <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> value for
the same remote server (i.e., one of equivalent <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT>)
if it again becomes active in the session. A new <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>
may likely be established even if the application has retained the
previous <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> value.
Therefore, to the application, it might appear that two different
servers with the same <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> 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 servers within a session (related APIs
are TBD). For example, the application may wish to control which
specific remote servers for which it keeps state (or limit the memory
resources used for remote servers state, etc) and the NORM API may be
extended in the future to control this behavior.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return value.</P>
<H3 CLASS="functionheading-western"><A NAME="NormNodeRelease()">NormNodeRelease()</A></H3>
<H4 CLASS="western">Synopsis</H4>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
&lt;normApi.h&gt;</FONT></FONT></P>
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
NormNodeRelease(<A HREF="#NormNodeHandle">NormNodeHandle</A> nodeHandle)</FONT></FONT></P>
<H4 CLASS="western">Description</H4>
<P CLASS="western" STYLE="font-style: normal">In complement to the
<FONT FACE="Courier"><A HREF="#NormNodeRetain()">NormNodeRetain()</A></FONT> function, this API call
releases the specified <FONT FACE="Courier"><U>nodeHandle</U></FONT>
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 <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>,
unless it is still valid.</P>
<H4 CLASS="western">Return Values</H4>
<P CLASS="western" STYLE="font-style: normal">This function has no
return value.</P>
</BODY>
</HTML>
Reference in New Issue View Git Blame Copy Permalink