2886 lines
198 KiB
HTML
2886 lines
198 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-15">
|
|
<TITLE>NORM Developer’s Guide</TITLE>
|
|
<META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1.2 (Linux)">
|
|
<META NAME="AUTHOR" CONTENT="Robert Adamson">
|
|
<META NAME="CREATED" CONTENT="20040824;15180000">
|
|
<META NAME="CHANGED" CONTENT="20050304;10303500">
|
|
<META NAME="DESCRIPTION" CONTENT="NORM Object Functions 42
|
|
NORM Object Functions
|
|
NORM_OBJECT_STREAM
|
|
NORM Sender Functions 19
|
|
NORM Sender Functions
|
|
">
|
|
<META NAME="KEYWORDS" CONTENT="norm object value application function ">
|
|
<STYLE>
|
|
<!--
|
|
@page { size: 8.5in 11in; margin-right: 1.25in; margin-top: 1in; margin-bottom: 0.5in }
|
|
@page:first { margin-top: 1in; margin-bottom: 1in }
|
|
P { margin-top: 0.08in; margin-bottom: 0in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
|
|
P.western { font-family: "Times"; font-size: 12pt; so-language: en-US; font-style: italic }
|
|
P.cjk { font-family: "Times"; font-size: 12pt; font-style: italic }
|
|
P.ctl { font-family: "Times"; font-size: 10pt }
|
|
H1 { margin-bottom: 0.04in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
|
|
H1.western { font-family: "Helvetica", sans-serif; font-size: 16pt; so-language: en-US }
|
|
H1.cjk { font-family: "Times"; font-size: 16pt }
|
|
H1.ctl { font-family: "Times"; font-size: 10pt; font-weight: medium }
|
|
H2 { margin-bottom: 0.04in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
|
|
H2.western { font-family: "Helvetica", sans-serif; font-size: 14pt; so-language: en-US; font-style: italic }
|
|
H2.cjk { font-family: "Times"; font-size: 14pt; font-style: italic }
|
|
H2.ctl { font-family: "Times"; font-size: 10pt; font-weight: medium }
|
|
H3 { margin-bottom: 0.04in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
|
|
H3.western { font-family: "Helvetica", sans-serif; font-size: 13pt; so-language: en-US }
|
|
H3.cjk { font-family: "Times"; font-size: 13pt }
|
|
H3.ctl { font-family: "Times"; font-size: 10pt; font-weight: medium }
|
|
H4 { margin-bottom: 0.04in; direction: ltr; color: #000000; widows: 2; orphans: 2 }
|
|
H4.western { font-family: "Times"; font-size: 14pt; so-language: en-US }
|
|
H4.cjk { font-family: "Times"; font-size: 14pt }
|
|
H4.ctl { font-family: "Times"; font-size: 10pt; font-weight: medium }
|
|
H3.functionheading-western { border-top: 1px solid #000000; border-bottom: none; border-left: none; border-right: none; padding-top: 0.01in; padding-bottom: 0in; padding-left: 0in; padding-right: 0in; font-family: "Courier"; font-size: 13pt; so-language: en-US }
|
|
H3.functionheading-cjk { border-top: 1px solid #000000; border-bottom: none; border-left: none; border-right: none; padding-top: 0.01in; padding-bottom: 0in; padding-left: 0in; padding-right: 0in; font-family: "Times"; font-size: 13pt }
|
|
H3.functionheading-ctl { border-top: 1px solid #000000; border-bottom: none; border-left: none; border-right: none; padding-top: 0.01in; padding-bottom: 0in; padding-left: 0in; padding-right: 0in; font-family: "Times"; font-size: 10pt; font-weight: medium }
|
|
A:link { color: #0000ff }
|
|
A:visited { color: #800080 }
|
|
-->
|
|
</STYLE>
|
|
</HEAD>
|
|
<BODY LANG="en-US" TEXT="#000000" LINK="#0000ff" VLINK="#800080" DIR="LTR">
|
|
<TABLE WIDTH=590 BORDER=0 CELLPADDING=7 CELLSPACING=0 STYLE="page-break-before: always">
|
|
<COL WIDTH=191>
|
|
<COL WIDTH=371>
|
|
<TR VALIGN=TOP>
|
|
<TD WIDTH=191>
|
|
<P ALIGN=CENTER STYLE="margin-top: 0.17in; font-style: normal"><IMG SRC="NormLogo.gif" NAME="Graphic1" ALIGN=BOTTOM WIDTH=184 HEIGHT=176 BORDER=0></P>
|
|
</TD>
|
|
<TD WIDTH=371>
|
|
<P ALIGN=LEFT STYLE="margin-left: 0.86in; margin-top: 0.17in; font-style: normal">
|
|
<FONT FACE="Helvetica, sans-serif"><FONT SIZE=6 STYLE="font-size: 28pt"><B>NORM<BR>Developer’s
|
|
<BR>Guide</B></FONT></FONT></P>
|
|
</TD>
|
|
</TR>
|
|
</TABLE>
|
|
<H1 CLASS="western">Background</H1>
|
|
<P CLASS="western" STYLE="font-style: normal">This document describes
|
|
an application programming interface (API) for the Nack-Oriented
|
|
Reliable Multicast (NORM) protocol implementation developed by the
|
|
United States Naval Research Laboratory (NRL). The NORM protocol
|
|
provides general purpose reliable data transport for applications
|
|
wishing to use Internet Protocol (IP) Multicast services for group
|
|
data delivery. NORM can also support unicast (point-to-point) data
|
|
communication and may be used for such when deemed appropriate.</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>
|
|
<H1 CLASS="western" ALIGN=CENTER STYLE="page-break-before: always">Table
|
|
of Contents</H1>
|
|
<DIV ID="Table of Contents1" DIR="LTR">
|
|
<P STYLE="margin-top: 0.25in; font-style: normal"><FONT FACE="Helvetica, sans-serif"><B>Overview</B></FONT></P>
|
|
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>API
|
|
Initialization</B></FONT></P>
|
|
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>Session
|
|
Creation and Control</B></FONT></P>
|
|
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>NORM
|
|
Data Transport</B></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2>NORM
|
|
Data Transmission</FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2>NORM
|
|
Data Reception</FONT></P>
|
|
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>API
|
|
Event Notification</B></FONT></P>
|
|
<P STYLE="margin-top: 0.25in; font-style: normal"><FONT FACE="Helvetica, sans-serif"><B>API
|
|
Reference</B></FONT></P>
|
|
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>API
|
|
Variable Types and Constants</B></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormInstanceHandle">NormInstanceHandle</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSessionHandle">NormSessionHandle</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#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="#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-top: 0.17in; font-style: normal"><FONT SIZE=2><B>API
|
|
Initialization</B></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormCreateInstance()">NormCreateInstance()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDestroyInstance()">NormDestroyInstance()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetCacheDirectory()">NormSetCacheDirectory()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormGetDescriptor()">NormGetDescriptor()</A></FONT></P>
|
|
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>Session
|
|
Creation and Control</B></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormCreateSession()">NormCreateSession()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDestroySession()">NormDestroySession()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormGetLocalNodeId()">NormGetLocalNodeId()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetMulticastInterface()">NormSetMulticastInterface()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTTL()">NormSetTTL()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTOS()">NormSetTOS()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetLoopback()">NormSetLoopback()</A></FONT></P>
|
|
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>NORM
|
|
Sender Functions</B></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStartSender()">NormStartSender()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStopSender()">NormStopSender()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetTransmitRate()">NormSetTransmitRate()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#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="#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="#NormAddAckingNode()">NormAddAckingNode()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormRemoveAckingNode()">NormRemoveAckingNode()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormFileEnqueue()">NormFileEnqueue()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDataEnqueue()">NormDataEnqueue()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamOpen()">NormStreamOpen()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamClose()">NormStreamClose()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamWrite()">NormStreamWrite()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamFlush()">NormStreamFlush()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamSetAutoFlush()">NormStreamSetAutoFlush()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamSetPushEnable()">NormStreamSetPushEnable()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamMarkEom()">NormStreamMarkEom()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetWatermark()">NormSetWatermark()</A></FONT></P>
|
|
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>NORM
|
|
Receiver Functions</B></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStartReceiver()">NormStartReceiver()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStopReceiver()">NormStopReceiver()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetSilentReceiver()">NormSetSilentReceiver()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetDefaultUnicastNack()">NormSetDefaultUnicastNack()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeSetUnicastNack()">NormNodeSetUnicastNack()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetDefaultNackingMode()">NormSetDefaultNackingMode()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeSetNackingMode()">NormNodeSetNackingMode()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectSetNackingMode()">NormObjectSetNackingMode()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormSetDefaultRepairBoundary()">NormSetDefaultRepairBoundary()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeSetRepairBoundary()">NormNodeSetRepairBoundary()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamRead()">NormStreamRead()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamSeekMsgStart()">NormStreamSeekMsgStart()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormStreamGetReadOffset()">NormStreamGetReadOffset()</A></FONT></P>
|
|
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>NORM
|
|
Object Functions</B></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetType()">NormObjectGetType()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectHasInfo()">NormObjectHasInfo()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetInfoLength()">NormObjectGetInfoLength()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetInfo()">NormObjectGetInfo()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetSize()">NormObjectGetSize()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectCancel()">NormObjectCancel()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectRelease()">NormObjectRelease()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormFileGetName()">NormFileGetName()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormFileRename()">NormFileRename()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDataAccessData()">NormDataAccessData()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormDataDetachData()">NormDataDetachData()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormObjectGetSender()">NormObjectGetSender()</A></FONT></P>
|
|
<P STYLE="margin-top: 0.17in; font-style: normal"><FONT SIZE=2><B>NORM
|
|
Node Functions</B></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeGetId()">NormNodeGetId()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeRetain()">NormNodeRetain()</A></FONT></P>
|
|
<P STYLE="margin-left: 0.17in; margin-top: 0in; font-style: normal"><FONT SIZE=2><A HREF="#NormNodeRelease()">NormNodeRelease()</A></FONT></P>
|
|
</DIV>
|
|
<H1 CLASS="western" STYLE="page-break-before: always">Overview</H1>
|
|
<P CLASS="western" STYLE="font-style: normal">The NORM API has been
|
|
designed to provide simple, straightforward access to and control of
|
|
NORM protocol state and functions. Functions are provided to create
|
|
and initialize instances of the NORM API and associated transport
|
|
sessions (<I>NormSessions</I>). Subsequently, NORM data
|
|
transmission (<I>NormSender</I>) operation can be activated and the
|
|
application can queue various types of data (<I>NormObjects</I>) for
|
|
reliable transport. Additionally or alternatively, NORM reception
|
|
(<I>NormReceiver</I>) operation can also be enabled on a per-session
|
|
basis and the protocol implementation alerts the application of
|
|
receive events.</P>
|
|
<P CLASS="western" STYLE="font-style: normal">By default, the NORM
|
|
API will create an operating system thread in which the NORM protocol
|
|
engine runs. This allows user application code and the underlying
|
|
NORM code to execute somewhat independently of one another. The NORM
|
|
protocol thread notifies the application of various protocol events
|
|
through a thread-safe event dispatching mechanism and API calls are
|
|
provided to allow the application to control NORM operation. (<I>Note:
|
|
API mechanisms for lower-level, non-threaded control and execution
|
|
of the NORM protocol engine will also be provided in the future</I>.)</P>
|
|
<P CLASS="western" STYLE="font-style: normal">The NORM API operation
|
|
can be roughly summarized with the following categories of functions:</P>
|
|
<OL>
|
|
<LI><P CLASS="western" STYLE="font-style: normal">API Initialization</P>
|
|
<LI><P CLASS="western" STYLE="font-style: normal">Session Creation
|
|
and Control</P>
|
|
<LI><P CLASS="western" STYLE="font-style: normal">Data Transport</P>
|
|
<LI><P CLASS="western" STYLE="font-style: normal">Event Notification</P>
|
|
</OL>
|
|
<P CLASS="western" STYLE="font-style: normal">Note the order of these
|
|
categories roughly reflects the order of function calls required to
|
|
use NORM in an application. The first step is to create and
|
|
initialize, as needed, at least one instance of the NORM API. Then
|
|
one or more NORM transport sessions (where a “session”
|
|
corresponds to data exchanges on a given multicast group and host
|
|
port number) may be created and controlled. Applications may
|
|
participate as senders and/or receivers within a NORM session. NORM
|
|
senders transmit data to the session destination address (usually an
|
|
IP multicast group) while receivers are notified of incoming data.
|
|
The NORM API provides and event notification scheme to notify the
|
|
application of significant sender and receiver events. There are
|
|
also a number support functions provided for the application to
|
|
control and monitor its participation within a NORM transport
|
|
session.</P>
|
|
<H2 CLASS="western">API Initialization</H2>
|
|
<P CLASS="western" STYLE="font-style: normal">The NORM API requires
|
|
that an application explicitly create at least one instance of the
|
|
NORM protocol engine which is subsequently used as a conduit for
|
|
further NORM API calls. By default, the NORM protocol engine runs in
|
|
its own operating system thread and interacts with the application in
|
|
a thread-safe manner through the API calls and event dispatching
|
|
mechanism. In general, only the thread creating the NORM API
|
|
instance should invoke API calls referencing that instance or any
|
|
sessions or state created within that instance (<I>NOTE: This
|
|
limitation may change in the future. The current implementation is
|
|
theoretically safe for concurrent access, but this has not been fully
|
|
tested</I>). Multiple API instances may be created as needed for
|
|
applications with specific requirements for accessing and controlling
|
|
participation in multiple NORM sessions from operating system
|
|
multiple threads.</P>
|
|
<H2 CLASS="western">Session Creation and Control</H2>
|
|
<P CLASS="western" STYLE="font-style: normal">Once an API instance
|
|
has been successfully created, the application may then create NORM
|
|
transport session instances as needed. The application can
|
|
participate in each session as a sender and/or receiver of data. If
|
|
an application is participating as a sender, it may enqueue data
|
|
transport objects for transmission. The control of transmission is
|
|
largely left to the sender and API calls are provided to control
|
|
transmission rate, FEC parameters, etc. Applications participating
|
|
as receivers will be notified via the NORM API's event dispatching
|
|
mechanism of pending and completed reliable reception of data along
|
|
with other significant events. Additionally, API controls for some
|
|
optional NORM protocol mechanisms, such as positive acknowledgment
|
|
collection, are also provided.</P>
|
|
<P CLASS="western" STYLE="font-style: normal">Note when multiple
|
|
senders are involved, receivers allocate system resources (buffer
|
|
space) for each active sender. With a very large number of
|
|
concurrently active senders, this may translate to significant memory
|
|
allocation on receiver nodes. Currently, the API allows the
|
|
application to control how much buffer space is allocated for each
|
|
active sender (<I>NOTE: In the future, API functions may be provided
|
|
limit the number of active senders monitored and/or provide the
|
|
application with finer control over receive buffer allocation,
|
|
perhaps on a per sender basis</I>).
|
|
</P>
|
|
<H2 CLASS="western">NORM Data Transport</H2>
|
|
<P CLASS="western" STYLE="font-style: normal">The NORM protocol
|
|
supports transport of three basic types of data content. These
|
|
include the types <FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT>
|
|
and <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT> which
|
|
represent predetermined, fixed-size application data content. The
|
|
only differentiation with respect to these two types is the implicit
|
|
“hint” to the receiver to use non-volatile (i.e. file
|
|
system) storage or memory. This “hint” lets the receiver
|
|
allocate appropriate storage space with no other information on the
|
|
incoming data. The NORM implementation reads/writes data for the
|
|
<FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT> type directly
|
|
from/to file storage, while application memory space is accessed for
|
|
the <FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT> type. The
|
|
third data content type, <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>,
|
|
represents unbounded, possibly persistent, streams of data content.
|
|
Using this transport paradigm, traditional, byte-oriented streaming
|
|
transport service (e.g. similar to that provided by a TCP socket) can
|
|
be provided. Additionally, NORM has provisions for
|
|
application-defined message-oriented transport where receivers can
|
|
recover message boundaries without any “handshake” with
|
|
the sender. Stream content is buffered by the NORM implementation
|
|
for transmission/retransmission and as it is received.</P>
|
|
<H3 CLASS="western">NORM Data Transmission</H3>
|
|
<P CLASS="western" STYLE="font-style: normal">The behavior of data
|
|
transport operation is largely placed in the control of the NORM
|
|
sender(s). NORM senders controls their data transmission rate,
|
|
forward error correction (FEC) encoding settings, and parameters
|
|
controlling feedback from the receiver group. Multiple senders may
|
|
operate in a session, each with independent transmission parameters.
|
|
NORM receivers learn needed parameter values from fields in NORM
|
|
message headers.</P>
|
|
<P CLASS="western" STYLE="font-style: normal">NORM transport
|
|
“objects” (file, data, or stream) are queued for
|
|
transmission by NORM senders. NORM senders may also cancel
|
|
transmission of objects at any time. The NORM sender controls the
|
|
transmission rate either manually (fixed transmission rate) or
|
|
automatically when NORM congestion control operation is enabled. The
|
|
NORM congestion control mechanism is designed to be "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>
|
|
<H3 CLASS="western">NORM Data Reception</H3>
|
|
<P CLASS="western" STYLE="font-style: normal">NORM receiver
|
|
applications learn of active senders and their corresponding pending
|
|
and completed data transfers, etc via the API event dispatching
|
|
mechanism. By default, NORM receivers use NACK messages to request
|
|
repair of transmitted content from the originating sender as needed
|
|
to achieve reliable transfer. Some API functions are available to
|
|
provide some additional control over the NACKing behavior, such as
|
|
initially NACKing for NORM_INFO content only or even to the extent of
|
|
disabling receiver feedback (silent receiver operation) entirely.</P>
|
|
<H2 CLASS="western">API Event Notification</H2>
|
|
<P CLASS="western" STYLE="font-style: normal">An asynchronous event
|
|
dispatching mechanism is provided to notify the application of
|
|
significant NORM protocol events ...</P>
|
|
<H1 CLASS="western">API Reference</H1>
|
|
<P CLASS="western" STYLE="font-style: normal">This section provides a
|
|
reference to the NORM API variable types, constants and functions.</P>
|
|
<H2 CLASS="western">API Variable Types and Constants</H2>
|
|
<P CLASS="western" STYLE="font-style: normal">The NORM API defines
|
|
and enumerates a number of supporting variable types and values which
|
|
are used in different function calls. The variable types are
|
|
described here.</P>
|
|
<H3 CLASS="functionheading-western"><A NAME="NormInstanceHandle">NormInstanceHandle</A></H3>
|
|
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormInstanceHandle">NormInstanceHandle</A>
|
|
</FONT>type is returned when a NORM API instance is created (see
|
|
<FONT FACE="Courier"><A HREF="#NormCreateInstance()">NormCreateInstance()</A></FONT>). This handle can
|
|
be subsequently used for API calls which require reference to a
|
|
specific NORM API instance. By default, each NORM API instance
|
|
instantiated creates an operating system thread for protocol
|
|
operation. Note that multiple NORM transport sessions may be created
|
|
for a single API instance. In general, it is expected that
|
|
applications will create a single NORM API instance, but some
|
|
multi-threaded application designs may prefer multiple corresponding
|
|
NORM API instances. The value <FONT FACE="Courier">NORM_INSTANCE_INVALID</FONT>
|
|
corresponds to an invalid API instance.</P>
|
|
<H3 CLASS="functionheading-western"><A NAME="NormSessionHandle">NormSessionHandle</A></H3>
|
|
<P CLASS="western" STYLE="font-style: normal">The <FONT FACE="Courier"><A HREF="#NormSessionHandle">NormSessionHandle</A></FONT>
|
|
type is used to reference NORM transport sessions which have been
|
|
created using the <FONT FACE="Courier"><A HREF="#NormCreateSession()">NormCreateSession()</A></FONT> API
|
|
call. Multiple <FONT FACE="Courier">NormSessionHandles</FONT> may be
|
|
associated with a given <FONT FACE="Courier"><A HREF="#NormInstanceHandle">NormInstanceHandle</A></FONT>.
|
|
The special value <FONT FACE="Courier">NORM_SESSION_INVALID </FONT>is
|
|
used to refer to invalid session references.</P>
|
|
<H3 CLASS="functionheading-western"><A NAME="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="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 function 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>
|
|
<H2 CLASS="western">API Initialization</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>
|
|
<A HREF="#NormCreateInstance()">NormCreateInstance()</A>;</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.
|
|
</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=100% BORDER=0 CELLPADDING=7 CELLSPACING=0>
|
|
<COL WIDTH=123*>
|
|
<COL WIDTH=133*>
|
|
<TR>
|
|
<TD COLSPAN=2 WIDTH=100% 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=48%>
|
|
<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=52%>
|
|
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
|
This event indicates that there is room for additional transmit
|
|
objects to be enqueued, or, if the handle of <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>
|
|
is given in the event "object" field, the application
|
|
may successfully write to the indicated stream.</P>
|
|
</TD>
|
|
</TR>
|
|
<TR VALIGN=TOP>
|
|
<TD WIDTH=48%>
|
|
<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=52%>
|
|
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
|
This event indicates the NORM protocol engine has no new data
|
|
pending transmission and the application may enqueue additional
|
|
objects for transmission.</P>
|
|
</TD>
|
|
</TR>
|
|
<TR VALIGN=TOP>
|
|
<TD WIDTH=48%>
|
|
<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=52%>
|
|
<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=48%>
|
|
<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=52%>
|
|
<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. 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=48%>
|
|
<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=52%>
|
|
<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=100% 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=48%>
|
|
<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=52%>
|
|
<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=48%>
|
|
<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=52%>
|
|
<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=48%>
|
|
<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=52%>
|
|
<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=48%>
|
|
<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=52%>
|
|
<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=48%>
|
|
<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=52%>
|
|
<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=48%>
|
|
<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=52%>
|
|
<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=48%>
|
|
<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=52%>
|
|
<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=48%>
|
|
<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=52%>
|
|
<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=48%>
|
|
<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=52%>
|
|
<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=100% 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=48%>
|
|
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
|
<FONT FACE="Courier"><I>NORM_EVENT_INVALID</I></FONT></P>
|
|
</TD>
|
|
<TD WIDTH=52%>
|
|
<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>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>NormDescriptor
|
|
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">NormDescriptor</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">NormDescriptor</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">NormDescriptor</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 <A HREF="#NormDestroyInstance()">NormDestroyInstance()</A> is
|
|
made. Upon error, a value of <I><FONT FACE="Courier">NORM_DESCRIPTOR_INVALID</FONT></I>
|
|
is returned.</P>
|
|
<H2 CLASS="western">Session Creation and Control</H2>
|
|
<H3 CLASS="functionheading-western"><A NAME="NormCreateSession()">NormCreateSession()</A></H3>
|
|
<H4 CLASS="western">Synopsis</H4>
|
|
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
|
<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=100% BORDER=0 CELLPADDING=7 CELLSPACING=0>
|
|
<COL WIDTH=50*>
|
|
<COL WIDTH=206*>
|
|
<TR VALIGN=TOP>
|
|
<TD WIDTH=20%>
|
|
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
|
<FONT FACE="Courier">instance</FONT></P>
|
|
</TD>
|
|
<TD WIDTH=80%>
|
|
<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=20%>
|
|
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
|
<FONT FACE="Courier">address</FONT></P>
|
|
</TD>
|
|
<TD WIDTH=80%>
|
|
<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=20%>
|
|
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
|
<FONT FACE="Courier">port</FONT></P>
|
|
</TD>
|
|
<TD WIDTH=80%>
|
|
<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=20%>
|
|
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
|
<FONT FACE="Courier">localId</FONT></P>
|
|
</TD>
|
|
<TD WIDTH=80%>
|
|
<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="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="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">NORM<SPAN STYLE="font-style: normal"> </SPAN>Sender
|
|
Functions</H2>
|
|
<H3 CLASS="functionheading-western"><A NAME="NormStartSender()">NormStartSender()</A></H3>
|
|
<H4 CLASS="western">Synopsis</H4>
|
|
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
|
<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> session<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=100% BORDER=0 CELLPADDING=7 CELLSPACING=0>
|
|
<COL WIDTH=56*>
|
|
<COL WIDTH=200*>
|
|
<TR VALIGN=TOP>
|
|
<TD WIDTH=22%>
|
|
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
|
<FONT FACE="Courier"><U>session</U></FONT></P>
|
|
</TD>
|
|
<TD WIDTH=78%>
|
|
<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=22%>
|
|
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
|
<FONT FACE="Courier"><U>bufferSpace</U></FONT></P>
|
|
</TD>
|
|
<TD WIDTH=78%>
|
|
<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=22%>
|
|
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
|
<FONT FACE="Courier"><U>segmentSize</U></FONT></P>
|
|
</TD>
|
|
<TD WIDTH=78%>
|
|
<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=22%>
|
|
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
|
<FONT FACE="Courier"><U>blockSize</U></FONT></P>
|
|
</TD>
|
|
<TD WIDTH=78%>
|
|
<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>(n-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=22%>
|
|
<P CLASS="western" STYLE="font-style: normal; page-break-inside: avoid">
|
|
<FONT FACE="Courier"><U>numParity</U></FONT></P>
|
|
</TD>
|
|
<TD WIDTH=78%>
|
|
<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>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="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</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="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). This function
|
|
is expected to most typically used to initialize ther 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 grtt value will be limited to the maximum GRTT as set (see
|
|
<FONT FACE="Courier">NormSetGrttMax()) </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>
|
|
<H4 CLASS="western">Return Values</H4>
|
|
<P CLASS="western" STYLE="font-style: normal">This function has no
|
|
return values.</P>
|
|
<H3 CLASS="functionheading-western"><A NAME="NormAddAckingNode()">NormAddAckingNode()</A></H3>
|
|
<H4 CLASS="western">Synopsis</H4>
|
|
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
|
<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 (<I>TBD</I>).</P>
|
|
<H4 CLASS="western">Return Values</H4>
|
|
<P CLASS="western" STYLE="font-style: normal">The function returns
|
|
<FONT FACE="Courier"><I>true</I></FONT> upon success and <FONT FACE="Courier"><I>false</I></FONT>
|
|
upon failure. The only failure condition is that insufficient memory
|
|
resources were available. If a specific <FONT FACE="Courier"><U>nodeId</U></FONT>
|
|
is added more than once, this has no effect.</P>
|
|
<H3 CLASS="functionheading-western"><A NAME="NormRemoveAckingNode()">NormRemoveAckingNode()</A></H3>
|
|
<H4 CLASS="western">Synopsis</H4>
|
|
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
|
<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>.
|
|
|
|
</P>
|
|
<H4 CLASS="western">Return Values</H4>
|
|
<P CLASS="western" STYLE="font-style: normal">The function has no
|
|
return values.</P>
|
|
<H3 CLASS="functionheading-western"><A NAME="NormFileEnqueue()">NormFileEnqueue()</A></H3>
|
|
<H4 CLASS="western">Synopsis</H4>
|
|
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
|
<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>bool
|
|
NormStreamClose(<A HREF="#NormObjectHandle">NormObjectHandle</A> streamHandle);</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>.
|
|
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. This
|
|
alternative function is simply provided to compliment the
|
|
<FONT FACE="Courier"><A HREF="#NormStreamOpen()">NormStreamOpen()</A></FONT> call.</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>
|
|
<H4 CLASS="western">Return Values</H4>
|
|
<P CLASS="western" STYLE="font-style: normal">This function returns
|
|
the number of bytes of data successfully enqueued for NORM stream
|
|
transmission.</P>
|
|
<H3 CLASS="functionheading-western"><A NAME="NormStreamFlush()">NormStreamFlush()</A></H3>
|
|
<H4 CLASS="western">Synopsis</H4>
|
|
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
|
<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> NormFlushMode 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_ACTIV</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> NormFlushMode 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, 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="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 positive acknowledgment collection
|
|
for a given <FONT FACE="Courier"><U>session</U></FONT>. For
|
|
<FONT FACE="Courier"><I>NORM_OBJECT_FILE</I></FONT> and
|
|
<FONT FACE="Courier"><I>NORM_OBJECT_DATA</I></FONT> transmissions,
|
|
the positive acknowledgement collection will begin when the specified
|
|
<FONT FACE="Courier"><U>object</U></FONT> has been completely
|
|
transmitted. The object parameter must be a valid handle to a
|
|
previously-created sender object (see <FONT SIZE=2><FONT FACE="Courier">NormEnqueueFile(),</FONT></FONT>
|
|
<FONT SIZE=2><FONT FACE="Courier">NormEnqueueData()</FONT></FONT>, or
|
|
<FONT SIZE=2><FONT FACE="Courier"><A HREF="#NormStreamOpen()">NormStreamOpen()</A></FONT></FONT>).
|
|
For <FONT FACE="Courier"><I>NORM_OBJECT_STREAM</I></FONT>
|
|
transmission, the positive acknowledgment collection begins
|
|
immediately, using the current position (last data written) of the
|
|
sender stream as a reference.
|
|
</P>
|
|
<P CLASS="western" STYLE="font-style: normal">As the acknowledgment
|
|
collection proceeds, <FONT FACE="Courier"><I>NORM_ACK_FAILED</I></FONT>
|
|
events will be posted for individual receiver <I>NormNodes</I> which
|
|
fail to acknowledge the request. The <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A>::node</FONT>
|
|
field contains a <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> for the
|
|
failed node and <FONT FACE="Courier"><A HREF="#NormNodeGetId()">NormNodeGetId()</A></FONT> can be
|
|
used to retrieve the failing node's <FONT FACE="Courier"><A HREF="#NormNodeId">NormNodeId</A></FONT>.
|
|
When the sender acknowledgment collection process has completed, the
|
|
<FONT FACE="Courier"><I>NORM_ACK_COMPLETE</I></FONT> event is posted
|
|
and the application may assume that the remaining nodes (those for
|
|
which there was no <FONT FACE="Courier"><I>NORM_ACK_FAILED</I></FONT>
|
|
event) successfully acknowledged the request.</P>
|
|
<P CLASS="western" STYLE="font-style: normal">If a subsequent call is
|
|
made to <FONT FACE="Courier"><A HREF="#NormSetWatermark()">NormSetWatermark()</A></FONT> before the
|
|
prior acknowledgement request has completed, the pending
|
|
acknowledgment request is canceled and new one may begin.</P>
|
|
<P CLASS="western" STYLE="font-style: normal">Note that the sender
|
|
may still enqueue <I>NormObjects</I> for transmission (or write to
|
|
the existing stream) and the positive acknowledgement collection will
|
|
be multiplexed with the ongoing data transmission. However, the
|
|
sender application may wish to defer sending more data until a
|
|
<FONT FACE="Courier"><I>NORM_ACK_COMPLETE</I></FONT> event is
|
|
received for the <FONT FACE="Courier"><U>session</U></FONT>. This
|
|
provides a form of explicit sender->receiver(s) flow control (with
|
|
respect to the current list of "acking" receivers) which
|
|
does not exist in NORM's default NACK-only operation.</P>
|
|
<H4 CLASS="western">Return Values</H4>
|
|
<P CLASS="western" STYLE="font-style: normal">The function returns
|
|
<FONT FACE="Courier"><I>true</I></FONT> upon successful establishment
|
|
of the watermark point. The function may return <FONT FACE="Courier"><I>false</I></FONT>
|
|
upon failure (<I>why would it fail? – TBD</I>).</P>
|
|
<H2 CLASS="western">NORM Receiver Functions</H2>
|
|
<H3 CLASS="functionheading-western"><A NAME="NormStartReceiver()">NormStartReceiver()</A></H3>
|
|
<H4 CLASS="western">Synopsis</H4>
|
|
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
|
<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="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> NormNackingMode 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=100% BORDER=0 CELLPADDING=7 CELLSPACING=0 STYLE="page-break-inside: avoid">
|
|
<COL WIDTH=131*>
|
|
<COL WIDTH=125*>
|
|
<TR VALIGN=TOP>
|
|
<TD WIDTH=51%>
|
|
<P CLASS="western" STYLE="margin-left: 0.5in; font-style: normal"><FONT FACE="Courier"><I>NORM_NACK_NONE</I></FONT></P>
|
|
</TD>
|
|
<TD WIDTH=49%>
|
|
<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=51%>
|
|
<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=49%>
|
|
<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=51%>
|
|
<P CLASS="western" STYLE="margin-left: 0.5in; font-style: normal"><FONT FACE="Courier"><I>NORM_NACK_NORMAL</I></FONT></P>
|
|
</TD>
|
|
<TD WIDTH=49%>
|
|
<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> NormNackingMode
|
|
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> NormNackingMode 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> NormRepairBoundary
|
|
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> NormRepairBoundary
|
|
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 true. However, if a break in the integrity of the
|
|
reliable received stream occurs, a value of false is returned to
|
|
indicate the break. 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">NORM Object Functions</H2>
|
|
<P CLASS="western" STYLE="font-style: normal">The functions described
|
|
in this section may be used for sender or receiver purposes to manage
|
|
transmission and reception of NORM transport objects. In most cases,
|
|
the receiver will be the typical user of these functions to retrieve
|
|
additional information on newly-received objects. All of these
|
|
functions require a valid <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>
|
|
argument which specifies the applicable object. Note that
|
|
<FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT> values obtained from a
|
|
<FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT> notification may be considered
|
|
valid <I>only</I> until a subsequent call to <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT>,
|
|
unless explicitly retained by the application (see
|
|
<FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT>). <FONT FACE="Courier"><A HREF="#NormObjectHandle">NormObjectHandle</A></FONT>
|
|
values obtained as a result of <FONT FACE="Courier"><A HREF="#NormFileEnqueue()">NormFileEnqueue()</A></FONT>,
|
|
<FONT FACE="Courier"><A HREF="#NormDataEnqueue()">NormDataEnqueue()</A></FONT>, or <FONT FACE="Courier">NormOpenStream()</FONT>
|
|
calls can be considered valid only until a corresponding
|
|
<FONT FACE="Courier"><I>NORM_TX_OBJECT_PURGED</I></FONT> notification
|
|
is posted or the object is dequeued using <FONT FACE="Courier">NormCancelObject()</FONT>,
|
|
unless, again, otherwise explicitly retained (see
|
|
<FONT FACE="Courier"><A HREF="#NormObjectRetain()">NormObjectRetain()</A></FONT>).</P>
|
|
<H3 CLASS="functionheading-western"><A NAME="NormObjectGetType()">NormObjectGetType()</A></H3>
|
|
<H4 CLASS="western">Synopsis</H4>
|
|
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
|
<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>off_t
|
|
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 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). Developers should configure their
|
|
build environment to correspond with the NORM library used to ensure
|
|
that the "<FONT SIZE=2><FONT FACE="Courier">off_t</FONT></FONT>"
|
|
type is appropriately defined.
|
|
</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="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 NORM Node Functions described later
|
|
in this document.</P>
|
|
<H4 CLASS="western">Return Values</H4>
|
|
<P CLASS="western" STYLE="font-style: normal">This function returns
|
|
the <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> corresponding to the
|
|
remote sender of the transport object associated with the given
|
|
<FONT FACE="Courier"><U>objectHandle</U></FONT> parameter. A value
|
|
of NORM_NODE_INVALID is returned if the specified <FONT FACE="Courier"><U>objectHandle</U></FONT>
|
|
references a locally originated, sender object.</P>
|
|
<H2 CLASS="western">NORM Node Functions</H2>
|
|
<P CLASS="western" STYLE="font-style: normal">The functions described
|
|
in this section may be used for NORM sender or receiver (most
|
|
typically receiver) purposes to retrieve additional information about
|
|
a <I>NormNode</I>, given a valid <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT>.
|
|
Note that, unless specifically retained (see <FONT FACE="Courier"><A HREF="#NormNodeRetain()">NormNodeRetain()</A></FONT>),
|
|
a <FONT FACE="Courier"><A HREF="#NormNodeHandle">NormNodeHandle</A></FONT> provided in a <FONT FACE="Courier"><A HREF="#NormEvent">NormEvent</A></FONT>
|
|
notification should be considered valid only until a subsequent call
|
|
to <FONT FACE="Courier"><A HREF="#NormGetNextEvent()">NormGetNextEvent()</A></FONT> is made.
|
|
<FONT FACE="Courier">NormNodeHandles </FONT>retrieved using
|
|
<FONT FACE="Courier"><A HREF="#NormObjectGetSender()">NormObjectGetSender()</A></FONT> can be considered
|
|
valid for the same period of time as the corresponding
|
|
<A HREF="#NormObjectHandle">NormObjectHandle</A> is valid.</P>
|
|
<H3 CLASS="functionheading-western"><A NAME="NormNodeGetId()">NormNodeGetId()</A></H3>
|
|
<H4 CLASS="western">Synopsis</H4>
|
|
<P STYLE="font-style: normal; page-break-after: avoid"><FONT FACE="Courier"><FONT SIZE=2>#include
|
|
<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="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>
|