3816 lines
266 KiB
HTML
3816 lines
266 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/J 1.1 (Unix)">
|
||
<META NAME="AUTHOR" CONTENT="Robert Adamson">
|
||
<META NAME="CREATED" CONTENT="20040824;14180000">
|
||
<META NAME="CHANGED" CONTENT="20050919;14362900">
|
||
<META NAME="DESCRIPTION" CONTENT="NORM Object Functions 42
|
||
NORM Object Functions
|
||
NORM_OBJECT_STREAM
|
||
NORM Sender Functions 19
|
||
NORM Sender Functions
|
||
">
|
||
<META NAME="KEYWORDS" CONTENT="norm object value application function ">
|
||
<STYLE>
|
||
<!--
|
||
@page { size: 8.5in 11in; margin-right: 1.25in; margin-top: 1in; margin-bottom: 0.5in }
|
||
@page:first { margin-top: 1in; margin-bottom: 1in }
|
||
P { margin-top: 0.08in; margin-bottom: 0in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
|
||
P.western { font-family: "Times"; font-size: 12pt; so-language: en-US; font-style: italic }
|
||
P.cjk { font-family: "Times"; font-size: 12pt; font-style: italic }
|
||
P.ctl { font-family: "Times"; font-size: 10pt }
|
||
H1 { margin-bottom: 0.04in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
|
||
H1.western { font-family: "Helvetica", sans-serif; font-size: 16pt; so-language: en-US }
|
||
H1.cjk { font-family: "Times"; font-size: 16pt }
|
||
H1.ctl { font-family: "Times"; font-size: 10pt; font-weight: medium }
|
||
H2 { margin-bottom: 0.04in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
|
||
H2.western { font-family: "Helvetica", sans-serif; font-size: 14pt; so-language: en-US; font-style: italic }
|
||
H2.cjk { font-family: "Times"; font-size: 14pt; font-style: italic }
|
||
H2.ctl { font-family: "Times"; font-size: 10pt; font-weight: medium }
|
||
H3 { margin-bottom: 0.04in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
|
||
H3.western { font-family: "Helvetica", sans-serif; font-size: 13pt; so-language: en-US }
|
||
H3.cjk { font-family: "Times"; font-size: 13pt }
|
||
H3.ctl { font-family: "Times"; font-size: 10pt; font-weight: medium }
|
||
H4 { margin-bottom: 0.04in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
|
||
H4.western { font-family: "Times"; font-size: 14pt; so-language: en-US }
|
||
H4.cjk { font-family: "Times"; font-size: 14pt }
|
||
H4.ctl { font-family: "Times"; font-size: 10pt; font-weight: medium }
|
||
H3.functionheading-western { border-top: 1px solid #000000; border-bottom: none; border-left: none; border-right: none; padding-top: 0.01in; padding-bottom: 0in; padding-left: 0in; padding-right: 0in; font-family: "Courier"; font-size: 13pt; so-language: en-US }
|
||
H3.functionheading-cjk { border-top: 1px solid #000000; border-bottom: none; border-left: none; border-right: none; padding-top: 0.01in; padding-bottom: 0in; padding-left: 0in; padding-right: 0in; font-family: "Times"; font-size: 13pt }
|
||
H3.functionheading-ctl { border-top: 1px solid #000000; border-bottom: none; border-left: none; border-right: none; padding-top: 0.01in; padding-bottom: 0in; padding-left: 0in; padding-right: 0in; font-family: "Times"; font-size: 10pt; font-weight: medium }
|
||
A:link { color: #0000ff }
|
||
A:visited { color: #800080 }
|
||
-->
|
||
</STYLE>
|
||
</HEAD>
|
||
<BODY LANG="en-US" TEXT="#000000" LINK="#0000ff" VLINK="#800080" DIR="LTR">
|
||
<TABLE WIDTH=590 BORDER=0 CELLPADDING=7 CELLSPACING=0 STYLE="page-break-before: always">
|
||
<COL WIDTH=191>
|
||
<COL WIDTH=371>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=191>
|
||
<P ALIGN=CENTER STYLE="margin-top: 0.17in; font-style: normal"><IMG SRC="NormLogo.gif" NAME="Graphic1" ALIGN=BOTTOM WIDTH=184 HEIGHT=176 BORDER=0></P>
|
||
</TD>
|
||
<TD WIDTH=371>
|
||
<P ALIGN=LEFT STYLE="margin-left: 0.86in; margin-top: 0.17in; font-style: normal">
|
||
<FONT FACE="Helvetica, sans-serif"><FONT SIZE=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.3b6)</FONT></B></FONT></FONT></P>
|
||
</TD>
|
||
</TR>
|
||
</TABLE>
|
||
<H1 CLASS="western"><A NAME="Background">Background</A></H1>
|
||
<P CLASS="western" STYLE="font-style: normal">This document describes
|
||
an application programming interface (API) for the <FONT COLOR="#0000ff"><U><A HREF="http://norm.pf.itd.nrl.navy.mil/">Nack-Oriented
|
||
Reliable Multicast (NORM)</A></U></FONT> protocol implementation
|
||
developed by the United States <FONT COLOR="#0000ff"><U><A HREF="http://www.nrl.navy.mil/">Naval
|
||
Research Laboratory</A></U></FONT> (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 <FONT COLOR="#0000ff"><U><A HREF="http://www.ietf.org/">Internet
|
||
Engineering Task Force</A></U></FONT> (IETF) <FONT COLOR="#0000ff"><U><A HREF="http://norm.pf.itd.nrl.navy.mil/rfc3940.pdf">RFC
|
||
3940</A></U></FONT>.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">The NORM protocol is
|
||
designed to provide end-to-end reliable transport of bulk data
|
||
objects or streams over generic IP multicast routing and forwarding
|
||
services. NORM uses a selective, negative acknowledgement (NACK)
|
||
mechanism for transport reliability and offers additional protocol
|
||
mechanisms to conduct reliable multicast sessions with limited "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>
|
||
<P CLASS="western" STYLE="font-style: normal">The NRL NORM library
|
||
attempts to provide a general useful capability for development of
|
||
reliable multicast applications for bulk file or other data delivery
|
||
as well as support of stream-based transport with possible real-time
|
||
delivery requirements. The API allows access to many NORM protocol
|
||
parameters and control functions to tailor performance for specific
|
||
applications. While default parameters, where provided, can be
|
||
useful to a potential wide range of requirements, the many different
|
||
possible group communication paradigms dictate different needs for
|
||
different applications. Even with NORM, the developer should have a
|
||
thorough understanding of the specific application's group
|
||
communication needs.</P>
|
||
<H1 CLASS="western" ALIGN=CENTER STYLE="page-break-before: always"><A NAME="Table
|
||
of Contents">Table
|
||
of Contents</A></H1>
|
||
<DIV ID="Table of Contents1" DIR="LTR">
|
||
<P STYLE="margin-top: 0.25in; font-style: normal"><BR>
|
||
</P>
|
||
<P STYLE="margin-top: 0.25in; font-style: normal"><FONT FACE="Helvetica, sans-serif"><B><A HREF="#Overview">Overview</A></B></FONT></P>
|
||
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#API Initialization">API Initialization</A></B></FONT></P>
|
||
<P 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 STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#Data Transport">Data Transport</A></B></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#Data Transmission">Data Transmission</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#Data Reception">Data Reception</A></FONT></P>
|
||
<P 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 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 STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#Unix Platforms">Unix Platforms</A></B></FONT></P>
|
||
<P 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 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 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 STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormInstanceHandle">NormInstanceHandle</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSessionHandle">NormSessionHandle</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSessionId">NormSessionId</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeId">NormNodeId</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectType">NormObjectType</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSize">NormSize</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectTransportId">NormObjectTransportId</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormEventType">NormEventType</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormEvent">NormEvent</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDescriptor">NormDescriptor</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormFlushMode">NormFlushMode</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormProbingMode">NormProbingMode</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNackingMode">NormNackingMode</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormRepairBoundary">NormRepairBoundary</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormAckingStatus">NormAckingStatus</A></FONT></P>
|
||
<P 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 STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormCreateInstance()">NormCreateInstance()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDestroyInstance()">NormDestroyInstance()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetCacheDirectory()">NormSetCacheDirectory()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormGetDescriptor()">NormGetDescriptor()</A></FONT></P>
|
||
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#Session Creation and Control Functions">Session Creation and Control Functions</A></B></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormCreateSession()">NormCreateSession()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDestroySession()">NormDestroySession()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetUserData()">NormSetUserData()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormGetUserData()">NormGetUserData()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormGetLocalNodeId()">NormGetLocalNodeId()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTxPort()">NormSetTxPort()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetRxPortReuse()">NormSetRxPortReuse()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetMulticastInterface()">NormSetMulticastInterface()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTTL()">NormSetTTL()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTOS()">NormSetTOS()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetLoopback()">NormSetLoopback()</A></FONT></P>
|
||
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#NORM Sender Functions">NORM Sender Functions</A></B></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStartSender()">NormStartSender()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStopSender()">NormStopSender()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTransmitRate()">NormSetTransmitRate()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTxSocketBuffer()">NormSetTxSocketBuffer()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetCongestionControl()">NormSetCongestionControl()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTransmitRateBounds()">NormSetTransmitRateBounds()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTransmitCacheBounds()">NormSetTransmitCacheBounds()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetAutoParity()">NormSetAutoParity()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetGrttEstimate()">NormSetGrttEstimate()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetGrttMax()">NormSetGrttMax()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetGrttProbingMode()">NormSetGrttProbingMode()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetGrttProbingInterval()">NormSetGrttProbingInterval()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormFileEnqueue()">NormFileEnqueue()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDataEnqueue()">NormDataEnqueue()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamOpen()">NormStreamOpen()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamClose()">NormStreamClose()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamSetAutoFlush()">NormStreamSetAutoFlush()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamSetPushEnable()">NormStreamSetPushEnable()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamHasVacancy()">NormStreamHasVacancy()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamMarkEom()">NormStreamMarkEom()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetWatermark()">NormSetWatermark()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormAddAckingNode()">NormAddAckingNode()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormRemoveAckingNode()">NormRemoveAckingNode()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormGetAckingStatus()">NormGetAckingStatus()</A></FONT></P>
|
||
<P 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 STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStopReceiver()">NormStopReceiver()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetRxSocketBuffer()">NormSetRxSocketBuffer()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetSilentReceiver()">NormSetSilentReceiver()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetDefaultUnicastNack()">NormSetDefaultUnicastNack()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeSetUnicastNack()">NormNodeSetUnicastNack()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetDefaultNackingMode()">NormSetDefaultNackingMode()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeSetNackingMode()">NormNodeSetNackingMode()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectSetNackingMode()">NormObjectSetNackingMode()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetDefaultRepairBoundary()">NormSetDefaultRepairBoundary()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeSetRepairBoundary()">NormNodeSetRepairBoundary()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamRead()">NormStreamRead()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamSeekMsgStart()">NormStreamSeekMsgStart()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamGetReadOffset()">NormStreamGetReadOffset()</A></FONT></P>
|
||
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#NORM Object Functions">NORM Object Functions</A></B></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetType()">NormObjectGetType()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectHasInfo()">NormObjectHasInfo()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetInfoLength()">NormObjectGetInfoLength()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetInfo()">NormObjectGetInfo()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetSize()">NormObjectGetSize()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetBytesPending()">NormObjectGetBytesPending()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectCancel()">NormObjectCancel()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormFileGetName()">NormFileGetName()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormFileRename()">NormFileRename()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDataAccessData()">NormDataAccessData()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDataDetachData()">NormDataDetachData()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetSender()">NormObjectGetSender()</A></FONT></P>
|
||
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B><A HREF="#NORM Node Functions">NORM Node Functions</A></B></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeGetId()">NormNodeGetId()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeGetAddress()">NormNodeGetAddress()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeRetain()">NormNodeRetain()</A></FONT></P>
|
||
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeRelease()">NormNodeRelease()</A></FONT></P>
|
||
</DIV>
|
||
<H1 CLASS="western" STYLE="page-break-before: always"><A NAME="Overview">Overview</A></H1>
|
||
<P CLASS="western" STYLE="font-style: normal">The NORM API has been
|
||
designed to provide simple, straightforward access to and control of
|
||
NORM protocol state and functions. Functions are provided to create
|
||
and initialize instances of the NORM API and associated transport
|
||
sessions (<I>NormSessions</I>). Subsequently, NORM data
|
||
transmission (<I>NormSender</I>) operation can be activated and the
|
||
application can queue various types of data (<I>NormObjects</I>) for
|
||
reliable transport. Additionally or alternatively, NORM reception
|
||
(<I>NormReceiver</I>) operation can also be enabled on a per-session
|
||
basis and the protocol implementation alerts the application of
|
||
receive events.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">By default, the NORM
|
||
API will create an operating system thread in which the NORM protocol
|
||
engine runs. This allows user application code and the underlying
|
||
NORM code to execute somewhat independently of one another. The NORM
|
||
protocol thread notifies the application of various protocol events
|
||
through a thread-safe event dispatching mechanism and API calls are
|
||
provided to allow the application to control NORM operation. (<I>Note:
|
||
API mechanisms for lower-level, non-threaded control and execution
|
||
of the NORM protocol engine may also be provided in the future</I>.)</P>
|
||
<P CLASS="western" STYLE="font-style: normal">The NORM API operation
|
||
can be roughly summarized with the following categories of functions:</P>
|
||
<OL>
|
||
<LI><P CLASS="western" STYLE="font-style: normal"><A HREF="#API Initialization">API Initialization</A></P>
|
||
<LI><P CLASS="western" STYLE="font-style: normal"><A HREF="#Session Creation and Control">Session Creation and Control</A></P>
|
||
<LI><P CLASS="western" STYLE="font-style: normal"><A HREF="#Data Transport">Data Transport</A></P>
|
||
<LI><P CLASS="western" STYLE="font-style: normal"><A HREF="#API Event Notification">API Event Notification</A></P>
|
||
</OL>
|
||
<P CLASS="western" STYLE="font-style: normal">Note the order of these
|
||
categories roughly reflects the order of function calls required to
|
||
use NORM in an application. The first step is to create and
|
||
initialize, as needed, at least one instance of the NORM API. Then
|
||
one or more NORM transport sessions (where a “session”
|
||
corresponds to data exchanges on a given multicast group and host
|
||
port number) may be created and controlled. Applications may
|
||
participate as senders and/or receivers within a NORM session. NORM
|
||
senders transmit data to the session destination address (usually an
|
||
IP multicast group) while receivers are notified of incoming data.
|
||
The NORM API provides and event notification scheme to notify the
|
||
application of significant sender and receiver events. There are
|
||
also a number support functions provided for the application to
|
||
control and monitor its participation within a NORM transport
|
||
session.</P>
|
||
<H2 CLASS="western"><A NAME="API Initialization">API Initialization</A></H2>
|
||
<P CLASS="western" STYLE="font-style: normal">The NORM API requires
|
||
that an application explicitly create at least one instance of the
|
||
NORM protocol engine which is subsequently used as a conduit for
|
||
further NORM API calls. By default, the NORM protocol engine runs in
|
||
its own operating system thread and interacts with the application in
|
||
a thread-safe manner through the API calls and event dispatching
|
||
mechanism.
|
||
</P>
|
||
<P CLASS="western" STYLE="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. While a NORM application can be designed
|
||
to be single-threaded, even with multiple active <I>NormSessions</I>,
|
||
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="font-style: normal">Once an API instance
|
||
has been successfully created, the application may then create NORM
|
||
transport session instances as needed. The application can
|
||
participate in each session as a sender and/or receiver of data. If
|
||
an application is participating as a sender, it may enqueue data
|
||
transport objects for transmission. The control of transmission is
|
||
largely left to the sender and API calls are provided to control
|
||
transmission rate, FEC parameters, etc. Applications participating
|
||
as receivers will be notified via the NORM API's event dispatching
|
||
mechanism of pending and completed reliable reception of data along
|
||
with other significant events. Additionally, API controls for some
|
||
optional NORM protocol mechanisms, such as positive acknowledgment
|
||
collection, are also provided.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">Note when multiple
|
||
senders are involved, receivers allocate system resources (buffer
|
||
space) for each active sender. With a very large number of
|
||
concurrently active senders, this may translate to significant memory
|
||
allocation on receiver nodes. Currently, the API allows the
|
||
application to control how much buffer space is allocated for each
|
||
active sender (<I>NOTE: In the future, API functions may be provided
|
||
limit the number of active senders monitored and/or provide the
|
||
application with finer control over receive buffer allocation,
|
||
perhaps on a per sender basis</I>).
|
||
</P>
|
||
<H2 CLASS="western"><A NAME="Data Transport">Data Transport</A></H2>
|
||
<P CLASS="western" STYLE="font-style: normal">The NORM protocol
|
||
supports transport of three basic types of data content. These
|
||
include the types <FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT>
|
||
and <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT> which
|
||
represent predetermined, fixed-size application data content. The
|
||
only differentiation with respect to these two types is the implicit
|
||
“hint” to the receiver to use non-volatile (i.e. file system)
|
||
storage or memory. This “hint” lets the receiver allocate
|
||
appropriate storage space with no other information on the incoming
|
||
data. The NORM implementation reads/writes data for the
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT> type directly
|
||
from/to file storage, while application memory space is accessed for
|
||
the <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT> type. The
|
||
third data content type, <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>,
|
||
represents unbounded, possibly persistent, streams of data content.
|
||
Using this transport paradigm, traditional, byte-oriented streaming
|
||
transport service (e.g. similar to that provided by a TCP socket) can
|
||
be provided. Additionally, NORM has provisions for
|
||
application-defined message-oriented transport where receivers can
|
||
recover message boundaries without any “handshake” with the
|
||
sender. Stream content is buffered by the NORM implementation for
|
||
transmission/retransmission and as it is received.</P>
|
||
<H3 CLASS="western"><A NAME="Data Transmission">Data Transmission</A></H3>
|
||
<P CLASS="western" STYLE="font-style: normal">The behavior of data
|
||
transport operation is largely placed in the control of the NORM
|
||
sender(s). NORM senders controls their data transmission rate,
|
||
forward error correction (FEC) encoding settings, and parameters
|
||
controlling feedback from the receiver group. Multiple senders may
|
||
operate in a session, each with independent transmission parameters.
|
||
NORM receivers learn needed parameter values from fields in NORM
|
||
message headers.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">NORM transport
|
||
“objects” (file, data, or stream) are queued for transmission by
|
||
NORM senders. NORM senders may also cancel transmission of objects
|
||
at any time. The NORM sender controls the transmission rate either
|
||
manually (fixed transmission rate) or automatically when NORM
|
||
congestion control operation is enabled. The NORM congestion control
|
||
mechanism is designed to be "friendly" to other data flows
|
||
on the network, fairly sharing available bandwidth.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">By default, the NORM
|
||
sender transmits application-enqueued data content, providing repair
|
||
transmissions (usually in the form of FEC messages) only when
|
||
requested by NACKs from the receivers. However, the application may
|
||
also configure NORM to proactively send some amount of FEC content
|
||
along with the original data content to create a "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="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="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="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="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="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="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="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="font-style: normal">NORM has been built and
|
||
tested on Linux (various architectures), MacOS (BSD), Solaris, and
|
||
IRIX (SGI) platforms. The code should be readily portable to other
|
||
Unix platforms.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">To support IPv6
|
||
operation, the NORM and the <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="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="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="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="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="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="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 y Protolib (and hence NORM) for this
|
||
system doesn't support some of the functions defined for this
|
||
library. This may be related to IPv6 support issues so it may be
|
||
possible that the Protolib build could be tweaked to provide a single
|
||
binary executable suitable for IPv4 operation only across a large
|
||
range of Windows platforms.</P>
|
||
<H1 CLASS="western"><A NAME="API Reference">API Reference</A></H1>
|
||
<P CLASS="western" STYLE="font-style: normal">This section provides a
|
||
reference to the NORM API variable types, constants and functions.</P>
|
||
<H2 CLASS="western"><A NAME="API Variable Types and Constants">API Variable Types and Constants</A></H2>
|
||
<P CLASS="western" STYLE="font-style: normal">The NORM API defines
|
||
and enumerates a number of supporting variable types and values which
|
||
are used in different function calls. The variable types are
|
||
described here.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormInstanceHandle">NormInstanceHandle</A></H3>
|
||
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormInstanceHandle">NormInstanceHandle</A>
|
||
</FONT>type is returned when a NORM API instance is created (see
|
||
<FONT FACE="Courier"><A HREF="#NormCreateInstance()">NormCreateInstance()</A></FONT>). This handle can
|
||
be subsequently used for API calls which require reference to a
|
||
specific NORM API instance. By default, each NORM API instance
|
||
instantiated creates an operating system thread for protocol
|
||
operation. Note that multiple NORM transport sessions may be created
|
||
for a single API instance. In general, it is expected that
|
||
applications will create a single NORM API instance, but some
|
||
multi-threaded application designs may prefer multiple corresponding
|
||
NORM API instances. The value <FONT FACE="Courier">NORM_INSTANCE_INVALID</FONT>
|
||
corresponds to an invalid API instance.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSessionHandle">NormSessionHandle</A></H3>
|
||
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormSessionHandle">NormSessionHandle</A></FONT>
|
||
type is used to reference NORM transport sessions which have been
|
||
created using the <FONT FACE="Courier"><A HREF="#NormCreateSession()">NormCreateSession()</A></FONT> API
|
||
call. Multiple <FONT FACE="Courier">NormSessionHandles</FONT> may be
|
||
associated with a given <FONT FACE="Courier"><A HREF="#NormInstanceHandle">NormInstanceHandle</A></FONT>.
|
||
The special value <FONT FACE="Courier">NORM_SESSION_INVALID </FONT>is
|
||
used to refer to invalid session references.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSessionId">NormSessionId</A></H3>
|
||
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormSessionId">NormSessionId</A></FONT>
|
||
type is used by applications to uniquely identify their instance of
|
||
participation as a sender within a <I>NormSession</I>. This type is
|
||
a parameter to the <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>
|
||
function. Robust applications can use different <FONT FACE="Courier"><A HREF="#NormSessionId">NormSessionId</A></FONT>
|
||
values when initiating sender operation so that receivers can
|
||
discriminate when a sender has terminated and restarted (whether
|
||
intentional or due to system failure). For example, an application
|
||
could cache its prior <FONT FACE="Courier"><A HREF="#NormSessionId">NormSessionId</A></FONT> value
|
||
in non-volatile storage which could then be recovered and incremented
|
||
(for example) upon system restart to produce a new value. The
|
||
<FONT FACE="Courier"><A HREF="#NormSessionId">NormSessionId</A></FONT> value is used for the value
|
||
of the <I>instance_id</I> field in NORM protocol sender messages (see
|
||
the NORM protocol specification) and receivers use this field to
|
||
detect sender restart within a <I>NormSession</I>.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormNodeHandle">NormNodeHandle</A></H3>
|
||
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A>
|
||
</FONT>type is used to reference state kept by the NORM
|
||
implementation with respect to other participants within a
|
||
<I>NormSession</I>. Most typically, the <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A>
|
||
</FONT>is used by receiver applications to dereference information
|
||
about remote senders of data as needed. The special value
|
||
<FONT FACE="Courier">NORM_NODE_INVALID</FONT> corresponds to an
|
||
invalid reference.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormNodeId">NormNodeId</A></H3>
|
||
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT>
|
||
type corresponds to a 32-bit numeric value which should uniquely
|
||
identify a participant (node) in a given <I>NormSession</I>. The
|
||
<FONT FACE="Courier"><A HREF="#NormNodeGetId()">NormNodeGetId()</A></FONT> function can be used to
|
||
retrieve this value given a valid <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>.
|
||
The special value <FONT FACE="Courier">NORM_NODE_NONE</FONT>
|
||
corresponds to an invalid (or null) node while the value
|
||
<FONT FACE="Courier">NORM_NODE_ANY</FONT> serves as a wildcard value
|
||
for some functions.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormObjectHandle">NormObjectHandle</A></H3>
|
||
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>
|
||
type is used to reference state kept for data transport objects being
|
||
actively transmitted or received. The state kept for NORM transport
|
||
objects is temporary, but the NORM API provides a function to
|
||
persistently retain state associated with a sender or receiver
|
||
<FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT> (see <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT>)
|
||
if needed. For sender objects, unless explicitly retained, the
|
||
<FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT> can be considered valid
|
||
until the referenced object is explicitly canceled (see
|
||
<FONT FACE="Courier"><A HREF="#NormObjectCancel()">NormObjectCancel()</A></FONT>) or purged from the
|
||
sender transmission queue (see the event <I><FONT FACE="Courier">NORM_TX_OBJECT_PURGED</FONT></I>).
|
||
For receiver objects, these handles should be treated as valid only
|
||
until a subsequent call to <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>
|
||
unless, again, specifically retained. The special value
|
||
<I><FONT FACE="Courier">NORM_OBJECT_INVALID</FONT></I> corresponds to
|
||
an invalid transport object reference.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormObjectType">NormObjectType</A></H3>
|
||
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormObjectType">NormObjectType</A></FONT>
|
||
type is an enumeration of possible NORM data transport object types.
|
||
As previously mentioned, valid types include:</P>
|
||
<OL>
|
||
<LI><P CLASS="western"><FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT></P>
|
||
<LI><P CLASS="western" STYLE="font-style: normal"><I><FONT FACE="Courier">NORM_OBJECT_DATA</FONT></I>,
|
||
and</P>
|
||
<LI><P CLASS="western"><FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT></P>
|
||
</OL>
|
||
<P CLASS="western" STYLE="font-style: normal">Given a
|
||
<FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>, the application may
|
||
determine an object's type using the <FONT FACE="Courier"><A HREF="#NormObjectGetType()">NormObjectGetType()</A></FONT>
|
||
function call. A special <FONT FACE="Courier"><A HREF="#NormObjectType">NormObjectType</A></FONT>
|
||
value, <I><FONT FACE="Courier">NORM_OBJECT_NONE</FONT></I>, indicates
|
||
an invalid object type.
|
||
</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSize">NormSize</A></H3>
|
||
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormSize">NormSize</A></FONT>
|
||
is the type used for <I>NormObject</I> size information. For
|
||
example, the <FONT FACE="Courier"><A HREF="#NormObjectGetSize()">NormObjectGetSize()</A></FONT> function
|
||
returns a value of type <FONT FACE="Courier"><A HREF="#NormSize">NormSize</A></FONT>. The
|
||
range of <FONT FACE="Courier"><A HREF="#NormSize">NormSize</A></FONT> values depends upon the
|
||
operating system and NORM library compilation settings. With "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="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="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="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A>
|
||
</FONT>type is a structure used to describe significant NORM protocol
|
||
events. This structure is defined as follows:</P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>typedef
|
||
struct<BR>{<BR> <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="font-style: normal">The <FONT FACE="Courier">type</FONT>
|
||
field indicates the <FONT FACE="Courier"><A HREF="#NormEventType">NormEventType</A></FONT> and
|
||
determines how the other fields should be interpreted. Note that not
|
||
all <FONT FACE="Courier"><A HREF="#NormEventType">NormEventType</A></FONT> fields are relevant to
|
||
all events. The <FONT FACE="Courier">session</FONT>, <FONT FACE="Courier">node</FONT>,
|
||
and <FONT FACE="Courier">object</FONT> fields indicate the applicable
|
||
<FONT FACE="Courier"><A HREF="#NormSessionHandle">NormSessionHandle</A></FONT>, <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>,
|
||
and <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>, respectively, to
|
||
which the event applies. NORM protocol events are made available to
|
||
the application via the <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>
|
||
function call.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormDescriptor">NormDescriptor</A></H3>
|
||
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormDescriptor">NormDescriptor</A></FONT>
|
||
type provides reference to a file descriptor (Unix) or HANDLE
|
||
(Win32). For a given <FONT FACE="Courier"><A HREF="#NormInstanceHandle">NormInstanceHandle</A></FONT>,
|
||
the <FONT FACE="Courier"><A HREF="#NormGetDescriptor()">NormGetDescriptor()</A></FONT> function can be
|
||
used to retrieve a <A HREF="#NormDescriptor">NormDescriptor</A> value that may, in turn, used in
|
||
appropriate system calls (e.g. <I>select()</I> or
|
||
<I>MsgWaitForMultipleObjects()</I>) to asynchronously monitor the
|
||
NORM protocol engine for notification events (see <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT>
|
||
description).
|
||
</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormFlushMode">NormFlushMode</A></H3>
|
||
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormFlushMode">NormFlushMode</A></FONT>
|
||
consist of the following enumeration:</P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>enum
|
||
<A HREF="#NormFlushMode">NormFlushMode</A><BR>{<BR> NORM_FLUSH_NONE,<BR> NORM_FLUSH_PASSIVE,<BR> NORM_FLUSH_ACTIVE<BR>};</FONT></FONT></P>
|
||
<P CLASS="western" STYLE="font-style: normal">The interpretation of
|
||
these values is given in the descriptions of <FONT FACE="Courier"><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT>
|
||
and <FONT FACE="Courier"><A HREF="#NormStreamSetAutoFlush()">NormStreamSetAutoFlush()</A></FONT> functions.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormProbingMode">NormProbingMode</A></H3>
|
||
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormProbingMode">NormProbingMode</A></FONT>
|
||
consist of the following enumeration:</P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>enum
|
||
<A HREF="#NormProbingMode">NormProbingMode</A><BR>{<BR> NORM_PROBE_NONE,<BR> NORM_PROBE_PASSIVE,<BR> NORM_PROBE_ACTIVE<BR>};</FONT></FONT></P>
|
||
<P CLASS="western" STYLE="font-style: normal">The interpretation of
|
||
these values is given in the description of <FONT FACE="Courier"><A HREF="#NormSetGrttProbingMode()">NormSetGrttProbingMode()</A></FONT>
|
||
function.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormNackingMode">NormNackingMode</A></H3>
|
||
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormNackingMode">NormNackingMode</A></FONT>
|
||
type consists of the following enumeration:</P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>enum
|
||
<A HREF="#NormNackingMode">NormNackingMode</A><BR>{<BR> NORM_NACK_NONE,<BR> NORM_NACK_INFO_ONLY,<BR> NORM_NACK_NORMAL<BR>};</FONT></FONT></P>
|
||
<P CLASS="western" STYLE="font-style: normal">The interpretation of
|
||
these values is given in the descriptions of the
|
||
<FONT FACE="Courier"><A HREF="#NormSetDefaultNackingMode()">NormSetDefaultNackingMode()</A></FONT>,
|
||
<FONT FACE="Courier"><A HREF="#NormNodeSetNackingMode()">NormNodeSetNackingMode()</A></FONT> and
|
||
<FONT FACE="Courier"><A HREF="#NormObjectSetNackingMode()">NormObjectSetNackingMode()</A></FONT> functions.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormRepairBoundary">NormRepairBoundary</A></H3>
|
||
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormRepairBoundary">NormRepairBoundary</A></FONT>
|
||
types consists of the following enumeration:</P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>enum
|
||
<A HREF="#NormRepairBoundary">NormRepairBoundary</A><BR>{<BR> NORM_BOUNDARY_BLOCK,<BR> NORM_BOUNDARY_OBJECT<BR>};</FONT></FONT></P>
|
||
<P CLASS="western" STYLE="font-style: normal">The interpretation of
|
||
these values is given in the descriptions of the
|
||
<FONT FACE="Courier"><A HREF="#NormSetDefaultRepairBoundary()">NormSetDefaultRepairBoundary()</A> </FONT>and
|
||
<FONT FACE="Courier"><A HREF="#NormNodeSetRepairBoundary()">NormNodeSetRepairBoundary()</A></FONT> functions.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormAckingStatus">NormAckingStatus</A></H3>
|
||
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormAckingStatus">NormAckingStatus</A></FONT>
|
||
consist of the following enumeration:</P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>enum
|
||
<A HREF="#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="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="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 STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormInstanceHandle">NormInstanceHandle</A>
|
||
NormCreateInstance(bool priorityBoost = false);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function creates
|
||
an instance of a NORM protocol engine and is the necessary first step
|
||
before any other API functions may be used. With the instantiation
|
||
of the NORM protocol engine, an operating system thread is created
|
||
for protocol execution. The returned <FONT FACE="Courier"><A HREF="#NormInstanceHandle">NormInstanceHandle</A>
|
||
</FONT>value may be used in subsequent API calls as needed, such
|
||
<FONT FACE="Courier">NormCreateSesssion()</FONT>, etc. The optional
|
||
<FONT FACE="Courier"><U>priorityBoost</U></FONT> parameter, when set
|
||
to a value of <FONT FACE="Courier"><I>true</I></FONT>, specifies that
|
||
the NORM protocol engine thread be run with higher priority
|
||
scheduling. On Win32 platforms, this corresponds to
|
||
<FONT FACE="Courier"><I>THREAD_PRIORITY_TIME_CRITICAL</I></FONT> and
|
||
on Unix systems with the <FONT FACE="Courier">sched_setscheduler()</FONT>
|
||
API, an attempt to get the maximum allowed <FONT FACE="Courier"><I>SCHED_FIFO</I></FONT>
|
||
priority is made. The use of this option should be carefully
|
||
evaluated since, depending upon the application's scheduling priority
|
||
and NORM API usage, this may have adverse effects instead of a
|
||
guaranteed performance increase!</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">A value of
|
||
<FONT FACE="Courier">NORM_INSTANCE_INVALID</FONT> is returned upon
|
||
failure. The function will only fail if system resources are
|
||
unavailable to allocate the instance and/or create the corresponding
|
||
thread.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormDestroyInstance()">NormDestroyInstance()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormDestroyInstance(<A HREF="#NormInstanceHandle">NormInstanceHandle</A> instance);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">The
|
||
<FONT FACE="Courier"><A HREF="#NormDestroyInstance()">NormDestroyInstance()</A></FONT> function
|
||
immediately shuts down and destroys the NORM protocol engine instance
|
||
referred to by the <U><FONT FACE="Courier">instance</FONT></U>
|
||
parameter. The application should make no subsequent references to
|
||
the indicated <FONT FACE="Courier"><A HREF="#NormInstanceHandle">NormInstanceHandle</A></FONT> or any
|
||
other API handles or objects associated with it. However, the
|
||
application is still responsible for releasing any object handles it
|
||
has retained (see <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> and
|
||
<FONT FACE="Courier"><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT>).
|
||
</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">The function has no
|
||
return value.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetCacheDirectory()">NormSetCacheDirectory()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetCacheDirectory(<A HREF="#NormInstanceHandle">NormInstanceHandle</A> instance,<BR> const
|
||
char* cachePath);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function sets the
|
||
directory path used by receivers to cache newly-received
|
||
<I><FONT FACE="Courier">NORM_OBJECT_FILE</FONT></I> objects. This
|
||
function must be called before any file objects may be received and
|
||
thus should be called before any calls to <FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT>
|
||
are made. However, note that the cache directory may be changed even
|
||
during active NORM reception. In this case, the new specified
|
||
directory path will be used for subsequently-received files. Any
|
||
files received before a directory path change will remain in the
|
||
previous cache location. Note that the <FONT FACE="Courier"><A HREF="#NormFileRename()">NormFileRename()</A></FONT>
|
||
function may be used to rename, and thus potentially move, received
|
||
files after reception has begun.
|
||
</P>
|
||
<P CLASS="western" STYLE="font-style: normal">The <U><FONT FACE="Courier">instance</FONT></U>
|
||
parameter specifies the NORM protocol engine instance (all
|
||
NormSessions associated with that <U><FONT FACE="Courier">instance</FONT></U>
|
||
share the same cache path) and the <U><FONT FACE="Courier">cachePath</FONT></U>
|
||
is a string specifying a valid (and writable) directory path. The
|
||
function returns <I><FONT FACE="Courier">true</FONT></I> on success
|
||
and <I><FONT FACE="Courier">false</FONT></I> on failure. The failure
|
||
conditions are that the indicated directory does not exist or the
|
||
process does not have permissions to write.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormGetNextEvent()">NormGetNextEvent()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormGetNextEvent(<A HREF="#NormInstanceHandle">NormInstanceHandle</A> instance,<BR> <A HREF="#NormEvent">NormEvent</A>* theEvent);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function retrieves
|
||
the next available NORM protocol event from the protocol engine. The
|
||
<FONT FACE="Courier"><U>instance</U></FONT><U> </U>parameter
|
||
specifies the applicable NORM protocol engine, and the <FONT FACE="Courier"><U>theEvent</U></FONT><U>
|
||
</U>parameter must be a valid pointer to a <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT>
|
||
structure capable of receiving the NORM event information. For
|
||
expected reliable protocol operation, the application should make
|
||
every attempt to retrieve and process NORM notification events in a
|
||
timely manner.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">Note that this is
|
||
currently the only blocking call in the NORM API. But non-blocking
|
||
operation may be achieved by using the <FONT FACE="Courier"><A HREF="#NormGetDescriptor()">NormGetDescriptor()</A></FONT>
|
||
function to obtain a descriptor (or HANDLE for WIN32) suitable for
|
||
asynchronous input/output (I/O) notification using such system calls
|
||
as <I><FONT FACE="Courier">select()</FONT></I> (UNIX) or
|
||
<I><FONT FACE="Courier">WaitForMultipleObjects()</FONT></I> (WIN32).
|
||
The descriptor is signaled when a notification event is pending and a
|
||
call to <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT> will not
|
||
block.</P>
|
||
<H4 CLASS="western">NORM Notification Event Types</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">The following table
|
||
enumerates the possible <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A> </FONT>values
|
||
and describes how these notifications should be interpreted as they
|
||
are retrieved by the application via the <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>
|
||
function call.</P>
|
||
<TABLE WIDTH=590 BORDER=0 CELLPADDING=7 CELLSPACING=0>
|
||
<COL WIDTH=269>
|
||
<COL WIDTH=293>
|
||
<TR>
|
||
<TD COLSPAN=2 WIDTH=576 VALIGN=TOP>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<B>Sender Notification Event Types:</B></P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_TX_QUEUE_VACANCY</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This event indicates that there is room for additional transmit
|
||
objects to be enqueued, or, if the handle of <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>
|
||
is given in the 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="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_TX_QUEUE_EMPTY</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This event indicates the NORM protocol engine has no new data
|
||
pending transmission and the application may enqueue additional
|
||
objects for transmission. 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="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_TX_FLUSH_COMPLETED</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This event indicates that the flushing process the NORM sender
|
||
observes when it no longer has data ready for transmission has
|
||
completed. The completion of the flushing process is a reasonable
|
||
indicator (with a sufficient NORM "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="font-style: normal; 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="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_TX_OBJECT_SENT</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This event indicates that the transport object referenced by the
|
||
event's "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="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This event indicates that the NORM protocol engine will no longer
|
||
refer to the transport object identified by the event's "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="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_LOCAL_SERVER_CLOSED</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This event is posted when the NORM protocol engine completes the
|
||
"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>
|
||
<TD COLSPAN=2 WIDTH=576 VALIGN=TOP>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<B>Receiver Notification Event Types:</B></P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_REMOTE_SERVER_NEW</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This notification is posted when a receiver first receives
|
||
messages from a specific remote NORM server. This marks the
|
||
beginning of the interval during which the application may
|
||
reference the provided "node" handle (<FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>).</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_REMOTE_SERVER_ACTIVE</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This event is posted when a previously inactive (or new) remote
|
||
server is detected operating as an active sender within the
|
||
session.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_REMOTE_SERVER_INACTIVE</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This event is posted after a significant period of inactivity (no
|
||
sender messages received) of a specific NORM sender within the
|
||
session. The NORM protocol engine frees buffering resources
|
||
allocated for this sender when it becomes inactive.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_REMOTE_SERVER_PURGED</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This event is posted when the NORM protocol engine frees resources
|
||
for, and thus invalidates the indicated "node" handle.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_RX_OBJECT_NEW</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This event is posted when reception of a new transport object
|
||
begins and marks the beginning of the interval during which the
|
||
specified "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="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_RX_OBJECT_INFO</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This notification is posted when the NORM_INFO content for the
|
||
indicated "object" is received.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_RX_OBJECT_UPDATED</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This event indicates that the identified receive "object"
|
||
has newly received data content.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=269>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_RX_OBJECT_COMPLETED</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This event is posted when a receive object is completely received,
|
||
including available NORM_INFO content. Unless the application
|
||
specifically retains the "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="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_RX_OBJECT_ABORTED</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This notification is posted when a pending receive object's
|
||
transmission is aborted by the remote sender. Unless the
|
||
application specifically retains the "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="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><I>NORM_EVENT_INVALID</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=293>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This <A HREF="#NormEventType">NormEventType</A> indicates an invalid or "null"
|
||
notification which should be ignored.</P>
|
||
</TD>
|
||
</TR>
|
||
</TABLE>
|
||
<P CLASS="western" STYLE="font-style: normal"><BR>
|
||
</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function generally
|
||
blocks the thread of application execution until a <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT>
|
||
is available and returns <FONT FACE="Courier"><I>true</I></FONT> when
|
||
a <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT> is available. However, there
|
||
are some exceptional cases when the function may immediately return
|
||
even when no event is pending. In these cases, the return value is
|
||
<FONT FACE="Courier"><I>false</I></FONT>.
|
||
</P>
|
||
<P CLASS="western">WIN32 Note: A future version of this API will
|
||
provide an option to have a user-defined Window message posted when a
|
||
NORM API event is pending. (Also some event filtering calls may be
|
||
provided (e.g. avoid the potentially numerous <FONT FACE="Courier"><I>NORM_RX_OBJECT_UPDATED</I></FONT>
|
||
events if undesired)).</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormGetDescriptor()">NormGetDescriptor()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormDescriptor">NormDescriptor</A>
|
||
NormGetDescriptor(<A HREF="#NormInstanceHandle">NormInstanceHandle</A> instance);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function is used
|
||
to retrieve a <FONT FACE="Courier"><A HREF="#NormDescriptor">NormDescriptor</A></FONT> (integer
|
||
file descriptor (UNIX) or HANDLE (WIN32)) suitable for asynchronous
|
||
I/O notification to avoid blocking calls to <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>.
|
||
A <FONT FACE="Courier"><A HREF="#NormDescriptor">NormDescriptor</A></FONT> is available for each
|
||
protocol engine <U><FONT FACE="Courier">instance</FONT></U>. The
|
||
descriptor (or WIN32 HANDLE) is suitable for use as an input (or
|
||
"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 <I><FONT FACE="Courier">select()</FONT></I>
|
||
system call (UNIX) (or <I><FONT FACE="Courier">WaitForMultipleObjects()</FONT></I>
|
||
(WIN32)) can be used to detect when the returned <FONT FACE="Courier"><A HREF="#NormDescriptor">NormDescriptor</A></FONT>
|
||
is signaled. For the <FONT FACE="Courier">select()</FONT> call
|
||
usage, the NORM descriptor should be treated as a "read"
|
||
descriptor.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">A descriptor is
|
||
returned which is valid until a call to <FONT FACE="Courier"><A HREF="#NormDestroyInstance()">NormDestroyInstance()</A></FONT>
|
||
is made. Upon error, a value of <I><FONT FACE="Courier">NORM_DESCRIPTOR_INVALID</FONT></I>
|
||
is returned.</P>
|
||
<H2 CLASS="western"><A NAME="Session Creation and Control Functions">Session Creation and Control Functions</A></H2>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormCreateSession()">NormCreateSession()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormSessionHandle">NormSessionHandle</A>
|
||
NormCreateSession(<A HREF="#NormInstanceHandle">NormInstanceHandle</A> 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="font-style: normal">This function creates a
|
||
NORM reliable multicast session (<I>NormSession</I>) using the
|
||
address parameters provided. While session state is allocated and
|
||
initialized, active session participation does not begin until a call
|
||
is made to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> and/or
|
||
<FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT> to join the specified
|
||
multicast group (if applicable) and start protocol operation. The
|
||
following parameters are required in this function call:</P>
|
||
<TABLE WIDTH=590 BORDER=0 CELLPADDING=7 CELLSPACING=0>
|
||
<COL WIDTH=101>
|
||
<COL WIDTH=461>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=101>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier">instance</FONT></P>
|
||
</TD>
|
||
<TD WIDTH=461>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This must be a valid <FONT FACE="Courier"><A HREF="#NormInstanceHandle">NormInstanceHandle</A></FONT>
|
||
previously obtained with a call to <FONT FACE="Courier"><A HREF="#NormCreateInstance()">NormCreateInstance()</A></FONT>.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=101>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier">address</FONT></P>
|
||
</TD>
|
||
<TD WIDTH=461>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This points to a string containing an IP address (e.g. dotted
|
||
decimal IPv4 address (or IPv6 address) or name resolvable to a
|
||
valid IP address. The specified <U><FONT FACE="Courier">address</FONT></U>
|
||
(along with the <U><FONT FACE="Courier">port</FONT></U> number)
|
||
determines the destination of NORM messages sent. For multicast
|
||
sessions, NORM senders and receivers must use a common multicast
|
||
address and port number. For unicast sessions, the sender and
|
||
receiver must use a common port number, but specify the other
|
||
node's IP address as the session address (Although note that
|
||
receiver-only unicast nodes who are providing unicast feedback to
|
||
senders will not generate any messages to the session IP address
|
||
and the <U><FONT FACE="Courier">address</FONT></U> parameter value
|
||
is thus inconsequential for this special case).</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=101>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier">port</FONT></P>
|
||
</TD>
|
||
<TD WIDTH=461>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This must be a valid, unused port number corresponding to the
|
||
desired NORM session address. See the <U><FONT FACE="Courier">address</FONT></U>
|
||
parameter description for more details.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=101>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier">localId</FONT></P>
|
||
</TD>
|
||
<TD WIDTH=461>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
The <FONT FACE="Courier">localId</FONT> parameter specifies the
|
||
<FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> that should be used to
|
||
identify the application's presence in the <I>NormSession</I>.
|
||
All participant's in a <I>NormSession</I> should use unique
|
||
<FONT FACE="Courier">localId</FONT> values. The application may
|
||
specify a value of <I><FONT FACE="Courier">NORM_NODE_ANY </FONT></I>or
|
||
<I><FONT FACE="Courier">NORM_NODE_ANY</FONT></I> for the <FONT FACE="Courier">localId</FONT>
|
||
parameter. In this case, the NORM implementation will attempt to
|
||
pick an identifier based on the host computer's "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="font-style: normal">The returned
|
||
<FONT FACE="Courier"><A HREF="#NormSessionHandle">NormSessionHandle</A></FONT> value is valid until a
|
||
call to <FONT FACE="Courier"><A HREF="#NormDestroySession()">NormDestroySession()</A></FONT> is made. A
|
||
value of <I><FONT FACE="Courier">NORM_SESSION_INVALID</FONT></I> is
|
||
returned upon error.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormDestroySession()">NormDestroySession()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormDestroySession(<A HREF="#NormSessionHandle">NormSessionHandle</A> session);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function
|
||
immediately terminates the application's participation in the
|
||
<I>NormSession</I> identified by the <U><FONT FACE="Courier">session</FONT></U>
|
||
parameter and frees any resources used by that session. An exception
|
||
to this is that the application is responsible for releasing any
|
||
explicitly retained <FONT FACE="Courier">NormObjectHandles</FONT>
|
||
(See <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> and
|
||
<FONT FACE="Courier"><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT>).</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
returned values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetUserData()">NormSetUserData()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetUserData(<A HREF="#NormSessionHandle">NormSessionHandle</A> session, const void* userData);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function allows
|
||
the application to attach a value to the previously-created
|
||
<I>NormSession</I> instance specified by the <FONT FACE="Courier"><U>session</U></FONT>
|
||
parameter. This value is not used or interpreted by NORM, but is
|
||
available to the application for use at the programmer's discretion.
|
||
The set <FONT FACE="Courier"><U>userData</U></FONT> value can be
|
||
later retrieved using the <FONT FACE="Courier"><A HREF="#NormGetUserData()">NormGetUserData()</A></FONT>
|
||
function call.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
returned values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormGetUserData()">NormGetUserData()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>const
|
||
void* NormGetUserData(<A HREF="#NormSessionHandle">NormSessionHandle</A> session);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function retrieves
|
||
the "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="font-style: normal">This function returns
|
||
the user data value set for the specified session. If no user data
|
||
value has been previously set a <FONT FACE="Courier"><I>NULL</I></FONT>
|
||
(i.e., <FONT FACE="Courier"><I>(const void*)0</I></FONT>) value is
|
||
returned.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormGetLocalNodeId()">NormGetLocalNodeId()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormNodeId">NormNodeId</A>
|
||
NormGetLocalNodeId(<A HREF="#NormSessionHandle">NormSessionHandle</A> session);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function retrieves
|
||
the <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> value used for the
|
||
application's participation in the <I>NormSession</I> identified by
|
||
the <FONT FACE="Courier"><U>session</U></FONT> parameter. The value
|
||
may have been explicitly set during the <FONT FACE="Courier"><A HREF="#NormCreateSession()">NormCreateSession()</A></FONT>
|
||
call or derived using the host computer's "default" IP
|
||
network address.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">The returned value
|
||
indicates the <I>NormNode</I> identifier used by the NORM protocol
|
||
engine for the local application's participation in the specified
|
||
<I>NormSession</I>.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetTxPort()">NormSetTxPort()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetTxPort(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> unsigned
|
||
short txPort);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function is used
|
||
to force NORM to use a specific port number for UDP packets sent for
|
||
the specified <FONT FACE="Courier"><U>session</U></FONT>. By
|
||
default, NORM uses separate port numbers for packet transmission and
|
||
session packet reception (the receive port is specified as part of
|
||
the <FONT FACE="Courier"><A HREF="#NormCreateSession()">NormCreateSession()</A></FONT> call), allowing
|
||
the operating system to pick a freely available port for
|
||
transmission. This call allows the application to pick a specific
|
||
port number for transmission, and furthermore allows the application
|
||
to even specify the same port number for transmission as is used for
|
||
reception. However, the use of separate transmit/receive ports
|
||
allows NORM to discriminate when unicast feedback is occurring and
|
||
thus it is not generally recommended that the transmit port be set to
|
||
the same value as the <FONT FACE="Courier"><U>session</U></FONT>
|
||
receive port.
|
||
</P>
|
||
<P CLASS="western" STYLE="font-style: normal">Note this call <I>must</I>
|
||
be made <I>before</I> any calls to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>
|
||
or <FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT> for the given
|
||
<FONT FACE="Courier"><U>session</U></FONT> to succeed.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetRxPortReuse()">NormSetRxPortReuse()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetRxPortReuse(<A HREF="#NormSessionHandle">NormSessionHandle</A>
|
||
session,<BR> bool
|
||
state);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function allows
|
||
the user to control the port reuse and binding behavior for the
|
||
receive socket used for the given NORM <FONT FACE="Courier"><U>session</U></FONT>.
|
||
When the <FONT FACE="Courier"><U>state</U></FONT> parameter is set
|
||
to <FONT FACE="Courier"><I>true</I></FONT>:</P>
|
||
<OL>
|
||
<LI><P CLASS="western" STYLE="font-style: normal">Reuse of the
|
||
<I>NormSession</I> port number is enabled, and</P>
|
||
<LI><P CLASS="western" STYLE="font-style: normal">the underlying
|
||
socket is also bound (see the <FONT FACE="Courier">bind()</FONT>
|
||
system call) to the <I>NormSession</I> destination address instead
|
||
of the default behavior of binding to INADDR_ANY.
|
||
</P>
|
||
</OL>
|
||
<P CLASS="western" STYLE="font-style: normal">The default binding to
|
||
INADDR_ANY (<FONT FACE="Courier"><U>state</U></FONT> equals <FONT FACE="Courier"><I>false</I></FONT>)
|
||
allows the <I>NormSession</I> receive socket to receive any multicast
|
||
or unicast transmissions to the given port number. This allows a
|
||
NORM receiver to receive from senders sending to a multicast session
|
||
address or the receiver's unicast address. Enabling port reuse and
|
||
binding the session destination address allows multiple NORM sessions
|
||
on the same port number, but participating in different multicast
|
||
groups.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">Note this call <I>must</I>
|
||
be made <I>before</I> any calls to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>
|
||
or <FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT> for the given
|
||
<FONT FACE="Courier"><U>session</U></FONT> to succeed.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">This call could also be
|
||
used in conjunction with <FONT FACE="Courier"><A HREF="#NormSetMulticastInterface()">NormSetMulticastInterface()</A></FONT>
|
||
so that multiple <I>NormSessions</I>, using the same port and
|
||
multicast address, could separately cover multiple network interfaces
|
||
(and some sort of application-layer bridging of reliable multicast
|
||
could be realized if desired).</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetMulticastInterface()">NormSetMulticastInterface()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetMulticastInterface(<A HREF="#NormSessionHandle">NormSessionHandle</A>
|
||
session,<BR> const
|
||
char* interfaceName);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function specifies
|
||
which host network interface is used for IP Multicast transmissions
|
||
and group membership. This should be called <I>before</I> any call
|
||
to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> or
|
||
<FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT> is made so that the
|
||
IP multicast group is joined on the proper host interface. However,
|
||
if a call to <FONT FACE="Courier"><A HREF="#NormSetMulticastInterface()">NormSetMulticastInterface()</A></FONT>
|
||
is made <I>after</I> either of these function calls, the call will
|
||
not affect the group membership interface, but only dictate that a
|
||
possibly different network interface is used for transmitted NORM
|
||
messages. Thus, the code:</P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>NormSetMulticastInterface(session,
|
||
"interface1");<BR>NormStartReceiver(session,
|
||
...);<BR>NormSetMulticastInterface(session, "interface2");</FONT></FONT></P>
|
||
<P CLASS="western" STYLE="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="font-style: normal">A return value of <FONT FACE="Courier"><I>true</I></FONT>
|
||
indicates success while a return value of <FONT FACE="Courier"><I>false</I></FONT>
|
||
indicates that the specified interface was valid. This function will
|
||
always return <FONT FACE="Courier"><I>true</I></FONT> if made before
|
||
calls to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> or
|
||
<FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT>. However, those
|
||
calls may fail if an invalid interface is specified.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetTTL()">NormSetTTL()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetTTL(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> unsigned
|
||
char ttl);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function specifies
|
||
the time-to-live (<FONT FACE="Courier"><U>ttl</U></FONT>) for IP
|
||
Multicast datagrams generated by NORM for the specified <FONT FACE="Courier"><U>session</U></FONT>.
|
||
The IP TTL field limits the number of router "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="font-style: normal">A return value of <FONT FACE="Courier"><I>true</I></FONT>
|
||
indicates success while a return value of <FONT FACE="Courier"><I>false</I></FONT>
|
||
indicates that the specified <FONT FACE="Courier"><U>ttl</U></FONT>
|
||
could not be set. This function will always return <FONT FACE="Courier"><I>true</I></FONT>
|
||
if made before calls to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>
|
||
or <FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT>. However, those
|
||
calls may fail if the desired <FONT FACE="Courier"><U>ttl</U></FONT>
|
||
value cannot be set..</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetTOS()">NormSetTOS()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetTOS(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> unsigned
|
||
char tos);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function specifies
|
||
the type-of-service (<FONT FACE="Courier"><U>tos</U></FONT>) field
|
||
value used in IP Multicast datagrams generated by NORM for the
|
||
specified <FONT FACE="Courier"><U>session</U></FONT>. The IP TOS
|
||
field value can be used as an indicator that a "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="font-style: normal">A return value of <FONT FACE="Courier"><I>true</I></FONT>
|
||
indicates success while a return value of <FONT FACE="Courier"><I>false</I></FONT>
|
||
indicates that the specified <FONT FACE="Courier"><U>tos</U></FONT>
|
||
could not be set. This function will always return <FONT FACE="Courier"><I>true</I></FONT>
|
||
if made before calls to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>
|
||
or <FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT>. However, those
|
||
calls may fail if the desired <FONT FACE="Courier"><U>tos</U></FONT>
|
||
value cannot be set..</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetLoopback()">NormSetLoopback()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetLoopback(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> bool loopbackEnable);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function enables
|
||
or disables loopback operation for the indicated NORM <FONT FACE="Courier"><U>session</U></FONT>.
|
||
If <FONT FACE="Courier"><U>loopbackEnable</U></FONT> is set to <FONT FACE="Courier"><I>true</I></FONT>,
|
||
loopback operation is enabled which allows the application to receive
|
||
its own message traffic. Thus, an application which is both actively
|
||
receiving and sending may receive its own transmissions. Note it is
|
||
expected that this option would be principally be used for test
|
||
purposes and that applications would generally not need to transfer
|
||
data to themselves. If <FONT FACE="Courier"><U>loopbackEnable</U></FONT>
|
||
is <FONT FACE="Courier"><I>false</I></FONT>, the application is
|
||
prevented from receiving its own NORM message transmissions. By
|
||
default, loopback operation is disabled when a <I>NormSession</I> is
|
||
created.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H2 CLASS="western"><A NAME="NORM Sender Functions">NORM Sender Functions</A></H2>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStartSender()">NormStartSender()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormStartSender(<A HREF="#NormSessionHandle">NormSessionHandle</A> 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="font-style: normal">The application's
|
||
participation as a sender within a specified <I>NormSession</I>
|
||
begins when this function is called. This includes protocol activity
|
||
such as congestion control and/or group round-trip timing (GRTT)
|
||
feedback collection and application API activity such as posting of
|
||
sender-related <I>NormEvents</I>. The parameters required for this
|
||
function call include:</P>
|
||
<TABLE WIDTH=590 BORDER=0 CELLPADDING=7 CELLSPACING=0>
|
||
<COL WIDTH=125>
|
||
<COL WIDTH=437>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=125>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><U>sessionHandle</U></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=437>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This must be a valid <FONT FACE="Courier"><A HREF="#NormSessionHandle">NormSessionHandle</A></FONT>
|
||
previously obtained with a call to <FONT FACE="Courier"><A HREF="#NormCreateSession()">NormCreateSession()</A></FONT>.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=125>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><U>sessionId</U></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=437>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
Application-defined value used as the <I>instance_id</I> field of
|
||
NORM sender messages for the application's participation within a
|
||
session. Receivers can detect when a sender has terminated and
|
||
restarted if the application uses different <FONT FACE="Courier"><U>sessionId</U></FONT>
|
||
values when initiating sender operation. For example, a robust
|
||
application could cache previous <FONT FACE="Courier"><U>sessionId</U></FONT>
|
||
values in non-volatile storage and gracefully recover (without
|
||
confusing receivers) from a total system shutdown and reboot by
|
||
using a new <FONT FACE="Courier"><U>sessionId</U></FONT> value
|
||
upon restart.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=125>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><U>bufferSpace</U></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=437>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This specifies the maximum memory space the NORM protocol engine
|
||
is allowed to use to buffer any sender calculated FEC segments and
|
||
repair state for the session. The optimum <FONT FACE="Courier"><U>bufferSpace</U></FONT>
|
||
value is function of the network topology <I>bandwidth*delay</I>
|
||
product and packet loss characteristics. If the <FONT FACE="Courier"><U>bufferSpace</U></FONT>
|
||
limit is too small, the protocol may operate less efficiently as
|
||
the sender is required to possibly recalculate FEC parity segments
|
||
and/or provide less efficient repair transmission strategies
|
||
(resort to explicit repair) when state is dropped due to
|
||
constrained buffering resources. However, note the protocol will
|
||
still provide reliable transfer. A large <U><FONT FACE="Courier">bufferSpace</FONT></U>
|
||
allocation is safer at the expense of possibly committing more
|
||
memory resources.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=125>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><U>segmentSize</U></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=437>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This parameter sets the maximum <I>payload</I> size (in bytes) of
|
||
NORM sender messages (<I>not</I> including any NORM message header
|
||
fields). A sender's <FONT FACE="Courier">segmentSize</FONT> value
|
||
is also used by receivers to limit the payload content of some
|
||
feedback messages (e.g. NORM_NACK message content, etc.) generated
|
||
in response to that sender. Note different senders within a
|
||
<I>NormSession</I> may use different <FONT FACE="Courier">segmentSize</FONT>
|
||
values. Generally, the appropriate segment size to use is
|
||
dependent upon the types of networks forming the multicast
|
||
topology, but applications may choose different values for other
|
||
purposes. Note that application designers MUST account for the
|
||
size of NORM message headers when selecting a <FONT FACE="Courier"><U>segmentSize</U></FONT>.
|
||
For example, the NORM_DATA message header for a
|
||
<I><FONT FACE="Courier">NORM_OBJECT_STREAM</FONT></I> with full
|
||
header extensions is 48 bytes in length. In this case, the UDP
|
||
payload size of these messages generated by NORM would be up to
|
||
(48 + <FONT FACE="Courier"><U>segmentSize</U></FONT>) bytes.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=125>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
<FONT FACE="Courier"><U>blockSize</U></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=437>
|
||
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
||
This parameter sets the number of source symbol segments (packets)
|
||
per coding block, for the systematic Reed-Solomon FEC code used in
|
||
the current NORM implementation. For traditional systematic block
|
||
code "<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="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="font-style: normal">A value of <FONT FACE="Courier"><I>true</I></FONT>
|
||
is returned upon success and <FONT FACE="Courier"><I>false</I></FONT>
|
||
upon failure. The reasons failure may occur include limited system
|
||
resources or that the network sockets required for communication
|
||
failed to open or properly configure. <I>(TBD – Provide a
|
||
<FONT FACE="Courier">NormGetError(<A HREF="#NormSessionHandle">NormSessionHandle</A> session)</FONT>
|
||
function to retrieve a more specific error indication for this and
|
||
other functions.)</I></P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStopSender()">NormStopSender()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormStopSender(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> bool graceful
|
||
= false);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function
|
||
terminates the application's participation in a <I>NormSession</I> as
|
||
a sender. By default, the sender will immediately exit the session
|
||
without notifying the receiver set of its intention. However a
|
||
"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_SERVER_CLOSED,</I></FONT> is
|
||
dispatched when the graceful shutdown process has completed.</P>
|
||
<P CLASS="western" STYLE="font-style: normal"><I>(NOTE: The
|
||
"</I><FONT FACE="Courier"><U><I>graceful</I></U></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"><U><I>graceful</I></U></FONT><I>
|
||
= </I><FONT FACE="Courier"><SPAN STYLE="font-style: normal">false</SPAN></FONT><I>).
|
||
The functionality described here will soon be supported in the API.</I></P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetTransmitRate()">NormSetTransmitRate()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetTransmitRate(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> double rate);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function sets the
|
||
transmission rate limit (in bits per second (bps)) used for
|
||
<I>NormSender</I> transmissions. For fixed-rate transmission of
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT> or
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>, this limit
|
||
determines the data rate at which NORM protocol messages and data
|
||
content. For <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>
|
||
transmissions, this is the maximum rate allowed for transmission.
|
||
Note that the application will need to consider the overhead of NORM
|
||
protocol headers when determining an appropriate transmission rate
|
||
for its purposes. When NORM congestion control is enabled (see
|
||
<FONT FACE="Courier"><A HREF="#NormSetCongestionControl()">NormSetCongestionControl()</A></FONT>), the rate set
|
||
here will be set, but congestion control operation may quickly
|
||
readjust the rate unless disabled.
|
||
</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetTxSocketBuffer()">NormSetTxSocketBuffer()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetTxSocketBuffer(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> unsigned
|
||
int bufferSize);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function can be
|
||
used to set a non-default socket buffer size for the UDP socket used
|
||
by the specified NORM <FONT FACE="Courier"><U>session</U></FONT> for
|
||
data transmission. The <FONT FACE="Courier"><U>bufferSize</U></FONT>
|
||
parameter specifies the desired socket buffer size in bytes. Large
|
||
transmit socket buffer sizes may be necessary to achieve high
|
||
throughput rates when NORM, as a user-space process, is unable to
|
||
precisely time its packet transmissions. Similarly, NORM receivers
|
||
may need to set large receive socket buffer sizes to achieve
|
||
sustained high data rate reception (see <FONT FACE="Courier"><A HREF="#NormSetRxSocketBuffer()">NormSetRxSocketBuffer()</A></FONT>).
|
||
|
||
</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function returns
|
||
<FONT FACE="Courier"><I>true</I></FONT> upon success and <FONT FACE="Courier"><I>false</I></FONT>
|
||
upon failure. Possible failure modes include an invalid session
|
||
parameter, a call to <FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT>
|
||
or <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> has not yet been
|
||
made for the session, or an invalid <FONT FACE="Courier"><U>bufferSize</U></FONT>
|
||
was given. Note some operating systems may require additional
|
||
configuration to use non-standard socket buffer sizes.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetCongestionControl()">NormSetCongestionControl()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetTransmitRate(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> bool enable);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function enables
|
||
(or disables) the NORM sender congestion control operation for the
|
||
session designated by the <FONT FACE="Courier"><U>session</U></FONT>
|
||
parameter. For best operation, this function should be called before
|
||
the call to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> is made,
|
||
but congestion control operation can be dynamically enabled/disabled
|
||
during the course of sender operation. If the value of <FONT FACE="Courier"><U>enable</U></FONT>
|
||
is <FONT FACE="Courier"><I>true</I></FONT>, congestion control
|
||
operation is enabled while it is disabled for <FONT FACE="Courier"><U>enable</U></FONT>
|
||
equal to <FONT FACE="Courier"><I>false</I></FONT>. When congestion
|
||
control operation is enabled, the NORM sender automatically adjusts
|
||
its transmission rate based on feedback from receivers. If bounds on
|
||
transmission rate have been set (see <FONT FACE="Courier"><A HREF="#NormSetTransmitRateBounds()">NormSetTransmitRateBounds()</A></FONT>)
|
||
the rate adjustment will remain within any set bounds. The rate set
|
||
by <FONT FACE="Courier"><A HREF="#NormSetTransmitRate()">NormSetTransmitRate()</A></FONT> has no effect
|
||
when congestion control operation is enabled. NORM's congestion
|
||
algorithm provides rate adjustment to fairly compete for available
|
||
network bandwidth with other TCP, NORM, or similarly governed traffic
|
||
flows.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetTransmitRateBounds()">NormSetTransmitRateBounds()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetTransmitRateBounds(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> double rateMin,<BR> double rateMax);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function sets the
|
||
range of sender transmission rates within which the NORM congestion
|
||
control algorithm is allowed to operate. By default, the NORM
|
||
congestion control algorithm operates with no lower or upper bound on
|
||
its rate adjustment. This function allows this to be limited where
|
||
<FONT FACE="Courier"><U>rateMin</U></FONT> corresponds to the minimum
|
||
transmission rate (bps) and <FONT FACE="Courier"><U>rateMax</U></FONT>
|
||
corresponds to the maximum transmission rate. One or both of these
|
||
parameters may be set to values less than zero to remove one or both
|
||
bounds. For example "<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="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 STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><A NAME="OLE_LINK1"></A>
|
||
<FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetTransmitCacheBounds(<A HREF="#NormSessionHandle">NormSessionHandle</A> 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="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="font-style: normal">The <FONT FACE="Courier"><U>sizeMax</U></FONT>
|
||
parameter sets the maximum total size, in bytes, of enqueued objects
|
||
allowed, providing the constraints of the <FONT FACE="Courier"><U>countMin</U></FONT>
|
||
and <FONT FACE="Courier"><U>countMax</U></FONT> parameters are met.
|
||
The <FONT FACE="Courier"><U>countMin</U></FONT> parameter sets the
|
||
minimum number of objects the application may enqueue, regardless of
|
||
the objects' sizes and the <FONT FACE="Courier"><U>sizeMax</U></FONT>
|
||
value. For example, the default <FONT FACE="Courier"><U>sizeMax</U></FONT>
|
||
value is 20 Mbyte and the default <FONT FACE="Courier"><U>countMin</U></FONT>
|
||
is 8, thus allowing the application to always have at least 8 pending
|
||
objects enqueued for transmission if it desires, even if their total
|
||
size is greater than 20 Mbyte. Similarly, the <FONT FACE="Courier"><U>countMax</U></FONT>
|
||
parameter sets a ceiling on how many objects may be enqueued,
|
||
regardless of their total sizes with respect to the <FONT FACE="Courier"><U>sizeMax</U></FONT>
|
||
setting. For example, the default <FONT FACE="Courier"><U>countMax</U></FONT>
|
||
value is 256, which means the application is never allowed to have
|
||
more than 256 objects pending transmission enqueued, even if they are
|
||
256 very small objects. <I>Note that </I><FONT FACE="Courier"><U><I>countMax</I></U></FONT><I>
|
||
must be greater than or equal to </I><FONT FACE="Courier"><U><I>countMin</I></U></FONT><I>
|
||
and </I><FONT FACE="Courier"><U><I>countMin</I></U></FONT><I> is
|
||
recommended to be at least two.</I></P>
|
||
<P CLASS="western" STYLE="font-style: normal">Note that in the case
|
||
of NORM_OBJECT_FILE objects, some operating systems impose limits
|
||
(e.g. 256) on how many open files a process may have at one time and
|
||
it may be appropriate to limit the <FONT FACE="Courier"><U>countMax</U></FONT>
|
||
value accordingly. In other cases, a large <FONT FACE="Courier"><U>countMin</U></FONT>
|
||
or <FONT FACE="Courier"><U>countMax</U></FONT> may be desired to
|
||
allow the NORM sender to act as virtual cache of files or other data
|
||
available for reliable transmission. Future iterations of the NRL
|
||
NORM implementation may support alternative NORM receiver "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="font-style: normal">This function has no
|
||
return value.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetAutoParity()">NormSetAutoParity()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetAutoParity(<A HREF="#NormSessionHandle">NormSessionHandle</A> sessionHandle,
|
||
<BR> unsigned
|
||
char autoParity);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="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="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="font-style: normal">The value of <FONT FACE="Courier"><U>autoParity</U></FONT>
|
||
set must be less than or equal to the <FONT FACE="Courier"><U>numParity</U></FONT>
|
||
parameter set when <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> was
|
||
called for the given <FONT FACE="Courier"><U>sessionHandle</U></FONT>.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetGrttEstimate()">NormSetGrttEstimate()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetGrttEstimate(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> double grtt);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function sets the
|
||
sender's estimate of group round-trip timing (GRTT) for the given
|
||
NORM <FONT FACE="Courier"><U>session</U></FONT>. This function is
|
||
expected to most typically used to initialize the sender's GRTT
|
||
estimate prior to the call to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>
|
||
when the application has <I>a priori</I> confidence that the default
|
||
initial GRTT value of 0.5 second is inappropriate. The sender GRTT
|
||
estimate will be updated during normal sender protocol operation
|
||
after sender startup or if this call is made while sender operation
|
||
is active. For experimental purposes (or very special application
|
||
needs), this API provides a mechanism to control or disable the
|
||
sender GRTT update process (see <FONT FACE="Courier">NormSetGrttProbing()</FONT>).
|
||
The <FONT FACE="Courier"><U>grtt</U></FONT> value will be limited to
|
||
the maximum GRTT as set (see <FONT FACE="Courier"><A HREF="#NormSetGrttMax()">NormSetGrttMax()</A>)
|
||
</FONT>or the default maximum of 10 seconds.
|
||
</P>
|
||
<P CLASS="western" STYLE="font-style: normal">The sender GRTT is
|
||
advertised to the receiver group and is used to scale various NORM
|
||
protocol timers. The default NORM GRTT estimation process
|
||
dynamically measures round-trip timing to determine an appropriate
|
||
operating value. An overly-large GRTT estimate can introduce
|
||
additional latency into the reliability process (resulting in a
|
||
larger virtual <I>delay*bandwidth</I> product for the protocol and
|
||
potentially requiring more buffer space to maintain reliability). An
|
||
overly-small GRTT estimate may introduce the potential for feedback
|
||
implosion, limiting the scalability of group size.
|
||
</P>
|
||
<P CLASS="western" STYLE="font-style: normal">Also note that the
|
||
advertised GRTT estimate can also be limited by transmission rate.
|
||
When the sender transmission rate is low, the GRTT is also governed
|
||
to a lower bound of the nominal packet transmission interval (i.e.,
|
||
<FONT FACE="Courier">1/txRate</FONT>). This maintains the “event
|
||
driven” nature of the NORM protocol with respect to receiver
|
||
reception of NORM sender data and commands.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetGrttMax()">NormSetGrttMax()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetGrttMax(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> double grttMax);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function sets the
|
||
sender's maximum advertised GRTT value for the given NORM <FONT FACE="Courier"><U>session</U></FONT>.
|
||
The <FONT FACE="Courier"><U>grttMax</U></FONT> parameter, in units
|
||
of <I>seconds</I>, limits the GRTT used by the group for scaling
|
||
protocol timers, regardless of larger measured round trip times.
|
||
The default maximum for the NRL NORM library is 10 seconds. See the
|
||
<FONT FACE="Courier"><A HREF="#NormSetGrttEstimate()">NormSetGrttEstimate()</A></FONT> function
|
||
description for the purpose of the NORM GRTT measurement process.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetGrttProbingMode()">NormSetGrttProbingMode()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetGrttProbingMode(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> <A HREF="#NormProbingMode">NormProbingMode</A> probingMode);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function sets the
|
||
sender's mode of probing for round trip timing measurement responses
|
||
from the receiver set for the given NORM <FONT FACE="Courier"><U>session</U></FONT>.
|
||
Possible values for the <FONT FACE="Courier"><U>probingMode</U></FONT>
|
||
parameter include <FONT FACE="Courier"><I>NORM_PROBE_NONE</I></FONT>,
|
||
<FONT FACE="Courier"><I>NORM_PROBE_PASSIVE</I></FONT>, and
|
||
<FONT FACE="Courier"><I>NORM_PROBE_ACTIVE</I></FONT>. The default
|
||
probing mode is <FONT FACE="Courier"><I>NORM_PROBE_ACTIVE</I></FONT>.
|
||
In this mode, the receiver set explicitly acknowledges NORM sender
|
||
GRTT probes (NORM_CMD(CC) messages) with NORM_ACK responses that are
|
||
group-wise suppressed. Note that NORM receivers also will include
|
||
their response to GRTT probing piggy-backed on any NORM_NACK messages
|
||
sent in this mode as well to minimize feedback.
|
||
</P>
|
||
<P CLASS="western" STYLE="font-style: normal">Note that the
|
||
<FONT FACE="Courier"><I>NORM_PROBE_ACTIVE</I></FONT> probing mode is
|
||
<I>required</I> and automatically set when NORM congestion control
|
||
operation is enabled (see <FONT FACE="Courier"><A HREF="#NormSetCongestionControl()">NormSetCongestionControl()</A></FONT>).
|
||
Thus, when congestion control is enabled, the
|
||
<FONT FACE="Courier"><A HREF="#NormSetGrttProbingMode()">NormSetGrttProbingMode()</A></FONT> function has no
|
||
effect.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">If congestion control
|
||
operation is not enabled, the NORM applicaiton may elect to reduce
|
||
the volume of feedback traffic by setting the <FONT FACE="Courier"><U>probingMode</U></FONT>
|
||
to <FONT FACE="Courier"><I>NORM_PROBE_PASSIVE.</I></FONT> Here, the
|
||
NORM sender still transmits NORM_CMD(CC) probe messages multiplexed
|
||
with its data transmission, but the receiver set does not explicitly
|
||
acknowledge these probes. Instead the receiver set is limited to
|
||
piggy-backing responses when NORM_NACK messages are generated. Note
|
||
that this may, in some cases, introduce some opportunity for bursts
|
||
of large volume receiver feedback when the sender’s estimate of
|
||
GRTT is incorrect due to the reduced probing feedback. But, in some
|
||
controlled network environments, this option for passive probing may
|
||
provide some benefits in reducing protocol overhead.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">Finally, the
|
||
<FONT FACE="Courier"><U>probingMode</U></FONT> can be set to
|
||
<FONT FACE="Courier"><I>NORM_PROBE_NONE</I></FONT> to eliminate the
|
||
overhead (and benefits) of NORM GRTT measurement entirely. In this
|
||
case, the sender application must explicitly set its estimate of GRTT
|
||
using the <FONT FACE="Courier"><A HREF="#NormSetGrttEstimate()">NormSetGrttEstimate()</A></FONT> function.
|
||
See this function for a description of the purpose of the NORM GRTT
|
||
measurement.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetGrttProbingInterval()">NormSetGrttProbingInterval()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetGrttProbingInterval(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> double intervalMin,<BR> double intervalMax);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function controls
|
||
the sender GRTT measurement and estimation process for the given NORM
|
||
<FONT FACE="Courier"><U>session</U></FONT>. The NORM sender
|
||
multiplexes periodic transmission of NORM_CMD(CC) messages with its
|
||
ongoing data transmission or when data transmission is idle. When
|
||
NORM congestion control operation is enabled, these probes are sent
|
||
once per RTT of the current limiting receiver (with respect to
|
||
congestion control rate). In this case the <FONT FACE="Courier"><U>intervalMin</U></FONT>
|
||
and <FONT FACE="Courier"><U>intervalMax</U></FONT> parameters (in
|
||
units of <I>seconds</I>) control the rate at which the sender’s
|
||
estimate of GRTT is updated. At session start, the estimate is
|
||
updated at <FONT FACE="Courier"><U>intervalMin</U></FONT> and the
|
||
update interval time is doubled until <FONT FACE="Courier"><U>intervalMax</U></FONT>
|
||
is reached. This dynamic allows for a rapid initial estimation of
|
||
GRTT and a slower, steady-state update of GRTT. When congestion
|
||
control is disabled and NORM GRTT probing is enabled
|
||
(NORM_PROBE_ACTIVE or NORM_PROBE_PASSIVE) the <FONT FACE="Courier"><U>intervalMin</U></FONT>
|
||
and <FONT FACE="Courier"><U>intervalMax</U></FONT> values also
|
||
determine the rate at which NORM_CMD(CC) probes are transmitted by
|
||
the sender. Thus by setting larger values for <FONT FACE="Courier"><U>intervalMin</U></FONT>
|
||
and <FONT FACE="Courier"><U>intervalMax</U></FONT>, the NORM sender
|
||
application can reduce the overhead of the GRTT measurement process.
|
||
However, this also reduces the ability of NORM to adapt to changes in
|
||
GRTT.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">The default NORM GRTT
|
||
<FONT FACE="Courier"><U>intervalMin</U></FONT> and <FONT FACE="Courier"><U>intervalMax</U></FONT>
|
||
values are 1.0 second and 30.0 seconds, respectively.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormFileEnqueue()">NormFileEnqueue()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
NormFileEnqueue(<A HREF="#NormSessionHandle">NormSessionHandle</A> 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="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="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="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 STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
NormDataEnqueue(<A HREF="#NormSessionHandle">NormSessionHandle</A> 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="font-style: normal">This function enqueues
|
||
a segment of application memory space for transmission within the
|
||
specified NORM <FONT FACE="Courier"><U>session</U></FONT>. Note that
|
||
<FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT> must have been
|
||
previously called before files or any transport objects may be
|
||
enqueued and transmitted. The <FONT FACE="Courier"><U>dataPtr</U></FONT>
|
||
parameter must be a valid pointer to the area of application memory
|
||
to be transmitted and the <FONT FACE="Courier"><U>dataLen</U></FONT>
|
||
parameter indicates the quantity of data to transmit. The NORM
|
||
protocol engine read and writes directly from/to application memory
|
||
space so it is important that the application does not modify (or
|
||
deallocate) the memory space during the time the NORM protocel engine
|
||
may access this area. The optional <FONT FACE="Courier"><U>infoPtr</U></FONT>
|
||
and <FONT FACE="Courier"><U>infoLen</U></FONT> parameters are used to
|
||
associate NORM_INFO content with the sent transport object. The
|
||
maximum allowed <FONT FACE="Courier"><U>infoLen</U></FONT>
|
||
corresponds to the <FONT FACE="Courier"><U>segmentSize</U></FONT>
|
||
used in the prior call to <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>.
|
||
The use and interpretation of the NORM_INFO content is left to the
|
||
application's discretion. Example usage of NORM_INFO content for
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT> might include
|
||
application-defined data typing or other information which will
|
||
enable NORM receiver applications to properly interpret the received
|
||
data when reception is complete. Of course, it is possible that the
|
||
application may embed such typing information in the object data
|
||
content itself. This is left to the application's discretion.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">The application is
|
||
allowed to enqueue multiple transmit objects within in the "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="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="NormStreamOpen()">NormStreamOpen()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
NormStreamOpen(<A HREF="#NormSessionHandle">NormSessionHandle</A> 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="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="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="font-style: normal">Note that the current
|
||
implementation of NORM is designed to support only one active stream
|
||
per session, and that any <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>
|
||
or <FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT> objects
|
||
enqueued for transmission will not begin transmission until an active
|
||
stream is closed. Applications requiring multiple streams or
|
||
concurrent file/data transfer should instantiate multiple
|
||
<I>NormSessions</I> as needed.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">Note there is no
|
||
corresponding "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="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 STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormStreamClose(<A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
streamHandle,<BR> bool graceful
|
||
= false);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function halts
|
||
transfer of the stream specified by the <FONT FACE="Courier"><U>streamHandle</U></FONT>
|
||
parameter and releases any resources used unless the associated
|
||
object has been explicitly retained by a call to <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT>.
|
||
No further calls to <FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT>
|
||
will be successful for the given <FONT FACE="Courier"><U>streamHandle</U></FONT>.
|
||
The optional <FONT FACE="Courier"><U>graceful</U></FONT> parameter,
|
||
when set to a value of <FONT FACE="Courier"><I>true</I></FONT>, may
|
||
be used by NORM senders to initiate "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="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStreamWrite()">NormStreamWrite()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>unsigned
|
||
int
|
||
NormStreamWrite(<A HREF="#NormObjectHandle">NormObjectHandle</A> streamHandle<BR> const
|
||
char* buffer,<BR> unsigned
|
||
int numBytes);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function enqueues
|
||
data for transmission within the NORM stream specified by the
|
||
<FONT FACE="Courier"><U>streamHandle</U></FONT> parameter. The
|
||
<FONT FACE="Courier"><U>buffer</U></FONT> parameter must be a pointer
|
||
to the data to be enqueued and the <FONT FACE="Courier"><U>numBytes</U></FONT>
|
||
parameter indicates the length of the data content. Note this call
|
||
does not block and will return immediately. The return value
|
||
indicates the number of bytes copied from the provided buffer to the
|
||
internal stream transmission buffers. Calls to this function will be
|
||
successful unless the stream's transmit buffer space is fully
|
||
occupied with data pending original or repair transmission if the
|
||
stream's "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.
|
||
</P>
|
||
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT>
|
||
NORM_TX_QUEUE_VACANCY is posted with its <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, after this event type is posted, the application <I>must</I>
|
||
make a call to <FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT> with a
|
||
non-zero <FONT FACE="Courier"><U>numBytes</U></FONT> value before
|
||
addition NORM_TX_QUEUE_VACANCY events are posted for the given
|
||
<FONT FACE="Courier"><U>streamHandle</U></FONT>.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function returns
|
||
the number of bytes of data successfully enqueued for NORM stream
|
||
transmission. If the underlying send stream buffer is full, this
|
||
function may return zero.
|
||
</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStreamFlush()">NormStreamFlush()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormStreamFlush(<A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
streamHandle,<BR> 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="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="font-style: normal">The optional <FONT FACE="Courier"><U>eom</U></FONT>
|
||
parameter, when set to <FONT FACE="Courier"><I>true</I></FONT>,
|
||
allows the sender application to mark an end-of-message indication
|
||
(see <FONT FACE="Courier"><A HREF="#NormStreamMarkEom()">NormStreamMarkEom()</A></FONT>) for the stream
|
||
and initiate flushing in a single function call. The end-of-message
|
||
indication causes NORM to mark the first NORM_DATA message generated
|
||
following a subsequent write to the stream with the
|
||
NORM_FLAGS_MSG_START flag. This mechanism provide a means for
|
||
message boundary recovery when receivers join or re-sync to a sender
|
||
mid-stream.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">Note that frequent
|
||
flushing, particularly for <FONT FACE="Courier"><I>NORM_FLUSH_ACTIVE</I></FONT>
|
||
operation, may result in more NORM protocol activity than usual, so
|
||
care must be taken in application design and deployment when
|
||
scalability to large group sizes is expected.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStreamSetAutoFlush()">NormStreamSetAutoFlush()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormStreamSetAutoFlush(<A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
streamHandle<BR> <A HREF="#NormFlushMode">NormFlushMode</A> flushMode);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="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 SIZE=2><FONT FACE="Courier"><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT></FONT>).
|
||
However, to simplify programming, the NORM API allows that automated
|
||
flushing be enabled such that the "flush" operation occurs
|
||
every time the <I>full</I> requested <FONT FACE="Courier"><U>buffer</U></FONT>
|
||
provided to a <FONT SIZE=2><FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT></FONT>
|
||
call is successfully enqueued. This may be appropriate for messaging
|
||
applications where the provided buffers corresponds to an application
|
||
messages requiring immediate, full transmission. This may make the
|
||
NORM protocol perhaps more "chatty" than its typical "bulk
|
||
transfer" form of operation, but can provide a useful capability
|
||
for some applications.
|
||
</P>
|
||
<P CLASS="western" STYLE="font-style: normal">Possible values for the
|
||
<FONT FACE="Courier"><U>flushMode</U></FONT> parameter include
|
||
<FONT FACE="Courier"><I>NORM_FLUSH_NONE</I></FONT>,
|
||
<FONT FACE="Courier"><I>NORM_FLUSH_PASSIVE</I></FONT>, and
|
||
<FONT FACE="Courier"><I>NORM_FLUSH_ACTIVE</I></FONT>. The default
|
||
setting for a NORM stream is <FONT FACE="Courier"><I>NORM_FLUSH_NONE</I></FONT>
|
||
where no flushing occurs unless explicitly requested via
|
||
<FONT SIZE=2><FONT FACE="Courier"><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT></FONT>.
|
||
By setting the automated <FONT FACE="Courier"><U>flushMode</U></FONT>
|
||
to <FONT FACE="Courier"><I>NORM_FLUSH_PASSIVE</I></FONT>, the only
|
||
action taken is to immediately transmit any data that has been
|
||
written to the stream, even if "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="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStreamSetPushEnable()">NormStreamSetPushEnable()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormStreamSetPushEnable(<A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
streamHandle<BR> bool pushEnable);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function controls
|
||
how the NORM API behaves when the application attempts to enqueue new
|
||
stream data for transmission when the associated stream's transmit
|
||
buffer is fully occupied with data pending original or repair
|
||
transmission. By default (<FONT FACE="Courier"><U>pushEnable</U></FONT>
|
||
== <FONT FACE="Courier"><I>false</I></FONT>), a call to
|
||
<FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT> will return a zero
|
||
value under this condition, indicating it was unable to enqueue the
|
||
new data. However, if <FONT FACE="Courier"><U>pushEnable</U></FONT>
|
||
is set to <FONT FACE="Courier"><I>true</I></FONT> for a given
|
||
<FONT FACE="Courier"><U>streamHandle</U></FONT>, the NORM protocol
|
||
engine will discard the oldest buffered stream data (even if it is
|
||
pending repair transmission or has never been transmitted) as needed
|
||
to enqueue the new data. Thus a call to <FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT>
|
||
will never fail to copy data. This behavior may be desirable for
|
||
applications where it is more important to quickly delivery new data
|
||
than to reliably deliver older data written to a stream. The default
|
||
behavior for a newly opened stream corresponds to <FONT FACE="Courier"><U>pushEnable</U></FONT>
|
||
equals <FONT FACE="Courier"><I>false</I></FONT>. This limits the
|
||
rate to which an application can write new data to the stream to the
|
||
current transmission rate and status of the reliable repair process.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStreamHasVacancy()">NormStreamHasVacancy()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormStreamHasVacancy(<A HREF="#NormObjectHandle">NormObjectHandle</A> streamHandle);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function can be
|
||
used to query whether the transmit stream, specified by the
|
||
<FONT FACE="Courier"><U>streamHandle</U></FONT> parameter, has buffer
|
||
space available so that the application may successfully make a call
|
||
to <FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT>. Normally, a call
|
||
to <FONT FACE="Courier"><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT> itself can be used
|
||
to make this determination, but this function can be useful when
|
||
"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="font-style: normal">This function returns a
|
||
value of <FONT FACE="Courier"><I>true</I></FONT> when there is
|
||
transmit buffer space to which the application may write and <FONT FACE="Courier"><I>false</I></FONT>
|
||
otherwise.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStreamMarkEom()">NormStreamMarkEom()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormStreamMarkEom(<A HREF="#NormObjectHandle">NormObjectHandle</A> streamHandle);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function allows
|
||
the application to indicate to the NORM protocol engine that the last
|
||
data successfully written to the stream indicated by <FONT FACE="Courier"><U>streamHandle</U></FONT>
|
||
corresponded to the end of an application-defined message boundary.
|
||
If the stream is either explicitly flushed at this point (see
|
||
<FONT FACE="Courier"><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT>) or the last write had
|
||
exactly filled a <I>NormSender</I> <FONT FACE="Courier"><U>segmentSize</U></FONT>
|
||
NORM_DATA message payload, the beginning of the next write will
|
||
correspond to the beginning of a new NORM_DATA message. The
|
||
end-of-message indication given here will cause the NORM protocol
|
||
engine to flag this new message with NORM_FLAG_MSG_START which allows
|
||
receivers to recover message boundary synchronization even when
|
||
beginning reception mid-stream. Note that the marking is most
|
||
effective when explicit flushing is used which forces alignment of
|
||
application message boundaries with NORM_DATA messages. It is
|
||
anticipated that future versions of the NORM protocol specification
|
||
(and/or the NRL implementation) will provide additional, more
|
||
flexible stream control mechanisms (e.g. mid-segment message boundary
|
||
alignment) that allow for more robust message boundary recovery.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">It is recommended that
|
||
the <FONT FACE="Courier"><A HREF="#NormStreamMarkEom()">NormStreamMarkEom()</A></FONT> should be used
|
||
with automated flushing modes (see <FONT FACE="Courier"><A HREF="#NormStreamSetAutoFlush()">NormStreamSetAutoFlush()</A></FONT>)
|
||
while the optional <FONT FACE="Courier"><U>eom</U></FONT> parameter
|
||
of <FONT FACE="Courier"><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT> is instead used when
|
||
explicit flushing is practiced. End-of-message marking <I>may</I> be
|
||
used when no flushing is done, but note then there is no guarantee of
|
||
message boundary to NORM_DATA message alignment unless the
|
||
application message sizes correspond to multiples of the configured
|
||
<I>NormSender</I> <FONT FACE="Courier"><U>segmentSize</U></FONT>.
|
||
Again, note future versions of NORM and this implementation may
|
||
provide more flexibility here.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetWatermark()">NormSetWatermark()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetWatermark(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> <A HREF="#NormObjectHandle">NormObjectHandle</A> object);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="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 SIZE=2><FONT FACE="Courier">,</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="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="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="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="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 STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormAddAckingNode(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> <A HREF="#NormNodeId">NormNodeId</A> nodeId);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">When this function is
|
||
called, the specified <FONT FACE="Courier"><U>nodeId</U></FONT> is
|
||
added to the list of <I>NormNodes</I> used when NORM sender operation
|
||
performs positive acknowledgement (ACK) collection for the specified
|
||
<FONT FACE="Courier"><U>session</U></FONT>. The optional NORM
|
||
positive acknowledgement collection occurs when a specified
|
||
transmission point (see <FONT FACE="Courier"><A HREF="#NormSetWatermark()">NormSetWatermark()</A>)</FONT>
|
||
is reached or for specialized protocol actions such as
|
||
positively-acknowledged application-defined commands. 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="font-style: normal">The function returns
|
||
<FONT FACE="Courier"><I>true</I></FONT> upon success and <FONT FACE="Courier"><I>false</I></FONT>
|
||
upon failure. The only failure condition is that insufficient memory
|
||
resources were available. If a specific <FONT FACE="Courier"><U>nodeId</U></FONT>
|
||
is added more than once, this has no effect.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormRemoveAckingNode()">NormRemoveAckingNode()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormRemoveAckingNode(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,<BR> <A HREF="#NormNodeId">NormNodeId</A> nodeId);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function deletes
|
||
the specified <FONT FACE="Courier"><U>nodeId</U></FONT> from the list
|
||
of <I>NormNodes</I> used when NORM sender operation performs positive
|
||
acknowledgement (ACK) collection for the specified <FONT FACE="Courier"><U>session</U></FONT>.
|
||
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="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 STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="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="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="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="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 STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormStartReceiver(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> unsigned
|
||
long bufferSpace);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function initiates
|
||
the application's participation as a receiver within the <I>NormSession</I>
|
||
identified by the <FONT FACE="Courier"><U>session</U></FONT>
|
||
parameter. The receiver will respond with appropriate protocol
|
||
messages (unless <FONT FACE="Courier">NormSetSilentReceiver(</FONT><FONT FACE="Courier"><I>true</I></FONT><FONT FACE="Courier">)</FONT>
|
||
is invoked) and begin providing the application with
|
||
receiver-related <I><A HREF="#NormEvent">NormEvent</A></I> notification. The <FONT FACE="Courier"><U>bufferSpace</U></FONT>
|
||
parameter is used to set a limit on the amount of <FONT FACE="Courier"><U>bufferSpace</U></FONT>
|
||
allocated by the receiver per active <I>NormSender</I> within the
|
||
session. The appropriate <FONT FACE="Courier"><U>bufferSpace</U></FONT>
|
||
to use is a function of expected network <I>delay*bandwidth</I>
|
||
product and packet loss characteristics. A discussion of trade-offs
|
||
associated with NORM transmit and receiver buffer space selection is
|
||
provided later in this document. An insufficient bufferSpace
|
||
allocation will result in potentially inefficient protocol operation,
|
||
even though reliable operation may be maintained. In some cases of a
|
||
large <I>delay*bandwidth</I> product and/or severe packet loss, a
|
||
small <FONT FACE="Courier"><U>bufferSpace</U></FONT> allocation
|
||
(coupled with the lack of explicit flow control in NORM) may result
|
||
in the receiver "re-syncing" to the sender, resulting in
|
||
"outages" in the reliable transmissions from a sender (this
|
||
is similar to the conditions resulting in a TCP connection timeout
|
||
failure).
|
||
</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">A value of <FONT FACE="Courier"><I>true</I></FONT>
|
||
is returned upon success and <FONT FACE="Courier"><I>false</I></FONT>
|
||
upon failure. The reasons failure may occur include limited system
|
||
resources or that the network sockets required for session
|
||
communication failed to open or properly configure.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStopReceiver()">NormStopReceiver()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormStopReceiver(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> unsigned
|
||
int gracePeriod = 0);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function ends the
|
||
application's participation as a receiver in the <I>NormSession</I>
|
||
specified by the <FONT FACE="Courier"><U>session</U></FONT>
|
||
parameter. By default, all receiver-related protocol activity is
|
||
immediately halted and all receiver-related resources are freed
|
||
(except for those which have been specifically retained (see
|
||
<FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT>). However, and
|
||
optional <FONT FACE="Courier"><U>gracePeriod</U></FONT> parameter is
|
||
provided to allow the receiver an opportunity to inform the group of
|
||
its intention. This is applicable when the local receiving <I>NormNode</I>
|
||
has been designated as an active congestion control representative
|
||
(i.e. current limiting receiver (CLR) or potential limiting receiver
|
||
(PLR)). In this case, a non-zero <FONT FACE="Courier"><U>gracePeriod</U></FONT>
|
||
value provides an opportunity for the receiver to respond to the
|
||
applicable sender(s) so the sender will not expect further congestion
|
||
control feedback from this receiver. The <FONT FACE="Courier"><U>gracePeriod</U></FONT>
|
||
integer value is used as a multiplier with the largest sender GRTT to
|
||
determine the actual time period for which the receiver will linger
|
||
in the group to provide such feedback (i.e. "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="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetRxSocketBuffer()">NormSetRxSocketBuffer()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormSetRxSocketBuffer(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> unsigned
|
||
int bufferSize);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function allows
|
||
the application to set an alternative, non-default buffer size for
|
||
the UDP socket used by the specified NORM <FONT FACE="Courier"><U>session</U></FONT>
|
||
for packet reception. This may be necessary for high speed NORM
|
||
sessions where the UDP receive socket buffer becomes a bottleneck
|
||
when the NORM protocol engine (which is running as a user-space
|
||
process) doesn't get to service the receive socket quickly enough
|
||
resulting in packet loss when the socket buffer overflows. The
|
||
<FONT FACE="Courier"><U>bufferSize</U></FONT> parameter specifies the
|
||
socket buffer size in bytes. Different operating systems and
|
||
sometimes system configurations allow different ranges of socket
|
||
buffer sizes to be set. Note that a call to <FONT FACE="Courier"><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT>
|
||
(or <FONT FACE="Courier"><A HREF="#NormStartSender()">NormStartSender()</A></FONT>) must have been
|
||
previously made for this call to succeed (i.e., the socket must be
|
||
already open).</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function returns
|
||
<FONT FACE="Courier"><I>true</I></FONT> upon success and <FONT FACE="Courier"><I>false</I></FONT>
|
||
upon failure. Possible reasons for failure include, 1) the specified
|
||
<FONT FACE="Courier"><U>session</U></FONT> is not valid, 2) that NORM
|
||
"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 STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetSilentReceiver(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> bool silent);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function provides
|
||
the option to configure a NORM receiver application as a "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>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetDefaultUnicastNack()">NormSetDefaultUnicastNack()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetDefaultUnicastNack(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> bool state);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function controls
|
||
the default behavior determining the destination of receiver feedback
|
||
messages generated while participating in the session. If <FONT FACE="Courier"><I>state</I></FONT>
|
||
is true, "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="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormNodeSetUnicastNack()">NormNodeSetUnicastNack()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormNodeSetUnicastNack(<A HREF="#NormNodeHandle">NormNodeHandle</A> senderNode,
|
||
<BR> bool state);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function controls
|
||
the the destination address of receiver feedback messages generated
|
||
in response to a specific remote NORM sender.. If <FONT FACE="Courier"><I>state</I></FONT>
|
||
is true, "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="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetDefaultNackingMode()">NormSetDefaultNackingMode()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetDefaultNackingMode(<A HREF="#NormSessionHandle">NormSessionHandle</A> session,
|
||
<BR> <A HREF="#NormNackingMode">NormNackingMode</A> nackingMode);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function sets the
|
||
default "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-style: normal"><FONT FACE="Courier"><I>NORM_NACK_NONE</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=332>
|
||
<P CLASS="western" STYLE="margin-left: 0.02in; font-style: normal">
|
||
Do not transmit any repair requests for the newly received object.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=231>
|
||
<P CLASS="western" STYLE="margin-left: 0.5in; font-style: normal"><FONT FACE="Courier"><I>NORM_NACK_INFO_ONLY</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=332>
|
||
<P CLASS="western" STYLE="margin-left: 0.02in; font-style: normal">
|
||
Transmit repair requests for NORM_INFO content only as needed.</P>
|
||
</TD>
|
||
</TR>
|
||
<TR VALIGN=TOP>
|
||
<TD WIDTH=231>
|
||
<P CLASS="western" STYLE="margin-left: 0.5in; font-style: normal"><FONT FACE="Courier"><I>NORM_NACK_NORMAL</I></FONT></P>
|
||
</TD>
|
||
<TD WIDTH=332>
|
||
<P CLASS="western" STYLE="margin-left: 0.02in; font-style: normal">
|
||
Transmit repair requests for entire object as needed.</P>
|
||
</TD>
|
||
</TR>
|
||
</TABLE>
|
||
<P CLASS="western" STYLE="font-style: normal">This function specifies
|
||
the default behavior with respect to any <I>new</I> sender or object.
|
||
This default behavior may be overridden for specific sender nodes or
|
||
specific object using <FONT FACE="Courier"><A HREF="#NormNodeSetNackingMode()">NormNodeSetNackingMode()</A></FONT>
|
||
or <FONT FACE="Courier"><A HREF="#NormObjectSetNackingMode()">NormObjectSetNackingMode()</A></FONT>,
|
||
respectively. The receiver application's use of <FONT FACE="Courier"><I>NORM_NACK_NONE</I></FONT>
|
||
essentially disables a guarantee of reliable reception, although the
|
||
receiver may still take advantage of sender repair transmissions in
|
||
response to other receivers' requests. When the sender provides,
|
||
NORM_INFO content for transmitted objects, the <FONT FACE="Courier"><I>NORM_NACK_INFO_ONLY</I></FONT>
|
||
mode may allows the receiver to reliably receive object context
|
||
information from which it may choose to "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="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormNodeSetNackingMode()">NormNodeSetNackingMode()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormNodeSetNackingMode(<A HREF="#NormNodeHandle">NormNodeHandle</A> nodeHandle,
|
||
<BR> <A HREF="#NormNackingMode">NormNackingMode</A>
|
||
nackingMode);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function sets the
|
||
default "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="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormObjectSetNackingMode()">NormObjectSetNackingMode()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormObjectSetNackingMode(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle,
|
||
<BR> <A HREF="#NormNackingMode">NormNackingMode</A> nackingMode);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function sets the
|
||
"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="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormSetDefaultRepairBoundary()">NormSetDefaultRepairBoundary()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormSetDefaultRepairBoundary(<A HREF="#NormSessionHandle">NormSessionHandle</A> sessionHandle,
|
||
<BR> <A HREF="#NormRepairBoundary">NormRepairBoundary</A>
|
||
repairBoundary);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function allows
|
||
the receiver application to customize, for a given <FONT FACE="Courier"><U>sessionHandle</U></FONT>,
|
||
at what points the receiver initiates the NORM NACK repair process
|
||
during protocol operation. Normally, the NORM receiver initiates
|
||
NACking for repairs at the FEC code block and transport object
|
||
boundaries. For smaller block sizes, the NACK repair process is
|
||
often/quickly initiated and the repair of an object will occur, as
|
||
needed, during the transmission of the object. This default
|
||
operation corresponds to <FONT FACE="Courier"><U>repairBoundary</U></FONT>
|
||
equal to <FONT FACE="Courier"><I>NORM_BOUNDARY_BLOCK</I></FONT>.
|
||
Using this function, the application may alternatively, setting
|
||
repairBoundary equal to <FONT FACE="Courier"><I>NORM_BOUNDARY_OBJECT</I></FONT>,
|
||
cause the protocol to defer NACK process initiation until the current
|
||
transport object has been completely transmitted. This mode of
|
||
operation may be useful when it is desirable to allow receivers with
|
||
high quality network connectivity (perhaps requiring only a little
|
||
(or even no) "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="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormNodeSetRepairBoundary()">NormNodeSetRepairBoundary()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormNodeSetRepairBoundary(<A HREF="#NormNodeHandle">NormNodeHandle</A> nodeHandle,
|
||
<BR> <A HREF="#NormRepairBoundary">NormRepairBoundary</A>
|
||
repairBoundary);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function allows
|
||
the receiver application to customize, for the specific remote sender
|
||
referenced by the <FONT FACE="Courier"><U>nodeHandle</U></FONT>
|
||
parameter, at what points the receiver initiates the NORM NACK repair
|
||
process during protocol operation. See the description of
|
||
<FONT FACE="Courier"><A HREF="#NormSetDefaultRepairBoundary()">NormSetDefaultRepairBoundary()</A></FONT> for
|
||
further details on the impact of setting the NORM receiver repair
|
||
boundary and possible values for the <FONT FACE="Courier"><U>repairBoundary</U></FONT>
|
||
parameter.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return values.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStreamRead()">NormStreamRead()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormStreamRead(<A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
streamHandle,<BR> char* buffer<BR> unsigned
|
||
int* numBytes);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function can be
|
||
used by the receiver application to read any available data from an
|
||
incoming NORM stream. NORM receiver applications "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="font-style: normal">Note that
|
||
<FONT FACE="Courier"><A HREF="#NormStreamRead()">NormStreamRead()</A></FONT> is never a blocking call
|
||
and only returns failure (<FONT FACE="Courier"><I>false</I></FONT>)
|
||
when a break in the integrity of the received stream occurs. The
|
||
<FONT FACE="Courier"><I>NORM_RX_OBJECT_UPDATE</I></FONT> provides an
|
||
indication to when there is stream data available for reading. When
|
||
such notification occurs, the application <I>should</I> repeatedly
|
||
read from the stream until the <FONT FACE="Courier"><U>numBytes</U></FONT>
|
||
storage is set to zero, even if a <FONT FACE="Courier"><I>false</I></FONT>
|
||
value is returned. Additional <FONT FACE="Courier"><I>NORM_RX_OBJECT_UPDATE</I></FONT>
|
||
notifications might not be posted until the application can has read
|
||
all available data.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function normally
|
||
returns a value of <FONT FACE="Courier"><I>true</I></FONT>. However,
|
||
if a break in the integrity of the reliable received stream occurs
|
||
(or the stream has been ended by the sender), a value of <FONT FACE="Courier"><I>false</I></FONT>
|
||
is returned to indicate the break. Unless the stream has been ended
|
||
(and the receiver application will receive <FONT FACE="Courier"><I>NORM_RX_OBJECT_COMPLETED</I></FONT>
|
||
notification for the stream in that case), the application may
|
||
continue to read from the stream as the NORM protocol will
|
||
automatically "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 STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormStreamSeekMsgStart(<A HREF="#NormObjectHandle">NormObjectHandle</A> streamHandle);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function advances
|
||
the read offset of the receive stream referenced by the <FONT FACE="Courier"><U>streamHandle</U></FONT>
|
||
parameter to align with the next available message boundary. Message
|
||
boundaries are defined by the sender application using the
|
||
<FONT FACE="Courier"><A HREF="#NormStreamMarkEom()">NormStreamMarkEom()</A></FONT> call. Note that any
|
||
received data prior to the next message boundary is discarded by the
|
||
NORM protocol engine and is not available to the application (i.e.,
|
||
there is currently no "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="font-style: normal">This function returns a
|
||
value of <FONT FACE="Courier"><I>true</I></FONT> when
|
||
start-of-message is found. The next call to <FONT FACE="Courier"><A HREF="#NormStreamRead()">NormStreamRead()</A></FONT>
|
||
will retrieve data aligned with the message start. If no new message
|
||
boundary is found in the buffered receive data for the stream, the
|
||
function returns a value of <FONT FACE="Courier"><I>false</I></FONT>.
|
||
In this case, the application should defer repeating a call to this
|
||
function until a subsequent <FONT FACE="Courier"><I>NORM_RX_OBJECT_UPDATE</I></FONT>
|
||
notification is posted.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormStreamGetReadOffset()">NormStreamGetReadOffset()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>unsigned
|
||
long NormStreamGetReadOffset(<A HREF="#NormObjectHandle">NormObjectHandle</A> streamHandle);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function retrieves
|
||
the current read offset value for the receive stream indicated by the
|
||
<FONT FACE="Courier"><U>streamHandle</U></FONT> parameter. Note that
|
||
for very long-lived streams, this value may wrap. Thus, in general,
|
||
applications should not be highly dependent upon the stream offset,
|
||
but this feature may be valuable for certain applications which
|
||
associate some application context with stream position.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function returns
|
||
the current read offset in bytes. The return value is undefined for
|
||
sender streams. There is no error result.
|
||
</P>
|
||
<H2 CLASS="western"><A NAME="NORM Object Functions">NORM Object Functions</A></H2>
|
||
<P CLASS="western" STYLE="font-style: normal">The functions described
|
||
in this section may be used for sender or receiver purposes to manage
|
||
transmission and reception of NORM transport objects. In most cases,
|
||
the receiver will be the typical user of these functions to retrieve
|
||
additional information on newly-received objects. All of these
|
||
functions require a valid <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>
|
||
argument which specifies the applicable object. Note that
|
||
<FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT> values obtained from a
|
||
<FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT> notification may be considered
|
||
valid <I>only</I> until a subsequent call to <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>,
|
||
unless explicitly retained by the application (see
|
||
<FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT>). <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>
|
||
values obtained as a result of <FONT FACE="Courier"><A HREF="#NormFileEnqueue()">NormFileEnqueue()</A></FONT>,
|
||
<FONT FACE="Courier"><A HREF="#NormDataEnqueue()">NormDataEnqueue()</A></FONT>, or <FONT FACE="Courier">NormOpenStream()</FONT>
|
||
calls can be considered valid only until a corresponding
|
||
<FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT> notification
|
||
is posted or the object is dequeued using <FONT FACE="Courier">NormCancelObject()</FONT>,
|
||
unless, again, otherwise explicitly retained (see
|
||
<FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT>).</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormObjectGetType()">NormObjectGetType()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormObjectType">NormObjectType</A>
|
||
NormObjectGetType(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function can be
|
||
used to determine the object type (<FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>,
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT>, or
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>) for the NORM
|
||
transport object identified by the <FONT FACE="Courier"><U>objectHandle</U></FONT>
|
||
parameter. The <FONT FACE="Courier"><U>objectHandle</U></FONT> <I>must</I>
|
||
refer to a current, valid transport object.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function returns
|
||
the NORM object type. Valid NORM object types include
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>,
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT>, or
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>. A type value
|
||
of <FONT FACE="Courier"><I>NORM_OBJECT_NONE</I></FONT> will be
|
||
returned for an objectHandle value of <FONT FACE="Courier"><I>NORM_OBJECT_INVALID</I></FONT>.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormObjectHasInfo()">NormObjectHasInfo()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormObjectHasInfo(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function can be
|
||
used to determine if the sender has associated any NORM_INFO content
|
||
with the transport object specified by the <FONT FACE="Courier"><U>objectHandle</U></FONT>
|
||
parameter. This can even be used <I>before</I> the NORM_INFO content
|
||
is delivered to the receiver and a <FONT FACE="Courier"><I>NORM_RX_OBJECT_INFO</I></FONT>
|
||
notification is posted.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">A value of <FONT FACE="Courier"><I>true</I></FONT>
|
||
is returned if NORM_INFO is (or will be) available for the specified
|
||
transport object. A value of <FONT FACE="Courier"><I>false</I></FONT>
|
||
is returned otherwise.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormObjectGetInfoLength()">NormObjectGetInfoLength()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>unsigned
|
||
short NormObjectGetInfoLength(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function can be
|
||
used to determine the length of currently available NORM_INFO content
|
||
(if any) associated with the transport object referenced by the
|
||
<FONT FACE="Courier"><U>objectHandle</U></FONT> parameter.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">The length of the
|
||
NORM_INFO content, in bytes, of currently available for the specified
|
||
transport object is returned. A value of <FONT FACE="Courier"><I>0</I></FONT>
|
||
is returned if no NORM_INFO content is currently available or
|
||
associated with the object.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormObjectGetInfo()">NormObjectGetInfo()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>unsigned
|
||
short NormObjectGetInfo(<A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
objectHandle,<BR> char* buffer,<BR> unsigned
|
||
short bufferLen);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function copies
|
||
any NORM_INFO content associated (by the sender application) with the
|
||
transport object specified by <FONT FACE="Courier"><U>objectHandle</U></FONT>
|
||
into the provided memory space referenced by the <FONT FACE="Courier"><U>buffer</U></FONT>
|
||
parameter. The <FONT FACE="Courier"><U>bufferLen</U></FONT>
|
||
parameter indicates the length of the <FONT FACE="Courier"><U>buffer</U></FONT>
|
||
space in bytes. If the provided <FONT FACE="Courier"><U>bufferLen</U></FONT>
|
||
is less than the actual NORM_INFO length, a partial copy will occur.
|
||
The actual length of NORM_INFO content available for the specified
|
||
object is returned. However, note that until a <FONT FACE="Courier"><I>NORM_RX_OBJECT_INFO</I></FONT>
|
||
notification is posted to the receive application, no NORM_INFO
|
||
content is available and a zero result will be returned, even if
|
||
NORM_INFO content may be subsequently available. The
|
||
<FONT FACE="Courier"><A HREF="#NormObjectHasInfo()">NormObjectHasInfo()</A></FONT> call can be used to
|
||
determine if any NORM_INFO content will ever be available for a
|
||
specified transport object (i.e., determine if the sender has
|
||
associated any NORM_INFO with the object in question).</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">The actual length of
|
||
<I>currently</I> <I>available</I> NORM_INFO content for the specified
|
||
transport object is returned. This function can be used to determine
|
||
the length of NORM_INFO content for the object even if a <FONT FACE="Courier"><I>NULL</I></FONT>
|
||
<FONT FACE="Courier"><U>buffer</U></FONT> value and zero <FONT FACE="Courier"><U>bufferLen</U></FONT>
|
||
is provided. A zero value is returned if NORM_INFO content has not
|
||
yet been received (or is non-existent) for the specified object.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormObjectGetSize()">NormObjectGetSize()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormSize">NormSize</A>
|
||
NormObjectGetSize(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function can be
|
||
used to determine the size (in bytes) of the transport object
|
||
specified by the <FONT FACE="Courier"><U>objectHandle</U></FONT>
|
||
parameter. NORM can support large object sizes for the
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT> type, so
|
||
typically the NORM library is built with any necessary, related
|
||
macros defined such that operating system large file support is
|
||
enabled (e.g., "<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="font-style: normal">For objects of type
|
||
<FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>, the size
|
||
returned here corresponds to the stream buffer size set by the sender
|
||
application when opening the referenced stream object.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">A size of the data
|
||
content of the specified object, in bytes, is returned. Note that it
|
||
may be possible that some objects have zero data content, but do have
|
||
NORM_INFO content available.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormObjectGetBytesPending()">NormObjectGetBytesPending()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormSize">NormSize</A>
|
||
NormObjectGetBytesPending(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function can be
|
||
used to determine the progress of reception of the NORM transport
|
||
object identified by the <FONT FACE="Courier"><U>objectHandle</U></FONT>
|
||
parameter. This function indicates the number of bytes that are
|
||
pending reception (I.e., when the object is completely received,
|
||
"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="font-style: normal">A number of object
|
||
source data bytes pending reception (or transmission) is returned.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormObjectCancel()">NormObjectCancel()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormObjectCancel(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function
|
||
immediately cancels the transmission of a local sender transport
|
||
object or the reception of a specified object from a remote sender as
|
||
specified by the <FONT FACE="Courier"><U>objectHandle</U></FONT>
|
||
parameter. The <FONT FACE="Courier"><U>objectHandle</U></FONT> must
|
||
refer to a currently valid NORM transport object. Any resources used
|
||
by the transport object in question are immediately freed unless the
|
||
object has been otherwise retained by the application via the
|
||
<FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> call. Unless the
|
||
application has retained the object in such fashion, the object in
|
||
question should be considered invalid and the application must not
|
||
again reference the <FONT FACE="Courier"><U>objectHandle</U></FONT>
|
||
after this call is made.
|
||
</P>
|
||
<P CLASS="western" STYLE="font-style: normal">If the canceled object
|
||
is a sender object not completely received by participating
|
||
receivers, the receivers will be informed of the object's
|
||
cancellation via the NORM protocol NORM_CMD(SQUELCH) message in
|
||
response to any NACKs requesting repair or retransmission of the
|
||
applicable object. In the case of receive objects, the NORM receiver
|
||
will not make further requests for repair of the indicated object,
|
||
but furthermore, <I>will</I> acknowledge the object as completed with
|
||
respect to any associated positive acknowledgement requests (see
|
||
<FONT FACE="Courier"><A HREF="#NormSetWatermark()">NormSetWatermark()</A></FONT>).</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return value.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormObjectRetain()">NormObjectRetain()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormObjectRetain(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function "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="font-style: normal">When the application
|
||
makes a call to <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> for a
|
||
given <FONT FACE="Courier"><U>objectHandle</U></FONT>, the
|
||
application may use that <FONT FACE="Courier"><U>objectHandle</U></FONT>
|
||
value in any NORM API calls until the application makes a call to
|
||
<FONT FACE="Courier"><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT> for the given object.
|
||
Note that the application <I>MUST</I> make a corresponding call to
|
||
<FONT FACE="Courier"><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT> for each call it has
|
||
made to <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> in order to
|
||
free any system resources (i.e., memory) used by that object. Also
|
||
note that retaining a receive object also automatically retains any
|
||
state associated with the <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A>
|
||
</FONT>corresponding to the remote sender of that receive object so
|
||
that the application may use NORM node API calls for the value
|
||
returned by <FONT FACE="Courier"><A HREF="#NormObjectGetSender()">NormObjectGetSender()</A></FONT> as
|
||
needed.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return value.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormObjectRelease()">NormObjectRelease()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormObjectRelease(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function
|
||
complements the <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> call
|
||
by immediately freeing any resources associated with the given
|
||
<FONT FACE="Courier"><U>objectHandle</U></FONT>, assuming the
|
||
underlying NORM protocol engine no longer requires access to the
|
||
corresponding transport object. Note the NORM protocol engine
|
||
retains/releases state for associated objects for its own needs and
|
||
thus it is very unsafe for an application to call <FONT FACE="Courier"><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT>
|
||
for an <FONT FACE="Courier"><U>objectHandle</U></FONT> for which it
|
||
has not previously explicitly retained via <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT>.
|
||
|
||
</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return value.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormFileGetName()">NormFileGetName()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormFileGetName(<A HREF="#NormObjectHandle">NormObjectHandle</A>
|
||
fileHandle)<BR> char* nameBuffer,<BR> unsigned
|
||
int bufferLen);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function copies
|
||
the name, as a NULL-terminated string, of the file object specified
|
||
by the <FONT FACE="Courier"><U>fileHandle</U></FONT> parameter into
|
||
the <FONT FACE="Courier"><U>nameBuffer</U></FONT> of length <FONT FACE="Courier"><U>bufferLen</U></FONT>
|
||
bytes provided by the application. The <FONT FACE="Courier"><U>fileHandle</U></FONT>
|
||
parameter must refer to a valid <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>
|
||
for an object of type NORM_OBJECT_FILE. If the actual name is longer
|
||
than the provided <FONT FACE="Courier"><U>bufferLen</U></FONT>, a
|
||
partial copy will occur. Note that the file name consists of the
|
||
entire path name of the specified file object and the application
|
||
should give consideration to operating system file path lengths when
|
||
providing the <FONT FACE="Courier"><U>nameBuffer</U></FONT>.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function returns
|
||
true upon success and false upon failure. Possible failure
|
||
conditions include the <FONT FACE="Courier"><U>fileHandle</U></FONT>
|
||
does not refer to an object of type <FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT>.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormFileRename()">NormFileRename()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>bool
|
||
NormFileRename(<A HREF="#NormObjectHandle">NormObjectHandle</A> fileHandle)<BR> const
|
||
char* fileName);</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function renames
|
||
the file used to store content for the <FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT>
|
||
transport object specified by the <FONT FACE="Courier"><U>fileHandle</U></FONT>
|
||
parameter. This allows receiver applications to rename (or move)
|
||
received files as needed. NORM uses temporary file names for
|
||
received files until the application explicitly renames the file.
|
||
For example, sender applications may choose to use the NORM_INFO
|
||
content associated with a file object to provide name and/or typing
|
||
information to receivers. The <FONT FACE="Courier"><U>fileName</U></FONT>
|
||
parameter must be a NULL-terminated string which should specify the
|
||
full desired path name to be used. NORM will attempt to create
|
||
sub-directories as needed to satisfy the request. Note that existing
|
||
files of the same name may be overwritten.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function returns
|
||
true upon success and false upon failure. Possible failure
|
||
conditions include the case where the <FONT FACE="Courier"><U>fileHandle</U></FONT>
|
||
does not refer to an object of type <FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT>
|
||
and where NORM was unable to successfully create any needed
|
||
directories and/or the file itself.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormDataAccessData()">NormDataAccessData()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>const
|
||
char* NormDataAccessData(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle)</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function allows
|
||
the application to access the data storage area associated with a
|
||
transport object of type <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>.
|
||
For example, the application may use this function to copy the
|
||
received data content for its own use. Alternatively, the
|
||
application may establish "ownership" for the allocated
|
||
memory space using the <FONT SIZE=2><FONT FACE="Courier"><A HREF="#NormDataDetachData()">NormDataDetachData()</A></FONT></FONT>
|
||
function if it is desired to avoid the copy.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">If the object specified
|
||
by the <FONT FACE="Courier"><U>objectHandle</U></FONT> parameter has
|
||
no data content (or is not of type <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>),
|
||
a NULL value may be returned. The application MUST NOT attempt to
|
||
modify the memory space used by <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>
|
||
objects during the time an associated <FONT FACE="Courier"><U>objectHandle</U></FONT>
|
||
is valid. The length of data storage area can be determined with a
|
||
call to <FONT FACE="Courier"><A HREF="#NormObjectGetSize()">NormObjectGetSize()</A></FONT> for the same
|
||
<FONT FACE="Courier"><U>objectHandle</U></FONT> value.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function returns a
|
||
pointer to the data storage area for the specified transport object.
|
||
A NULL value may be returned if the object has no associated data
|
||
content or is not of type <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormDataDetachData()">NormDataDetachData()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>char*
|
||
NormDataDetachData(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle)</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function allows
|
||
the application to disassociate data storage allocated by the NORM
|
||
protocol engine for a receive object from the <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>
|
||
transport object specified by the <FONT FACE="Courier"><U>objectHandle</U></FONT>
|
||
parameter. It is important that this function is called <I>after</I>
|
||
the NORM protocol engine has indicated it is finished with the data
|
||
object (i.e., after a <FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT>,
|
||
<FONT FACE="Courier"><I>NORM_RX_OBJECT_COMPLETED</I></FONT>, or
|
||
<FONT FACE="Courier"><I>NORM_RX_OBJECT_ABORTED</I></FONT>
|
||
notification event). But the application must call
|
||
<FONT FACE="Courier"><A HREF="#NormDataDetachData()">NormDataDetachData()</A></FONT> <I>before</I> a call
|
||
is made to <FONT FACE="Courier"><A HREF="#NormObjectCancel()">NormObjectCancel()</A></FONT> or
|
||
<FONT FACE="Courier"><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT> for the object if it
|
||
plans to access the data content afterwards. Otherwise, the NORM
|
||
protocol engine will free the applicable memory space when the
|
||
associated <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>
|
||
transport object is deleted and the application will be unable to
|
||
access the received data unless it has previously copied the content.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">Once the application
|
||
has used this call to "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="font-style: normal">This function returns a
|
||
pointer to the data storage area for the specified transport object.
|
||
A NULL value may be returned if the object has no associated data
|
||
content or is not of type <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT>.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormObjectGetSender()">NormObjectGetSender()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormNodeHandle">NormNodeHandle</A>
|
||
NormObjectGetSender(<A HREF="#NormObjectHandle">NormObjectHandle</A> objectHandle)</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function retrieves
|
||
the <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> corresponding to the
|
||
remote sender of the transport object associated with the given
|
||
<FONT FACE="Courier"><U>objectHandle</U></FONT> parameter. Note that
|
||
the returned <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> value is only
|
||
valid for the same period that the <FONT FACE="Courier"><U>objectHandle</U></FONT>
|
||
is valid. The returned <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>
|
||
may optionally be retained for further use by the application using
|
||
the <FONT FACE="Courier"><A HREF="#NormNodeRetain()">NormNodeRetain()</A></FONT> function call. The
|
||
returned value can be used in the <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="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="font-style: normal">The functions described
|
||
in this section may be used for NORM sender or receiver (most
|
||
typically receiver) purposes to retrieve additional information about
|
||
a <I>NormNode</I>, given a valid <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>.
|
||
Note that, unless specifically retained (see <FONT FACE="Courier"><A HREF="#NormNodeRetain()">NormNodeRetain()</A></FONT>),
|
||
a <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> provided in a <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT>
|
||
notification should be considered valid only until a subsequent call
|
||
to <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT> is made.
|
||
<FONT FACE="Courier">NormNodeHandles </FONT>retrieved using
|
||
<FONT FACE="Courier"><A HREF="#NormObjectGetSender()">NormObjectGetSender()</A></FONT> can be considered
|
||
valid for the same period of time as the corresponding
|
||
<A HREF="#NormObjectHandle">NormObjectHandle</A> is valid.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormNodeGetId()">NormNodeGetId()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormNodeId">NormNodeId</A>
|
||
NormNodeGetId(<A HREF="#NormNodeHandle">NormNodeHandle</A> nodeHandle)</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function retrieves
|
||
the <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> identifier for the remote
|
||
participant referenced by the given <FONT FACE="Courier"><U>nodeHandle</U></FONT>
|
||
value. The <A HREF="#NormNodeId">NormNodeId</A> is a 32-bit value used within the NORM
|
||
protocol to uniquely identify participants within a NORM session.
|
||
The participants identifiers are assigned by the application or
|
||
derived (by the NORM API code) from the host computers default IP
|
||
address.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function returns
|
||
the <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> value associated with the
|
||
specified <FONT FACE="Courier"><U>nodeHandle</U></FONT>. In the case
|
||
<FONT FACE="Courier"><U>nodeHandle</U></FONT> is equal to
|
||
<FONT FACE="Courier"><I>NORM_NODE_INVALID</I></FONT>, the return
|
||
value will be <FONT FACE="Courier"><I>NORM_NODE_NONE</I></FONT>.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormNodeGetAddress()">NormNodeGetAddress()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2><A HREF="#NormNodeId">NormNodeId</A>
|
||
NormNodeGetAddress(<A HREF="#NormNodeHandle">NormNodeHandle</A> nodeHandle)</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function retrieves
|
||
the <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> identifier for the remote
|
||
participant referenced by the given <FONT FACE="Courier"><U>nodeHandle</U></FONT>
|
||
value. The <A HREF="#NormNodeId">NormNodeId</A> is a 32-bit value used within the NORM
|
||
protocol to uniquely identify participants within a NORM session.
|
||
The participants identifiers are assigned by the application or
|
||
derived (by the NORM API code) from the host computers default IP
|
||
address.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function returns
|
||
the <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> value associated with the
|
||
specified <FONT FACE="Courier"><U>nodeHandle</U></FONT>. In the case
|
||
<FONT FACE="Courier"><U>nodeHandle</U></FONT> is equal to
|
||
<FONT FACE="Courier"><I>NORM_NODE_INVALID</I></FONT>, the return
|
||
value will be <FONT FACE="Courier"><I>NORM_NODE_NONE</I></FONT>.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormNodeRetain()">NormNodeRetain()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormNodeRetain(<A HREF="#NormNodeHandle">NormNodeHandle</A> nodeHandle)</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">In the same manner as
|
||
the <FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT> function, this
|
||
function allows the application to retain state associated with a
|
||
given <FONT FACE="Courier"><U>nodeHandle</U></FONT> value even when
|
||
the underlying NORM protocol engine might normally free the
|
||
associated state and thus invalidate the <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>.
|
||
If the application uses this function, it must make a corresponding
|
||
call to <FONT FACE="Courier"><A HREF="#NormNodeRelease()">NormNodeRelease()</A></FONT> when finished
|
||
with the node information to avoid a memory leak condition.
|
||
<FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> values (unless retained)
|
||
are valid from the time of a <FONT FACE="Courier"><I>NORM_REMOTE_SERVER_NEW</I></FONT>
|
||
notification until a complimentary <FONT FACE="Courier"><I>NORM_REMOTE_SERVER_PURGED</I></FONT>
|
||
notification. During that interval, the application will receive
|
||
<FONT FACE="Courier"><I>NORM_REMOTE_SERVER_ACTIVE</I></FONT> and
|
||
<FONT FACE="Courier"><I>NORM_REMOTE_SERVER_INACTIVE</I></FONT>
|
||
notifications according to the server's message transmission activity
|
||
within the session.</P>
|
||
<P CLASS="western" STYLE="font-style: normal">It is important to note
|
||
that, if the NORM protocol engine posts a <FONT FACE="Courier"><I>NORM_REMOTE_SERVER_PURGED</I></FONT>
|
||
notification for a given <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>,
|
||
the NORM protocol engine could possibly, subsequently establish a
|
||
new, different <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> value for
|
||
the same remote server (i.e., one of equivalent <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT>)
|
||
if it again becomes active in the session. A new <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>
|
||
may likely be established even if the application has retained the
|
||
previous <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> value.
|
||
Therefore, to the application, it might appear that two different
|
||
servers with the same <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT> are
|
||
participating if these notifications are not carefully monitored.
|
||
This behavior is contingent upon how the application has configured
|
||
the NORM protocol engine to manage resources when there is potential
|
||
for a large number of remote servers within a session (related APIs
|
||
are TBD). For example, the application may wish to control which
|
||
specific remote servers for which it keeps state (or limit the memory
|
||
resources used for remote servers state, etc) and the NORM API may be
|
||
extended in the future to control this behavior.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return value.</P>
|
||
<H3 CLASS="functionheading-western"><A NAME="NormNodeRelease()">NormNodeRelease()</A></H3>
|
||
<H4 CLASS="western">Synopsis</H4>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
||
<normApi.h></FONT></FONT></P>
|
||
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>void
|
||
NormNodeRelease(<A HREF="#NormNodeHandle">NormNodeHandle</A> nodeHandle)</FONT></FONT></P>
|
||
<H4 CLASS="western">Description</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">In complement to the
|
||
<FONT FACE="Courier"><A HREF="#NormNodeRetain()">NormNodeRetain()</A></FONT> function, this API call
|
||
releases the specified <FONT FACE="Courier"><U>nodeHandle</U></FONT>
|
||
so that the NORM protocol engine may free associated resources as
|
||
needed. Once this call is made, the application should no longer
|
||
reference the specified <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>,
|
||
unless it is still valid.</P>
|
||
<H4 CLASS="western">Return Values</H4>
|
||
<P CLASS="western" STYLE="font-style: normal">This function has no
|
||
return value.</P>
|
||
</BODY>
|
||
</HTML>
|