4405 lines
305 KiB
HTML
4405 lines
305 KiB
HTML
<!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 2.2 (Unix)">
|
||
<META NAME="AUTHOR" CONTENT="Robert Adamson">
|
||
<META NAME="CREATED" CONTENT="20040824;14180000">
|
||
<META NAME="CHANGED" CONTENT="20070911;15435700">
|
||
<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 TYPE="text/css">
|
||
<!--
|
||
@page { size: 8.5in 11in; margin-left: 0.79in; margin-right: 1.25in; margin-top: 1in; margin-bottom: 0.5in }
|
||
@page:first { margin-top: 1in; margin-bottom: 1in }
|
||
TD P { margin-top: 0.08in; margin-bottom: 0in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
|
||
TD P.western { font-family: "Times"; font-size: 12pt; so-language: en-US; font-style: italic }
|
||
TD P.cjk { font-family: "Times"; font-size: 12pt; font-style: italic }
|
||
TD 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 }
|
||
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 }
|
||
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.02in; 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.02in; 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.02in; 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 CLASS="western" ALIGN=CENTER STYLE="margin-top: 0.17in"><IMG SRC="NormLogo.gif" NAME="graphics1" ALIGN=BOTTOM WIDTH=184 HEIGHT=176 BORDER=0></P>
|
||
</TD>
|
||
<TD WIDTH=371>
|
||
<P CLASS="western" ALIGN=LEFT STYLE="margin-left: 0.86in; margin-top: 0.17in; font-style: normal">
|
||
<FONT FACE="Helvetica, sans-serif"><FONT SIZE=4 STYLE="font-size: 16pt"><B><FONT SIZE=6 STYLE="font-size: 28pt">NORM<BR>Developer’s
|
||
<BR>Guide<BR></FONT><FONT SIZE=4>(version 1.4b1)</FONT></B></FONT></FONT></P>
|
||
</TD>
|
||
</TR>
|
||
</TABLE>
|
||
<H1 CLASS="western"><A NAME="Background">Background</A></H1>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in"><SPAN STYLE="font-style: normal">This
|
||
document describes an application programming interface (API) for the
|
||
</SPAN><A HREF="http://norm.pf.itd.nrl.navy.mil/"><FONT COLOR="#0000ff"><SPAN STYLE="font-style: normal"><U>Nack-Oriented
|
||
Reliable Multicast (NORM)</U></SPAN></FONT></A><SPAN STYLE="font-style: normal">
|
||
protocol implementation developed by the Protocol Engineering and
|
||
Advance Networking (</SPAN><A HREF="http://cs.itd.nrl.navy.mil/"><FONT COLOR="#0000ff"><SPAN STYLE="font-style: normal"><U>PROTEAN</U></SPAN></FONT></A><SPAN STYLE="font-style: normal">)
|
||
Research Group of the United States </SPAN><A HREF="http://www.nrl.navy.mil/"><FONT COLOR="#0000ff"><SPAN STYLE="font-style: normal"><U>Naval
|
||
Research Laboratory</U></SPAN></FONT></A><SPAN STYLE="font-style: normal">
|
||
(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 </SPAN><A HREF="http://www.ietf.org/"><FONT COLOR="#0000ff"><SPAN STYLE="font-style: normal"><U>Internet
|
||
Engineering Task Force</U></SPAN></FONT></A><SPAN STYLE="font-style: normal">
|
||
(IETF) </SPAN><A HREF="http://norm.pf.itd.nrl.navy.mil/rfc3940.pdf"><FONT COLOR="#0000ff"><SPAN STYLE="font-style: normal"><U>RFC
|
||
3940</U></SPAN></FONT></A><SPAN STYLE="font-style: normal">.</SPAN></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 "a priori" 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>
|
||
<DIV ID="Table of Contents1" DIR="LTR">
|
||
<P CLASS="western" STYLE="margin-top: 0.25in"><SPAN 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.</SPAN></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.25in"><FONT FACE="Helvetica, sans-serif"><SPAN STYLE="font-style: normal"><B><A HREF="#Overview">Overview</A></B></SPAN></FONT></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#API Initialization">API Initialization</A></B></FONT></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#Session Creation and Control">Session Creation and Control</A></B></FONT></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#Data Transport">Data Transport</A></B></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#Data Transmission">Data Transmission</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#Data Reception">Data Reception</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#API Event Notification">API Event Notification</A></B></FONT></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.25in; font-style: normal"><FONT FACE="Helvetica, sans-serif"><B><A HREF="#Build Notes">Build Notes</A></B></FONT></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#Unix Platforms">Unix Platforms</A></B></FONT></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#Win32/WiNCE Platforms">Win32/WiNCE Platforms</A></B></FONT></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.25in; font-style: normal"><FONT FACE="Helvetica, sans-serif"><B><A HREF="#API Reference">API Reference</A></B></FONT></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#API Variable Types and Constants">API Variable Types and Constants</A></B></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormInstanceHandle">NormInstanceHandle</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSessionHandle">NormSessionHandle</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSessionId">NormSessionId</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormNodeId">NormNodeId</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormObjectType">NormObjectType</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSize">NormSize</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormObjectTransportId">NormObjectTransportId</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormEventType">NormEventType</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormEvent">NormEvent</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormDescriptor">NormDescriptor</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormFlushMode">NormFlushMode</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormProbingMode">NormProbingMode</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormNackingMode">NormNackingMode</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormRepairBoundary">NormRepairBoundary</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormAckingStatus">NormAckingStatus</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#API Initialization and Operation">API Initialization and Operation</A></B></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormCreateInstance()">NormCreateInstance()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormDestroyInstance()">NormDestroyInstance()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStopInstance()">NormStopInstance()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormRestartInstance()">NormRestartInstance()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetCacheDirectory()">NormSetCacheDirectory()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormGetDescriptor()">NormGetDescriptor()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#Session Creation and Control Functions">Session Creation and Control Functions</A></B></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormCreateSession()">NormCreateSession()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormDestroySession()">NormDestroySession()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetUserData()">NormSetUserData()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormGetUserData()">NormGetUserData()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormGetLocalNodeId()">NormGetLocalNodeId()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetTxPort()">NormSetTxPort()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetRxPortReuse()">NormSetRxPortReuse()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetMulticastInterface()">NormSetMulticastInterface()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetTTL()">NormSetTTL()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetTOS()">NormSetTOS()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetLoopback()">NormSetLoopback()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#NORM Sender Functions">NORM Sender Functions</A></B></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStartSender()">NormStartSender()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStopSender()">NormStopSender()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetTransmitRate()">NormSetTransmitRate()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetTxSocketBuffer()">NormSetTxSocketBuffer()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetCongestionControl()">NormSetCongestionControl()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetTransmitRateBounds()">NormSetTransmitRateBounds()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetTransmitCacheBounds()">NormSetTransmitCacheBounds()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetAutoParity()">NormSetAutoParity()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormGetGrttEstimate()">NormGetGrttEstimate()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetGrttEstimate()">NormSetGrttEstimate()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetGrttMax()">NormSetGrttMax()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetGrttProbingMode()">NormSetGrttProbingMode()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetGrttProbingInterval()">NormSetGrttProbingInterval()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetBackoffFactor()">NormSetBackoffFactor()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetGroupSize()">NormSetGroupSize()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormFileEnqueue()">NormFileEnqueue()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormDataEnqueue()">NormDataEnqueue()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormRequeueObject()">NormRequeueObject()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStreamOpen()">NormStreamOpen()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStreamClose()">NormStreamClose()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStreamSetAutoFlush()">NormStreamSetAutoFlush()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStreamSetPushEnable()">NormStreamSetPushEnable()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStreamHasVacancy()">NormStreamHasVacancy()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStreamMarkEom()">NormStreamMarkEom()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetWatermark()">NormSetWatermark()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormAddAckingNode()">NormAddAckingNode()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormRemoveAckingNode()">NormRemoveAckingNode()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormGetAckingStatus()">NormGetAckingStatus()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#NORM Receiver Functions">NORM Receiver Functions</A></B></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStopReceiver()">NormStopReceiver()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetRxSocketBuffer()">NormSetRxSocketBuffer()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetSilentReceiver()">NormSetSilentReceiver()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetDefaultUnicastNack()">NormSetDefaultUnicastNack()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormNodeSetUnicastNack()">NormNodeSetUnicastNack()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetDefaultNackingMode()">NormSetDefaultNackingMode()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormNodeSetNackingMode()">NormNodeSetNackingMode()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormObjectSetNackingMode()">NormObjectSetNackingMode()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormSetDefaultRepairBoundary()">NormSetDefaultRepairBoundary()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormNodeSetRepairBoundary()">NormNodeSetRepairBoundary()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStreamRead()">NormStreamRead()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStreamSeekMsgStart()">NormStreamSeekMsgStart()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormStreamGetReadOffset()">NormStreamGetReadOffset()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#NORM Object Functions">NORM Object Functions</A></B></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormObjectGetType()">NormObjectGetType()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormObjectHasInfo()">NormObjectHasInfo()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormObjectGetInfoLength()">NormObjectGetInfoLength()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormObjectGetInfo()">NormObjectGetInfo()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormObjectGetSize()">NormObjectGetSize()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormObjectGetBytesPending()">NormObjectGetBytesPending()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormObjectCancel()">NormObjectCancel()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormFileGetName()">NormFileGetName()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormFileRename()">NormFileRename()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormDataAccessData()">NormDataAccessData()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormDataDetachData()">NormDataDetachData()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormObjectGetSender()">NormObjectGetSender()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#NORM Node Functions">NORM Node Functions</A></B></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormNodeGetId()">NormNodeGetId()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormNodeGetAddress()">NormNodeGetAddress()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormNodeGetGrtt()">NormNodeGetGrtt()</A></FONT></P>
|
||
<P CLASS="western" STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal">
|
||
<FONT SIZE=2><A HREF="#NormNodeRetain()">NormNodeRetain()</A></FONT></P>
|
||
<P CLASS="western" 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"><A NAME="Overview">Overview</A></H1>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 code </I><I><U>may</U></I>
|
||
<I>also be provided in the future</I>.)</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
NORM API operation can be roughly summarized with the following
|
||
categories of functions:</P>
|
||
<OL>
|
||
<LI><P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">
|
||
<A HREF="#API Initialization">API Initialization</A></P>
|
||
<LI><P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">
|
||
<A HREF="#Session Creation and Control">Session Creation and Control</A></P>
|
||
<LI><P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">
|
||
<A HREF="#Data Transport">Data Transport</A></P>
|
||
<LI><P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">
|
||
<A HREF="#API Event Notification">API Event Notification</A></P>
|
||
</OL>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 (or unicast
|
||
address) and host port number) may be created and controlled.
|
||
Applications may participate as senders and/or receivers within a
|
||
NORM session. NORM senders transmit data to the session destination
|
||
address (usually an IP multicast group) while receivers are notified
|
||
of incoming data. The NORM API provides and event notification scheme
|
||
to notify the application of significant sender and receiver events.
|
||
There are also a number support functions provided for the
|
||
application to control and monitor its participation within a NORM
|
||
transport session.</P>
|
||
<H2 CLASS="western"><A NAME="API Initialization">API Initialization</A></H2>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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.
|
||
</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">In
|
||
general, only a single thread should access the <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>
|
||
API call for a given <FONT FACE="Courier">NormInstance</FONT>. This
|
||
function serves as the conduit for delivering NORM protocol engine
|
||
events to the application. A NORM application can be designed to be
|
||
single-threaded, even with multiple active <I>NormSessions</I>, but
|
||
also multiple API instances can be created (see <FONT FACE="Courier"><A HREF="#NormCreateInstance()">NormCreateInstance()</A></FONT>)
|
||
as needed for applications with specific requirements for accessing
|
||
and controlling participation in multiple <I>NormSessions</I> from
|
||
separate operating system multiple threads. Or, alternatively, a
|
||
single <FONT FACE="Courier">NormInstance</FONT> could be used, with a
|
||
"master thread" serving as an intermediary between the
|
||
<FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT> function,
|
||
demultiiplexing and dispatching events as appropriate to other "child
|
||
threads" that are created to handle "per-<I>NormSession</I>"
|
||
input/output. The advantage of this alternative approach is that the
|
||
end result would be one NORM protocol engine thread plus one "master
|
||
thread" plus one "child thread" per <I>NormSession</I>
|
||
instead of two threads (protocol engine plus application thread) per
|
||
<I>NormSession</I> if such multi-threaded operation is needed by the
|
||
application.</P>
|
||
<H2 CLASS="western"><A NAME="Session Creation and Control">Session Creation and Control</A></H2>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 senders and API calls are
|
||
provided to control transmission rate, FEC parameters, etc.
|
||
Applications participating as receivers will be notified via the NORM
|
||
API's event dispatching mechanism of pending and completed reliable
|
||
reception of data along with other significant events. Additionally,
|
||
API controls for some optional NORM protocol mechanisms, such as
|
||
positive acknowledgment collection, are also provided.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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"><A NAME="Data Transport">Data Transport</A></H2>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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"><A NAME="Data Transmission">Data Transmission</A></H3>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 "friendly"
|
||
to other data flows on the network, fairly sharing available
|
||
bandwidth.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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
|
||
"robust" transmission that, in some cases, may be reliably
|
||
received without any NACKing activity. This can allow for some degree
|
||
of reliable protocol operation even without receiver feedback
|
||
available. NORM senders may also requeue (within the limits of
|
||
"transmit cache" settings) objects for repeat transmission,
|
||
and receivers may combine together multiple transmissions to reliably
|
||
receive content. Additionally, hybrid proactive/reactive FEC repair
|
||
operation is possible with the receiver NACK process as a "backup"
|
||
for when network packet loss exceeds the repair capability of the
|
||
proactive FEC settings.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 ("acking
|
||
node list") and set "watermark" points for which
|
||
positive acknowledgement is collected. This process can provide the
|
||
application with explicit flow control for an application-determined
|
||
critical set of receivers in the group.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">For
|
||
a NORM application to perform data transmission, it must first create
|
||
a session using <FONT FACE="Courier"><A HREF="#NormCreateSession()">NormCreateSession()</A></FONT> and
|
||
make a call to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> before
|
||
sending actual user data. The functions <FONT FACE="Courier">NormEnqueueFile()</FONT>,
|
||
<FONT FACE="Courier">NormEnqueueData()</FONT>, and <FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT>
|
||
are available for the application to pass data to the NORM protocol
|
||
engine for transmission. Note that to use <FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT>,
|
||
a "sender stream" must first be created using
|
||
<FONT FACE="Courier"><A HREF="#NormStreamOpen()">NormStreamOpen()</A></FONT>.
|
||
</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
calls to enqueue transport objects or write to a stream may be called
|
||
at any time, but the <FONT FACE="Courier"><I>NORM_TX_QUEUE_EMPTY</I></FONT>
|
||
and <FONT FACE="Courier"><I>NORM_TX_QUEUE_VACANCY</I></FONT>
|
||
notification events (see <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>)
|
||
provide useful cues for when these functions may be successfully
|
||
called. Typically, an application might catch both
|
||
<FONT FACE="Courier"><I>NORM_TX_QUEUE_EMPTY</I></FONT> and
|
||
<FONT FACE="Courier"><I>NORM_TX_QUEUE_VACANCY</I></FONT> event types
|
||
as cues for enqueuing additional transport objects or writing to a
|
||
stream. However, an application may choose to cue off of
|
||
<FONT FACE="Courier"><I>NORM_TX_QUEUE_EMPTY</I></FONT> only if it
|
||
wishes to provide the "freshest" data to NORM for
|
||
transmission. The advantage of additionally using
|
||
<FONT FACE="Courier"><I>NORM_TX_QUEUE_VACANCY</I></FONT> is that if
|
||
the application uses this cue to fill up NORM transport object or
|
||
stream buffers, it can keep the NORM stream busy sending data and
|
||
realize the highest possible transmission rate when attempting very
|
||
high speed communication (Otherwise, the NORM protocol engine may
|
||
experience some "dead air time" waiting for the application
|
||
thread to respond to a <FONT FACE="Courier"><I>NORM_TX_QUEUE_EMPTY</I></FONT>
|
||
event). Note the sender application can control buffer depths as
|
||
needed with the <A HREF="#NormSetTransmitCacheBounds()">NormSetTransmitCacheBounds()</A> and <A HREF="#NormStreamOpen()">NormStreamOpen()</A>
|
||
calls.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">Another
|
||
cue that can be leveraged by the sender application to determine when
|
||
it is appropriate to enqueue (or write) additional data for
|
||
transmission is the <FONT FACE="Courier"><I>NORM_TX_WATERMARK_COMPLETED</I></FONT>
|
||
event. This event is posted when the flushing or explicit positive
|
||
acknowledgment collection process has completed for a "watermark"
|
||
point in transmission that was set by the sender (see
|
||
<FONT FACE="Courier"><A HREF="#NormSetWatermark()">NormSetWatermark()</A></FONT> and
|
||
<FONT FACE="Courier"><A HREF="#NormAddAckingNode()">NormAddAckingNode()</A></FONT>). A list of
|
||
<FONT FACE="Courier">NormNodeIds</FONT> can be supplied from which
|
||
explicit acknowledgement is expected and/or the <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT>
|
||
NORM_NODE_NONE can be set (using <FONT FACE="Courier"><A HREF="#NormAddAckingNode()">NormAddAckingNode()</A></FONT>)
|
||
for completion of a NACK-based version of the watermark flushing
|
||
procedure. This flushing process can be used as a flow control
|
||
mechanism for NORM applications. Note this is distinct from NORM's
|
||
congestion control mechanism that, while it provides network-friendly
|
||
transmission rate control, does guarantee flow control to receiving
|
||
nodes.</P>
|
||
<H3 CLASS="western"><A NAME="Data Reception">Data Reception</A></H3>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 or
|
||
emission-controlled (EMCON) operation) entirely. Otherwise, the
|
||
parameters and operation of reliable data transmission are left to
|
||
sender applications and receivers learn of sender parameters in NORM
|
||
protocol message headers and are instructed by NORM_CMD messages from
|
||
the sender(s).</P>
|
||
<H2 CLASS="western"><A NAME="API Event Notification">API Event Notification</A></H2>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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"><A NAME="Build Notes">Build Notes</A></H1>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">To
|
||
build applications that use the NORM library, a path to the
|
||
"normApi.h" header file must be provided and the linker
|
||
step needs to reference the NORM library file ("libnorm.a"
|
||
for Unix platforms and "Norm.lib" for Win32 platforms).
|
||
NORM also depends upon the NRL Protean Protocol Prototyping toolkit
|
||
"Protokit" library (a.k.a "Protolib") (static
|
||
library files "libProtokit.a" for Unix and "Protokit.lib"
|
||
for Win32). Shared or dynamically-linked versions of these libraries
|
||
may also be built from the NORM source code or provided. Depending
|
||
upon the platform, some additional library dependencies may be
|
||
required to support the needs of NORM and/or Protokit. These are
|
||
described below.</P>
|
||
<H2 CLASS="western"><A NAME="Unix Platforms">Unix Platforms</A></H2>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; font-style: normal">To
|
||
support IPv6 operation, the NORM and the <I>Protokit</I> library must
|
||
be compiled with the "HAVE_IPV6" macro defined. This is
|
||
default in the NORM and <I>Protokit</I> Makefiles for platforms that
|
||
support IPv6. It is important that NORM and <I>Protokit</I> be built
|
||
with this macro defined the same. With NORM, it is recommended that
|
||
"large file support" options be enabled when possible.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
NORM API uses threading so that the NORM protocol engine may run
|
||
independent of the application. Thus the "POSIX Threads"
|
||
library must be included ("-'pthread") in the linking step.
|
||
MacOS/BSD also requires the addition of the "-lresolv"
|
||
(resolver) library and Solaris requires the dynamic loader,
|
||
network/socket, and resolver libraries ("–lnsl –lsocket
|
||
–lresolv") to achieve successful compilation. The Makefiles in
|
||
the NORM source code distribution are a reference for these
|
||
requirements. Note that MacOS 9 and earlier are not supported.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 "large
|
||
file support". 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 "normApi.h"
|
||
depends upon this compilation flag).</P>
|
||
<H2 CLASS="western"><A NAME="Win32/WiNCE Platforms">Win32/WiNCE Platforms</A></H2>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 "Protokit" and "NORM" project files,
|
||
it is important that common code generation settings be used when
|
||
building the NORM application. The NORM and Protokit projects are
|
||
built with the "Multithreading DLL" 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="margin-bottom: 0.2in; font-style: normal">NORM
|
||
and Protokit also depend on the Winsock 2.0 ("ws2_32.lib"
|
||
(or "ws2.lib" (WinCE)) and the IP Helper API
|
||
("iphlpapi.lib") libraries and these must be included in
|
||
the project "Link" attributes.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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
|
||
<I>Protokit</I>-based code with debugging capabilities enabled.
|
||
However, this has been resolved in VC++ .NET and is hoped to be
|
||
resolved in the future for the WinCE build tools.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">Operation
|
||
on Windows NT4 (and perhaps other older Windows operating systems)
|
||
requires that the compile time macro <FONT FACE="Courier"><I>WINVER=0x0400</I></FONT>
|
||
defined. This is because the version of the IP Helper API library
|
||
(<I>iphlpapi.lib</I>) used by <I>Protolib</I> (and hence NORM) for
|
||
this system doesn't support some of the functions defined for this
|
||
library. This may be related to IPv6 support issues so it may be
|
||
possible that the <I>Protolib</I> build could be tweaked to provide a
|
||
single binary executable suitable for IPv4 operation only across a
|
||
large range of Windows platforms.</P>
|
||
<H1 CLASS="western"><A NAME="API Reference">API Reference</A></H1>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
section provides a reference to the NORM API variable types,
|
||
constants and functions.</P>
|
||
<H2 CLASS="western"><A NAME="API Variable Types and Constants">API Variable Types and Constants</A></H2>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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
|
||
<FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT>). 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
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_INVALID</I></FONT> corresponds to
|
||
an invalid transport object reference.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormObjectType">NormObjectType</A></H3>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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" STYLE="margin-bottom: 0.2in"><FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT></P>
|
||
<LI><P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>, and</P>
|
||
<LI><P CLASS="western" STYLE="margin-bottom: 0.2in"><FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT></P>
|
||
</OL>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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, <FONT FACE="Courier"><I>NORM_OBJECT_NONE</I></FONT>, indicates
|
||
an invalid object type.
|
||
</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSize">NormSize</A></H3>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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
|
||
"large file support" enabled, as is the case with
|
||
distributed NORM library "Makefiles", 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="margin-bottom: 0.2in; 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 "recycled"
|
||
for use for future transport objects. NORM sender nodes assign these
|
||
values in a monotonically increasing fashion during the course of a
|
||
session as part of protocol operation. Typically, the application
|
||
should not need access to these values, but an API call
|
||
<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="margin-bottom: 0.2in; font-style: normal">The
|
||
<FONT FACE="Courier"><A HREF="#NormEventType">NormEventType</A></FONT> is an enumeration of NORM
|
||
API events. "Events" are used by the NORM API to signal the
|
||
application of significant NORM protocol operation events (e.g.,
|
||
receipt of a new receive object, etc). A description of possible
|
||
<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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>typedef
|
||
struct<BR>{<BR> <A HREF="#NormEventType">NormEventType</A> type;<BR> <A HREF="#NormSessionHandle">NormSessionHandle</A> session;<BR> <A HREF="#NormNodeHandle">NormNodeHandle</A> node;<BR> <A HREF="#NormObjectHandle">NormObjectHandle</A> object;<BR>}
|
||
<A HREF="#NormEvent">NormEvent</A>;</FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; font-style: normal">The
|
||
<FONT FACE="Courier"><A HREF="#NormFlushMode">NormFlushMode</A></FONT> type consists of the
|
||
following enumeration:</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>enum
|
||
<A HREF="#NormFlushMode">NormFlushMode</A><BR>{<BR> NORM_FLUSH_NONE,<BR> NORM_FLUSH_PASSIVE,<BR> NORM_FLUSH_ACTIVE<BR>};</FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; font-style: normal">The
|
||
<FONT FACE="Courier"><A HREF="#NormProbingMode">NormProbingMode</A></FONT> type consists of the
|
||
following enumeration:</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>enum
|
||
<A HREF="#NormProbingMode">NormProbingMode</A><BR>{<BR> NORM_PROBE_NONE,<BR> NORM_PROBE_PASSIVE,<BR> NORM_PROBE_ACTIVE<BR>};</FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; font-style: normal">The
|
||
<FONT FACE="Courier"><A HREF="#NormNackingMode">NormNackingMode</A></FONT> type consists of the
|
||
following enumeration:</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>enum
|
||
<A HREF="#NormNackingMode">NormNackingMode</A><BR>{<BR> NORM_NACK_NONE,<BR> NORM_NACK_INFO_ONLY,<BR> NORM_NACK_NORMAL<BR>};</FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; font-style: normal">The
|
||
<FONT FACE="Courier"><A HREF="#NormRepairBoundary">NormRepairBoundary</A></FONT> types consists of the
|
||
following enumeration:</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>enum
|
||
<A HREF="#NormRepairBoundary">NormRepairBoundary</A><BR>{<BR> NORM_BOUNDARY_BLOCK,<BR> NORM_BOUNDARY_OBJECT<BR>};</FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormAckingStatus">NormAckingStatus</A></H3>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
<FONT FACE="Courier"><A HREF="#NormAckingStatus">NormAckingStatus</A></FONT> consist of the following
|
||
enumeration:</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>enum
|
||
<A HREF="#NormAckingStatus">NormAckingStatus</A><BR>{<BR> NORM_ACK_INVALID,<BR> NORM_ACK_FAILURE,<BR> NORM_ACK_PENDING,<BR> NORM_ACK_SUCCESS<BR>};</FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
interpretation of these values is given in the descriptions of the
|
||
<FONT FACE="Courier"><A HREF="#NormGetAckingStatus()">NormGetAckingStatus()</A></FONT> function.</P>
|
||
<H2 CLASS="western"><A NAME="API Initialization and Operation">API Initialization and Operation</A></H2>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
first step in using the NORM API is to create an "instance"
|
||
of the NORM protocol engine. Note that multiple instances may be
|
||
created by the application if necessary, but generally only a single
|
||
instance is required since multiple <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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 <FONT FACE="Courier"><U>instance</U></FONT>
|
||
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="margin-bottom: 0.2in; font-style: normal">The
|
||
function has no return value.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStopInstance()">NormStopInstance()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormStopInstance(<A HREF="#NormInstanceHandle">NormInstanceHandle</A> instance);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function immediately stops the NORM protocol engine thread
|
||
corresponding to the given <FONT FACE="Courier"><U>instance</U></FONT>
|
||
parameter. It also posts a "dummy" notification event so
|
||
that if another thread is blocked on a call to <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>,
|
||
that thread will be released. Hence, for some multithreaded uses of
|
||
the NORM API, this function may be useful as a preliminary step to
|
||
safely coordinate thread shutdown before a call is made to
|
||
<FONT FACE="Courier"><A HREF="#NormDestroyInstance()">NormDestroyInstance()</A></FONT>. After
|
||
<FONT FACE="Courier"><A HREF="#NormStopInstance()">NormStopInstance()</A></FONT> is called and any
|
||
pending events posted prior to its call have been retrieved,
|
||
<FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT> will return a value of
|
||
<FONT FACE="Courier"><I>false</I></FONT>.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">When
|
||
this function is invoked, state for any <I>NormSessions</I>
|
||
associated with the given <FONT FACE="Courier"><U>instance</U></FONT>
|
||
is "frozen". The complementary function,
|
||
<FONT FACE="Courier"><A HREF="#NormRestartInstance()">NormRestartInstance()</A></FONT> can be subsequently
|
||
used to "unfreeze" and resume NORM protocol operation (a
|
||
new thread is created and started).</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
function has no return value.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormRestartInstance()">NormRestartInstance()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormRestartInstance(<A HREF="#NormInstanceHandle">NormInstanceHandle</A> instance);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function creates and starts an operating system thread to resume NORM
|
||
protocol engine operation for the given <FONT FACE="Courier"><U>instance</U></FONT>
|
||
that was previously stopped by a call to <FONT FACE="Courier"><A HREF="#NormStopInstance()">NormStopInstance()</A></FONT>.
|
||
It is not expected that this function will be used often, but there
|
||
may be special application cases where "freezing" and later
|
||
resuming NORM protocol operation may be useful.
|
||
</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
function returns <FONT FACE="Courier"><I>true</I></FONT> when the
|
||
NORM protocol engine thread is successfully restarted, and <FONT FACE="Courier"><I>false</I></FONT>
|
||
otherwise.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in"><BR><BR>
|
||
</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetCacheDirectory()">NormSetCacheDirectory()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetCacheDirectory(<A HREF="#NormInstanceHandle">NormInstanceHandle</A> instance,<BR> const
|
||
char* cachePath);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function sets the directory path used by receivers to cache
|
||
newly-received <FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT>
|
||
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="margin-bottom: 0.2in; font-style: normal">The
|
||
<FONT FACE="Courier"><U>instance</U></FONT> parameter specifies the
|
||
NORM protocol engine instance (all NormSessions associated with that
|
||
<FONT FACE="Courier"><U>instance</U></FONT> share the same cache
|
||
path) and the <FONT FACE="Courier"><U>cachePath</U></FONT> is a
|
||
string specifying a valid (and writable) directory path. The function
|
||
returns <FONT FACE="Courier"><I>true</I></FONT> on success and <FONT FACE="Courier"><I>false</I></FONT>
|
||
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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormGetNextEvent(<A HREF="#NormInstanceHandle">NormInstanceHandle</A> instance,<BR> <A HREF="#NormEvent">NormEvent</A>* theEvent);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 <FONT FACE="Courier"><I>select()</I></FONT>
|
||
(UNIX) or <FONT FACE="Courier"><I>WaitForMultipleObjects()</I></FONT>
|
||
(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="margin-bottom: 0.2in; 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="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 corresponding event "object" field, the
|
||
application may successfully write to the indicated stream object.
|
||
Note this event is not dispatched until a call to
|
||
<FONT FACE="Courier">NormEnqueueFile()</FONT>, <FONT FACE="Courier">NormEnqueueData()</FONT>,
|
||
or <FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT> fails because of
|
||
a filled transmit cache or stream buffer.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="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. If the handle of a sender
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT> is given in
|
||
the corresponding event "object" field, this indicates
|
||
the stream transmit buffer has been emptied and the sender
|
||
application may write to the stream (Use of <FONT FACE="Courier"><I>NORM_TX_QUEUE_VACANCY</I></FONT>
|
||
may be preferred for this purpose since it allows the application
|
||
to keep the NORM protocol engine busier sending data, resulting in
|
||
higher throughput when attempting very high transfer rates).</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="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 "robust factor" value)
|
||
that the receiver set no longer has any pending repair requests.
|
||
Note the use of NORM's optional positive acknowledgement feature
|
||
is more deterministic in this regards, but this notification is
|
||
useful when there are non-acking (NACK-only) receivers. The
|
||
default NORM robust factor of 20 (20 flush messages are sent at
|
||
end-of-transmission) provides a high assurance of reliable
|
||
transmission, even with packet loss rates of 50%.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="page-break-inside: avoid"><FONT FACE="Courier"><I>NORM_TX_WATERMARK_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 initiated by a
|
||
prior application call to <FONT FACE="Courier"><A HREF="#NormSetWatermark()">NormSetWatermark()</A></FONT>
|
||
has completed The posting of this event indicates the appropriate
|
||
time for the application to make a call <FONT FACE="Courier"><A HREF="#NormGetAckingStatus()">NormGetAckingStatus()</A></FONT>
|
||
to determine the results of the watermark flushing process.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="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 "object" field has completed at least one pass
|
||
of total transmission. Note that this does not guarantee that
|
||
reliable transmission has yet completed; only that the entire
|
||
object content has been transmitted. Depending upon network
|
||
behavior, several rounds of NACKing and repair transmissions may
|
||
be required to complete reliable transfer.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="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 "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
|
||
"object". After this event, the given "object"
|
||
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="page-break-inside: avoid"><FONT FACE="Courier"><I>NORM_LOCAL_SENDER_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
|
||
"graceful shutdown" of its participation as a sender in
|
||
the indicated "session" (see <FONT FACE="Courier"><A HREF="#NormStopSender()">NormStopSender()</A></FONT>).</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="page-break-inside: avoid"><FONT FACE="Courier"><I>NORM_CC_ACTIVE</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This event indicates that congestion control feedback from
|
||
receivers has begun to be received (<I>This also implies that
|
||
receivers in the group are actually present and can be used as a
|
||
cue to begin data transmission.</I>). Note that congestion control
|
||
must be enabled (see <FONT FACE="Courier"><A HREF="#NormSetCongestionControl()">NormSetCongestionControl()</A></FONT>)
|
||
for this event to be posted. Congestion control feedback can be
|
||
assumed to be received until a <FONT FACE="Courier"><I>NORM_CC_INACTIVE</I></FONT>
|
||
event is posted.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="page-break-inside: avoid"><FONT FACE="Courier"><I>NORM_CC_INACTIVE</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This event indicates there has been no recent congestion control
|
||
feedback received from the receiver set and that the local NORM
|
||
sender has reached its minimum transmit rate. Applications may
|
||
wish to refrain from new data transmission until a <FONT FACE="Courier"><I>NORM_CC_ACTIVE</I></FONT>
|
||
event is posted. This notification is only posted when congestion
|
||
control operation is enabled (see <FONT FACE="Courier"><A HREF="#NormSetCongestionControl()">NormSetCongestionControl()</A></FONT>)
|
||
<I>and</I> a previous <FONT FACE="Courier"><I>NORM_CC_ACTIVE</I></FONT>
|
||
event has occurred.</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="page-break-inside: avoid"><FONT FACE="Courier"><I>NORM_REMOTE_SENDER_NEW</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This event is posted when a receiver first receives messages from
|
||
a specific remote NORM sender. This marks the beginning of the
|
||
interval during which the application may reference the provided
|
||
"node" handle (<FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>).</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="page-break-inside: avoid"><FONT FACE="Courier"><I>NORM_REMOTE_SENDER_ACTIVE</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid"><A NAME="OLE_LINK5"></A><A NAME="OLE_LINK4"></A>
|
||
This event is posted when a previously inactive (or new) remote
|
||
sender is detected operating as an active sender within the
|
||
session.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="page-break-inside: avoid"><FONT FACE="Courier"><I>NORM_REMOTE_SENDER_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="page-break-inside: avoid"><FONT FACE="Courier"><I>NORM_REMOTE_SENDER_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 "node" handle.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="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 "object" (<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="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 "object" is received.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="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 "object"
|
||
has newly received data content.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="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 "object" 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="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 "object" 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="page-break-inside: avoid"><FONT FACE="Courier"><I>NORM_GRTT_UPDATED</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This notification indicates that either the local sender estimate
|
||
of GRTT has changed, or that a remote sender's estimate of GRTT
|
||
has changed. The "sender" member of the <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT>
|
||
is set to <FONT FACE="Courier"><I>NORM_NODE_INVALID</I></FONT> if
|
||
the local sender's GRTT estimate has changed or to the
|
||
<FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> of the remote sender
|
||
that has updated its estimate of GRTT.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="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 <FONT FACE="Courier"><A HREF="#NormEventType">NormEventType</A></FONT> indicates an
|
||
invalid or "null" notification which should be ignored.</P>
|
||
</TD>
|
||
</TR>
|
||
</TABLE>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in"><BR><BR>
|
||
</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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" STYLE="margin-bottom: 0.2in">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 not needed by the application)).</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormGetDescriptor()">NormGetDescriptor()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 <FONT FACE="Courier"><U>instance</U></FONT>.
|
||
The descriptor (or WIN32 HANDLE) is suitable for use as an input (or
|
||
"read") 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 <FONT FACE="Courier"><I>select()</I></FONT>
|
||
system call (UNIX) (or <FONT FACE="Courier"><I>WaitForMultipleObjects()</I></FONT>
|
||
(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 "read"
|
||
descriptor.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 <FONT FACE="Courier"><I>NORM_DESCRIPTOR_INVALID</I></FONT>
|
||
is returned.</P>
|
||
<H2 CLASS="western"><A NAME="Session Creation and Control Functions">Session Creation and Control Functions</A></H2>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">Whether
|
||
participating in a NORM protocol session as a sender, receiver, or
|
||
both, there are some common API calls used to instantiate a
|
||
<I>NormSession</I> and set some common session parameters. Functions
|
||
are provided to control network socket and multicast parameters.
|
||
Additionally, a "user data" value may be associated with a
|
||
<FONT FACE="Courier"><A HREF="#NormSessionHandle">NormSessionHandle</A></FONT> for programming
|
||
convenience when dealing with multiple sessions.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormCreateSession()">NormCreateSession()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormSessionHandle">NormSessionHandle</A>
|
||
NormCreateSession(<A HREF="#NormInstanceHandle">NormInstanceHandle</A> instance,<BR> const
|
||
char* address,<BR> unsigned
|
||
short port,<BR> <A HREF="#NormNodeId">NormNodeId</A> localId);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function creates a NORM protocol session (<I>NormSession</I>) using
|
||
the address (multicast or unicast) 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"><U>instance</U></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"><U>address</U></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 <FONT FACE="Courier"><U>address</U></FONT>
|
||
(along with the <FONT FACE="Courier"><U>port</U></FONT> 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 <FONT FACE="Courier"><U>address</U></FONT> 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"><U>port</U></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 <FONT FACE="Courier"><U>address</U></FONT>
|
||
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"><U>localId</U></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 <FONT FACE="Courier"><I>NORM_NODE_ANY
|
||
</I></FONT>or <FONT FACE="Courier"><I>NORM_NODE_ANY</I></FONT> 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 "default" IP address (based on
|
||
the computer's default host name). Note there is a chance that
|
||
this approach may not provide unique node identifiers in some
|
||
situations and the NORM protocol does not currently provide a
|
||
mechanism to detect or resolve <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="margin-bottom: 0.2in; 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 <FONT FACE="Courier"><I>NORM_SESSION_INVALID</I></FONT>
|
||
is returned upon error.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormDestroySession()">NormDestroySession()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; font-style: normal">This
|
||
function immediately terminates the application's participation in
|
||
the <I>NormSession</I> identified by the <FONT FACE="Courier"><U>session</U></FONT>
|
||
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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; font-style: normal">This
|
||
function retrieves the "user data" 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 "default" IP network address.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetTxPort(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> unsigned
|
||
short txPort);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetRxPortReuse(<A HREF="#NormSessionHandle">NormSessionHandle</A>
|
||
session,<BR> bool enable,<BR> bool bindToSessionAddr
|
||
= true);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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>enable</U></FONT> parameter is set
|
||
to <FONT FACE="Courier"><I>true</I></FONT>, reuse of the <I>NormSession</I>
|
||
port number is enabled, and, if the <FONT FACE="Courier"><U>bindToSessionAddr</U></FONT>
|
||
is also set to <FONT FACE="Courier"><I>true</I></FONT> (default), 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>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">When
|
||
this call is not made, the default binding to IP address INADDR_ANY
|
||
(equivalent to when this call is made and <FONT FACE="Courier"><U>bindToSessionAddr</U></FONT>
|
||
is set to <FONT FACE="Courier"><I>false</I></FONT>) allows the
|
||
<I>NormSession</I> receive socket to receive <I>any</I> multicast or
|
||
unicast transmissions to the session port number provided in the call
|
||
to <FONT FACE="Courier"><A HREF="#NormCreateSession()">NormCreateSession()</A></FONT>. 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetMulticastInterface(<A HREF="#NormSessionHandle">NormSessionHandle</A>
|
||
session,<BR> const
|
||
char* interfaceName);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>NormSetMulticastInterface(session,
|
||
"interface1");<BR>NormStartReceiver(session,
|
||
...);<BR>NormSetMulticastInterface(session, "interface2");</FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">will
|
||
result in NORM group membership (i.e. multicast reception) being
|
||
managed on "interface1" while NORM multicast transmissions
|
||
are made via "interface2".</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetTTL(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> unsigned
|
||
char ttl);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 "hops" that a generated multicast
|
||
packet may traverse before being dropped. For example, if TTL is
|
||
equal to one, the transmissions will be limited to the local area
|
||
network (LAN) of the host computers network interface. Larger TTL
|
||
values should be specified to span large networks. Also note that
|
||
some multicast router configurations use artificial "TTL
|
||
threshold" values to constrain some multicast traffic to an
|
||
administrative boundary. In these cases. the NORM TTL setting must
|
||
also exceed the router "TTL threshold" in order for the
|
||
NORM traffic to be allowed to exit the administrative area.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetTOS(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> unsigned
|
||
char tos);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 "flow" of
|
||
packets may merit special Quality-of-Service (QoS) treatment by
|
||
network devices. Users should refer to applicable QoS information for
|
||
their network to determine the expected interpretation and treatment
|
||
(if any) of packets with explicit TOS marking.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetLoopback(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> bool loopbackEnable);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; font-style: normal">This
|
||
function has no return values.</P>
|
||
<H2 CLASS="western"><A NAME="NORM Sender Functions">NORM Sender Functions</A></H2>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
functions described in this section apply only to NORM sender
|
||
operation. Applications may participate strictly as senders or as
|
||
receivers, or may act as both in the context of a NORM protocol
|
||
session. The NORM sender is responsible for most parameters
|
||
pertaining to its transmission of data. This includes transmission
|
||
rate, data segmentation sizes, FEC coding parameters, stream buffer
|
||
sizes, etc.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStartSender()">NormStartSender()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormStartSender(<A HREF="#NormSessionHandle">NormSessionHandle</A> sessionHandle<BR> <A HREF="#NormSessionId">NormSessionId</A> sessionId<BR> unsigned
|
||
long bufferSpace<BR> unsigned
|
||
short segmentSize,<BR> unsigned
|
||
char blockSize,<BR> unsigned
|
||
char numParity);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 <FONT FACE="Courier"><U>bufferSpace</U></FONT>
|
||
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 <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>
|
||
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 "<I>(n,k)</I>" nomenclature, the <FONT FACE="Courier"><U>blockSize</U></FONT>
|
||
value corresponds to <I>"k".</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 "<I>(n,k)"</I>
|
||
nomenclature mention above, the <FONT FACE="Courier"><U>numParity</U></FONT>
|
||
value corresponds to "<I>n-k</I>". 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="margin-bottom: 0.2in; 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 "<I>sessionId</I>" 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="margin-bottom: 0.2in; 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
|
||
</I><FONT FACE="Courier"><I>NormGetError(<A HREF="#NormSessionHandle">NormSessionHandle</A> session)</I></FONT>
|
||
<I>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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormStopSender(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> bool graceful
|
||
= false);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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
|
||
"graceful shutdown" 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_SENDER_CLOSED,</I></FONT> is
|
||
dispatched when the graceful shutdown process has completed.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal"><I>(NOTE:
|
||
The "</I><FONT FACE="Courier"><I><U>graceful</U></I></FONT><I>"
|
||
parameter is currently not available, and the current behavior of
|
||
this API call corresponds to the default behavior of </I><FONT FACE="Courier"><I><U>graceful</U></I></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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetTransmitRate(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> double rate);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetTxSocketBuffer(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> unsigned
|
||
int bufferSize);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetTransmitRate(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> bool enable);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetTransmitRateBounds(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> double rateMin,<BR> double rateMax);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 "<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>"
|
||
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="margin-bottom: 0.2in; 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> <
|
||
<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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetTransmitCacheBounds(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> <A HREF="#NormSize">NormSize</A> sizeMax,<BR> unsigned
|
||
int countMin,<BR> unsigned
|
||
int countMax);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 "purges"
|
||
older objects from its "transmit cache" 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="margin-bottom: 0.2in; 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"><I><U>countMax</U></I></FONT>
|
||
<I>must be greater than or equal to </I><FONT FACE="Courier"><I><U>countMin</U></I></FONT>
|
||
<I>and </I><FONT FACE="Courier"><I><U>countMin</U></I></FONT> <I>is
|
||
recommended to be at least two.</I></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 "group
|
||
join" policies that would allow the receivers to request
|
||
transmission of cached content.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetAutoParity(<A HREF="#NormSessionHandle">NormSessionHandle</A> sessionHandle,
|
||
<BR> unsigned
|
||
char autoParity);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function sets the quantity of proactive "auto parity"
|
||
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="margin-bottom: 0.2in; font-style: normal">The
|
||
use of proactively-sent "auto parity" may eliminate the
|
||
need for any receiver NACKing to achieve reliable transfer in
|
||
networks with low packet loss. However, note that the quantity of
|
||
"auto parity" set adds overhead to transport object
|
||
transmission. In networks with a predictable level of packet loss and
|
||
potentially large round-trip times, the use of "auto parity"
|
||
may allow lower latency in the reliable delivery process. Also, its
|
||
use may contribute to a smaller amount of receiver feedback as only
|
||
receivers with exceptional packet loss may need to NACK for
|
||
additional repair content.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; font-style: normal">This
|
||
function has no return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormGetGrttEstimate()">NormGetGrttEstimate()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>double
|
||
NormGetGrttEstimate(<A HREF="#NormSessionHandle">NormSessionHandle</A> session);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function returns the sender's current estimate(in seconds) of group
|
||
round-trip timing (GRTT) for the given NORM <FONT FACE="Courier"><U>session</U></FONT>.
|
||
This function may be useful for applications to leverage for other
|
||
purposes the assessment of round-trip timing made by the NORM
|
||
protocol engine. For example, an application may scale its own
|
||
timeouts based on connectivity delays among participants in a NORM
|
||
session. Note that the <FONT FACE="Courier"><I>NORM_GRTT_UPDATED</I></FONT>
|
||
event is posted (see <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>)
|
||
by the NORM protocol engine to indicate when changes in the local
|
||
sender or remote senders' GRTT estimate occurs.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function returns the current sender group round-trip timing (GRTT)
|
||
estimate (in units of seconds). A value of <FONT FACE="Courier"><I>-1.0</I></FONT>
|
||
is returned if an invalid <FONT FACE="Courier"><U>session</U></FONT>
|
||
value is provided.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetGrttEstimate()">NormSetGrttEstimate()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetGrttEstimate(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> double grtt);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetGrttMax(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> double grttMax);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetGrttProbingMode(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> <A HREF="#NormProbingMode">NormProbingMode</A> probingMode);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetGrttProbingInterval(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> double intervalMin,<BR> double intervalMax);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; font-style: normal">This
|
||
function has no return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetBackoffFactor()">NormSetBackoffFactor()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetBackoffFactor(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> double backoffFactor);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function sets the sender's "backoff factor" for the given
|
||
<FONT FACE="Courier"><U>session</U></FONT>.. The backoff factor is
|
||
used to scale various timeouts related to the NACK repair process.
|
||
The sender advertises its backoff factor setting to the receiver
|
||
group in NORM protocol message headers. The default backoff factor
|
||
for NORM sessions is <FONT FACE="Courier"><I>4.0</I></FONT>. The
|
||
backoff factor is used to determine the maximum time that receivers
|
||
may delay NACK transmissions (and other feedback messages) as part of
|
||
NORM's probabilistic feedback suppression technique. For example, the
|
||
maximum NACK delay time is <FONT FACE="Courier"><U>backoffFactor</U></FONT><FONT FACE="Courier">*GRTT</FONT>.
|
||
Thus a large <FONT FACE="Courier"><U>backoffFactor</U></FONT> value
|
||
introduces latency into the NORM repair process. However, a small
|
||
<FONT FACE="Courier"><U>backoffFactor</U></FONT> value causes
|
||
feedback suppression to be less effective and increases the risk of
|
||
feedback implosion for large receiver group sizes. The default
|
||
setting of <FONT FACE="Courier"><I>4.0</I></FONT> provides reasonable
|
||
feedback suppression for moderate to large group sizes when multicast
|
||
feedback is possible. The NORM specification recommends a backoff
|
||
factor value of <FONT FACE="Courier"><I>6.0</I></FONT> when unicast
|
||
feedback is used. However, for demanding applications (with respect
|
||
to repair latency) when group sizes are modest, a small (even <FONT FACE="Courier"><I>0.0</I></FONT>)
|
||
<FONT FACE="Courier"><U>backoffFactor</U></FONT> value can be
|
||
specified to reduce the latency of reliable data delivery.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function has no return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetGroupSize()">NormSetGroupSize()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetGroupSize(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> unsigned
|
||
int groupSize);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function sets the sender's estimate of receiver group size for the
|
||
given session. The sender advertises its group size setting to the
|
||
receiver group in NORM protocol message headers that, in turn, use
|
||
this information to shape the distribution curve of their random
|
||
timeouts for the timer-based, probabilistic feedback suppression
|
||
technique used in the NORM protocol. Note that the <FONT FACE="Courier"><U>groupSize</U></FONT>
|
||
estimate does not have to be very accurate and values within an order
|
||
of magnitude of the actual group size tend to produce acceptable
|
||
performance. The default group size setting in NORM is <FONT FACE="Courier"><I>1,000</I></FONT>
|
||
and thus can work well for a wide range of actual receiver group
|
||
sizes. The penalty of an overly large estimate is statistically a
|
||
little more latency in reliable data delivery with respect to the
|
||
round trip time and some potential for excess feedback. A substantial
|
||
underestimation of group size increases the risk of feedback
|
||
implosion. Currently, the NORM implementation does not attempt to
|
||
automatically measure group size from receiver feedback. Applications
|
||
could add their own mechanism for this (perhaps keeping explicit
|
||
track of group membership), or it is possible that future versions of
|
||
the NRL NORM implementation may have some provision for automatic
|
||
group size estimation by the sender based on receiver feedback
|
||
messages.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function has no return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormFileEnqueue()">NormFileEnqueue()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
NormFileEnqueue(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> const
|
||
char* filename,<BR> const
|
||
char* infoPtr =
|
||
NULL,<BR> unsigned
|
||
int infoLen = 0);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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
|
||
"repair window" as needed for some applications. While
|
||
relative paths with respect to the current working directory may be
|
||
used, it is recommended that full paths be used when possible. The
|
||
optional <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="margin-bottom: 0.2in; font-style: normal">The
|
||
application is allowed to enqueue multiple transmit objects within in
|
||
the "transmit cache" 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="margin-bottom: 0.2in; 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 "transmit cache" 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
NormDataEnqueue(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> const
|
||
char* dataPtr,<BR> unsigned
|
||
int dataLen,<BR> const
|
||
char* infoPtr =
|
||
NULL,<BR> unsigned
|
||
int infoLen = 0);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; font-style: normal">The
|
||
application is allowed to enqueue multiple transmit objects within in
|
||
the "transmit cache" 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="margin-bottom: 0.2in; 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 "transmit cache" 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="NormRequeueObject()">NormRequeueObject()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool NormRequeueObject(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> <A HREF="#NormObjectHandle">NormObjectHandle</A> object);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function allows the application to resend (or reset transmission of)
|
||
a <FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT> or
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT> transmit object
|
||
that was previously enqueued for the indicated <FONT FACE="Courier"><U>session</U></FONT>.
|
||
This function is useful for applications sending to silent
|
||
(non-NACKing) receivers as it enables the receivers to take advantage
|
||
of multiple retransmissions of objects (including any auto-parity
|
||
set, see <FONT FACE="Courier"><A HREF="#NormSetAutoParity()">NormSetAutoParity()</A></FONT>) to more
|
||
robustly receive content. The <FONT FACE="Courier"><U>object</U></FONT>
|
||
parameter must be a valid transmit <A HREF="#NormObjectHandle">NormObjectHandle</A> that has not yet
|
||
been "purged" from the sender's transmit queue. Upon
|
||
success, the specified <FONT FACE="Courier"><U>object</U></FONT> will
|
||
be fully retransmitted using the same NORM object transport
|
||
identifier as was used on its initial transmission. This call may be
|
||
made at any time to restart transmission of a previously-enqueued
|
||
object, but the <FONT FACE="Courier"><I>NORM_TX_OBJECT_SENT</I></FONT>
|
||
or <FONT FACE="Courier"><I>NORM_TX_FLUSH_COMPLETED</I></FONT>
|
||
notifications can serve as good cues for an appropriate time to
|
||
resend an object. If multiple objects are re-queued, they will be
|
||
resent in order of their initial enqueuing.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
transmit cache bounds set by <FONT FACE="Courier"><A HREF="#NormSetTransmitCacheBounds()">NormSetTransmitCacheBounds()</A></FONT>
|
||
determine the number of previously-sent objects retained in the
|
||
sender's transmit queue and that are thus eligible to be requeued for
|
||
retransmission. An object may be requeued via this call multiple
|
||
times, but each distinct requeue should be done after an indication
|
||
such as <FONT FACE="Courier"><I>NORM_TX_OBJECT_SENT</I></FONT> or
|
||
<FONT FACE="Courier"><I>NORM_TX_FLUSH_COMPLETED</I></FONT> for the
|
||
given object. Otherwise, the object will simply be reset from its
|
||
current transmission point to transmit from the beginning (i.e.
|
||
restart). Note that the object type <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>
|
||
cannot currently be requeued.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in"><I>(TBD – should a
|
||
"numRepeats" parameter be added to this function?)</I></P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">A
|
||
value of <FONT FACE="Courier"><I>true</I></FONT> is returned upon
|
||
success and a value of <FONT FACE="Courier"><I>false</I></FONT> is
|
||
returned upon failure. Possible reasons for failure include an
|
||
invalid object handle was provided (i.e. a non-transmit object or
|
||
transmit object that has been "purged" from the transmit
|
||
queue (see <FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT>))
|
||
or the provided <FONT FACE="Courier"><U>object</U></FONT> was of type
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStreamOpen()">NormStreamOpen()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
NormStreamOpen(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> unsigned
|
||
int bufferSize,<BR> const
|
||
char* infoPtr =
|
||
NULL,<BR> unsigned
|
||
int infoLen = 0);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 "repair window" which limits how far
|
||
back the sender will "rewind" to satisfy receiver repair
|
||
requests.
|
||
</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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
|
||
"resync" 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; font-style: normal">Note
|
||
there is no corresponding "open" 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="margin-bottom: 0.2in; 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 "transmit cache" 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormStreamClose(<A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
streamHandle,<BR> bool graceful
|
||
= false);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 "graceful" shutdown of
|
||
a transmit stream. In this case, the sender application will be
|
||
notified that stream has (most likely) completed reliable transfer
|
||
via the <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 "FLAG_STREAM_END"
|
||
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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>unsigned int
|
||
NormStreamWrite(<A HREF="#NormObjectHandle">NormObjectHandle</A> streamHandle<BR> const
|
||
char* buffer,<BR> unsigned
|
||
int numBytes);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 "push mode" is set to <FONT FACE="Courier"><I>false</I></FONT>
|
||
(default, see <FONT FACE="Courier">NormStreamSetPushMode()</FONT> for
|
||
details). If the stream's "push mode" 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. Other flow control strategies are
|
||
possible using the <FONT FACE="Courier"><A HREF="#NormSetWatermark()">NormSetWatermark()</A></FONT>
|
||
function.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
<FONT FACE="Courier">NormEvents </FONT><FONT FACE="Courier"><I>NORM_TX_QUEUE_EMPTY</I></FONT>
|
||
and <FONT FACE="Courier"><I>NORM_TX_QUEUE_VACANCY</I></FONT> are
|
||
posted with the <I><A HREF="#NormEvent">NormEvent</A>::object</I> field set to a valid sender
|
||
stream <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT> to indicate when
|
||
the stream is ready for writing via this function. Note that the
|
||
<FONT FACE="Courier"><I>NORM_TX_QUEUE_VACANCY </I></FONT>event type
|
||
is posted <I>only after</I> the stream's transmit buffer has been
|
||
completely filled. Thus, the application <I>must</I> make a call to
|
||
<FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT> that copies less than
|
||
the requested <FONT FACE="Courier"><U>numBytes</U></FONT> value
|
||
(return value less than <FONT FACE="Courier"><U>numBytes</U></FONT>)
|
||
before additional <FONT FACE="Courier"><I>NORM_TX_QUEUE_VACANCY</I></FONT>
|
||
events are posted for the given <FONT FACE="Courier"><U>streamHandle</U></FONT>
|
||
(i.e., the event type is not re-posted until the application has
|
||
again filled the available stream transmit buffer space). By cueing
|
||
off of <FONT FACE="Courier"><I>NORM_TX_QUEUE_EMPTY</I></FONT>, the
|
||
application can write its "freshest" available data to the
|
||
stream, but by cueing off of <FONT FACE="Courier"><I>NORM_TX_QUEUE_VACANCY</I></FONT>,
|
||
an application can keep the NORM protocol engine busiest, to achieve
|
||
the maximum possible throughput at high data rates.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function returns the number of bytes of data successfully enqueued
|
||
for NORM stream transmission. If the underlying send stream buffer is
|
||
full, this function may return zero or a value less than the
|
||
requested <FONT FACE="Courier"><U>numBytes</U></FONT>.
|
||
</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStreamFlush()">NormStreamFlush()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormStreamFlush(<A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
streamHandle,<BR> bool eom
|
||
= false,<BR> <A HREF="#NormFlushMode">NormFlushMode</A> flushMode
|
||
= NORM_FLUSH_PASSIVE);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function causes an immediate "flush" 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 "flush" 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 "small" 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 "active" 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormStreamSetAutoFlush(<A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
streamHandle<BR> <A HREF="#NormFlushMode">NormFlushMode</A> flushMode);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function sets "<I>automated</I> flushing" for the NORM
|
||
transmit stream indicated by the <FONT FACE="Courier"><U>streamHandle</U></FONT>
|
||
parameter. By default, a NORM transmit stream is "flushed"
|
||
only when explicitly requested by the application (see
|
||
<FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT></FONT>).
|
||
However, to simplify programming, the NORM API allows that automated
|
||
flushing be enabled such that the "flush" operation occurs
|
||
every time the <I>full</I> requested <FONT FACE="Courier"><U>buffer</U></FONT>
|
||
provided to a <FONT FACE="Courier"><FONT SIZE=2><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 "chatty" than its typical "bulk
|
||
transfer" form of operation, but can provide a useful capability
|
||
for some applications.
|
||
</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 FACE="Courier"><FONT SIZE=2><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 "runt" 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormStreamSetPushEnable(<A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
streamHandle<BR> bool pushEnable);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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
|
||
"push mode" 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 "push
|
||
mode" 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetWatermark(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> <A HREF="#NormObjectHandle">NormObjectHandle</A> object);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function specifies a "watermark" transmission point at
|
||
which NORM sender protocol operation should perform a flushing
|
||
process and/or positive acknowledgment collection for a given
|
||
<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 FACE="Courier">NormEnqueueFile()</FONT><FONT FACE="Courier"><FONT SIZE=2>,</FONT></FONT>
|
||
<FONT FACE="Courier">NormEnqueueData()</FONT>, or <FONT FACE="Courier"><A HREF="#NormStreamOpen()">NormStreamOpen()</A></FONT>).
|
||
For <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>
|
||
transmission, the positive acknowledgment collection begins
|
||
immediately, using the current position (offset of most recent data
|
||
written) of the sender stream as a reference.
|
||
</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
functions <FONT FACE="Courier"><A HREF="#NormAddAckingNode()">NormAddAckingNode()</A></FONT> and
|
||
<FONT FACE="Courier"><A HREF="#NormRemoveAckingNode()">NormRemoveAckingNode()</A></FONT> are used to manage
|
||
the list of <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> values
|
||
corresponding to NORM receivers that are expected to explicitly
|
||
acknowledge the watermark flushing messages transmitted by the
|
||
sender. Note that the <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT>
|
||
<FONT FACE="Courier"><I>NORM_NODE_NONE</I></FONT> may be included in
|
||
the list. Inclusion of <FONT FACE="Courier"><I>NORM_NODE_NONE</I></FONT>
|
||
forces the watermark flushing process to proceed through a full
|
||
<FONT FACE="Courier"><I>NORM_ROBUST_FACTOR</I></FONT> number of
|
||
rounds before completing, prompting any receivers that have not
|
||
completed reliable reception to the given watermark point to NACK for
|
||
any repair needs. If NACKs occur, the flushing process is reset and
|
||
repeated until completing with no NACKs for data through the given
|
||
watermark transmission point are received. Thus, even without
|
||
explicit positive acknowledgment, the sender can use this process (by
|
||
adding <FONT FACE="Courier"><I>NORM_NODE_NONE</I></FONT> to the
|
||
<FONT FACE="Courier"><U>session</U></FONT>'s list of acking nodes)
|
||
for a high level of assurance that the receiver set is "happy"
|
||
(completed reliable data reception) through the given <FONT FACE="Courier"><U>object</U></FONT>
|
||
(or stream transmission point).
|
||
</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
event <FONT FACE="Courier"><I>NORM_TX_WATERMARK_COMPLETED</I></FONT>
|
||
is posted for the given <FONT FACE="Courier"><U>session</U></FONT>
|
||
when the flushing process or positive acknowledgment collection has
|
||
completed. The process completes as soon as all listed receivers have
|
||
responded unless <FONT FACE="Courier"><I>NORM_NODE_NONE</I></FONT> is
|
||
included in the acking list. The sender application may use the
|
||
function <FONT FACE="Courier"><A HREF="#NormGetAckingStatus()">NormGetAckingStatus()</A></FONT> to
|
||
determine the degree of success of the flushing process in general or
|
||
for individual <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> values.
|
||
</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
flushing is conducted concurrently with ongoing data transmission and
|
||
does not impede the progress of reliable data transfer. Thus the
|
||
sender may still enqueue <I>NormObjects</I> for transmission (or
|
||
write to the existing stream) and the positive acknowledgement
|
||
collection and flushing procedure will be multiplexed with the
|
||
ongoing data transmission. However, the sender application may wish
|
||
to defer from or limit itself in sending more data until a
|
||
<FONT FACE="Courier"><I>NORM_TX_WATERMARK_COMPLETED</I></FONT> event
|
||
is received for the given <FONT FACE="Courier"><U>session</U></FONT>.
|
||
This provides a form of sender->receiver(s) flow control which
|
||
does not exist in NORM's default protocol operation. If a subsequent
|
||
call is made to <FONT FACE="Courier"><A HREF="#NormSetWatermark()">NormSetWatermark()</A></FONT> before
|
||
the current acknowledgement request has completed, the pending
|
||
acknowledgment request is canceled and the new one begins.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormAddAckingNode()">NormAddAckingNode()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormAddAckingNode(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> <A HREF="#NormNodeId">NormNodeId</A> nodeId);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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. Additionally a
|
||
value of <FONT FACE="Courier"><U>nodeId</U></FONT> equal to
|
||
<FONT FACE="Courier"><I>NORM_NODE_NONE</I></FONT> may be set to force
|
||
the watermark flushing process through a full <FONT FACE="Courier"><I>NORM_ROBUST_FACTOR</I></FONT>
|
||
number of rounds regardless of actual acking nodes. Otherwise the
|
||
flushing process is terminated when all of the nodes in the acking
|
||
node list have responded.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormRemoveAckingNode(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> <A HREF="#NormNodeId">NormNodeId</A> nodeId);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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>. Note that if the <FONT FACE="Courier"><U>nodeId</U></FONT>
|
||
<FONT FACE="Courier"><I>NORM_NODE_NONE</I></FONT> has been added to
|
||
the list, it too must be removed to change the watermark flushing
|
||
behavior if desired.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
function has no return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormGetAckingStatus()">NormGetAckingStatus()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormAckingStatus">NormAckingStatus</A>
|
||
NormGetAckingStatus(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> <A HREF="#NormNodeId">NormNodeId</A> nodeId
|
||
=
|
||
NORM_NODE_ANY);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function queries the status of the watermark flushing process and/or
|
||
positive acknowledgment collection initiated by a prior call to
|
||
<FONT FACE="Courier"><A HREF="#NormSetWatermark()">NormSetWatermark()</A></FONT> for the given <FONT FACE="Courier"><U>session</U></FONT>.
|
||
In general, it is expected that applications will invoke this
|
||
function <I>after</I> the corresponding <FONT FACE="Courier"><I>NORM_TX_WATERMARK_COMPLETED</I></FONT>
|
||
event has been posted. Setting the default parameter value <FONT FACE="Courier"><U>nodeId</U></FONT>
|
||
= <FONT FACE="Courier"><I>NORM_NODE_ANY</I></FONT> returns a "status"
|
||
indication for the overall process. Also, individual <FONT FACE="Courier"><U>nodeId</U></FONT>
|
||
values may be queried using the <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT>
|
||
values of receivers that were included in previous calls to
|
||
<FONT FACE="Courier"><A HREF="#NormAddAckingNode()">NormAddAckingNode()</A></FONT> to populate the
|
||
sender <FONT FACE="Courier"><U>session</U></FONT>'s acking node list.
|
||
</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">If
|
||
the flushing/acknowledgment process is being used for application
|
||
flow control, the sender application may wish to reset the watermark
|
||
and flushing process (using <FONT FACE="Courier"><A HREF="#NormSetWatermark()">NormSetWatermark()</A></FONT>)
|
||
if the response indicates that some nodes have failed to respond.
|
||
However, note that the flushing/acknowledgment process itself does
|
||
elicit NACKs from receivers as needed and is interrupted and reset by
|
||
any repair response that occurs. Thus, even by the time the flushing
|
||
process has completed (and <FONT FACE="Courier"><I>NORM_TX_WATERMARK_COMPLETED</I></FONT>
|
||
is posted) once, this is an indication that the NORM protocol has
|
||
made a valiant attempt to deliver the content. Resetting the
|
||
watermark process <I>can</I> increase robustness, but it may be in
|
||
vain to repeat this process multiple times when likely network
|
||
connectivity has been lost or expected receivers have failed (dropped
|
||
out, shut down, etc).</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
Possible return values include:</P>
|
||
<TABLE WIDTH=592 BORDER=1 BORDERCOLOR="#000000" CELLPADDING=8 CELLSPACING=0>
|
||
<COL WIDTH=200>
|
||
<COL WIDTH=358>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=200>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid; page-break-after: avoid">
|
||
NORM_ACK_INVALID</P>
|
||
</TD>
|
||
<TD WIDTH=358>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid; page-break-after: avoid">
|
||
The given session is invalid or the given <FONT FACE="Courier"><U>nodeId</U></FONT>
|
||
is not in the session's acking list.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=200>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid; page-break-after: avoid">
|
||
NORM_ACK_FAILURE</P>
|
||
</TD>
|
||
<TD WIDTH=358>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid; page-break-after: avoid">
|
||
The positive acknowledgement collection process did not receive
|
||
acknowledgment from every listed receiver (<FONT FACE="Courier"><U>nodeId</U></FONT>
|
||
= <FONT FACE="Courier"><I>NORM_NODE_ANY</I></FONT>) or the
|
||
identified <FONT FACE="Courier"><U>nodeId</U></FONT> did not
|
||
respond.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=200>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid; page-break-after: avoid">
|
||
NORM_ACK_PENDING</P>
|
||
</TD>
|
||
<TD WIDTH=358>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid; page-break-after: avoid">
|
||
The flushing process at large has not yet completed (<FONT FACE="Courier"><U>nodeId</U></FONT>
|
||
= <FONT FACE="Courier"><I>NORM_NODE_ANY</I></FONT>) or the given
|
||
individual <FONT FACE="Courier"><U>nodeId</U></FONT> is still
|
||
being queried for response.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=200>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
NORM_ACK_SUCCESS</P>
|
||
</TD>
|
||
<TD WIDTH=358>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
All receivers (<FONT FACE="Courier"><U>nodeId</U></FONT> =
|
||
<FONT FACE="Courier"><I>NORM_NODE_ANY</I></FONT>) responded with
|
||
positive acknowledgement or the given specific <FONT FACE="Courier"><U>nodeId</U></FONT>
|
||
did acknowledge.</P>
|
||
</TD>
|
||
</TR>
|
||
</TABLE>
|
||
<H2 CLASS="western"><A NAME="NORM Receiver Functions">NORM Receiver Functions</A></H2>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStartReceiver()">NormStartReceiver()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormStartReceiver(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> unsigned
|
||
long bufferSpace);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 NORM protocol engine will begin providing the
|
||
application with receiver-related <I><A HREF="#NormEvent">NormEvent</A></I> notifications,
|
||
and, unless <FONT FACE="Courier">NormSetSilentReceiver(</FONT><FONT FACE="Courier"><I>true</I></FONT><FONT FACE="Courier">)</FONT>
|
||
is invoked, respond to senders with appropriate protocol messages.
|
||
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 <FONT FACE="Courier"><U>bufferSpace</U></FONT>
|
||
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 "re-syncing" to the sender, resulting in
|
||
"outages" in the reliable transmissions from a sender (this
|
||
is analogous to a TCP connection timeout failure).
|
||
</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormStopReceiver(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> unsigned
|
||
int gracePeriod = 0);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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. "grace time" =
|
||
(<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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetRxSocketBuffer(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> unsigned
|
||
int bufferSize);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 "receiver" (or "sender")
|
||
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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetSilentReceiver(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> bool silent,<BR> INT32 maxDelay
|
||
= -1);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function provides the option to configure a NORM receiver application
|
||
as a "silent receiver". This mode of receiver operation
|
||
dictates that the host does not generate any protocol messages while
|
||
operating as a receiver within the specified <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>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">The
|
||
optional <FONT FACE="Courier"><U>maxDelay</U></FONT> parameter is
|
||
most applicable for reception of the <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>
|
||
type. The default value of <FONT FACE="Courier"><U>maxDelay</U></FONT>
|
||
<FONT FACE="Courier"><I>= -1</I></FONT> corresponds to normal
|
||
operation where source data segments for incompletely-received FEC
|
||
coding blocks (or transport objects) are passed to the application
|
||
only when imposed buffer constraints (either the <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>
|
||
buffer size (see <FONT FACE="Courier"><A HREF="#NormStreamOpen()">NormStreamOpen()</A></FONT>) or the
|
||
FEC receive buffer limit (see <FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT>)
|
||
require. Thus, the default behavior (<FONT FACE="Courier"><U>maxDelay</U></FONT>
|
||
= <FONT FACE="Courier"><I>-1</I></FONT>), causes the receiver to
|
||
buffer received FEC code blocks for as long as possible (within
|
||
buffer constraints as newer data arrives) before allowing the
|
||
application to read the data. Hence, the receive latency (delay) can
|
||
be quite long depending upon buffer size settings, transmission rate,
|
||
etc. When the <FONT FACE="Courier"><U>maxDelay</U></FONT> parameter
|
||
is set to a non-negative value, the value determines the maximum
|
||
number of FEC coding blocks (according to a NORM sender's current
|
||
transmit position) the receiver will cache an incompletely-received
|
||
FEC block before giving the applicatin the (incomplete) set of
|
||
received source segments. For example, a value of <FONT FACE="Courier"><U>maxDelay</U></FONT>
|
||
<FONT FACE="Courier"><I>= 0</I></FONT> will provide the receive
|
||
application with any data from the previous FEC block as soon as a
|
||
subsequent FEC block is begun reception. However, this provide no
|
||
protection against the possibility of out-of-order delivery of
|
||
packets by the network. Therefore, if lower latency operation is
|
||
desired when using silent receivers, a minimum <FONT FACE="Courier"><U>maxDelay</U></FONT>
|
||
value of <FONT FACE="Courier"><I>1</I></FONT> is recommended. For
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT> and
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>, the only impact
|
||
of a non-negative maxDelay value is that previous transport objects
|
||
will be immediately aborted when subsequent object begin reception.
|
||
Thus, it is not usually recommended to apply a non-negative maxDelay
|
||
value when <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT> is
|
||
not being used.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetDefaultUnicastNack(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> bool state);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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,
|
||
"unicast NACKing" 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 "unicast NACKing" is disabled (default),
|
||
NACK messages are sent to the session address (usually a multicast
|
||
address) and port, but "unicast NACKing", 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 "unicast
|
||
NACKing" be enabled. Note that receiver feedback messages
|
||
subject to the state of "unicast NACKing" include
|
||
NACK-messages as well as some ACK messages such as congestion control
|
||
feedback. Explicitly solicited ACK messages, such as those used to
|
||
satisfy sender watermark acknowledgement requests (see
|
||
<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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormNodeSetUnicastNack(<A HREF="#NormNodeHandle">NormNodeHandle</A> senderNode,
|
||
<BR> bool state);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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, "unicast
|
||
NACKing" 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" behavior.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetDefaultNackingMode(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> <A HREF="#NormNackingMode">NormNackingMode</A> nackingMode);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function sets the default "nacking mode" 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 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 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 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="margin-bottom: 0.2in; 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 "upgrade" 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 "default nacking mode" 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormNodeSetNackingMode(<A HREF="#NormNodeHandle">NormNodeHandle</A> nodeHandle,
|
||
<BR> <A HREF="#NormNackingMode">NormNackingMode</A>
|
||
nackingMode);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function sets the default "nacking mode" 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormObjectSetNackingMode(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle,
|
||
<BR> <A HREF="#NormNackingMode">NormNackingMode</A> nackingMode);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function sets the "nacking mode" 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetDefaultRepairBoundary(<A HREF="#NormSessionHandle">NormSessionHandle</A> sessionHandle,
|
||
<BR> <A HREF="#NormRepairBoundary">NormRepairBoundary</A>
|
||
repairBoundary);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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) "auto parity" (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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormNodeSetRepairBoundary(<A HREF="#NormNodeHandle">NormNodeHandle</A> nodeHandle,
|
||
<BR> <A HREF="#NormRepairBoundary">NormRepairBoundary</A>
|
||
repairBoundary);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormStreamRead(<A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
streamHandle,<BR> char* buffer<BR> unsigned
|
||
int* numBytes);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 "learn" 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="margin-bottom: 0.2in; 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 has read all
|
||
available data.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 "resync" to streams, even if network
|
||
conditions are sufficiently poor that breaks in reliability occur. If
|
||
such a "break" and "resync" occurs, the
|
||
application may be able to leverage other NORM API calls such as
|
||
<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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 "rewind" function
|
||
for a NORM stream). Also note this call cannot be used to skip
|
||
messages. Once a valid message boundary is found, the application
|
||
<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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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"><A NAME="NORM Object Functions">NORM Object Functions</A></H2>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>unsigned short
|
||
NormObjectGetInfo(<A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
objectHandle,<BR> char* buffer,<BR> unsigned
|
||
short bufferLen);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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., "<FONT FACE="Courier">#define _FILE_OFFSET_BITS
|
||
64</FONT>" 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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,
|
||
"bytes pending" 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 "transmit pending" status of
|
||
sender objects, but it does not account for pending FEC repair
|
||
transmissions and thus may not produce useful results for this
|
||
purpose.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; font-style: normal">This
|
||
function "retains" 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormFileGetName(<A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
fileHandle)<BR> char* nameBuffer,<BR> unsigned
|
||
int bufferLen);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormFileRename(<A HREF="#NormObjectHandle">NormObjectHandle</A> fileHandle)<BR> const
|
||
char* fileName);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 "ownership" for the allocated memory space
|
||
using the <FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormDataDetachData()">NormDataDetachData()</A></FONT></FONT>
|
||
function if it is desired to avoid the copy.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; font-style: normal">Once
|
||
the application has used this call to "detach" the data
|
||
content, it is the application's responsibility to subsequently free
|
||
the data storage space as needed.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 <A HREF="#NORM Node Functions">NORM Node Functions</A> described later
|
||
in this document.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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"><A NAME="NORM Node Functions">NORM Node Functions</A></H2>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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 <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT>
|
||
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="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormNodeGetAddress(<A HREF="#NormNodeHandle">NormNodeHandle</A>
|
||
nodeHandle,<BR> char* addrBuffer,<BR> unsigned
|
||
int* bufferLen,<BR> unsigned
|
||
short* port = (unsigned short*)0);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function retrieves the current network source address detected for
|
||
packets received from remote NORM sender referenced by the <FONT FACE="Courier"><U>nodeHandle</U></FONT>
|
||
parameter. The <FONT FACE="Courier"><U>addrBuffer</U></FONT> must be
|
||
a pointer to storage of <FONT FACE="Courier"><U>bufferLen</U></FONT>
|
||
bytes in length in which the referenced sender node's address will be
|
||
returned. Optionally, the remote sender source port number (see
|
||
<FONT FACE="Courier"><A HREF="#NormSetTxPort()">NormSetTxPort()</A></FONT>) is also returned if the
|
||
optional <FONT FACE="Courier"><U>port</U></FONT> pointer to storage
|
||
parameter is provided in the call. Note that in the case of Network
|
||
Address Translation (NAT) or other firewall activities, the source
|
||
address detected by the NORM receiver may not be the original address
|
||
of the original NORM sender.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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. An
|
||
invalid <FONT FACE="Courier"><U>nodeHandle</U></FONT> parameter value
|
||
would lead to failure.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormNodeGetGrtt()">NormNodeGetGrtt()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>double NormNodeGetId(<A HREF="#NormNodeHandle">NormNodeHandle</A>
|
||
nodeHandle)</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function retrieves the advertised estimate of group round-trip timing
|
||
(GRTT) for the remote sender referenced by the given <FONT FACE="Courier"><U>nodeHandle</U></FONT>
|
||
value. Newly-starting senders that have been participating as a
|
||
receiver within a group may wish to use this function to provide a
|
||
more accurate startup estimate of GRTT (see <FONT FACE="Courier"><A HREF="#NormSetGrttEstimate()">NormSetGrttEstimate()</A></FONT>)
|
||
prior to a call to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>.
|
||
Applications may use this information for other purpose as well. Note
|
||
that the <FONT FACE="Courier"><I>NORM_GRTT_UPDATED</I></FONT> event
|
||
is posted (see <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>) by the
|
||
NORM protocol engine to indicate when changes in the local sender or
|
||
remote senders' GRTT estimate occurs.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">This
|
||
function returns the remote sender's advertised GRTT estimate in
|
||
units of seconds. A value of <FONT FACE="Courier"><I>-1.0</I></FONT>
|
||
is returned upon failure. An invalid <FONT FACE="Courier"><U>nodeHandle</U></FONT>
|
||
parameter value will lead to such failure.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormNodeRetain()">NormNodeRetain()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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_SENDER_NEW</I></FONT>
|
||
notification until a complimentary <FONT FACE="Courier"><I>NORM_REMOTE_SENDER_PURGED</I></FONT>
|
||
notification. During that interval, the application will receive
|
||
<FONT FACE="Courier"><I>NORM_REMOTE_SENDER_ACTIVE</I></FONT> and
|
||
<FONT FACE="Courier"><I>NORM_REMOTE_SENDER_INACTIVE</I></FONT>
|
||
notifications according to the sender's message transmission activity
|
||
within the session.</P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal">It
|
||
is important to note that, if the NORM protocol engine posts a
|
||
<FONT FACE="Courier"><I>NORM_REMOTE_SENDER_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 sender (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 senders 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 senders within a session (related APIs are TBD). For
|
||
example, the application may wish to control which specific remote
|
||
senders for which it keeps state (or limit the memory resources used
|
||
for remote sender state, etc) and the NORM API may be extended in the
|
||
future to control this behavior.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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 CLASS="western" STYLE="margin-bottom: 0.2in; font-style: normal; page-break-after: avoid">
|
||
<FONT FACE="Courier"><FONT SIZE=2>#include <normApi.h></FONT></FONT></P>
|
||
<P CLASS="western" STYLE="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; 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="margin-bottom: 0.2in; font-style: normal">This
|
||
function has no return value.</P>
|
||
</BODY>
|
||
</HTML>
|